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

package/dist/assets/design/skills/hyperframes-animation/rules/avatar-cloud-network.md

@@ -0,0 +1,145 @@
+---
+name: avatar-cloud-network
+description: Avatars distributed on an elliptical ring connected by SVG dashed lines to a center hub — social proof "community" reveal with staggered entry.
+metadata:
+  tags: avatar, cloud, network, social-proof, ellipse, connection, stagger
+---
+
+# Avatar Cloud Network
+
+Avatars on an elliptical ring around a central hub (logo / counter), with SVG dashed lines drawing outward from the hub to each avatar — "community" / social proof. Distinct from [orbit-3d-entry.md](orbit-3d-entry.md) (continuous orbit): this settles into a static composed formation.
+
+## How It Works
+
+Three layers: SVG lines (z-index 1, behind), avatars (z-index 2), hub (z-index 5 — lines terminate AT its edge, never pass through). Avatar positions and lines are built once at setup from ONE shared center; the timeline then runs hub fade → avatar cascade → outward line draw → breathing dwell. Drawing FROM the center is the narrative: "the hub connects to its community."
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<svg class="lines" viewBox="0 0 1920 1080"><!-- lines injected --></svg>
+<div class="hub-wrap">
+  <div class="hub">{counterValue} {counterLabel}</div>
+  <!-- avatars injected -->
+</div>
+```
+
+```css
+.lines {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+}
+.hub-wrap {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+}
+.hub {
+  position: relative;
+  z-index: 5;
+}
+.avatar {
+  position: absolute;
+  z-index: 2;
+  transform: translate(-50%, -50%); /* centers on the (left, top) the script sets */
+  will-change: transform, opacity;
+}
+```
+
+```js
+// CENTER_X/Y must equal the hub's RENDERED center exactly — every avatar
+// position and line endpoint derives from it. For a place-items:center hub on
+// a 1920×1080 canvas: (W/2, H × CENTER_Y_FACTOR).
+const C = { x: CENTER_X, y: CENTER_Y };
+const wrap = document.querySelector(".hub-wrap");
+const svg = document.querySelector(".lines");
+
+for (let i = 0; i < AVATAR_COUNT; i++) {
+  const a = (i / AVATAR_COUNT) * Math.PI * 2 - Math.PI / 2; // start at top
+  const x = C.x + Math.cos(a) * RADIUS_X;
+  const y = C.y + Math.sin(a) * RADIUS_Y;
+
+  const av = document.createElement("div");
+  av.className = "avatar"; // assign image / glyph from authoring data
+  av.style.left = `${x}px`;
+  av.style.top = `${y}px`;
+  wrap.appendChild(av);
+
+  const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+  const attrs = {
+    x1: C.x,
+    y1: C.y,
+    x2: x,
+    y2: y,
+    stroke: "{lineColor}",
+    "stroke-dasharray": "6 8",
+  };
+  Object.entries(attrs).forEach(([k, v]) => line.setAttribute(k, String(v)));
+  const len = Math.hypot(x - C.x, y - C.y); // straight line — Math.hypot, not getTotalLength()
+  line.style.strokeDashoffset = String(len);
+  svg.appendChild(line);
+}
+
+tl.from(".hub", { opacity: 0, scale: 0.8, duration: HUB_DUR, ease: `back.out(${HUB_BOUNCE})` }, 0);
+
+const avatars = document.querySelectorAll(".avatar");
+avatars.forEach((av, i) => {
+  tl.from(
+    av,
+    { opacity: 0, scale: 0, duration: AVATAR_DUR, ease: `back.out(${AVATAR_BOUNCE})` },
+    AVATAR_AT + i * AVATAR_STAGGER,
+  );
+});
+svg.querySelectorAll("line").forEach((line, i) => {
+  tl.to(
+    line,
+    { strokeDashoffset: 0, duration: LINE_DUR, ease: "power2.out" },
+    LINES_AT + i * LINE_STAGGER,
+  );
+});
+
+// Climax dwell — out-of-phase breathing holds the eye on the formed network:
+// one phase proxy (0 → 2π·BREATH_CYCLES, ease "none"); onUpdate scales avatar i by
+// 1 + sin(p + (i/n)·2π) · BREATH_AMP — sine-wave-loop's multiplicative onUpdate form.
+// Keep the -50% centering in the same transform write.
+```
+
+## Variations
+
+- **Size variety**: vary avatar sizes by a small index-keyed array so the ring doesn't read rigidly repetitive.
+- **Solid lines**: drop the dash + draw; lines fade in via opacity — more corporate, less networky.
+- **Multi-orbit**: inner ring (fewer, larger) connected to the hub; outer ring is an unconnected "halo."
+- **Glyph avatars**: flags / emoji / icons instead of faces — reads "global community" or role spread.
+
+## Values
+
+| token          | range                        | notes                                                            |
+| -------------- | ---------------------------- | ---------------------------------------------------------------- |
+| AVATAR_COUNT   | 8–12                         | fewer feels sparse; more clutters the ellipse                    |
+| RADIUS_X / \_Y | ~20–30% W / ~18–25% H        | ratio X/Y 1.5–3.0 reads as perspective; 1 (circle) reads flat    |
+| avatar size    | 80–120px @1920               | ring must fit 10+ without overlap                                |
+| HUB_DUR        | 0.4–0.6s                     | HUB_BOUNCE 1.4–1.8                                               |
+| AVATAR_AT      | ≥ 0.6 × HUB_DUR              | hub established before satellites arrive                         |
+| AVATAR_DUR     | 0.4–0.7s                     | AVATAR_BOUNCE 1.4–1.8, slightly firmer than hub                  |
+| AVATAR_STAGGER | 0.06–0.10s                   | cascade reads "joining"; simultaneous reads "already there"      |
+| LINES_AT       | overlaps last avatar settle  | start ~0.1–0.2s before it — draw reads as consequence of landing |
+| LINE_DUR       | 0.4–0.7s                     | LINE_STAGGER 0.02–0.05s = a wave outward                         |
+| BREATH_CYCLES  | 1.0–2.0 over the remaining s | under 1 = single sigh; over 2 = anxious. BREATH_AMP 0.02–0.06    |
+
+Tokens: dark `{bgColor}` so the cloud reads as a constellation; translucent accent `{lineColor}`; soft border + glow keeps avatars legible on dark.
+
+## Critical Constraints
+
+- **CENTER_X/Y must match the hub's actual rendered center** — when composed with another scene (e.g. a recentered logo), bake them from the same source as the hub's final position, or lines visibly miss the hub.
+- **Hub z-index above lines** — lines terminate at the hub edge, never cross it.
+- **Lines draw outward** (dashoffset len → 0), starting after avatars are mostly settled.
+- **`RADIUS_X > RADIUS_Y`** — a horizontal ellipse reads as perspective; a circle reads flat.
+- **Climax dwell ≥ 1s** after lines complete so the formed network is readable.
+- Straight lines: `Math.hypot` for length — `getTotalLength()` not needed.
+
+## See also
+
+`counting-dynamic-scale` (the hub IS a growing counter) · `sine-wave-loop` (the breathing form) · `orbit-3d-entry` (the continuously-orbiting cousin).

package/dist/assets/design/skills/hyperframes-animation/rules/camera-cursor-tracking.md

@@ -0,0 +1,133 @@
+---
+name: camera-cursor-tracking
+description: Two-phase virtual camera that locks viewport to a moving focal point with configurable initial positioning.
+metadata:
+  tags: camera, tracking, viewport, two-phase, spring
+---
+
+# Two-Phase Camera Cursor Tracking
+
+Keeps a horizontally-growing element (a search bar with typing text, a long URL animating in) visible by switching between two camera modes.
+
+## How It Works
+
+Separate **World Space** (the full target element with all content) from **Screen Space** (the viewport). Two phases:
+
+- **Phase 1 (Static)** — the world container sits at a fixed initial offset; the camera doesn't move. Anchors the viewer's eye before tracking begins.
+- **Phase 2 (Tracking)** — activates when the focal point (cursor, highlight, last typed glyph) exceeds a target screen position (`CURSOR_TARGET_FRACTION × viewportWidth` from the left). The world translates leftward (`x: -delta`) keeping the focal point pinned at that screen position.
+
+The offset math is **mathematically continuous** at the phase boundary — at the instant tracking starts, the world position equals what the static phase had, so the transition is seamless. The piecewise form:
+
+```
+finalWorldX = Math.min(INITIAL_OFFSET, trackingOffset)
+```
+
+`INITIAL_OFFSET` is the static-phase value; `trackingOffset` is whatever shift keeps the focal point at the target screen X. While the focal point hasn't grown past the target, `trackingOffset` is a less-negative number and `Math.min` returns the static value; once the focal point would cross the target, `trackingOffset` overtakes and tracking takes over. Do NOT replace this with a hard `if (typingProgress > threshold)` branch — the camera will visibly jump.
+
+## Recipe
+
+```html
+<div class="viewport">
+  <div class="world">
+    <div class="search-bar">
+      <span class="text" id="reveal-text">{phrase}</span><span class="cursor">|</span>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.viewport {
+  position: absolute;
+  inset: 0;
+  overflow: hidden; /* clip the world's left edge as it pans off-screen */
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  padding-left: VIEWPORT_PAD_LEFT; /* Phase-1 anchor X — must match the JS constant */
+}
+.world {
+  display: flex;
+  align-items: center;
+  white-space: nowrap; /* text must stay on one line for the camera math */
+}
+.search-bar .text {
+  display: inline-block;
+  overflow: hidden;
+  vertical-align: bottom;
+}
+.search-bar .cursor {
+  display: inline-block; /* inline sibling of the text, NOT absolutely positioned —
+     absolute positioning misaligns with the camera math */
+  width: CURSOR_WIDTH;
+  margin-left: CURSOR_GAP;
+  background: {accentColor};
+  height: CURSOR_HEIGHT_EM;
+  vertical-align: bottom;
+  /* no CSS blink animation — CSS clocks don't sync to seek; blink is a GSAP tween below */
+}
+```
+
+```js
+// Pre-measure the target text width to compute tracking distance.
+// Measure SYNCHRONOUSLY — no fonts.ready gate (see Critical Constraints).
+const textEl = document.getElementById("reveal-text");
+const targetCursorScreenX = CURSOR_TARGET_FRACTION * VIEWPORT_WIDTH;
+const fullWidth = textEl.scrollWidth; // total text width after full reveal
+const trackingDelta = Math.max(0, VIEWPORT_PAD_LEFT + fullWidth - targetCursorScreenX);
+
+// Phase 1 — text reveals progressively; camera holds. maxWidth tween
+// (width/left/top tweens are forbidden); ease "none" = linear typing rate.
+tl.fromTo(
+  ".search-bar .text",
+  { maxWidth: 0 },
+  { maxWidth: fullWidth, duration: REVEAL_DUR, ease: "none" },
+  REVEAL_START,
+);
+
+// Phase 2 — camera tracks. Start BEFORE full reveal so the handoff feels
+// continuous (Math.min form above makes it mathematically continuous).
+tl.to(".world", { x: -trackingDelta, duration: TRACK_DUR, ease: "power2.inOut" }, TRACK_START);
+
+// Cursor blink — finite GSAP yoyo (never CSS @keyframes; CSS animation clocks
+// aren't synced to HF's seek and flicker non-deterministically).
+const blinkRepeats = Math.ceil(SCENE_DURATION / BLINK_HALF_PERIOD) - 1;
+tl.to(
+  ".search-bar .cursor",
+  { opacity: 0, duration: BLINK_HALF_PERIOD, ease: "steps(1)", yoyo: true, repeat: blinkRepeats },
+  0,
+);
+```
+
+## Variations
+
+- **Centered → center-tracked**: `.viewport { justify-content: center; padding: 0; }`, `CURSOR_TARGET_FRACTION = 0.5` — tracks once the focal point crosses the midline.
+- **Left-aligned → right-tracked**: as written; best when content exceeds viewport width from the start.
+- **Continuous typing driver**: replace the `maxWidth` tween with an `onUpdate` typing clock (`charsTyped = Math.floor(progress)`) plus per-frame `measureNodeWidth` driving the cursor screen X — required when the typed text is consumed elsewhere in the scene (e.g. by a parent strip's camera offset).
+
+## Values
+
+| token                  | range                       | notes                                                                           |
+| ---------------------- | --------------------------- | ------------------------------------------------------------------------------- |
+| VIEWPORT_PAD_LEFT      | 0 → ~10% of viewport width  | must match the CSS `padding-left` or the camera math drifts                     |
+| VIEWPORT_WIDTH         | = the root's `data-width`   | never tweened                                                                   |
+| CURSOR_TARGET_FRACTION | 0.5–0.75                    | lower = less revealed text in frame; higher delays tracking                     |
+| CURSOR_WIDTH / GAP     | 4–10 px / a few px          | gap ≤ cursor width or it visually detaches                                      |
+| CURSOR_HEIGHT_EM       | 0.85–1.0 em                 | matches the typed glyph height                                                  |
+| REVEAL_DUR             | chars × 0.05–0.15s          | ease `"none"` — any easing distorts the per-keystroke cadence                   |
+| TRACK_START            | < REVEAL_START + REVEAL_DUR | overlap the reveal so the handoff feels continuous                              |
+| TRACK_DUR              | 0.8–2.0s                    | `power2.inOut`/`power3.inOut`; `back.out` reads as UI bounce, not camera        |
+| BLINK_HALF_PERIOD      | 0.2–0.4s                    | `steps(1)` hard on/off; repeats derived from SCENE_DURATION (= `data-duration`) |
+
+## Critical Constraints
+
+- **Build the timeline SYNCHRONOUSLY — no `fonts.ready` gate.** HF renders frames in parallel workers, each a fresh browser. A `document.fonts.ready.then(...)` wrapper means some workers seek frames BEFORE the Promise resolves and find no timeline → those frames render at CSS initial state (`max-width: 0` ⇒ empty text) while others render correctly → visible flicker. Register the timeline at script-parse time: the camera math tolerates a few percent width error from fallback-font measurement; worker-race flicker is unacceptable. If precise post-font measurement matters, re-measure inside the tween's `onUpdate` (still deterministic per-frame), or set `font-display: block` on the @font-face.
+- **Measure with `getBoundingClientRect()` / `scrollWidth` / probe nodes**, never character count × font-size — proportional fonts have variable glyph widths.
+- **Continuous math at the phase boundary** — the `Math.min(INITIAL_OFFSET, trackingOffset)` form, never a hard threshold branch.
+- **`white-space: nowrap` on the world** and pre-allocated width (tween `maxWidth` to the full target width) — prevents layout shift mid-tween.
+- **Cursor is an inline sibling of the text**, and blinks via a finite GSAP yoyo — never CSS `@keyframes … infinite`.
+- **`overflow: hidden` on `.viewport`** — clips the world as it pans.
+
+## See also
+
+[context-sensitive-cursor.md](context-sensitive-cursor.md) (cursor color per text segment) · [discrete-text-sequence.md](discrete-text-sequence.md) (non-linear text reveals under this camera).

package/dist/assets/design/skills/hyperframes-animation/rules/card-morph-anchor.md

@@ -0,0 +1,134 @@
+---
+name: card-morph-anchor
+description: Container morphs dimensions and border-radius between shots, serving as a visual transition anchor.
+metadata:
+  tags: morph, anchor, transition, border-radius, container, shape
+---
+
+# Card Morph Anchor
+
+A free-floating container morphs apparent size, corner radius, and surface treatment between two shots — the morph itself IS the transition; the viewer's eye tracks the persistent container. Distinct from [anchored-layout-expand.md](anchored-layout-expand.md) (an edge-pinned live layout participant that grows along one axis and reflows neighbors — here nothing is pushed) and [theme-crossfade-morph.md](theme-crossfade-morph.md) (a whole-theme reskin under a fixed anchor — here a single container changes shape).
+
+## How It Works
+
+Since `width`/`height` tweens are forbidden, **substitute uniform `scale` for apparent size**; the remaining morph channels are **paint-only**: `borderRadius`, `background`, `boxShadow`. All channels ride ONE tween (one ease, one duration) so the shape morphs in lockstep. Content choreography: old content fades out during the first ~40% of the morph, new content fades in during the last ~40% — the shape-only gap between is the natural "blink." Optionally the morph card itself fades at the very end, revealing the real next-shot element rendered behind it.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<!-- DOM order = stacking: the anchor renders BEFORE the card, so the card is on top -->
+<div class="next-shot-anchor"><img src="{nextShotAnchor}" alt="anchor" /></div>
+<div class="morph-card">
+  <div class="content-old">{shotOneContent}</div>
+  <div class="content-new">{shotTwoContent}</div>
+</div>
+```
+
+```css
+.morph-card {
+  width: SHOT_ONE_W;
+  height: SHOT_ONE_H; /* shot-1 geometry; the morph is scale, never width/height */
+  border-radius: SHOT_ONE_RADIUS;
+  background: {surfaceShotOne};
+  overflow: hidden; /* content must clip during the shape change */
+  display: grid;
+  place-items: center;
+  will-change: transform;
+}
+.content-old,
+.content-new {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+}
+.content-new {
+  opacity: 0; /* author its inner sizes at apparent-size ÷ END_SCALE — it scales with the card */
+}
+.next-shot-anchor {
+  position: absolute;
+  opacity: 0; /* fades in as the morph card fades out */
+}
+```
+
+```js
+const END_SCALE = SHOT_TWO_W / SHOT_ONE_W; // uniform — keep the two shots aspect-matched
+
+// Hold shot 1 for HOLD_BEAT first — an instant morph reads as glitchy.
+
+// One tween, all channels: uniform scale + paint-only properties.
+tl.to(
+  ".morph-card",
+  {
+    scale: END_SCALE,
+    borderRadius: SHOT_TWO_RADIUS / END_SCALE, // borderRadius is pre-scale — divide to land the APPARENT radius
+    background: "{surfaceShotTwo}",
+    boxShadow: "{shadowShotTwo}",
+    duration: MORPH_DUR,
+    ease: "power2.inOut",
+  },
+  MORPH_START,
+);
+
+tl.to(
+  ".content-old",
+  { opacity: 0, duration: MORPH_DUR * OLD_FADE_FRAC, ease: "power1.in" },
+  MORPH_START,
+);
+tl.to(
+  ".content-new",
+  { opacity: 1, duration: MORPH_DUR * NEW_FADE_FRAC, ease: "power1.out" },
+  MORPH_START + MORPH_DUR * (1 - NEW_FADE_FRAC),
+);
+
+// Optional handoff — card fades out over the pixel-identical real anchor.
+tl.to(
+  ".morph-card",
+  { opacity: 0, duration: MORPH_DUR * FINAL_FADE_FRAC, ease: "power1.in", immediateRender: false },
+  MORPH_START + MORPH_DUR * (1 - FINAL_FADE_FRAC),
+);
+tl.to(
+  ".next-shot-anchor",
+  { opacity: 1, duration: MORPH_DUR * FINAL_FADE_FRAC, ease: "power1.out" },
+  MORPH_START + MORPH_DUR * (1 - FINAL_FADE_FRAC),
+);
+```
+
+## Morph channels
+
+| channel        | how                                                                                            |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| apparent size  | uniform `scale` — the substitution for the forbidden `width`/`height` tween; aspect preserved  |
+| `borderRadius` | paint-only; pre-scale units — tween to `APPARENT_RADIUS / END_SCALE`, ≤ half the smaller side  |
+| `background`   | paint-only; gradients interpolate only with equal stop counts (solid→solid: `backgroundColor`) |
+| `boxShadow`    | paint-only; base shadow → accent glow shifts emphasis                                          |
+
+## Variations
+
+- **Landing on a non-centered target** (dock icon, sidebar slot): add `x`/`y` to the same tween, computed as the FLIP-style delta between the card's and the target's rects — `getBoundingClientRect()` both at build time (single-scene only, per the contract) and tween the difference. Don't hand-compute from CSS values: paddings, borders, and parent transforms compound, and center-vs-edge arithmetic is the classic off-by-half bug.
+- **Aspect change between shots**: uniform scale preserves aspect — morph to the nearest uniform fit and let the crossfade/handoff absorb the small delta, or drop the handoff and hold the card's final state.
+
+## Values
+
+| token             | range                     | notes                                                                                |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------ |
+| HOLD_BEAT         | 0.6–1.5s                  | ≥ shot 1's entry settle; the viewer must register shot 1 first                       |
+| MORPH_DUR         | 0.6–1.2s                  | < 0.5s can't fit both content fades                                                  |
+| END_SCALE         | SHOT_TWO_W / SHOT_ONE_W   | icon-sized handoffs typically land at 80–400px apparent width                        |
+| SHOT_TWO_RADIUS   | ≤ min(W, H)/2 apparent    | half the smaller side = perfect circle; beyond is clamped                            |
+| OLD/NEW_FADE_FRAC | 0.3–0.5 each, sum ≤ 1     | the gap between is the shape-only "blink"                                            |
+| FINAL_FADE_FRAC   | 0 (no handoff) or 0.1–0.2 | only when a pixel-identical anchor exists                                            |
+| ease              | `power2.inOut` canonical  | `power3`/`expo.inOut` OK; never `back`/`elastic` — overshoot fights the shape change |
+
+## Critical Constraints
+
+- ** Uniform-scale substitution** — never tween `width`/`height`; `scale` + the paint-only channels (`borderRadius`, `background`, `boxShadow`) are the ONLY morph properties.
+- ** Handoff anchor must be pixel-identical to the card's final state** — same apparent size, radius, background, shadow, inner icon dimensions. Any delta = a visible pop during the crossfade. Can't match exactly? Drop the handoff and hold the morph card.
+- ** Stacking by DOM order, never a z-index snap mid-fade** — render the anchor before the card; a `tl.set({ zIndex })` during an active opacity tween flips stacking before the fade finishes and flickers.
+- **`overflow: hidden`** on the card — content must clip as the radius changes.
+- **Hold a beat before morphing**; same ease family for shape and crossfade (mixed eases read unsynchronized).
+
+## See also
+
+`anchored-layout-expand` (edge-pinned one-axis growth with reflow) · `theme-crossfade-morph` (whole-theme reskin under a fixed anchor) · `scale-swap-transition` (content swap without shape change) · `sine-wave-loop` (a breath on the final state).

