hyperframes/skills/hyperframes-animation/blueprints/cta-orbit-collapse.md

---

id: cta-orbit-collapse role: cta duration_seconds: [5, 8] phases: 5 visual_arc: icons-orbit → cursor-click → collapse → demo-appears → demo-floats uses_rules: [orbit-3d-entry, cursor-click-ripple, center-outward-expansion, sine-wave-loop] element_roles: orbit_icons: 3D-entry icons representing categories / use-cases, orbiting the centerpiece center_cta: Central CTA element (input bar, button) that receives the click cursor: Animated cursor that moves to the CTA and clicks with ripple feedback demo: Product demo (video / image) that appears from the collapse point and floats when_to_use:

• Show product versatility (works for many categories / use-cases)
• Icons represent different content types, genres, modes, or technology surfaces
• User-click metaphor triggers transformation from categories → result
• "Many options → one action → one result" narrative compression when_not_to_use:
• Categories have no distinct iconography (use a text list)
• No user-action metaphor — product works automatically
• Scene is purely informational triggers: [works for any genre, multiple categories, click to generate, versatile tool, one click result]

---

CTA · Orbit Collapse (HyperFrames)

This is a "scope → choice → consequence → product" emotional arc: the viewer first sees a ring of categories drifting around an empty CTA (the product handles many things), a cursor walks in and decisively clicks (the user picks one), the orbit implodes toward the click point (the choice consumes the options), and the demo springs out of that collapse point as the answer. A final breathing yoyo says "this is what you get."

One paused GSAP timeline, five phases. Phase 1 (orbit) and Phase 3 (collapse) share a single master onUpdate clock — they cannot be independent tweens, see Phase 1↔3 seam.

When to Use

• Versatility scene: the product handles many categories, and you need the eye to feel that span before the pivot
• The transformation from "options" to "result" should feel physical — a click pulls the icons inward, not a fade
• A cursor click drives the narrative pivot (versus a zoom, a wipe, a swap)
• Total duration sits in 5–8 s; shorter and the orbit doesn't register as ambient

Orchestration

Each phase, the rule (or inline) that drives it, and why this variation:

