/vox-explainer

Velocity-Matched Transitions — technique catalog

Five SEAM techniques, one principle: cut at peak velocity, match direction and speed on both sides of the cut — plus the two in-scene techniques (§6 arrivals, §7 slides). The seam law — vector law, the current, the ledger, and the verification gate — lives in motion-continuity.md; read it first. This reference contains the parameters and mechanics. All GSAP code templates are in velocity-matched-transitions-gsap.md.

Catalog

One element running two or more animations back to back is a different problem — the velocity law applied WITHIN an object rather than across a cut. See animation-overlap.md.

Z direction is a sign

"Same axis" is not enough on Z — the sign of d(scale)/dt must match across the cut:

Banned mirrors: a receding exit answered by a grow-from-small entry (pull flips to push — the common one, since grow-from-small is the default element entrance), and a push exit answered by an oversized retraction. This binds the incoming scene's OWN entrances during the seam window (cut + ~0.5s), not just the wrapper tween: hold the incoming frame composed, or author its entrance to match the sign. Verify per seam verification gate rule 7.

Magnitude, not just sign. Matching d(scale)/dt sign is necessary but not sufficient: at the swap frame the incoming's APPARENT FIELD OF VIEW must be equal or tighter (deeper) than the outgoing's final framing when continuing a push, and equal or wider when continuing a pull — never the reverse. Verify with a landmark: measure a feature common to both plates (road width, a building) at the cut; a push whose incoming landmark is SMALLER than the outgoing's reads as a rubber-band (zoom in, snap back out), and blur does not hide it. When the incoming plate cannot be cropped deep enough, lower the outgoing's exit magnification to meet it. The same law binds one subject across a vanish: an element that exits through the lens may reappear at another scale only through an authored arrival the eye can ride (an inverse zoom-through, visible travel into place, or a reveal that redirects attention first) — a same-frame re-dock at a different magnification is a teleport and reads as random.

Blur logic (all Z variants)

Same peak blur on both sides at the swap frame. Blur the WRAPPER, never children.

1. Zoom-Through (forward)

Z-axis velocity-matched cut; never both texts visible. Everything GROWS: the outgoing text accelerates toward camera, a hard swap hides at peak blur, the incoming text keeps growing into the focal plane. Headlines and short phrases only. Total ≈ 0.4s.

Exit opacity MUST be its own linear tween — power3.in holds opacity near 1 too long. On entry all properties share expo.out.

2. Inverse Zoom-Through (backward)

The pull-back mirror: the outgoing element RECEDES; the incoming arrives OVERSIZED (as if just behind camera) and retracts into the focal plane. Everything SHRINKS. Spend on ARRIVAL/payoff beats — a payoff line, a giant reply, a held end-state — never ordinary boundaries. Total ≈ 0.7s (30% exit / 70% entry).

Blur is 10px text-scale; 18–20px only when both sides are full-bleed surfaces.

Sign discipline: the incoming scene arrives as a composed frame inside the retracting wrapper — no grow-from-small intro in the seam window. Staged entrances happen after the retraction settles, or start ≥1 and retract.

3. Continuation Cut (default scene boundary)

X/Y velocity-matched cut — the default for ALL scene-to-scene boundaries, in the film's current, not an accent. The outgoing hero accelerates in one direction, the cut lands mid-motion, the incoming hero continues the SAME direction and decelerates. Total ≈ 0.6s; directions LEFT / RIGHT / UP / DOWN (default LEFT).

Partial travel: ~12% of frame (≈230px at 1920) — never full off-screen moves.

Mechanics:

• Mirrored eases: exit power4.in + entry power4.out, same distance and duration — the two halves of one power4.inOut, so velocity matches exactly at the cut.
• The fade trick: exit opacity completes at ~25–30% of its travel (fade ≈ 0.18–0.3s vs motion 0.3–0.34s); entry ignites at ~0.35 opacity mid-path. Time the last fading element to die right at the cut — a gap where nothing moves reads as dead air.
• Exit 0.2–0.4s; entry ≥ exit. Optional blur 8–10px.
• Stage ground: #root must be opaque (background: var(--canvas-deep, var(--canvas, #000))) — the mid-window cut opens a summed-opacity < 1 window that flashes white otherwise (see render-safe-seams.md).

