freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.2

package/dist/assets/design/skills/hyperframes-animation/rules/depth-of-field-blur.md

@@ -0,0 +1,112 @@
+---
+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. `filter` and `opacity` are paint-only, so both tween seek-safe. This is the backing rule for the focus-falloff beat the blueprints reach for: outer nodes blurring during a push-in (`constellation-hub`), rack-focus across a parallax card stack (`cursor-ui-demo`), non-highlighted cards dimming to spotlight a hero metric (`dataviz-countup`).
+
+## How It Works
+
+Every layer carries a `--dof` custom property (px of blur), read by `filter: blur(var(--dof))`, plus its own `opacity`. A 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 `--dof` stays `0`. Per-layer targets derive from `data-depth` / index, so the falloff is identical on every seek.
+
+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: plane A's blur ramps 0 → max at the same position plane B's ramps max → 0. State continuity matters exactly as in `press-release-spring`: A's resting blur after the rack must equal what B held before it — author both as tweens on the same `--dof` at the same position so the hand-off is seamless.
+3. **Blur-the-cluster-while-pushing-in** — the DoF tween runs at the SAME timeline position as a camera push-in (`multi-phase-camera` / `coordinate-target-zoom`): "the world recedes" and "we push in" read as one move.
+
+## Recipe
+
+```html
+<div class="world" id="world">
+  <!-- Focal layer — stays sharp -->
+  <div class="layer focal" id="focal">{FocalLabel}</div>
+  <!-- Off-focus layers — blur + dim; data-depth orders near→far -->
+  <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>
+```
+
+```css
+.world {
+  /* single wrapper so a concurrent camera push-in transforms everything
+     together; DoF is independent of the camera */
+  position: relative;
+  width: 100%;
+  height: 100%;
+  transform-origin: 50% 50%;
+}
+.layer {
+  --dof: 0px; /* px of blur; filter reads it — starts sharp */
+  filter: blur(var(--dof));
+  will-change: filter; /* promotes the layer so per-frame re-rasterization is cheap */
+}
+.focal {
+  z-index: 2; /* sharp layer must sit ABOVE the blurred ones, or its crisp
+     edges read as bleeding into the haze */
+}
+.ctx {
+  z-index: 1;
+}
+```
+
+```js
+// Mechanic 1 — FOCAL PULL. Blur scales with data-depth so far planes blur
+// more than near ones; the focal layer (--dof: 0, opacity: 1) is untouched.
+gsap.utils.toArray(".ctx").forEach((el) => {
+  const depth = Number(el.dataset.depth) || 1;
+  tl.to(
+    el,
+    {
+      "--dof": `${BLUR_PER_DEPTH * depth}px`,
+      opacity: DIM_LEVEL, // dim, not gone
+      duration: FOCUS_DUR,
+      ease: "power2.inOut",
+    },
+    FOCUS_START,
+  );
+});
+```
+
+## Variations
+
+- **Rack focus between two depth planes** — `gsap.set` plane B pre-blurred BEFORE the rack (no pop), then two tweens sharing `RACK_START` + `RACK_DUR`: A → `MAX_BLUR` + `DIM_LEVEL`, B → `0px` + `1`. Shared window makes them cross at the midpoint.
+- **Blur the cluster while pushing in** — run the focal-pull tweens at the same position + duration as a camera tween on `#world` (`scale/x/y`, `power2.inOut`). Camera transforms the world; DoF tweens the layers — independent property channels, no conflict.
+- **Spotlight a hero metric in a card grid** — `gsap.utils.toArray(".card:not(.hero)")` all defocus (`GRID_BLUR` + `DIM_LEVEL`) on one shared window; heroes are skipped.
+- **Refocus / settle** — if the beat resolves back to "everything visible" (or hands off to a crossfade needing a clean outgoing frame), ramp all `--dof` back to `0px` / opacity 1 over the tail (`REFOCUS_START + REFOCUS_DUR ≤ DURATION`).
+- **Bounded focus-breathing on the focal layer (optional)** — a finite `ease:"none"` driver writes `Math.max(0, Math.sin(p)) * FOCAL_BREATH_PX` into the focal `--dof` during a hold. Keep it ≤ ~0.6px or it reads as "still focusing"; default to omitting it.
+
+## Values
+
+| token                 | range                                  | notes                                                                                                    |
+| --------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| BLUR_PER_DEPTH        | 3–6 px per depth step                  | a 3-plane stack tops out ~9–18 px; low = gentle DoF, high = tilt-shift falloff                           |
+| MAX_BLUR              | 8 soft → 16 default → 24 heavy px      | terminal blur for a fully-defocused plane; above ~24 px on a big surface, shrink/group the layer instead |
+| GRID_BLUR             | 6–12 px                                | pushes cards back without losing the grid's shape                                                        |
+| DIM_LEVEL             | 0.4 strong → 0.55 default → 0.7 subtle | rarely below 0.35 — fully dark reads as "removed," not "defocused"                                       |
+| FOCUS_DUR             | 0.5–1.2 s                              | a rack/pull is a deliberate move, not a snap; shorter = snap focus, longer = languid                     |
+| RACK_START / RACK_DUR | shared by both planes                  | `gsap.set` the pre-blurred plane BEFORE `RACK_START`                                                     |
+| FOCAL_BREATH_PX       | ≤ 0.6 px, period 2–3 s                 | barely-there nicety                                                                                      |
+| FOCAL vs CTX sizing   | context smaller / grouped              | small context layers let a modest radius still read as "out of focus" — and blur cheaply                 |
+
+Tokens: dark `{bgGradient}` so the sharp focal layer reads as lit and forward; heavy display `{font}` weight — blurred copy needs it to stay shape-legible.
+
+## Critical Constraints
+
+- **Tween the `--dof` variable on the timeline** — reading `filter: blur(var(--dof))` keeps the blur on the HF seek clock.
+- **Blur the SMALL / GROUPED layers, not the giant one.** Filter cost scales with radius × pixel area; a 20 px blur on a full-frame background is the worst case. Keep per-layer radius ≤ ~24 px on large surfaces and lean on the `opacity` **dim** to do the push-back work — dim + modest blur reads more like real DoF than blur cranked to the max.
+- **`will-change: filter`** on every layer whose blur animates (drop it after settle if the layer also does heavy transform work).
+- **Focal layer stays genuinely sharp** — `--dof: 0`, untouched (or breathing ≤ 0.6 px). Any visible blur on the focal element kills the "this is the thing" read.
+- **State continuity on a rack** — the outgoing plane starts at the blur the incoming plane was holding, and vice-versa; adjacent tweens on the same `--dof` at the same position.
+- **DoF is independent of the camera** — blur the layers, transform `.world` for the push-in; don't fake DoF with the camera transform or vice-versa.
+- **Settle sharp before a hand-off** — refocus to `--dof: 0` in the tail if the next beat is a crossfade/push; handing off mid-defocus reads as "the render glitched."
+- **Sharp focal layer above blurred layers** (`z-index`).
+
+## See also
+
+[multi-phase-camera.md](multi-phase-camera.md) (the push-in this rule's falloff accompanies) · [coordinate-target-zoom.md](coordinate-target-zoom.md) (zoom onto the focal core — the `constellation-hub` hook) · [viewport-change.md](viewport-change.md) (pan + rack across a tilted card plane) · [counting-dynamic-scale.md](counting-dynamic-scale.md) (hero metric counts up sharp — the `dataviz-countup` spotlight) · [3d-page-scroll.md](3d-page-scroll.md) (the parallax stack to rack between) · [sine-wave-loop.md](sine-wave-loop.md) (post-rack idle; keep both amplitudes tiny).

package/dist/assets/design/skills/hyperframes-animation/rules/depth-scatter-assemble.md

@@ -0,0 +1,139 @@
+---
+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, logo fragments) fly in from a rotating 3D depth-cloud and lock into a flat layout — or the reverse. Each element has its OWN index-derived point in the cloud (translateZ depth + rotateX/Y tumble + x/y scatter). Distinct from `orbit-3d-entry` (flip-in then continuous orbit) and `center-outward-expansion` (flat burst from one shared center): here the resolve is a flat assembled layout.
+
+## How It Works
+
+Each element's flat target lives in `data-target-x/y`; its scattered state is pure trig on its index — golden-angle spread, stepped depth — so the cloud is byte-identical every render with no `Math.random`:
+
+```js
+const GOLDEN = Math.PI * (3 - Math.sqrt(5)); // ~2.39943 rad — even spread, no clumping
+const a = i * GOLDEN;
+const scatterX = Math.cos(a) * RADIUS;
+const scatterY = Math.sin(a) * RADIUS;
+const scatterZ = Z_NEAR - (i / (n - 1)) * (Z_NEAR - Z_FAR); // stepped depth
+const rotX = Math.sin(a) * TUMBLE;
+const rotY = Math.cos(a) * TUMBLE;
+```
+
+Elements are PARKED at their scatter points (`gsap.set`, opacity 0) before any tween, then each tweens to its flat target while the whole stage slowly rotates so the scatter has life before it locks. Requires `perspective` on the scene root and `preserve-3d` on the stage AND each element, or depth + tumble flatten to a 2D scale.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<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>
+  <!-- … one .frag per glyph / fragment … -->
+</div>
+```
+
+```css
+.scene-root {
+  display: grid;
+  place-items: center;
+  perspective: 1400px; /* REQUIRED */
+}
+.cloud-stage {
+  position: relative;
+  display: grid;
+  place-items: center;
+  transform-style: preserve-3d;
+  will-change: transform;
+}
+.frag {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform-style: preserve-3d;
+  backface-visibility: hidden; /* hides the mirrored face mid-tumble */
+  will-change: transform, opacity;
+}
+```
+
+```js
+const frags = Array.from(document.querySelectorAll(".frag"));
+const n = frags.length;
+const GOLDEN = Math.PI * (3 - Math.sqrt(5));
+
+// 1) Park every fragment in the cloud BEFORE any tween fires
+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,
+  };
+});
+frags.forEach((el, i) => gsap.set(el, { xPercent: -50, yPercent: -50, ...scatter[i], opacity: 0 }));
+
+// 2) The cloud rotates so the scatter has life during assembly
+tl.to(
+  ".cloud-stage",
+  { rotationY: CLOUD_SPIN_DEG, duration: CLOUD_SPIN_DUR, ease: "power1.out" },
+  0,
+);
+
+// 3) ASSEMBLE — cloud point → flat target, index stagger = cloud collapsing inward
+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,
+    },
+    i * STAGGER,
+  );
+});
+```
+
+## Variations
+
+- **Tumble-swap** (the beat-change hand-off): two glyph sets share the cloud; ONE shared 0→1 progress tween drives both in its `onUpdate` — outgoing lerps layout→cloud with `opacity: 1−p`, incoming lerps cloud→layout with `opacity: p`. Two separate tweens drift out of phase under seek and the cross stops reading as one hand-off. Inject per-glyph spans per phrase at setup (measure advance widths after `document.fonts.ready` — single-scene only).
+- **Radial letter-explode → resolve**: flat-plane special case — `Z_NEAR = Z_FAR = 0`, small `TUMBLE`; reverse the assemble for the explode. Pure in-plane.
+- **Scatter-OUT**: reverse assemble (layout → cloud, opacity 1→0) ONLY as the composition's final beat — mid-shot it reads as the shot ending.
+- **Parallax lockup**: back layers get deeper `|Z_FAR|` + longer `ASSEMBLE_DUR`, foreground shallower/shorter — depth-speeded slide-in that locks into the logo.
+
+## Values
+
+| token                  | range                 | notes                                                                         |
+| ---------------------- | --------------------- | ----------------------------------------------------------------------------- |
+| n                      | 4–14 (fragments 4–9)  | above ~14 individual paths stop reading                                       |
+| RADIUS                 | 250–700px             | keep the farthest scatter in frame or fragments pop in with no travel         |
+| Z_NEAR / Z_FAR         | +150…+450 / −150…−500 | large `\|z\|` needs a wider `perspective` or fragments smear                  |
+| TUMBLE                 | 40–110°               | past 90° glyphs show blank mid-tween (intended); cap ~80° for one-faced cards |
+| ASSEMBLE_DUR           | 0.7–1.4s              |                                                                               |
+| ASSEMBLE_EASE          | `power3.out` default  | `expo.out` snaps, `back.out(1.4)` seats with overshoot; never `in`            |
+| STAGGER                | 0.03–0.09s            | `n × STAGGER < ASSEMBLE_DUR` — one collapsing motion, not a queue             |
+| CLOUD_SPIN_DEG / \_DUR | 15–60° over ≥ dur     | gentle life; too fast competes with the assembly                              |
+| SWAP_DUR               | 0.5–1.0s              | on the beat boundary; shorter = hard cross                                    |
+
+## Critical Constraints
+
+- **Every scattered value is index-derived** — `cos/sin(i × GOLDEN)` + stepped `z`. The golden angle spreads points evenly with no clumps and no `Math.random`.
+- **`gsap.set` the cloud BEFORE adding tweens** — skipping it leaves frame 0 showing the assembled layout, then a teleport when the first tween starts.
+- **`perspective` + `preserve-3d` on stage AND each fragment** — missing any one flattens the depth.
+- **Resolve flat** — settled state is `z: 0`, rotations 0; a still-tilted resolve reads unfinished.
+- **Tumble-swap: one shared progress for both glyph sets.**
+- **Depth ordering is automatic** inside `preserve-3d` (paint order follows actual Z) — no manual z-index, unlike the orbit case's capped band.
+
+## See also
+
+`orbit-3d-entry` (settles into a continuous orbit instead) · `hacker-flip-3d` (glyphs decode on arrival) · `3d-text-depth-layers` (extrude the locked wordmark) · `center-outward-expansion` (flat 2D cousin) · `sine-wave-loop` (idle breathe on the resolved layout).

package/dist/assets/design/skills/hyperframes-animation/rules/discrete-text-sequence.md

@@ -0,0 +1,146 @@
+---
+name: discrete-text-sequence
+description: Replace entire text states at frame thresholds for non-linear typing effects — typos, bulk additions, pauses, backspaces, simulated thinking.
+metadata:
+  tags: text, typing, discrete, threshold, non-linear, sequence
+---
+
+# Discrete Text Sequence
+
+Instead of character-by-character typewriter, replace entire string states at time thresholds — enabling non-linear effects (typos, backspaces, bulk paste, "thinking" gaps) that smooth per-char typing can't achieve. If your effect is "type each character, no edits", this rule is overkill — use the smooth-slice variation below.
+
+## How It Works
+
+The typing is authored as a sparse array of `{ t, text }` states; on every `onUpdate` a **reverse search** finds the latest entry whose `t` has passed and renders its text. Display jumps between states with no animation between them — the realism comes from the schedule shape: fast keystroke clusters (0.06–0.20s apart), pauses at word breaks (0.3–0.6s), a typo, backspaces peeling back to the fork, then a bulk paste replacing many chars in one entry. A block cursor blinks via a deterministic sin square wave on the same timeline.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="terminal">
+  <div class="prompt">$</div>
+  <div class="text-wrap">
+    <span class="text" id="text"></span><span class="cursor" id="cursor">_</span>
+  </div>
+</div>
+```
+
+```css
+.terminal {
+  font-family: {monoFont}; /* monospace required — proportional jitters even in a fixed box */
+  display: flex;
+  align-items: baseline;
+  font-size: TERMINAL_FONT_SIZE;
+}
+.text-wrap {
+  display: inline-flex;
+  align-items: baseline;
+  min-width: TEXT_WRAP_MIN_WIDTH; /* ≥ widest state — stops right-edge jitter */
+  white-space: nowrap;
+}
+.cursor {
+  display: inline-block; /* inline ignores width */
+  width: CURSOR_WIDTH;
+}
+```
+
+```js
+// Each entry shows from its t until the NEXT entry's t.
+// Shape: keystrokes → typo → backspace to the fork → bulk paste → completion mark.
+const SEQUENCE = [
+  { t: 0.0, text: "" },
+  { t: T_K1, text: "{p1}" }, // first keystrokes (~3-5 chars, 0.1-0.2s apart)
+  { t: T_K2, text: "{p1 + ' ' + p2_typo}" }, // continuation containing a typo
+  { t: T_BS, text: "{p1 + ' ' + p2_partial}" }, // backspace(s) — peel back to the fork
+  { t: T_BULK, text: "{fullCorrectedText}" }, // bulk paste — many chars in one jump
+  { t: T_DONE, text: "{fullCorrectedText + ' ✓'}" }, // completion marker
+];
+
+// Reverse-search for the latest entry whose t has passed
+function textAt(time) {
+  for (let i = SEQUENCE.length - 1; i >= 0; i--) {
+    if (time >= SEQUENCE[i].t) return SEQUENCE[i].text;
+  }
+  return "";
+}
+
+const textEl = document.getElementById("text");
+const cursorEl = document.getElementById("cursor");
+
+const driver = { t: 0 };
+tl.to(
+  driver,
+  {
+    t: TOTAL_DURATION,
+    duration: TOTAL_DURATION,
+    ease: "none",
+    onUpdate: () => {
+      textEl.textContent = textAt(driver.t);
+    },
+  },
+  0,
+);
+
+// Cursor blink — deterministic sin square wave, never a CSS animation
+const blink = { p: 0 };
+tl.to(
+  blink,
+  {
+    p: Math.PI * 2 * BLINK_CYCLES,
+    duration: TOTAL_DURATION,
+    ease: "none",
+    onUpdate: () => {
+      cursorEl.style.opacity = Math.sin(blink.p) > 0 ? "1" : "0";
+    },
+  },
+  0,
+);
+```
+
+## Variations
+
+- **Smooth character slice** (continuous typewriter — no pauses, no edits): faster to author but uniformly "machine-typed", missing the human realism:
+
+```js
+const fullText = "{fullPhrase}";
+const len = { v: 0 };
+tl.to(
+  len,
+  {
+    v: fullText.length,
+    duration: TYPE_DUR,
+    ease: "power1.inOut",
+    onUpdate: () => {
+      textEl.textContent = fullText.substring(0, Math.floor(len.v));
+    },
+  },
+  0,
+);
+```
+
+- **Thinking pause** — hold one state for `THINK_HOLD_DUR` (0.8–2.0s; under 0.5s reads as a stutter, not thought) simply by leaving a gap before the next entry's `t`.
+- **State pulse on completion** — when the final state lands, `tl.to(".text", { scale: 1.03–1.08, duration: 0.15–0.3, yoyo: true, repeat: 1 }, T_DONE)`.
+- **Per-state color shift** — in `onUpdate`, branch on `driver.t` vs the milestones: success color after `T_DONE`, dim mid-edit, normal while typing.
+
+## Values
+
+| token               | range                                        | notes                                                                  |
+| ------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| TERMINAL_FONT_SIZE  | 48–96px                                      | full-bleed comps; smaller for terminal-style detail                    |
+| TEXT_WRAP_MIN_WIDTH | ≥ widest state                               | measure with a hidden probe after `document.fonts.ready` if unsure     |
+| milestone `t`s      | keystrokes 0.06–0.20s apart; pauses 0.3–0.6s | monotonically increasing; `T_DONE ≤ TOTAL_DURATION − ~1s` climax dwell |
+| TYPE_DUR (smooth)   | `chars × 0.06–0.12s`                         | fast → relaxed                                                         |
+| BLINK_CYCLES        | one cycle per 0.5–0.8s                       | `TOTAL_DURATION / 0.8 ≤ BLINK_CYCLES ≤ TOTAL_DURATION / 0.5`           |
+| CURSOR_WIDTH        | ~0.3× font size                              | gap to text single-digit px so the cursor feels attached               |
+
+## Critical Constraints
+
+- **Reverse-search the array each frame** — O(n) with small n (≤30 typical); don't index by frame, the sequence is sparse.
+- **`min-width` on the text wrap is mandatory** — without it the right edge jitters as state length changes.
+- **Discrete jumps must be INSTANT** — any transition on the text turns the jump into a smear and kills the "typing" feel.
+- **Cursor blink is sin/sequence-driven on the timeline**, `display: inline-block`, monospace font, `white-space: nowrap` (wrapping mid-state breaks the illusion; trailing spaces must survive).
+- **Discrete vs smooth** — use discrete only for non-linear states (typos, pauses, bulk paste); plain typing takes the smooth-slice variation.
+
+## See also
+
+`context-sensitive-cursor` (same SEQUENCE pattern + segment-colored cursor) · `3d-text-depth-layers` (discrete text with layered depth) · `counting-dynamic-scale` (discrete label beside a smooth counter) · `press-release-spring` (post-completion press beat).