• Phase 1 — orbit entry: use orbit-3d-entry for the per-icon 3D flip-in (back.out(ENTRY_BACK), mild end of the rule's range). But the orbit motion itself is NOT taken from the rule's per-item onUpdate — it's folded into the master clock in Phase 3, because the same clock must also drive the collapse. See Phase 1↔3 seam.
• Phase 2 — cursor click: use cursor-click-ripple end to end — cursor move (back.out(CURSOR_BACK) for a calm settle, since the click must read as deliberate not darting), depression yoyo on cursor + CTA button, and the rule's keyframed attack-decay ripple variation (the explicit 0 → peak → 0 envelope), because the click is the narrative climax and a linear fade reads as weak. Single ring — the orbit is already busy enough that multiple rings would muddy the moment.
• Phase 3 — collapse: use center-outward-expansion in its reversed driver form — the rule's progress * (target - center) math run with progress going 0 → 1 becomes the inward path. The reversal is the only thing we keep; the rule's per-item tweens are replaced by the same master onUpdate that runs the orbit (see Phase 1↔3 seam). Ease: back.out(COLLAPSE_BACK) consumed via gsap.parseEase (see Phase 3 ease seam).
• Phase 4 — demo entry: inline single fromTo with back.out(DEMO_BACK) on .demo from scale: 0 to scale: 1. One tween, no orchestration — making this a rule would be overengineering, same call as the brand-reveal hero pop.
• Phase 5 — demo floats: use sine-wave-loop in its simple fromTo + finite yoyo form (not the multiplicative onUpdate form). The demo settles at exact scale: 1 after Phase 4 (no outer-wrapper zoom is composing onto it), so a direct y + rotation yoyo is the simplest expression. If you change Phase 4 so the demo lands at a non-1 scale, switch to the rule's multiplicative form — see Phase 5 seam.

Phase Timing

Phase	Start ≥	Internal duration	Notes
1	0	(N-1) * ENTRY_STAGGER + ENTRY_DUR	Orbit clock starts at t=0 even before flips finish
2	last-entry-finish + ~0.3s settle gap	CURSOR_MOVE + decision_pause	Settle gap lets the orbit read as ambient before the cursor arrives
3	CLICK_AT	COLLAPSE_DUR	Orbit and collapse share one onUpdate — see seam
4	CLICK_AT + COLLAPSE_DUR − COLLAPSE_OVERLAP	DEMO_DUR	Negative gap (overlap) — energy transfer, not a hard cut
5	DEMO_AT + DEMO_DUR + ~0.2s IDLE_TAIL	TOTAL − IDLE_START	Spring tail must finish before sine takes over

The Phase 1 → 2 settle gap (≥ 0.3 s after the last icon lands) is what lets the orbit read as ambient motion rather than "still entering" — without it, the cursor's entry overlaps the cascade and the viewer doesn't know what to look at. The Phase 2 → 3 transition has no gap by design: the click instant IS the collapse pivot. The Phase 3 → 4 step is intentionally negative (COLLAPSE_OVERLAP, 0.05–0.20 s) — the demo entry begins just before the collapse fully completes so the click reads as energy transferring into the demo, not as two separate events. The Phase 4 → 5 gap (IDLE_TAIL, ~0.2 s) is the same logic as every other spring→sine handoff: back.out decays to near-zero velocity but never literally zero, and a sine wave starting on top of that produces visible chatter.

Initial DOM Nesting (Critical)

Each icon needs three nested wrappers because three independent sources write to it: the master onUpdate writes orbit-position to the outermost layer, the same onUpdate writes collapse scale/opacity to the middle layer, and the per-icon entry fromTo writes 3D rotation to the innermost layer. Tweening the same property on the same element from two sources is undefined behavior in GSAP, so these cannot share an element.

.icon-pos        ← outermost — orbit x/y (from master onUpdate)
  .icon-collapse ← middle    — collapse scale/opacity (from master onUpdate)
    .icon-entry  ← innermost — 3D flip rotateX/rotateY/z/scale/opacity (per-icon tween)
      <svg> + label

perspective is applied to .icon-pos (the layer that owns the orbit transform) so the inner 3D rotation has depth — without it the flip-in reads as 2D scale. The orbit's elliptical radii (RADIUS_X, RADIUS_Y) are baked into the onUpdate math, not into per-icon CSS.

The cursor sits at z-index: 999 and the ripple at z-index ≈ 6 — between the CTA card and the cursor. This ordering matters more here than in a plain cursor-click-ripple scene because the orbiting icons can pass in front of the CTA at any angle; without the explicit cursor z-index the cursor flickers behind icons mid-move.

Phase 1↔3 Seam: One Master onUpdate for Orbit + Collapse

This is the blueprint's core glue and the single most important decision in the file. The orbit must keep advancing while the radius shrinks — otherwise the icons "snap" inward in a way that doesn't read as collapse. So orbit angle and collapse radius are computed in the same onUpdate that runs continuously from t=0 through the end of Phase 3:

const COLLAPSE_EASE = gsap.parseEase(`back.out(${COLLAPSE_BACK})`);
const ORBIT_END = DEMO_AT; // master clock stops once icons are gone

tl.to(
  { tick: 0 },
  {
    tick: 1, // unused — this is just a clock target
    duration: ORBIT_END,
    ease: "none",
    onUpdate: () => {
      const t = tl.time();
      const collapseLinear = Math.max(0, Math.min(1, (t - CLICK_AT) / COLLAPSE_DUR));
      const collapseEased = COLLAPSE_EASE(collapseLinear); // proxy spring
      const radiusFactor = 1 - collapseEased; // 1 → 0 over Phase 3
      const collapseScale = 1 - collapseEased * COLLAPSE_SCALE_DEPTH;

      // Two-segment opacity envelope — see Opacity Knee seam below
      const o = collapseEased;
      const collapseOpacity =
        o < OPACITY_KNEE_T
          ? 1 - o * ((1 - OPACITY_KNEE) / OPACITY_KNEE_T)
          : (OPACITY_KNEE * (1 - o)) / (1 - OPACITY_KNEE_T);

      ICONS.forEach(({ sel, initialAngle, entryDelay }) => {
        const localT = Math.max(0, t - entryDelay);
        const angle = initialAngle + localT * ORBIT_SPEED;
        gsap.set(`${sel}.icon-pos`, {
          x: Math.cos(angle) * RADIUS_X * radiusFactor,
          y: Math.sin(angle) * RADIUS_Y * radiusFactor,
        });
        gsap.set(`${sel} .icon-collapse`, { scale: collapseScale, opacity: collapseOpacity });
      });
    },
  },
  0,
);

Three things are doing real work here and won't be obvious if you skim:

tl.time(), not the proxy tween's progress. The orbit must be a pure function of the timeline clock so HF seek lands deterministically at every frame. Using the proxy tween's progress would be equivalent under play but drifts under seek-after-pause.

gsap.parseEase instead of a separate eased proxy tween. A proxy tween (tl.to(driver, { v: 1, ease: 'back.out(...)' })) and gsap.parseEase('back.out(...)')(progress) produce identical values for the same progress fraction, but parseEase is anchored to tl.time() directly. A sibling proxy tween can drift from the master clock after seek, leaving the orbit and collapse out of step by a frame.

entryDelay shows up in localT, not in a conditional if (t < entryDelay) skip. Each icon's orbit phase advances from the moment that icon's entry tween fires, not from t=0 — so icons that flipped in later are at an earlier angle on the orbit when the collapse begins. This is what gives the orbit its "cascade-into-motion" feel. A naive if gate around the gsap.set produces a hard jump when each icon's gate opens.

Phase 3 Ease Seam: Two-Segment Opacity Knee

The [1 → OPACITY_KNEE → 0] opacity envelope is what makes the collapse read as energy converging rather than pop-vanish. A linear 1 → 0 fade across the collapse duration looks like the icons are simply being deleted — fine for a transition but wrong for a click-driven implosion. The knee form keeps icons mostly opaque through OPACITY_KNEE_T (typically 0.7–0.9 of the collapse), then drops sharply to 0 at the end — visually, the icons stay solid as they accelerate inward and only dissolve at the moment of impact.

The two segments meet at (OPACITY_KNEE_T, OPACITY_KNEE). The first segment is a line from (0, 1) to that point; the second is a line from there to (1, 0). Both segments are computed against collapseEased (post-back.out), not collapseLinear — so the dissolve also gets the spring's late-stage slowdown, which makes the energy-release feel more deliberate.

Phase 3↔4 Seam: Collapse Origin = Demo Origin (Exactly)

The demo's CSS-centering offsets must align exactly with the viewport-center point the icons collapse toward. The icons collapse to (0, 0) in .icon-pos translate-space, which (because of the rule's xPercent: -50, yPercent: -50 centering) maps to the centroid of .orbit-stage. The demo uses left: 50%; top: 50% plus xPercent: -50, yPercent: -50 (via GSAP, since the demo also takes a scale tween).