package/dist/assets/design/skills/hyperframes-animation/rules/center-outward-expansion.md

@@ -0,0 +1,88 @@
+---
+name: center-outward-expansion
+description: Elements start clustered at screen center and expand outward to their final positions, driven by a shared progress value.
+metadata:
+  tags: expansion, scatter, center, reveal, layout, sync, burst
+---
+
+# Center-Outward Expansion
+
+Elements begin at one shared center point and radiate outward to their final positions — the entry beat itself, or motion driven by another animation's progress (a counting number, a beat). Flat 2D cousin of [depth-scatter-assemble.md](depth-scatter-assemble.md) (per-element 3D cloud): here every element shares the SAME origin.
+
+## How It Works
+
+Each element carries its final offset as `data-target-x/y`. Its position lerps between center and target: `x = targetX × progress`. Self-centering is baked as `xPercent/yPercent: -50` so the tweened `x`/`y` are pure offsets from the stage center. Standalone burst = per-item staggered `fromTo`; driven burst = one shared proxy (see Variations).
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="burst-wrap">
+  <div class="burst-item" data-target-x="-360" data-target-y="-180">{itemA}</div>
+  <div class="burst-item" data-target-x="360" data-target-y="-180">{itemB}</div>
+  <div class="burst-item" data-target-x="0" data-target-y="360">{itemC}</div>
+</div>
+```
+
+```css
+.burst-wrap {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+}
+.burst-item {
+  position: absolute;
+  top: 50%;
+  left: 50%; /* GSAP xPercent/yPercent -50 bakes the centering; x/y tween the offset */
+  will-change: transform;
+}
+```
+
+```js
+document.querySelectorAll(".burst-item").forEach((el, i) => {
+  tl.fromTo(
+    el,
+    { xPercent: -50, yPercent: -50, x: 0, y: 0, scale: 0.6, opacity: 0 },
+    {
+      x: Number(el.dataset.targetX),
+      y: Number(el.dataset.targetY),
+      scale: 1,
+      opacity: 1,
+      duration: EXPAND_DUR,
+      ease: EXPAND_EASE,
+    },
+    ENTRY_AT + i * STAGGER,
+  );
+});
+```
+
+## Variations
+
+- **Synced to a driver (chord)**: when the burst shadows a counter / beat, drop the stagger and drive all items from ONE 0→1 proxy tween with the driver's exact duration AND ease; `onUpdate` writes `translate(-50%,-50%) translate(targetX*p, targetY*p)` per item — the two read as one beat.
+- **Partially-spread start**: with 6+ items the full cluster piles up — start from `{ x: targetX * START_PROGRESS, ... }`.
+- **Idle micro-float**: hand off to [sine-wave-loop.md](sine-wave-loop.md) after landing instead of freezing.
+
+## Values
+
+| token          | range                | notes                                                            |
+| -------------- | -------------------- | ---------------------------------------------------------------- |
+| ITEM_COUNT     | 3–8                  | > 8 = visual chaos mid-expansion; low counts want wider spread   |
+| EXPAND_DUR     | 1.0–1.8s             | must equal the driver's duration in the synced variant           |
+| EXPAND_EASE    | `power3.out` default | `power2.out` gentler, `expo.out` dramatic stop; NEVER `in` eases |
+| STAGGER        | 0.04–0.08s           | tighter = chord; looser = lazy arpeggio                          |
+| ENTRY_AT       | 0–0.5s               | a beat of compositional quiet before the burst                   |
+| START_PROGRESS | 0–0.5                | 0 = dramatic full cluster; ~0.3 avoids the pile-up               |
+
+## Critical Constraints
+
+- **Tween `x`/`y` over the baked `xPercent/yPercent: -50`** — mutating `left`/`top` fights the centering and causes pixel jitter.
+- **Out-easing only** — `in` easings read as items being sucked back mid-air.
+- **No other absolute-positioned siblings inside `.burst-wrap`** — they'd steal the centered baseline.
+- ** The burst IS the beat** — don't park a "real headline" label below it (the eye snaps to the label and ignores the burst). If a label is needed, reveal it post-burst in the same stack.
+- Synced variant: identical duration + ease as the driver, or the chord falls apart.
+
+## See also
+
+`counting-dynamic-scale` (the classic chord driver) · `depth-scatter-assemble` (3D per-element cloud) · `card-morph-anchor` (burst out of a morphed card) · `sine-wave-loop` (post-landing life).

package/dist/assets/design/skills/hyperframes-animation/rules/chart-scrub-readout.md

@@ -0,0 +1,151 @@
+---
+name: chart-scrub-readout
+description: A cursor/playhead scrubs an already-drawn chart — one driver moves a vertical tracking line and marker along a baked data polyline while a date/value tooltip steps through the data array; a second series can activate on cross. Deterministic data, readout writes only on index change.
+metadata:
+  tags: chart, scrub, readout, tooltip, tracking-line, data, cursor, playhead
+---
+
+# Chart Scrub Readout
+
+The chart is already ON screen — this rule **interrogates** it. A vertical tracking line rides the scrub position, a marker dot follows the series, and a live tooltip reads out `date: value` per position, values flickering past like an odometer. It's the "this data is real — look closer" beat: the scrub proves the chart is an instrument, not a picture.
+
+Boundary with its neighbors: [stat-bars-and-fills.md](stat-bars-and-fills.md) owns the chart's ARRIVAL; [counting-dynamic-scale.md](counting-dynamic-scale.md) owns a single number swelling in place. This rule assumes the graphic already exists and adds a **read head** moving across it. The three chain naturally: the line draws in (svg-path-draw / stat-bars), this rule scrubs it, and the landing value hands off to a count-up lockup.
+
+## How It Works
+
+1. **Data baked at setup** — a literal `DATA` array of `{ d, v }` points (or a pure index formula). The polyline's `points` attribute is computed ONCE from `DATA` by pure mapping functions: chart and readout share one source of truth. The argument of the shot is "this data is real" — a random walk regenerated per render breaks both determinism and the rhetorical claim.
+2. **One driver tween** `p: 0 → 1` derives everything in its `onUpdate`: tracking-line x, marker x/y, tooltip position. Every output is a pure function of `p` — any seek lands the identical frame. Parallel tweens that merely share timing drift apart under rounding and read as chart chrome, not a read head.
+3. **The marker rides the polyline** — its y interpolates between the two neighboring baked points, from the same arrays that built the chart; a separately-keyframed marker inevitably floats off the line.
+4. **The readout is threshold-stepped** — the nearest data index derives from `p`, and `textContent` is written ONLY when that index changes (last-index guard). Transforms glide per frame (compositor-cheap); text steps per data point — no per-frame DOM text thrash. The guard is an optimization, not state: any seek recomputes the same index and the same text.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip. Size the SVG so viewBox units === CSS pixels:
+     one coordinate space serves the polyline, tracking line, marker, AND the HTML tooltip. -->
+<div class="chart-wrap">
+  <!-- position: relative — the tooltip transforms against this box -->
+  <svg class="chart" viewBox="0 0 CHART_W CHART_H" width="CHART_W" height="CHART_H">
+    <polyline id="series-a" class="series" fill="none" />
+    <line id="track-line" y1="0" y2="CHART_H" stroke-dasharray="6 6" />
+    <circle id="marker" r="MARKER_R" />
+  </svg>
+  <div class="tooltip" id="tooltip">
+    <span id="tip-date">{firstDate}</span>
+    <span id="tip-value">{firstValue}</span>
+  </div>
+</div>
+```
+
+```css
+.tooltip {
+  position: absolute;
+  top: 0;
+  left: 0;
+  min-width: TIP_MIN_WIDTH; /* fixed — the box must not resize as values change length */
+}
+#tip-value {
+  font-variant-numeric: tabular-nums; /* MANDATORY — digits flicker past; widths must not */
+}
+```
+
+```js
+// Data baked at setup — literal values.
+const DATA = [
+  { d: "{date1}", v: V1 },
+  // ... N points, chronological ...
+];
+
+// Pure mapping functions — geometry derives from DATA once.
+const PAD = CHART_PAD;
+const PLOT_W = CHART_W - PAD * 2;
+const PLOT_H = CHART_H - PAD * 2;
+const vals = DATA.map((p) => p.v);
+const V_MIN = Math.min(...vals);
+const V_MAX = Math.max(...vals);
+const X = (i) => PAD + (i / (DATA.length - 1)) * PLOT_W;
+const Y = (v) => PAD + PLOT_H * (1 - (v - V_MIN) / (V_MAX - V_MIN));
+
+document
+  .getElementById("series-a")
+  .setAttribute("points", DATA.map((p, i) => `${X(i)},${Y(p.v)}`).join(" "));
+
+const line = document.getElementById("track-line");
+const marker = document.getElementById("marker");
+const tooltip = document.getElementById("tooltip");
+const tipDate = document.getElementById("tip-date");
+const tipValue = document.getElementById("tip-value");
+
+// Tooltip pops in as the scrub begins — a small fromTo scale/opacity spring at SCRUB_AT.
+
+// ONE driver — line, marker, and tooltip are all projections of p.
+const scrub = { p: 0 };
+let lastIdx = -1;
+tl.to(
+  scrub,
+  {
+    p: 1,
+    duration: SCRUB_DUR,
+    ease: SCRUB_EASE,
+    onUpdate: () => {
+      const f = scrub.p * (DATA.length - 1); // fractional index
+      const i = Math.min(DATA.length - 2, Math.floor(f));
+      const t = f - i;
+      const x = X(i) + (X(i + 1) - X(i)) * t;
+      const y = Y(DATA[i].v) + (Y(DATA[i + 1].v) - Y(DATA[i].v)) * t;
+
+      // Transforms glide every frame (cheap, deterministic)
+      line.setAttribute("x1", x);
+      line.setAttribute("x2", x);
+      marker.setAttribute("cx", x);
+      marker.setAttribute("cy", y);
+      tooltip.style.transform = `translate(${x + TIP_DX}px, ${y - TIP_DY}px)`;
+
+      // Text steps only when the nearest data point changes
+      const idx = Math.round(f);
+      if (idx !== lastIdx) {
+        tipDate.textContent = DATA[idx].d;
+        tipValue.textContent = `${DATA[idx].v.toLocaleString()} {unitLabel}`;
+        lastIdx = idx;
+      }
+    },
+  },
+  SCRUB_AT,
+);
+// End hold: the driver finishes before the scene does — the landed value reads.
+```
+
+## Variations
+
+- **Peak stop** — the scrub is the wind-up, the landing is the stat: `SCRUB_EASE: "power3.out"` decelerates onto the final/peak point, then pop the emphasis at landing (`fromTo` marker `scale: 1 → PEAK_POP_SCALE` at `SCRUB_AT + SCRUB_DUR`). Pair with a pill tooltip that springs to its final label ([spring-pop-entrance.md](spring-pop-entrance.md)) — the classic "line breaks above the band" climax.
+- **Second-series activation on cross** — series B sits dimmed; at `SCRUB_AT + SCRUB_DUR * CROSS_P` tween its stroke to the lit color (0.25s, `power2.out`), and in the driver's `onUpdate` read from B's array once `scrub.p ≥ CROSS_P` (still index-guarded). The color flip lands ON the cross — same-frame causality.
+- **Two-chart glide** — two scrub beats: sweep chart A, glide the cursor/tooltip group across the gutter (a plain `x` tween, no readout — dead travel, not data), then chart B activates with its own driver. One driver per chart.
+- **Cursor-led scrub** — an oversized cursor is the visible actor: another projection of the SAME driver (positioned from `x` in the same `onUpdate`, tip at the tracking line's head) — never a second tween that merely matches timing. Cursor look and click grammar from [cursor-click-ripple.md](cursor-click-ripple.md).
+- **Playhead form** — no cursor; the tracking line IS the actor (timeline scrubbers, audio waves, session replays). `ease: "none"` — mechanical playback, not a hand.
+
+## Values
+
+| token                   | range / default               | notes                                                                                                                    |
+| ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| N (data points)         | 10–40                         | <10 reads as a slideshow; >40 blurs into texture. The flicker is the point — only first and final values must be legible |
+| SCRUB_DUR               | 1.5–3s                        | shorter = confident sweep; longer = inspection. Leave ≥0.8s of scene after the driver ends so the landed value holds     |
+| SCRUB_EASE              | `power1.inOut` default        | `"none"` playhead form; `power3.out` peak stop. Never `back.out` — a read head that overshoots and re-reads looks broken |
+| CROSS_P                 | 0.55–0.75                     | earlier and A never establishes; later and B's readout has no time to live                                               |
+| TIP_DX / TIP_DY         | 16–48px, up-and-right         | flip the sign near the chart's right edge so the tooltip never exits the frame                                           |
+| MARKER_R / stroke width | r 6–12 / 4–8px                | the marker must dominate the line it rides                                                                               |
+| TIP_MIN_WIDTH           | ≥ longest `date: value` state | without it the box breathes as digits change                                                                             |
+
+## Critical Constraints
+
+- **`DATA` is literal at setup**; polyline points derive from it via pure functions — chart and readout share one source of truth.
+- **Seed at setup** — call the scrub applier once with `p = 0` right after building (à la `3d-camera-flight`'s `applyCamera()`), or a seek to t=0 before the driver runs shows the tracking line/marker at their HTML-default positions.
+- **Single driver** — one `p` tween; all scrub outputs (line, marker, tooltip, any cursor) computed in its `onUpdate`, each a pure function of `p`.
+- **Readout writes guarded by index change** — `onUpdate` stays O(1): a few attribute sets, one transform, text only on step.
+- **SVG `viewBox` units = CSS pixels** (`viewBox="0 0 W H"` with matching `width`/`height`) — one coordinate space must serve the SVG internals and the HTML tooltip's transform.
+- **`tabular-nums` + fixed `min-width`** on the tooltip value.
+- **The chart pre-exists** — draw-in belongs to `svg-path-draw` / `stat-bars-and-fills`; sequence it BEFORE the scrub, don't blend them.
+- **Land the read** — hold the final value ≥0.8s (or hand off to a count-up lockup).
+
+## See also
+
+`svg-path-draw` (the series draws in first) · `stat-bars-and-fills` (surrounding dashboard chrome) · `spring-pop-entrance` (peak dot + pill pop at the landing) · `counting-dynamic-scale` (closing stat lockup) · `cursor-click-ripple` / `context-sensitive-cursor` (the cursor-led form's actor) · `control-target-sync` (the sibling WRITE direction — there a control edits a target; here a scrub reads a dataset).