package/dist/assets/design/skills/hyperframes-animation/rules/dynamic-content-sequencing.md

@@ -0,0 +1,149 @@
+---
+name: dynamic-content-sequencing
+description: Auto-calculate timeline start/end times from content length + per-item duration config — longer content gets more screen time without hardcoded numbers.
+metadata:
+  tags: timeline, sequencing, dynamic, duration, content-aware, utility
+---
+
+# Dynamic Content Sequencing
+
+A utility pattern (not a motion rule in itself) for scenes that show a SEQUENCE of items (cards, phrases, stats): each item's duration is computed from its content length + per-item config, and the sequencer assigns absolute start/end times automatically — no hardcoded offsets per item. Distinct from [discrete-text-sequence](discrete-text-sequence.md) (one text element changing states) — this rule swaps between distinct content blocks.
+
+## How It Works
+
+A content array of `{ eyebrow, title, body, speedFactor, hold }` entries is reduced once at build time into a flat `TIMELINE` of `{ …entry, start, end }` — duration per entry is `BASE_DURATION + body.length × SEC_PER_CHAR + hold`, so longer text earns more reading time. A single linear driver's `onUpdate` reverse-searches the active entry and swaps the DOM **only on transitions** (a `lastTitle` guard — per-frame `textContent` writes flicker in render); an optional progress bar fills 0→100% across the whole run.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="display">
+  <div class="eyebrow" id="eyebrow"></div>
+  <div class="title" id="title"></div>
+  <div class="body" id="body"></div>
+  <div class="progress-bar"><div class="progress-fill" id="progress-fill"></div></div>
+</div>
+```
+
+```css
+.body {
+  min-height: 160px; /* reserve space — content height varies; without this, layout jumps */
+}
+.progress-fill {
+  height: 100%;
+  width: 0%;
+}
+```
+
+```js
+// N entries, each with its own pacing (optionally a speedFactor multiplier);
+// the final entry uses a larger hold (closing beat).
+const CONTENT = [
+  { eyebrow: "{eyebrow1}", title: "{title1}", body: "{body1}", hold: HOLD_MID },
+  // …
+  { eyebrow: "{eyebrowN}", title: "{titleN}", body: "{bodyN}", hold: HOLD_FINAL },
+];
+
+// Pre-compute absolute start/end ONCE — never in onUpdate.
+let cumulative = 0;
+const TIMELINE = CONTENT.map((entry) => {
+  const dur = BASE_DURATION + entry.body.length * SEC_PER_CHAR + entry.hold;
+  const start = cumulative;
+  cumulative += dur;
+  return { ...entry, start, end: cumulative };
+});
+
+function entryAt(time) {
+  for (let i = TIMELINE.length - 1; i >= 0; i--) {
+    if (time >= TIMELINE[i].start) return TIMELINE[i];
+  }
+  return TIMELINE[0];
+}
+
+const eyebrowEl = document.getElementById("eyebrow");
+const titleEl = document.getElementById("title");
+const bodyEl = document.getElementById("body");
+const progressEl = document.getElementById("progress-fill");
+
+const TOTAL_DURATION = cumulative + TAIL_PAD;
+const driver = { t: 0 };
+let lastTitle = "";
+
+tl.to(
+  driver,
+  {
+    t: TOTAL_DURATION,
+    duration: TOTAL_DURATION,
+    ease: "none",
+    onUpdate: () => {
+      const entry = entryAt(driver.t);
+      // Swap content only on transitions — no per-frame DOM thrash
+      if (entry.title !== lastTitle) {
+        eyebrowEl.textContent = entry.eyebrow;
+        titleEl.textContent = entry.title;
+        bodyEl.textContent = entry.body;
+        lastTitle = entry.title;
+      }
+      progressEl.style.width = `${(driver.t / TOTAL_DURATION) * 100}%`;
+    },
+  },
+  0,
+);
+```
+
+## Variations
+
+- **Crossfade between items** — return BOTH adjacent entries during an overlap window (`time ≥ e.start − overlap && time ≤ e.end + overlap`, overlap ≈ 0.3s) and render them with opacities computed from distance to the boundary.
+- **Per-item motion variation** — map an `entry.style` key to an existing rule per chapter (e.g. `3d-text-depth-layers` → `hacker-flip-3d` → `counting-dynamic-scale`); the sequencer only orchestrates timing.
+- **Auto-extend composition duration** — you can set `data-duration` from the computed `TOTAL_DURATION` in script, but HF reads `data-duration` at composition load and setting it after init may not take effect — author the duration manually from a rough total.
+
+### Accelerating cadence (geometric hold decay)
+
+For rhetorical escalation — "everyone says…", a roll-call, a praise flurry — the beat grid itself accelerates: early entries hold ~1s (read speed), then windows shrink geometrically into a ~0.15–0.3s flurry, braking on an emphasis state before the resolve. The acceleration is pre-computed into the same flat `TIMELINE` — still content-driven, still deterministic, no speed-up tween anywhere:
+
+```js
+// Geometric decay on the hold, clamped at a flurry floor; the brake state holds longest.
+const HOLDS = CONTENT.map((entry, i) => Math.max(FLURRY_FLOOR, HOLD_START * Math.pow(DECAY, i)));
+HOLDS[CONTENT.length - 1] = HOLD_FINAL;
+
+let cumulative = 0;
+const TIMELINE = CONTENT.map((entry, i) => {
+  // Past ~0.5s states are glanced as motion texture, not read —
+  // drop the per-char term or you never reach flurry speed.
+  const readable = HOLDS[i] >= READ_THRESHOLD;
+  const dur = HOLDS[i] + (readable ? entry.body.length * SEC_PER_CHAR : 0);
+  const start = cumulative;
+  cumulative += dur;
+  return { ...entry, start, end: cumulative };
+});
+```
+
+Worked example — **praise-chip flurry**: ~16 short quotes hard-cut through a chip beside a pinned wordmark. First 3 states at `HOLD_START = 1.0` (each reads fully); `DECAY = 0.8` shrinks every following window until `FLURRY_FLOOR = 0.2` catches it (≈12 states over ~2.5s — a churn of acclaim, individually glanced); the longest phrase takes `HOLD_FINAL ≈ 1.6` as the brake before the closing lockup.
+
+Values: `HOLD_START` 0.8–1.2s; `DECAY` 0.75–0.88 (higher = longer runway before the flurry bites); `FLURRY_FLOOR` 0.15–0.3s (below ~0.15s swaps strobe); `READ_THRESHOLD` ~0.5s; brake ≥ 4× the floor or the stop doesn't register as a beat. The 3–6 entry guidance relaxes here — 12–18 states are legal precisely because flurry states aren't individually read. The hard-cut discipline (`lastTitle` guard, instant swaps) is what lets 0.2s states render clean.
+
+## Values
+
+| token         | range                 | notes                                                                                                                 |
+| ------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| BASE_DURATION | 0.6–1.5s              | minimum per entry regardless of length — even one-word entries get read time                                          |
+| SEC_PER_CHAR  | 0.03–0.06 s/char      | ≈17–33 chars/sec; uniform across the sequence so the pace reads as one engine; lean high for wide-character languages |
+| HOLD_MID      | 0.5–1.0s              | dwell on a non-final entry; `< HOLD_FINAL`                                                                            |
+| HOLD_FINAL    | 1.0–2.0s              | climax dwell — must exceed HOLD_MID by a clear margin so the close reads as a beat                                    |
+| SPEED_FACTOR  | 0.5–2.0 (default 1.0) | per-entry only; if every entry shares a factor, fold it into SEC_PER_CHAR                                             |
+| TAIL_PAD      | 0.0–1.0s              | quiet beat after the last entry; prefer 0 when the next composition owns the breath                                   |
+| CONTENT N     | 3–6 entries           | <3 isn't a sequence; >6 drags (accelerating cadence relaxes this — see above)                                         |
+
+Reference: `../examples/messaging-multi-phrase.html`.
+
+## Critical Constraints
+
+- **Pre-compute the TIMELINE once at build** — never recompute in `onUpdate`; the reverse search over the flat array is the whole per-frame cost.
+- **DOM swap only on entry transition** (`lastTitle`/key guard) — per-frame `textContent` assignment flickers in HF render.
+- **`min-height` on the body element** — without reservation, downstream elements (progress bar, brand) jitter as content height varies.
+- **Sequential only** — for parallel tracks use a different reduction.
+- **Titles fit one line at the chosen size; bodies fit inside `min-height` after wrapping.**
+
+## See also
+
+`discrete-text-sequence` (per-entry typewriter on the body) · `context-sensitive-cursor` (cursor color per chapter) · `vertical-spring-ticker` (animated word swap instead of hard cut) · `scale-swap-transition` (visual morph between entries).