@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/.agents/skills/hyperframes-animation/rules/depth-of-field-blur.md

@@ -0,0 +1,313 @@
+---
+name: depth-of-field-blur
+description: Selective-focus rack-focus — pull the eye to a focal element by GSAP-tweening filter blur (+ a small opacity dim) on the off-focus layers while the focal one stays sharp. Drive blur via a `--dof` CSS var; finite tweens, no CSS transition, deterministic. Covers single focal pull, rack-focus between two depth planes, and blur-the-cluster-while-pushing-in.
+metadata:
+  tags: blur, focus, depth-of-field, dof, rack-focus, filter, dim, spotlight, cinematic, push-in
+---
+
+# Depth-of-Field Blur (Selective Focus / Rack Focus)
+
+Pulls the eye to one focal element by **blurring** (and slightly **dimming**) everything around it while the focal layer stays sharp — the camera's depth-of-field falling off the background, or a rack-focus shifting which plane is in focus. The motion is `filter: blur(Npx)` plus a small `opacity` dim, tweened from sharp(0) to blurred over the focus-shift window — both seek-safe, since `filter` and `opacity` are paint-only properties HF interpolates correctly frame-by-frame.
+
+This is the backing rule for the focus-falloff beat the blueprints keep reaching for: the outer nodes blurring during the push-in (`constellation-hub`), the rack-focus across a parallax card stack (`cursor-ui-demo`), and the non-highlighted cards dimming + blurring to spotlight the hero metric (`dataviz-countup`). Each of those flags "no backing rule" for the DoF half of the move — this is it.
+
+## How It Works
+
+Every layer carries a `--dof` custom property (px of blur), read by `filter: blur(var(--dof))`, plus its own `opacity`. A single GSAP tween advances each layer's `--dof` from `0` to its target blur and its opacity from `1` to a dim level, over the focus-shift window. The focal layer's tween targets `--dof: 0` (stays sharp); the off-focus layers target a positive blur.
+
+Three mechanics, same primitive:
+
+1. **Focal pull** — one window: off-focus layers go sharp(0) → blurred while the focal layer holds at 0. The eye is pulled to the only thing still crisp.
+2. **Rack focus** — two adjacent windows on the same property: focus releases plane A (its blur ramps 0 → max) at the same position plane B's blur ramps max → 0. State continuity matters exactly as in `press-release-spring`: A's resting blur after the rack must be the value B held before it, so authoring the two as adjacent tweens on the same `--dof` is what makes the hand-off seamless.
+3. **Blur-the-cluster-while-pushing-in** — the DoF tween runs concurrently with a camera push-in (`multi-phase-camera` / `coordinate-target-zoom`): the surrounding cluster blurs + dims on the SAME timeline position as the camera scales toward the focal core, so "the world recedes" and "we push in" read as one move.
+
+Because the blur is a tween target (not a CSS `transition`), the renderer can land it at any frame — and because each layer's target is derived from its index / a data attribute (never `Math.random`), the falloff is identical on every seek.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="dof-scene"
+  data-composition-id="dof-scene"
+  data-start="0"
+  data-duration="DURATION"
+  data-track-index="0"
+>
+  <div class="world" id="world">
+    <!-- Focal layer — stays sharp -->
+    <div class="layer focal" id="focal" data-dof="0">{FocalLabel}</div>
+
+    <!-- Off-focus layers — blur + dim. data-depth orders them near→far
+         so the falloff can scale blur by depth (see Variations). -->
+    <div class="layer ctx" data-depth="1">{Context A}</div>
+    <div class="layer ctx" data-depth="2">{Context B}</div>
+    <div class="layer ctx" data-depth="3">{Context C}</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgGradient};
+}
+.world {
+  /* Single wrapper so a concurrent camera push-in (multi-phase-camera)
+     transforms everything together; DoF is independent of the camera. */
+  position: relative;
+  width: 100%;
+  height: 100%;
+  transform-origin: 50% 50%;
+}
+.layer {
+  /* --dof is the px of blur; filter reads it. Starts sharp. */
+  --dof: 0px;
+  filter: blur(var(--dof));
+  /* will-change: filter — promotes the layer so the blur is cheap to
+     re-rasterize each frame. See the perf note in Key Principles. */
+  will-change: filter;
+  font-family: {font};
+  font-weight: 900;
+  color: {textColor};
+}
+.focal {
+  /* Sits above the context layers and never blurs. */
+  z-index: 2;
+  font-size: FOCAL_FONT_SIZE;
+}
+.ctx {
+  /* The off-focus plane(s). Smaller / grouped so the blur radius can
+     stay modest yet still read — blurring a small layer is cheap. */
+  z-index: 1;
+  font-size: CTX_FONT_SIZE;
+  opacity: 1;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const ctx = gsap.utils.toArray(".ctx");
+
+  // ── Mechanic 1: FOCAL PULL ─────────────────────────────────────────
+  // Off-focus layers blur + dim from sharp to defocused over the
+  // focus-shift window. Blur scales with data-depth so far planes blur
+  // more than near ones (deterministic — derived from the attribute,
+  // never Math.random).
+  ctx.forEach((el) => {
+    const depth = Number(el.dataset.depth) || 1;
+    const targetBlur = BLUR_PER_DEPTH * depth; // px
+    tl.to(
+      el,
+      {
+        "--dof": `${targetBlur}px`,
+        opacity: DIM_LEVEL, // e.g. 0.55 — dim, not gone
+        duration: FOCUS_DUR,
+        ease: "power2.inOut",
+      },
+      FOCUS_START,
+    );
+  });
+  // Focal layer is already sharp (--dof:0, opacity:1) and untouched.
+
+  window.__timelines["dof-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Rack focus between two depth planes (foreground ⇄ background)
+
+Two adjacent tweens on the same `--dof` per plane — focus leaves plane A as it lands on plane B. State continuity: B's _resting_ blur before the rack equals what A holds after, so the hand-off has no jump.
+
+```js
+// Start: A sharp, B pre-blurred (set BEFORE the rack so there's no pop).
+gsap.set("#planeA", { "--dof": "0px", opacity: 1 });
+gsap.set("#planeB", { "--dof": `${MAX_BLUR}px`, opacity: DIM_LEVEL });
+
+// Rack: A defocuses while B comes into focus, same position + duration.
+tl.to(
+  "#planeA",
+  { "--dof": `${MAX_BLUR}px`, opacity: DIM_LEVEL, duration: RACK_DUR, ease: "power2.inOut" },
+  RACK_START,
+);
+tl.to(
+  "#planeB",
+  { "--dof": "0px", opacity: 1, duration: RACK_DUR, ease: "power2.inOut" },
+  RACK_START,
+);
+```
+
+### Blur the cluster while pushing in (DoF + camera, one beat)
+
+Run the focal-pull tween at the **same timeline position** as a camera push-in so the surrounding cluster recedes into blur exactly as the camera scales toward the core. The camera transforms `.world`; the DoF tweens the layers — independent properties, no conflict.
+
+```js
+// Camera push-in toward the focal core (see multi-phase-camera / coordinate-target-zoom).
+tl.to(
+  "#world",
+  { scale: PUSH_SCALE, x: PUSH_X, y: PUSH_Y, duration: FOCUS_DUR, ease: "power2.inOut" },
+  FOCUS_START,
+);
+// Cluster blurs + dims on the SAME position — "the world recedes as we push in."
+ctx.forEach((el) => {
+  const depth = Number(el.dataset.depth) || 1;
+  tl.to(
+    el,
+    {
+      "--dof": `${BLUR_PER_DEPTH * depth}px`,
+      opacity: DIM_LEVEL,
+      duration: FOCUS_DUR,
+      ease: "power2.inOut",
+    },
+    FOCUS_START,
+  );
+});
+```
+
+### Spotlight a hero metric in a card grid (dim + blur the rest)
+
+The `dataviz-countup` beat: a subset of grid cards stays sharp (the hero metric) while the remainder dim + blur. Tag the hero(es) and skip them; everything else defocuses on one shared window.
+
+```js
+gsap.utils.toArray(".card:not(.hero)").forEach((el) => {
+  tl.to(
+    el,
+    { "--dof": `${GRID_BLUR}px`, opacity: DIM_LEVEL, duration: FOCUS_DUR, ease: "power2.out" },
+    FOCUS_START,
+  );
+});
+```
+
+### Refocus / settle (release the blur before the scene ends)
+
+If the beat resolves back to "everything visible" (or hands off to a crossfade that needs a clean outgoing frame), ramp the blur back to 0 over the tail so the scene settles sharp instead of mid-defocus.
+
+```js
+ctx.forEach((el) =>
+  tl.to(
+    el,
+    { "--dof": "0px", opacity: 1, duration: REFOCUS_DUR, ease: "power2.inOut" },
+    REFOCUS_START,
+  ),
+);
+```
+
+### Bounded focus-breathing on the focal layer (optional)
+
+For a subtle "rack settling" feel, let the focal layer's blur breathe a hair around 0 during its hold — a _finite_ `ease:"none"` driver writing `sin()` into `--dof` (never `repeat:-1`, never a CSS animation). Keep the amplitude well under 1px or it reads as "still focusing."
+
+```js
+const drift = { p: 0 };
+tl.to(
+  drift,
+  {
+    p: Math.PI * 2 * BREATH_CYCLES,
+    duration: BREATH_DUR,
+    ease: "none",
+    onUpdate: () => {
+      const b = Math.max(0, Math.sin(drift.p)) * FOCAL_BREATH_PX; // ≤ ~0.6px
+      document.getElementById("focal").style.setProperty("--dof", `${b}px`);
+    },
+  },
+  BREATH_START,
+);
+```
+
+## How to Choose Values
+
+### Geometry / layout
+
+- **FOCAL_FONT_SIZE / CTX_FONT_SIZE** — focal vs context sizing.
+  - Range: focal is the visual lead; context layers smaller so a modest blur radius still reads as "out of focus."
+  - Effects: small context layers let you use a smaller `BLUR_PER_DEPTH` (cheaper) yet still look soft.
+- **z-index** — focal `z-index: 2`, context `z-index: 1`.
+  - Constraints: the sharp focal layer must sit **above** the blurred ones, or its crisp edges read as bleeding into the haze.
+
+### Blur amounts
+
+- **BLUR_PER_DEPTH** — px of blur added per depth step (`data-depth`).
+  - Range: 3-6 px per step (a 3-plane stack tops out at ~9-18 px)
+  - Effects: low → gentle DoF; high → strong miniature/tilt-shift falloff
+  - Constraints: keep **per-layer blur ≤ ~24 px on large layers** — radius cost grows with both blur and area; large radius over a full-frame element is the expensive case (see Key Principles)
+- **MAX_BLUR** — terminal blur for a fully-defocused plane (rack / focal-pull peak).
+  - Range: 8 (soft) → 16 (default) → 24 (heavy) px
+  - Constraints: above ~24 px on a big surface, prefer scaling the layer down or grouping its contents so the blurred footprint shrinks
+- **GRID_BLUR** — blur on dimmed grid cards (spotlight variation).
+  - Range: 6-12 px — enough to push them back without losing the grid's shape
+
+### Dim amounts
+
+- **DIM_LEVEL** — opacity of off-focus layers at full defocus.
+  - Range: 0.4 (strong push-back) → 0.55 (default) → 0.7 (subtle)
+  - Effects: lower → context recedes hard / near-spotlight; higher → still legibly present, just secondary
+  - Constraints: rarely below 0.35 — fully dark off-focus layers read as "removed," not "defocused"
+
+### Timing
+
+- **FOCUS_START / FOCUS_DUR** — when the focal pull begins and how long the rack takes.
+  - Range: `FOCUS_DUR` 0.5-1.2 s — a rack/pull is a deliberate move, not a snap
+  - Effects: shorter → urgent "snap focus"; longer → languid cinematic rack
+- **RACK_START / RACK_DUR** — rack-focus window (foreground ⇄ background).
+  - Constraints: both planes' tweens share `RACK_START` and `RACK_DUR` so they cross at the midpoint; `gsap.set` the pre-blurred plane BEFORE `RACK_START`
+- **REFOCUS_START / REFOCUS_DUR** — settle-back window.
+  - Constraints: `REFOCUS_START + REFOCUS_DUR ≤ DURATION` so the scene actually reaches sharp before it ends / hands off
+- **PUSH_SCALE / PUSH_X / PUSH_Y** (cluster-while-pushing-in variation) — camera move on `.world`.
+  - Constraints: shares `FOCUS_START` + `FOCUS_DUR` with the DoF tween so move and defocus read as one beat; counter-translate math lives in `coordinate-target-zoom` / `viewport-change`
+- **BREATH_CYCLES / BREATH_DUR / FOCAL_BREATH_PX** (focus-breathing variation).
+  - Range: `FOCAL_BREATH_PX ≤ 0.6` px; period 2-3 s; this is a barely-there nicety, default to omitting it
+
+### Tokens
+
+- **{bgGradient}** — typically dark so the sharp focal layer reads as lit and forward
+- **{textColor}** — high-contrast on `{bgGradient}`; the blur softens edges, so don't rely on hairline contrast
+- **{font}** — display weight; blurred copy needs heavy weight to stay shape-legible when defocused
+
+## Key Principles
+
+- **`--dof` drives the blur; tween the variable, never a CSS `transition`.** Reading `filter: blur(var(--dof))` and animating `--dof` on the GSAP timeline keeps the blur on the HF seek clock. A CSS `transition` on `filter` interpolates on the browser's own clock and flickers/desyncs under frame-by-frame seek.
+- **Blur the SMALL / GROUPED layers, not the giant one.** Filter-blur cost scales with both radius and the blurred element's pixel area. A 20 px blur on a full-frame background is the worst case; the same blur on a smaller context card, or on a single grouped wrapper, is cheap. Prefer pushing the focal plane _forward and sharp_ over cranking the background blur radius.
+- **`will-change: filter`** on every layer that animates its blur — promotes it to its own layer so the re-rasterization each frame is cheap. Drop it once the blur settles if the layer also does heavy transform work.
+- **Keep the radius modest.** ≤ ~24 px on large surfaces; lean on the `opacity` **dim** to do the "push it back" work alongside a smaller blur, rather than blur alone. Dim + modest blur reads more like real DoF than blur cranked to the max.
+- **Focal layer stays genuinely sharp** — its `--dof` is `0` and untouched (or breathes ≤0.6 px). Any visible blur on the focal element kills the "this is the thing" read.
+- **State continuity on a rack** — the plane coming OUT of focus must start the rack at the blur the incoming plane _was_ holding, and vice-versa; author both as tweens on the same `--dof` at the same position so the cross is seamless (same rule as `press-release-spring`'s press↔release).
+- **DoF is independent of the camera** — blur the layers, transform `.world` for the push-in. They're different property channels, so they compose without fighting. Don't try to fake DoF with the camera transform or vice-versa.
+- **Settle sharp before a hand-off** — if the next beat is a crossfade/push, refocus to `--dof:0` in the tail so the outgoing frame is crisp; handing off mid-defocus reads as "the render glitched."
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `transition`** on `filter` / `opacity` — animate `--dof` and `opacity` on the timeline instead
+- **No `repeat` / `yoyo` / infinite tweens** — the focus pull is a finite tween; any breathing is a bounded `onUpdate` reading the driver phase (or a finite tween), never `repeat:-1`
+- **No `Math.random` / `Date.now`** — per-layer blur is derived from `data-depth` / element index so every seek is identical
+- **Tween `filter` (blur) + `opacity` only here** — both paint-only and seek-safe. Use GSAP transform aliases (`x`, `y`, `scale`) for any concurrent camera move; never tween `width` / `height` / `left` / `top`
+- **`will-change: filter`** on layers whose blur animates; keep the blurred footprint small
+- **Per-layer blur radius ≤ ~24 px on large surfaces** — beyond that the cost (and visible banding) climbs; shrink/group the layer instead
+
+## Combinations
+
+- [multi-phase-camera.md](multi-phase-camera.md) — the push-in / push-through whose focus-falloff this rule supplies; run the DoF tween at the same position as the PUSH phase
+- [coordinate-target-zoom.md](coordinate-target-zoom.md) — zoom onto the focal core while the off-center layers blur (the `constellation-hub` hook)
+- [viewport-change.md](viewport-change.md) — pan across a tilted card plane with a rack-focus between near and far cards (the `cursor-ui-demo` focus-pull)
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — the hero metric counts up sharp while the surrounding cards dim + blur (the `dataviz-countup` spotlight)
+- [3d-page-scroll.md](3d-page-scroll.md) — the parallax card stack whose planes you rack focus between
+- [sine-wave-loop.md](sine-wave-loop.md) — the focal layer idle-breathes after the rack settles (keep idle amplitude and focus-breath both tiny)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — tweening a CSS custom property + multi-tween coordination
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/.agents/skills/hyperframes-animation/rules/depth-scatter-assemble.md

@@ -0,0 +1,303 @@
+---
+name: depth-scatter-assemble
+description: N elements scatter into / reassemble from a rotating 3D depth-cloud, each starting at a deterministic index-derived 3D offset and settling to a clean flat layout.
+metadata:
+  tags: 3d, scatter, assemble, depth, cloud, tumble, kinetic, letter, fragment, logo, reassemble
+---
+
+# Depth Scatter ↔ Assemble
+
+N elements (glyphs, cards, icons, logo fragments) fly in from a rotating 3D depth-cloud and lock into a clean on-screen layout — or the reverse. Each element starts at a **deterministic** 3D offset (translateZ depth + rotateX/rotateY + an x/y scatter derived from its index), then tweens to its assembled flat position (`z: 0, rotation: 0`). Because every scattered position is computed by trig on the element's index — never `Math.random` — it renders identically every frame.
+
+Distinct from `orbit-3d-entry` (flip-in then a continuous orbit) and `center-outward-expansion` (a flat 2D burst from one shared center): here each element has its **own** point in a 3D cloud, and the resolve is a flat assembled layout, not an orbit or a radial spray.
+
+## How It Works
+
+Each element resolves to a flat layout position (`targetX/Y`, set once in CSS or via `data-*`). Its **scattered** state is derived from its index `i`:
+
+```js
+const GOLDEN = Math.PI * (3 - Math.sqrt(5)); // ~2.39943 rad — even angular spread, no clumping
+const a = i * GOLDEN; // this element's angle in the cloud
+const scatterX = Math.cos(a) * RADIUS; // index-derived, deterministic
+const scatterY = Math.sin(a) * RADIUS;
+const scatterZ = Z_NEAR - (i / (n - 1)) * (Z_NEAR - Z_FAR); // stepped depth across the cloud
+const rotX = Math.sin(a) * TUMBLE; // tumble orientation, also from the angle
+const rotY = Math.cos(a) * TUMBLE;
+```
+
+A single 0→1 `progress` proxy interpolates each element between scattered and assembled (lerp every channel). At `progress = 0` the elements form the depth-cloud; at `progress = 1` they sit flat in the layout. Run it forward and it's **assemble**; the cloud itself slowly rotates (a stage `rotateY` tween) so the scatter has life before it locks.
+
+Requires `perspective` on the stage and `transform-style: preserve-3d` on the stage AND each element, or the z-depth and tumble flatten to a 2D scale.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="assemble-scene"
+  data-composition-id="assemble-scene"
+  data-start="0"
+  data-duration="4"
+  data-track-index="0"
+>
+  <!-- The cloud rotates; the layout lives inside it. targetX/Y = each
+       element's FLAT assembled offset from stage center (px). -->
+  <div class="cloud-stage">
+    <div class="frag" data-target-x="-260" data-target-y="0">{glyph1}</div>
+    <div class="frag" data-target-x="-130" data-target-y="0">{glyph2}</div>
+    <div class="frag" data-target-x="0" data-target-y="0">{glyph3}</div>
+    <div class="frag" data-target-x="130" data-target-y="0">{glyph4}</div>
+    <div class="frag" data-target-x="260" data-target-y="0">{glyph5}</div>
+  </div>
+</div>
+```
+
+For a logo lockup, `targetX/Y` describe the parts' resting layout; for kinetic type, one `.frag` per glyph (inject spans from the phrase string at setup so width is exact — see Variations).
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+  perspective: 1400px; /* REQUIRED — without it, z-depth + tumble read as flat 2D scale */
+}
+.cloud-stage {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  transform-style: preserve-3d; /* REQUIRED — preserves child 3D context */
+  will-change: transform;
+}
+.frag {
+  position: absolute;
+  /* Live at stage center; GSAP translates each one to its layout / cloud point. */
+  top: 50%;
+  left: 50%;
+  display: grid;
+  place-items: center;
+  font-family: {font};
+  font-weight: 900;
+  font-size: 120px;
+  color: {textColor};
+  transform-style: preserve-3d; /* each fragment keeps its own 3D context */
+  backface-visibility: hidden; /* hides the mirrored face mid-tumble */
+  will-change: transform, opacity;
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  const frags = Array.from(document.querySelectorAll(".frag"));
+  const n = frags.length;
+  const GOLDEN = Math.PI * (3 - Math.sqrt(5)); // ~2.39943 — even spread, no clumps
+
+  // RADIUS, Z_NEAR, Z_FAR, TUMBLE, ASSEMBLE_DUR, ASSEMBLE_EASE, STAGGER,
+  // CLOUD_SPIN_DEG, CLOUD_SPIN_DUR — named constants per "How to Choose Values".
+
+  // Precompute each fragment's deterministic scattered state from its index.
+  const scatter = frags.map((el, i) => {
+    const a = i * GOLDEN;
+    const depthT = n > 1 ? i / (n - 1) : 0;
+    return {
+      x: Math.cos(a) * RADIUS,
+      y: Math.sin(a) * RADIUS,
+      z: Z_NEAR - depthT * (Z_NEAR - Z_FAR),
+      rotationX: Math.sin(a) * TUMBLE,
+      rotationY: Math.cos(a) * TUMBLE,
+    };
+  });
+
+  // 1) Park every fragment in the cloud BEFORE any tween fires.
+  frags.forEach((el, i) => {
+    const s = scatter[i];
+    gsap.set(el, {
+      xPercent: -50,
+      yPercent: -50, // bake self-centering so x/y are offsets from stage center
+      x: s.x,
+      y: s.y,
+      z: s.z,
+      rotationX: s.rotationX,
+      rotationY: s.rotationY,
+      opacity: 0,
+    });
+  });
+
+  // 2) The cloud rotates so the scatter has life before / during assembly.
+  tl.to(
+    ".cloud-stage",
+    { rotationY: CLOUD_SPIN_DEG, duration: CLOUD_SPIN_DUR, ease: "power1.out" },
+    0,
+  );
+
+  // 3) ASSEMBLE — each fragment tweens from its cloud point to its flat target.
+  frags.forEach((el, i) => {
+    tl.to(
+      el,
+      {
+        x: Number(el.dataset.targetX),
+        y: Number(el.dataset.targetY),
+        z: 0,
+        rotationX: 0,
+        rotationY: 0,
+        opacity: 1,
+        duration: ASSEMBLE_DUR,
+        ease: ASSEMBLE_EASE, // out-ease — fragments fly in then settle
+      },
+      i * STAGGER, // index stagger reads as "cloud collapsing inward"
+    );
+  });
+
+  window.__timelines["assemble-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Tumble-swap (mid-shot hand-off between two phrases)
+
+The signature for `kinetic-type-beats` beat changes: one phrase's glyphs scatter **into** the cloud at the same moment the next phrase's glyphs assemble **out** of it — a 3D hand-off between two states, never an empty frame. Two glyph sets share the cloud; drive both with one shared 0→1 `progress` so they cross deterministically.
+
+```js
+// outgoing[] and incoming[] are two glyph arrays, each with precomputed scatter[] (above).
+const swap = { p: 0 };
+tl.to(
+  swap,
+  {
+    p: 1,
+    duration: SWAP_DUR,
+    ease: "power2.inOut",
+    onUpdate: () => {
+      const p = swap.p;
+      outgoing.forEach((el, i) => {
+        // 1 → 0: layout → cloud (scatters AWAY)
+        const s = outScatter[i];
+        const tx = Number(el.dataset.targetX);
+        const ty = Number(el.dataset.targetY);
+        el.style.opacity = String(1 - p);
+        el.style.transform =
+          `translate(-50%,-50%) translate3d(${tx + (s.x - tx) * p}px,${ty + (s.y - ty) * p}px,${s.z * p}px)` +
+          ` rotateX(${s.rotationX * p}deg) rotateY(${s.rotationY * p}deg)`;
+      });
+      incoming.forEach((el, i) => {
+        // 0 → 1: cloud → layout (assembles IN)
+        const s = inScatter[i];
+        const tx = Number(el.dataset.targetX);
+        const ty = Number(el.dataset.targetY);
+        el.style.opacity = String(p);
+        el.style.transform =
+          `translate(-50%,-50%) translate3d(${s.x + (tx - s.x) * p}px,${s.y + (ty - s.y) * p}px,${s.z * (1 - p)}px)` +
+          ` rotateX(${s.rotationX * (1 - p)}deg) rotateY(${s.rotationY * (1 - p)}deg)`;
+      });
+    },
+  },
+  SWAP_AT,
+);
+```
+
+Inject a per-glyph span set for each phrase at setup (so `targetX` per glyph is the exact laid-out advance width — measure after `document.fonts.ready`), and hide each set's opacity to 0 until its window.
+
+### Radial letter-explode → resolve
+
+A flat-plane special case (the `kinetic-type-beats` "letters explode radially then resolve" GAP): set `Z_NEAR = Z_FAR = 0` and `TUMBLE` small so the cloud is a 2D ring, then reverse the assemble for the explode — fragments fling out to `scatter[i]` then snap back to layout. Pure in-plane, no depth.
+
+### Scatter-OUT (final-frame exit only)
+
+Reverse the assemble (layout → cloud, opacity 1→0) ONLY as the composition's last beat. A scatter-out mid-shot reads as an exit and breaks the shot — keep entrances and hand-offs as assemble or tumble-swap.
+
+### Parallax depth slide-in (logo lockup)
+
+For `logo-assemble-lockup`, give back layers a larger `|Z_FAR|` and a longer `ASSEMBLE_DUR`, foreground parts a shallower depth and shorter duration — parts at different depths slide in at different apparent speeds (parallax) and lock into the lockup.
+
+## How to Choose Values
+
+- **n (ELEMENT_COUNT)** — fragments / glyphs in the cloud
+  - Range: 4–14 (glyph sets follow the word length; for fragments/cards stay 4–9)
+  - Effects: few reads as deliberate assembly; many reads as a dense swarm condensing
+  - Constraints: above ~14 the cloud crowds the center and individual paths stop reading
+
+- **RADIUS** — cloud spread in the x/y plane, px
+  - Range: 250–700 px
+  - Effects: small = a tight knot that barely separates; large = fragments arrive from the frame edges
+  - Constraints: keep the farthest scatter inside frame at the chosen `perspective`, or fragments pop in from off-screen with no travel read
+
+- **Z_NEAR / Z_FAR** — depth band of the cloud, px (front / back)
+  - Range: Z_NEAR +150 to +450; Z_FAR −150 to −500
+  - Effects: a wide band (e.g. +400 / −400) gives strong fly-toward / recede-from camera depth; a narrow band keeps it nearly flat
+  - Constraints: very large `|z|` against a short `perspective` over-distorts (fragments smear huge then tiny) — widen `perspective` to match
+
+- **TUMBLE** — peak rotateX/rotateY of scattered fragments, deg
+  - Range: 40–110°
+  - Effects: low = fragments drift in nearly upright; high = they tumble through space and rotate upright on arrival
+  - Constraints: with `backface-visibility: hidden`, glyphs past 90° show blank mid-tween (intended for the tumble); for cards with content on one face, cap near 80°
+
+- **ASSEMBLE_DUR** — per-fragment cloud → layout tween, s
+  - Range: 0.7–1.4 s
+  - Effects: short = snappy lock-in; long = a floating condense
+  - Constraints: `(n − 1) × STAGGER + ASSEMBLE_DUR` must fit the scene's assembly window
+
+- **ASSEMBLE_EASE** — shared ease across fragments
+  - Discrete choice: `power3.out`, `expo.out`, `back.out(1.4)`
+  - Selection: `power3.out` default (fly in, settle). `expo.out` snaps hard at the end. `back.out` adds a small overshoot as parts seat. Avoid `in` easings — fragments look sucked backward into the cloud mid-air.
+
+- **STAGGER** — gap between successive fragments' assembly starts, s
+  - Range: 0.03–0.09 s
+  - Effects: < 0.03 = a single chord (whole cloud collapses at once); > 0.09 = a slow drip that loses the "swarm" read
+  - Constraints: `n × STAGGER` should stay below `ASSEMBLE_DUR` so the cloud is collapsing as one motion, not a queue
+
+- **CLOUD_SPIN_DEG / CLOUD_SPIN_DUR** — stage rotateY over the assembly, deg / s
+  - Range: 15–60° over a duration ≥ `ASSEMBLE_DUR`
+  - Effects: a gentle spin gives the scatter life so it doesn't read as a frozen explosion diagram; too fast competes with the assembly
+  - Constraints: keep finite and ending by settle — no `repeat`
+
+- **SWAP_DUR / SWAP_AT** (tumble-swap) — hand-off length / when it fires, s
+  - Range: SWAP_DUR 0.5–1.0 s; SWAP_AT on the beat boundary
+  - Effects: shorter = a hard cross; longer = a visible dissolve-through-cloud
+  - Constraints: outgoing and incoming MUST share one `progress` (one tween) so they cross at the same instant
+
+## Key Principles
+
+- **`perspective` on the scene root + `preserve-3d` on stage AND each fragment** — without all three, z-depth and tumble collapse to a flat scale
+- **Every scattered value is index-derived** — `cos/sin(i × GOLDEN)`, stepped `z` by `i/(n−1)`. The golden angle spreads points evenly with no clumps and (critically) **no `Math.random`**, so the cloud is byte-identical every render
+- **`gsap.set` the cloud BEFORE adding tweens** — park each fragment at its scatter point with `opacity: 0` first; the assemble tweens FROM there. Skipping the set leaves frame 0 showing the assembled layout, then a teleport when the first tween starts
+- **Resolve flat** — the settled state is `z: 0, rotationX: 0, rotationY: 0` in the layout. A cloud that resolves still-tilted reads as unfinished
+- **Assemble / hand-off only; scatter-OUT is an exit** — fragments leaving for the cloud mid-shot reads as the shot ending. Use forward assemble for entrances, tumble-swap for beat changes; reserve scatter-out for the final frame
+- **Depth ordering is automatic** — inside `preserve-3d`, paint order follows actual Z, so nearer fragments correctly occlude farther ones with no manual z-index (unlike the orbit case, where the orbit is faked in 2D and needs capped z-index)
+
+## Critical Constraints
+
+- **No `Math.random` / `Date.now`** — derive every scatter coordinate from the index (golden-angle trig + stepped depth). This is the whole point of the rule: a randomized cloud renders differently each frame and the seek breaks
+- **No CSS `transition`** — all motion is GSAP tweens on the paused timeline
+- **No `repeat` / `yoyo` / infinite** — the cloud spin and every assemble are finite, one-shot tweens that end before settle
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **Transform aliases only** — `x`, `y`, `z`, `scale`, `rotation`/`rotationX`/`rotationY`. Never `width`/`height`/`left`/`top`; `x`/`y` compose with the `xPercent/yPercent -50` self-centering
+- **`will-change: transform`** on stage + fragments — many simultaneous 3D transforms benefit from compositor hints
+- **In tumble-swap, one shared `progress` for both glyph sets** — two separate tweens can drift out of phase under seek and the cross stops looking like a single hand-off
+
+## Combinations
+
+- [orbit-3d-entry.md](orbit-3d-entry.md) — alternative 3D entrance (settles into a continuous orbit instead of a flat lockup); shares the `perspective` + `preserve-3d` stage setup
+- [hacker-flip-3d.md](hacker-flip-3d.md) — per-glyph 3D flip/decode as the fragments seat; layer for a "letters tumble in AND decode on arrival" read
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — give the assembled wordmark a stacked extrusion once it locks
+- [center-outward-expansion.md](center-outward-expansion.md) — flat 2D cousin (single shared center, no depth) when perspective isn't wanted
+- [press-release-spring.md](press-release-spring.md) — a spring settle on the assembled lockup once the cloud resolves
+- [sine-wave-loop.md](sine-wave-loop.md) — idle breathe on the resolved layout instead of a frozen hold
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + `onUpdate` API (the shared-progress tumble-swap)
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`