push-slide exists but violates partial-travel and mid-motion phase; prefer the continuation cut.

4. Word-Cascade Cut (word-by-word continuation cut)

The continuation cut at WORD granularity — the strongest leftward cut for text-to-text seams. Outgoing words ramp out on their own curves; incoming words cascade in mid-flight — a wave the eye rides across the seam.

Scope: worker-authored inside one multi-beat comp (stacked full-frame .beat layers), NOT a registry/injector type — it tweens word spans, not clip wrappers. The boundary into and out of the text-beat block still gets a normal registry transition. Does not count against the 2–3 transition budget.

Rules:

• One direction per chain, riding the current. Inverse zoom is the chain's ARRIVAL beat only.
• Pre-set all words to x: +230, opacity: 0 at build time — immediateRender: false alone leaves un-started words visible at rest.
• A short first beat may exit whole-line: its fade ends ~0.02s before the cut so it is still streaking when the next words ignite — no dead gap.
• Transform/opacity only (seek-safe); opaque stage ground applies.

5. Rack-Focus Blur-Cut (the visible cut)

The one variant where the cut is SEEN: a defocus blur SPIKE hides a single-frame hard swap — a handheld-DSLR focus-pull. Use as an occasional flourish for a state swap of the SAME surface within one visual theme; never the default boundary.

Differences from the others: outgoing stays FULLY OPAQUE until the cut (the blur hides the swap — no early fade); eases power2.in / power2.out (soft optics, not momentum).

Rules:

• Fire only at a narrative beat, ≤ once per ~8s; never mid-caption or during a hold.
• Cut at PEAK blur (≥6px; peak 8–12px, ≤16–18px max) — swapping on the way up shows the cut.
• A subtle scale (~1.06 lens-breathing) sells it as optics.
• Same direction on both sides — the vector law still holds. Entry ≥ exit duration.
• Blur the wrapper; never blur + opacity in one tween on one element (headless compositing bug); never blur a <video> directly (wrap it).

6. Cascade Entry (in-scene arrival — not a seam)

Staggered ARRIVAL cascade: words/elements whip in from below (one consistent direction), each starting before the previous settles — an accelerating wave that resolves into a composed layout. Title cards, segment openers, list/feature intros. The seam sibling is §4; do not mix their rules:

Choreography:

• Overlap, don't queue — next element starts within ±2 frames of the previous settling; gaps SHRINK across the cascade; the last element snaps.
• Velocity varies by weight — heavy/anchor elements travel further and longer; light words/punctuation snap in tight:

• Ease power4.out (expo.out for extra snap); never .inOut on an entry.
• One direction per cascade.
• Split the FINAL word into fragments to extend the climax; fragments travel further.
• Post-settle, the group usually slides to make room for the next beat — that's §7.

7. Three-Phase Slide (in-scene group slide — not a seam)

Slow-fast-slow repositioning of a composed group (word rows, card stacks, lists) to reveal content or make room. No single built-in ease produces it — power4.inOut smacks to a stop. Chain three tweens on one property:

Rules:

• The tail is ≥3× the ramp-in in TIME. If it still smacks: extend the tail's time (not distance) or use power5.out.
• Phase 2 stays linear — easing it loses the burst contrast.
• Reveal new content DURING phase 2 — the burst masks its appearance.
• Same ratios vertical; scale distances proportionally, keep the time ratios.

Choosing a Variant

Anti-Patterns

Code

All GSAP templates — worker-authored versions, registry gsap_templates, the combined continuation cut + zoom, word-cascade DOM/CSS/JS, rack-focus — live in velocity-matched-transitions-gsap.md.