This match must be exact. The eye is extremely good at picking up a few-pixel misalignment between the collapse target and the demo entry point — it reads as a teleport rather than emergence. If .orbit-stage is not the full viewport (e.g. a fixed-size centered stage), the demo must live inside the same stage container, not as a sibling — otherwise their viewport-center math differs by the stage's offset.

COLLAPSE_OVERLAP (0.05–0.20 s) controls how much the demo entry overlaps the tail of the collapse. Too small (< 0.05) and the click reads as two disconnected events; too large (> 0.20) and the icons appear to pass through the visible demo, breaking the energy-transfer illusion.

Phase 4↔5 Seam: Why the Simple Yoyo (Not Multiplicative)

sine-wave-loop has two implementation forms: a simple fromTo + yoyo and a multiplicative onUpdate that adds the breath onto an existing scale. We pick the simple form here because Phase 4 lands the demo at exact scale: 1 with no outer wrapper composing onto it (unlike brand-reveal's hero, which has a .zoom-scale parent). The yoyo's from of y: 0, rotation: 0 matches the demo's settled state at IDLE_START, so sin(0) = 0 translates directly into "no jump at the seam."

The repeat count is computed to land before the composition ends:

const halfCycles = Math.max(0, Math.floor((TOTAL - IDLE_START) / HALF_CYCLE) - 1);

The -1 keeps a half-cycle of buffer — without it, you risk the last visible frame catching the demo mid-breath. HyperFrames forbids repeat: -1, so this finite computation is mandatory.

If you later add a scale overshoot that leaves the demo at, say, scale: 1.05 after Phase 4 settles, switch to sine-wave-loop's multiplicative form — the simple yoyo would re-tween from scale: 1, undoing the overshoot.

Key Values to Choose (Not Already in the Rules)

Only listing parameters unique to this blueprint — standard ranges (ENTRY_DUR, STAGGER, RADIUS_X, BOUNCE_FACTOR, etc.) live in the referenced rules.

• COLLAPSE_OVERLAP (0.05–0.20 s): the negative gap between Phase 3 and Phase 4. Tune by eye against the demo's spring overshoot — a stiffer DEMO_BACK wants a smaller overlap, a softer one tolerates more.
• COLLAPSE_SCALE_DEPTH (0.3–0.7): how far each icon shrinks during the collapse (1 → 1 - depth). Low values keep icons visible at the moment of impact (reads as "they were absorbed"); high values let them disappear into the click point (reads as "they were consumed"). Pick by narrative intent.
• OPACITY_KNEE / OPACITY_KNEE_T (knee 0.3–0.6, knee_t 0.7–0.9): the kink in the two-segment opacity envelope. A high knee_t with a moderate knee is the "energy converging then released" curve. Lower knee_t reads as a normal fade.
• N (icon count): 4–12 is the comfort range. The 2π / N angular spacing must leave room for the icon glyph plus label — measure the worst case (icon directly above or below CTA, where label sits closest to the CTA card).
• CURSOR_TARGET (X, Y): must align with the visual centroid of the CTA button, not the CTA card center. A 4-pixel miss reads as missing the button.

Critical Constraints (ordered by failure frequency)

• Three nested wrappers per icon — never collapse them. Tweening orbit position, collapse scale, and 3D flip on the same element produces silent GSAP last-write-wins behavior. This is the failure people hit first and stare at longest.
• COLLAPSE_BACK > ENTRY_BACK: the collapse must feel snappier than the entry, otherwise the click feels uncaused — the eye reads the cascade and the implosion as one continuous motion instead of cause-and-effect. The narrative pivot lives in this contrast.
• Demo origin matches collapse center exactly: see Phase 3↔4 seam. A few-pixel misalignment reads as a teleport.
• Orbit angle is a function of tl.time(), not proxy tween progress: see Phase 1↔3 seam. The proxy form drifts under HF seek.
• One master onUpdate for orbit + collapse, not two tweens: independent tweens cannot keep orbit advancing while radius shrinks. The blueprint's name (orbit-collapse) is implementing exactly this composition.
• Orbit speed constant before and during collapse — only radius shrinks. Slowing the orbit during collapse breaks the "snappy contraction" feel; speeding it up looks like the icons spin into a drain.
• Cursor z-index: 999: orbiting icons can pass in front of the CTA at any angle and will occlude a non-elevated cursor.
• Ripple z-index between CTA and cursor (~6): above the CTA card, below the cursor.
• CTA button visibly depresses on click: the press-scale tween on .cta-button is the causal trigger. Without it, the collapse feels uncaused even though the cursor lands on target.
• Phase 5 simple yoyo assumes demo settles at scale 1: if you change Phase 4's spring to leave residual scale, switch to the multiplicative form in sine-wave-loop.

Spring → Ease Selection

Five spring-shaped beats, four back.out coefficients plus one sine yoyo. Full mapping table lives in hyperframes-animation/SKILL.md; the intent-to-ease pairing here is:

• Phase 1 icon flip → back.out(ENTRY_BACK) (calm arrive, low end of range)
• Phase 2 cursor move → back.out(CURSOR_BACK) (calm settle)
• Phase 3 collapse → back.out(COLLAPSE_BACK) via gsap.parseEase (snappy — must exceed ENTRY_BACK)
• Phase 4 demo spring → back.out(DEMO_BACK) (snappy arrive with overshoot)
• Phase 5 breath → sine.inOut yoyo with finite repeat

Golden Sample

• cta-orbit-collapse.html — runnable 6.5-second composition with concrete values for every named constant above. Demonstrates the three-wrapper icon anatomy and the gsap.parseEase pattern for a spring-shaped driver consumed inside a master onUpdate. Run it first, then change values — much faster than building from scratch.