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

package/dist/assets/design/skills/hyperframes-animation/rules/theme-crossfade-morph.md

@@ -0,0 +1,126 @@
+---
+name: theme-crossfade-morph
+description: Whole-theme in-place morph under a fixed anchor — background, typography, corner radii, icons, chrome and logos all blend simultaneously (~0.3s) through N pre-styled skins while one anchor element never moves. Recipe = stacked full layers + opacity crossfade, anchor rendered once on top. Seek-safe by construction.
+metadata:
+  tags: theme, skin, crossfade, morph, anchor, reskin, cycle, ui, stacked-layers
+---
+
+# Theme Crossfade Morph
+
+The whole world re-skins while one thing holds still. A composer box cycles through four IDE themes; a checkout widget flips through brand skins — background, typography, corner radii, toolbar icons, footer logos all change **at once**, in place, in ~0.3s, N times — and through every flip one anchor element (the prompt string, the widget layout, the wordmark) **never moves**. The anchor's stillness is the rhetorical claim: _everything changes, this doesn't._
+
+Boundary: [card-morph-anchor.md](card-morph-anchor.md) morphs **one container** between two shots — its dimensions, radius, and surface tween continuously. This rule re-skins an **entire scene** through **N discrete states**: nothing tweens property-by-property (fonts, icons, and logos can't interpolate); the "morph" is a fast simultaneous crossfade of complete pre-styled layers. ([scale-swap-transition.md](scale-swap-transition.md) swaps an element at center; here the surroundings swap and the element holds.)
+
+## How It Works
+
+1. **One skin = one complete layer.** Each theme state is a fully pre-styled, full-bleed layer (`position: absolute; inset: 0`) containing everything that changes: background, shell/chrome, toolbar icons, footer logos, typography. All `N_SKINS` layers exist in the DOM from `t=0`, stacked; skin 0 starts visible, the rest at `opacity: 0`.
+2. **The morph is a crossfade.** At each boundary, two opposing opacity tweens run at the same timeline position over `MORPH_DUR` (~0.3s): outgoing `1 → 0`, incoming `0 → 1`. Because both layers are complete, every property "blends" simultaneously for free — including the un-tweenable ones (font families, icon glyphs, logos), which read as morphing precisely because everything else is mid-blend around them.
+3. **The anchor renders once, on top.** The element that must not move lives in its own layer above all skins and is **excluded from every skin layer**. No transforms, no re-parenting, no per-skin restyle.
+4. **Windows are precomputed.** `T_k = CYCLE_START + k × (SKIN_HOLD + MORPH_DUR)`. Steady cadence by default; hold the final skin longest when it's the resolve.
+
+The only animated property is `opacity` — which is why this rule is seek-safe with zero special machinery.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="theme-stage">
+  <!-- One complete pre-styled layer per skin; skin-0 visible at t=0 -->
+  <div class="skin skin-0"><div class="shell">…terminal chrome, mono type, footer badge…</div></div>
+  <div class="skin skin-1">
+    <div class="shell">…rounded composer, sans type, toolbar pills, logo…</div>
+  </div>
+  <div class="skin skin-2"><div class="shell">…dark shell, its own chrome and footer…</div></div>
+
+  <!-- The anchor: rendered ONCE, above every skin. It never moves. -->
+  <div class="anchor" id="anchor">{anchorText}</div>
+</div>
+```
+
+```css
+.theme-stage {
+  position: absolute;
+  inset: 0;
+}
+.skin {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+  /* Each skin fully self-styled: its own background, fonts, radii,
+     icons, chrome, logos. Nothing inherited across skins. */
+}
+.skin-0 {
+  opacity: 1; /* the opening state — matches the timeline's fromTo */
+}
+.shell {
+  /* CRITICAL: shared geometry. The shell box (and any element that
+     "persists" across skins — toolbar row, footer row) sits at the SAME
+     coordinates in every skin, so mid-blend frames read as one UI
+     changing clothes, not two UIs ghosting. */
+  position: absolute;
+  left: SHELL_LEFT;
+  top: SHELL_TOP;
+  width: SHELL_WIDTH;
+  height: SHELL_HEIGHT;
+}
+.anchor {
+  position: absolute;
+  z-index: 10; /* above every skin */
+  left: ANCHOR_LEFT;
+  top: ANCHOR_TOP;
+  /* No transforms, no transitions — the stillness is load-bearing. */
+}
+```
+
+```js
+const skins = gsap.utils.toArray(".skin");
+
+// Boundary k→k+1 at T_k: outgoing fades down as incoming fades up —
+// ONE simultaneous crossfade, everything blends at once.
+skins.forEach((skin, k) => {
+  if (k === 0) return; // skin-0 is the opening state
+  const at = CYCLE_START + k * (SKIN_HOLD + MORPH_DUR);
+  tl.fromTo(skin, { opacity: 0 }, { opacity: 1, duration: MORPH_DUR, ease: "power2.inOut" }, at);
+  tl.to(
+    skins[k - 1],
+    { opacity: 0, duration: MORPH_DUR, ease: "power2.inOut" },
+    at, // same position — the blend is simultaneous, never sequential
+  );
+});
+
+// The anchor gets NO tweens. Its absence from the timeline is the point.
+```
+
+## Variations
+
+- **Anchor-typography reskin (per-layer copies)** — when the anchor's own type treatment must change with the theme (mono in the terminal skin, sans in the editor skin), each skin carries its own copy of the anchor at **pixel-identical geometry** and there is no separate top layer; the invariant shifts from "one element" to "one geometry." Verify the copies overlay exactly (screenshot two skins at 50% opacity) — a 2px baseline drift reads as the anchor flinching, which breaks the whole claim.
+- **Skin-cycle tour with logo relay** — a large brand logo outside the anchored shell crossfades **in the same windows** as the skins (logo k with skin k, same `MORPH_DUR`). The paired swap sells "same product, every brand."
+- **Washout finale** — after the last skin, a final low-key layer (faint dot-grid, blueprint wash) fades in while the last shell drops to ~0.25 opacity — the cycle resolves into a held diagram of itself. One extra window; the anchor may fade with the shell or hold full-strength.
+- **Emphasis brake** — steady cadence for `N−1` skins, then hold the final skin 2–3× `SKIN_HOLD`; the cycle demonstrates breadth, the brake lands the resolve. Precompute the hold array; don't drift the cadence without cause.
+
+## Values
+
+| token           | range                                       | notes                                                                                                |
+| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| N_SKINS         | 3–5                                         | two is a before/after (consider `card-morph-anchor`); past five the cycle pads                       |
+| SKIN_HOLD       | 0.8–1.5s                                    | long enough to register the logo/footer identity, short enough to keep the churn rhetorical          |
+| MORPH_DUR       | 0.25–0.4s, ~0.3s canonical                  | faster reads as a hard cut; slower reads as a mushy dissolve with lingering double-exposure          |
+| CYCLE_START     | ≥ anchor settle + a beat                    | after the anchor and skin-0 have fully registered                                                    |
+| SHELL geometry  | —                                           | shell / toolbar / footer coordinates identical across skins; contents inside the slots differ freely |
+| ANCHOR position | —                                           | identical to the pixel across the scene (per-layer form: identical in every skin)                    |
+| washout / brake | shell ~0.2–0.3 opacity; hold 2–3× SKIN_HOLD | —                                                                                                    |
+
+## Critical Constraints
+
+- **The anchor never moves.** No transforms, no opacity dips, no re-parenting, no restyle — the contrast between total churn and total stillness is the entire device; one flinch and the shot becomes a slideshow.
+- **Nothing tweens but `opacity`** — no `borderRadius` / `background` tweens; radii and colors change by being different in the next layer. Visibility via `opacity` only, never `display` / `visibility` toggles (they can't blend mid-fade).
+- **Pixel-align the shared geometry** — mid-blend both skins are partially visible; aligned shells read as one UI changing clothes, misaligned shells ghost into two UIs.
+- **Pre-style everything** — each skin is complete and static; no class toggling, no runtime restyle mid-tween.
+- **Outgoing and incoming tweens share one timeline position** — a staggered blend flashes the stage background between skins.
+- **Adjacent windows only** — skin k crossfades with k+1, never k+2; at no frame are three skins partially visible.
+- **Camera static — always.** A push-in on top of a theme cycle destroys the stillness that makes the anchor read.
+- **Hard cuts are the cheaper sibling** — if the states should _snap_, that's `discrete-text-sequence` territory; the ~0.3s blend is specifically the "morph" read.
+
+## See also
+
+`context-sensitive-cursor` (caret color switches at each `T_k`) · `discrete-text-sequence` (type the anchor first; or the hard-cut alternative) · `card-morph-anchor` (the single-container sibling) · `spring-pop-entrance` (the lockup that joins the anchor at the resolve) · `sine-wave-loop` (drifting field under the cycle — never on the anchor).

package/dist/assets/design/skills/hyperframes-animation/rules/vertical-spring-ticker.md

@@ -0,0 +1,104 @@
+---
+name: vertical-spring-ticker
+description: Slot-machine style vertical scrolling using additive spring physics within a masked container — each spring contributes one "step" of scroll.
+metadata:
+  tags: text, ticker, spring, scroll, vertical, slot-machine, sequence
+---
+
+# Vertical Spring Ticker (Slot Machine)
+
+Multiple spring tweens are ADDED TOGETHER to produce total Y translation — each spring contributes one discrete "step", so instead of a single linear scroll you get the slot-machine "click click click" rhythm with natural settling. Distinct from a continuous marquee: this rule's semantics are discrete steps that land; for endless linear motion see [sine-wave-loop.md](sine-wave-loop.md).
+
+## How It Works
+
+A masked window of fixed height `ITEM_HEIGHT` (`overflow: hidden`) holds a vertical stack of items, each exactly `ITEM_HEIGHT` tall. Each spring holds a 0→1 progress; a shared `onUpdate` sums them and applies `translateY(-sum × ITEM_HEIGHT)`. Springs fire sequentially with overlap (`STEP_SPACING ≤ STEP_DUR`), so each step snaps in while the previous is still settling — that overlap is what makes them additive, and the `back.out` overshoot is what makes each step read as a "click".
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="ticker" id="ticker">
+  <div class="stack-inner" id="stack-inner">
+    <div class="item">{item0}</div>
+    <div class="item">{item1}</div>
+    <div class="item">{itemN}</div>
+  </div>
+</div>
+```
+
+```css
+.ticker {
+  width: TICKER_WIDTH;
+  height: ITEM_HEIGHT; /* MUST match .item height exactly */
+  overflow: hidden; /* the mask is the window */
+}
+.stack-inner {
+  display: flex;
+  flex-direction: column; /* mandatory — vertical stacking */
+}
+.item {
+  height: ITEM_HEIGHT; /* MUST equal .ticker height */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* font-variant-numeric: tabular-nums; — for numeric tickers */
+}
+```
+
+```js
+const innerEl = document.getElementById("stack-inner");
+const springs = Array.from({ length: STEPS }, () => ({ p: 0 }));
+
+function applyTransform() {
+  const sumP = springs.reduce((acc, s) => acc + s.p, 0);
+  innerEl.style.transform = `translateY(${-sumP * ITEM_HEIGHT}px)`;
+}
+applyTransform(); // initial state
+
+springs.forEach((spring, i) => {
+  tl.to(
+    spring,
+    {
+      p: 1,
+      duration: STEP_DUR,
+      ease: `back.out(${BOUNCE_FACTOR})`,
+      onUpdate: applyTransform,
+    },
+    STEP_START + i * STEP_SPACING,
+  );
+});
+```
+
+## Variations
+
+- **Numeric ticker (price / counter rolling)** — items are the digit sequence; run the same spring-step pattern per decimal position. `font-variant-numeric: tabular-nums` required.
+- **Reverse direction (countdown)** — flip the sign (`translateY(${sumP * ITEM_HEIGHT}px)`) and arrange items in reverse order.
+- **Pause between groups** — several fast steps (small `STEP_SPACING`), a long pause, then one dramatic final step with a bigger `BOUNCE_FACTOR`. The pause is where the eye locks in.
+- **Continuous infinite ticker** — NOT this rule (this rule is discrete steps); a looping news ticker is a single linear tween with duplicated items — see [sine-wave-loop.md](sine-wave-loop.md) for continuous-motion semantics.
+
+## Values
+
+| token         | range                 | notes                                                                                 |
+| ------------- | --------------------- | ------------------------------------------------------------------------------------- |
+| ITEM_HEIGHT   | ~`fontSize × 1.25`    | must hold capital descenders; `.ticker` height MUST equal it exactly                  |
+| TICKER_WIDTH  | 30–60% viewport width | wide enough for the longest item without ellipsis                                     |
+| STEPS         | 1–4                   | number of transitions, not items; `STEPS ≤ itemCount − 1`                             |
+| STEP_DUR      | 0.3–0.7s              | under 0.3 the overshoot is invisible; over 0.7 the click reads as a slide             |
+| STEP_SPACING  | 0.3–0.5s              | **≤ STEP_DUR** so springs overlap (additive); wider gaps read as a lazy linear scroll |
+| BOUNCE_FACTOR | 1.4–2.5               | 1.4 gentle click / 2.0 firm / 2.5+ casino spin-and-land for a climax step             |
+
+Reference: `../examples/proof-logo-chain.html` (204px, 1 step, 0.45s).
+
+## Critical Constraints
+
+- **Container height = item height, pixel-exact, all items equal** — mismatches show partial item edges above/below the mask and accumulate drift across steps.
+- **`overflow: hidden` on the container, not the inner stack**; `flex-direction: column` on the stack.
+- **Sum the springs in `onUpdate` — never tween the final position directly.** Each spring contributing its OWN snap is the slot-machine pacing.
+- **Overlap steps and keep `back.out` per step** — non-overlapping steps or an out-only ease collapse into a linear scroll.
+- **Never update items via `innerHTML` between steps** — the ticker moves the SAME items via translate; swapping content shows the previous item AS the new one (broken illusion).
+- **Climax dwell ≥1s after the final step** (SKILL universal constraint).
+- **`tabular-nums` for numeric tickers** — variable digit widths break alignment.
+
+## See also
+
+`reactive-displacement` (ticker pushed by an incoming element) · `scale-swap-transition` (ticker scales out after settling) · `press-release-spring` (button press triggers the spin).

package/dist/assets/design/skills/hyperframes-animation/rules/viewport-change.md

@@ -0,0 +1,148 @@
+---
+name: viewport-change
+description: Virtual camera — simulate zoom / pan / focus-lock by transforming a wrapper around all scene content. Camera moves right → world translates left.
+metadata:
+  tags: viewport, camera, zoom, pan, focus-lock, virtual-camera
+---
+
+# Viewport Change (Virtual Camera)
+
+Simulates camera effects (zoom / pan / focus-lock on a moving element) by transforming a wrapper around ALL scene content. The "world" moves opposite to the perceived camera. Distinct from [multi-phase-camera](multi-phase-camera.md) (2-3 discrete phases + drift) — viewport-change is a single continuous zoom/pan, often used for focus-lock following a moving element.
+
+## How It Works
+
+Camera intent → world transform. Camera **pans right** → world `translateX(-distance)`; camera **zooms in** → world `scale(>1)`; camera **follows element X** → world `translateX(viewportCenter - elementWorldX)` per-frame. Get the sign right or everything moves the wrong way. The single `.world` wrapper holds the camera transform; elements inside are positioned in world space, unchanged.
+
+**Single-element composite transform (this rule's form).** Both scale and translate live on ONE wrapper as `translate(x, y) scale(S)`. CSS applies scale FIRST, then translate (right-to-left matrix composition), so a point at world offset `(ox, oy)` lands on screen at `(S × ox + x, S × oy + y)`. To map the target to viewport center, solve `S × offset + T = 0`:
+
+```
+T = -offset × S
+```
+
+This is **different from [coordinate-target-zoom](coordinate-target-zoom.md)**, which uses two nested wrappers (outer scales, inner translates) and derives `T = -offset` (independent of S). Mixing up the two forms drifts the target off-center as scale changes. Use this single-wrapper form when you want one source of truth for camera state (`cam.scale`, `cam.x`, `cam.y`) written via `onUpdate`; use nested wrappers when scale and translate can tween independently with shared ease.
+
+## Recipe
+
+```html
+<div class="world" id="world">
+  <div class="content">
+    <div class="hero">{Brand}</div>
+    <div class="tagline">{tagline}</div>
+    <div class="cta" id="cta">{ctaUrl}</div>
+  </div>
+</div>
+```
+
+```css
+.scene {
+  overflow: hidden; /* REQUIRED — any non-1.0 scale reveals edges or pushes content off-frame */
+  background: {bgGradient}; /* on .scene, NOT .world — a world-borne background warps with the camera */
+}
+.world {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  transform-origin: 50% 50%; /* centered scaling is what the math assumes */
+  will-change: transform;
+}
+```
+
+```js
+const world = document.getElementById("world");
+
+// Camera state — single source of truth. The world transform is composed from
+// this object in ONE place so the transform string order is stable.
+const cam = { scale: 1, x: 0, y: 0 };
+function applyCamera() {
+  world.style.transform = `translate(${cam.x}px, ${cam.y}px) scale(${cam.scale})`;
+}
+applyCamera(); // seed frame 0
+
+// Zoom in on the CTA: single-element composite transform → T = -offset × S.
+// TARGET_OFFSET_Y is the target's measured offset from viewport center at
+// neutral camera (sign matters — positive = below center).
+const counterY = -TARGET_OFFSET_Y * TARGET_SCALE;
+
+tl.to(
+  cam,
+  {
+    scale: TARGET_SCALE,
+    y: counterY,
+    duration: ZOOM_DUR,
+    ease: "power3.inOut",
+    onUpdate: applyCamera,
+  },
+  ZOOM_START,
+);
+```
+
+## Scale Value Guide
+
+| Effect      | Scale       | Feel                                |
+| ----------- | ----------- | ----------------------------------- |
+| Subtle      | 1.02 - 1.05 | Barely perceptible — "professional" |
+| Medium      | 1.05 - 1.15 | "Ta-da" emphasis                    |
+| Noticeable  | 1.15 - 1.30 | Focus on region                     |
+| Dramatic    | 1.5 - 2.5   | Element fills screen                |
+| Full-screen | 3.0+        | Element covers viewport             |
+
+Perception: < 5% scale change is imperceptible; 10-15% is comfortable emphasis; > 30% is cinematic/dramatic. For a natural product feel, prefer 1.05-1.15× over 2-3s; save big > 1.3× zooms for dramatic narrative moments.
+
+### Extreme range — 4–12× outward (workspace reveal)
+
+The same single-cam math runs far past the table: a zoom-out workspace reveal opens punched-in at **4–12×** on one detail (a single cell, message, or button) and pulls out to the full workspace in one continuous move. The mechanics don't change — one `cam` object, `T = -offset × S`, one `applyCamera()` writer — only the authoring direction does:
+
+- **Build the workspace at its final (1×) layout and OPEN scaled-in** (`cam.scale = 8`, counter-translate aiming the opening detail; state it in a `fromTo` / seed via `applyCamera()` so a seek to t=0 lands punched-in). The wide landing frame is then everything at native design size — text crisp, raster assets at source resolution.
+- **Never the inverse** — authoring the close-up at 1× and scaling the world down to 0.08–0.25 for the wide frame drops every label below legible pixel size and softens raster media; the reveal lands on mush.
+- **Measure the opening target** — at S = 8, a 1 px error in the baked offset is 8 px on screen at the opening pose. Take the offset from the target's real laid-out center (`getBoundingClientRect` after `fonts.ready`, once at setup — the measuring doctrine in [coordinate-target-zoom.md](coordinate-target-zoom.md)), never from a layout formula.
+- **The opening detail must survive ×S** — it renders at `S ×` its design size on the first frames (vector/DOM text is safe; raster needs `sourceResolution ≥ rendered × S`).
+
+## Variations
+
+- **Focus-lock (camera follows a moving cursor/character)** — keep the element at a fixed screen X by computing the world offset per-frame inside the driver's `onUpdate`:
+
+```js
+const focusEl = document.querySelector(".moving-cursor");
+const targetScreenX = VIEWPORT_WIDTH * FOCUS_SCREEN_X_FRAC; // 0.4–0.7; 0.5 = dead center
+const focusUpdate = { p: 0 };
+tl.to(
+  focusUpdate,
+  {
+    p: 1,
+    duration: FOLLOW_DUR, // matches how long the focused element is in motion
+    ease: "power2.inOut",
+    onUpdate: () => {
+      const rect = focusEl.getBoundingClientRect();
+      cam.x = targetScreenX - (rect.left + rect.width / 2);
+      applyCamera();
+    },
+  },
+  FOLLOW_START,
+);
+```
+
+- **Composite scale (multi-phase)** — two proxy tweens multiplied through one writer: `cam.scale = scaleUp.v * scaleDown.v; applyCamera()`. Combine a slow push-in (~1.15) with a brief release (~0.9) for a breath/punch shape.
+- **Camera mode transition (centered → follow)** — crossfade two camera modes via a 0→1 weight tween; intermediate frames interpolate between the modes' offsets.
+
+## Values
+
+| token           | range                                | notes                                                                                       |
+| --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| TARGET_OFFSET_Y | measured, not a free parameter       | target's offset from viewport center at neutral camera; measure via `getBoundingClientRect` |
+| TARGET_SCALE    | 1.3× modest → 1.6–2.0× typical → 3×+ | raster media needs `sourceResolution ≥ rendered × TARGET_SCALE`                             |
+| ZOOM_START      | content landed + ~0.5s scan time     | let the viewer read before the camera moves                                                 |
+| ZOOM_DUR        | 1.0–2.0s                             | under 0.8s teleports, over 2.5s drags                                                       |
+| DWELL           | ≥ 1.0s after the zoom settles        | the viewer must be able to read the focal point (climax dwell)                              |
+| VIEWPORT_WIDTH  | = the root's `data-width`            | real value, not abstract                                                                    |
+
+## Critical Constraints
+
+- **One `.world` wrapper carries the whole camera** — every scene element lives inside it; a second transformed wrapper is a second camera.
+- **Single source of truth via the `cam` object + `applyCamera()`** — when scale and translate both change, write them in ONE place; never split them across tweens that touch `world.style.transform` directly (the transform string composition order becomes unpredictable).
+- **Single-wrapper counter-translate is `T = -offset × S`** — don't import the nested-wrapper `T = -offset` formula.
+- **`overflow: hidden` on `.scene`**; **`transform-origin: 50% 50%` on `.world`**; **background on `.scene`, never on `.world`**.
+
+## See also
+
+[coordinate-target-zoom.md](coordinate-target-zoom.md) (nested-wrapper alternative, `T = -offset`) · [multi-phase-camera.md](multi-phase-camera.md) (viewport-change inside one phase) · [sine-wave-loop.md](sine-wave-loop.md) (idle micro-drift after the viewport settles).

package/dist/assets/design/skills/hyperframes-animation/rules/waterfall-entry.md

@@ -0,0 +1,81 @@
+---
+name: waterfall-entry
+description: Staggered ARRIVAL cascade — words/elements whip in from below (one consistent direction), each starting before the previous settles, an accelerating wave that resolves into a composed layout. Title cards, segment openers, list/feature intros. Opacity is BINARY 0→1 via tl.set — never fade an arrival.
+metadata:
+  tags: entrance, cascade, stagger, kinetic-text, title-card, segment-opener, arrival, waterfall, whip
+---
+
+# Waterfall Entry
+
+Staggered ARRIVAL cascade: words/elements whip in from below (one consistent direction),
+each starting before the previous settles — an accelerating wave that resolves into a
+composed layout. Title cards, segment openers, list/feature intros.
+
+**This is an in-scene arrival, not a seam.** Its seam sibling is the waterfall CUT
+(`cut-the-curve` doctrine skill, `seams/waterfall-cut.md`); do not mix their rules:
+
+|               | Entry (this rule — arrival)                   | Waterfall Cut (seam)                                      |
+| ------------- | --------------------------------------------- | --------------------------------------------------------- |
+| Opacity       | BINARY 0→1 via `tl.set` at entry — never fade | ignites at 0.35 mid-path — the fade IS the velocity trick |
+| Axis default  | Y, from below                                 | X, riding the current                                     |
+| Outgoing side | none                                          | words ramp out on mirrored power4.in                      |
+
+## Choreography
+
+- **Overlap, don't queue** — next element starts within ±2 frames of the previous
+  settling; gaps SHRINK across the cascade; the last element snaps.
+- **Velocity varies by weight** — heavy/anchor elements travel further and longer;
+  light words/punctuation snap in tight:
+
+| Parameter | Anchor/heavy | Normal word | Light/punctuation |
+| --------- | ------------ | ----------- | ----------------- |
+| Y offset  | 60–80px      | 40–50px     | 30–48px           |
+| Duration  | 0.16–0.20s   | 0.13–0.16s  | 0.10–0.13s        |
+| Overlap   | 0–2f gap     | 1f overlap  | 1–2f overlap      |
+
+- Ease `power4.out` (`expo.out` for extra snap); never `.inOut` on an entry.
+- One direction per cascade.
+- Split the FINAL word into fragments to extend the climax; fragments travel further.
+- Post-settle, the group usually slides to make room for the next beat — that's
+  [nudge-curve.md](nudge-curve.md).
+
+## JS
+
+Each element: `tl.set` (instant reveal + offset) then `tl.to` (whip to rest).
+`nextStart = prevStart + prevDuration − (overlapFrames × F)`; +overlap = cascade,
+−overlap = deliberate gap. CSS: elements start `opacity: 0; display: inline-block`.
+
+```js
+var F = 1 / 60;
+var t0 = 0.1;
+// anchor (heaviest): biggest travel, longest settle
+tl.set("#el-1", { opacity: 1, y: 80 }, t0);
+tl.to("#el-1", { y: 0, duration: 0.18, ease: "power4.out" }, t0);
+// normal word: 2 frames after the anchor finishes
+var t1 = t0 + 0.18 + 2 * F;
+tl.set("#el-2", { opacity: 1, y: 45 }, t1);
+tl.to("#el-2", { y: 0, duration: 0.15, ease: "power4.out" }, t1);
+// light word: 1 frame BEFORE the previous finishes (overlap)
+var t2 = t1 + 0.15 - F;
+tl.set("#el-3", { opacity: 1, y: 40 }, t2);
+tl.to("#el-3", { y: 0, duration: 0.14, ease: "power4.out" }, t2);
+// split final-word fragments: tightest overlap, extra travel (lighter)
+var t3 = t2 + 0.14 - F;
+tl.set("#frag-a", { opacity: 1, y: 70 }, t3);
+tl.to("#frag-a", { y: 0, duration: 0.16, ease: "power4.out" }, t3);
+var t4 = t3 + 0.14 - F;
+tl.set("#frag-b", { opacity: 1, y: 70 }, t4);
+tl.to("#frag-b", { y: 0, duration: 0.15, ease: "power4.out" }, t4);
+// punctuation: lightest, fastest
+var t5 = t4 + 0.13 - 2 * F;
+tl.set("#dot", { opacity: 1, y: 48 }, t5);
+tl.to("#dot", { y: 0, duration: 0.12, ease: "power4.out" }, t5);
+```
+
+## Anti-patterns
+
+| Don't                                                  | Instead                                                                           |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| Queued entries (each waits for the previous to settle) | Overlap ±1–2 frames — the cascade is a wave, not a queue                          |
+| Same offset/duration for every cascade element         | Vary by weight: anchors travel further, punctuation snaps                         |
+| Gradual opacity fade on an arrival                     | Binary 0→1 via `tl.set` — fading fights the snap (seam cuts fade; arrivals don't) |

package/dist/assets/design/skills/hyperframes-animation/rules-index.md

@@ -0,0 +1,113 @@
+# Rules Index
+
+Atomic motion recipes. Each lives at `rules/<name>.md`. Compose 2-4 per scene with a single paused timeline.
+
+## The contract — every rule assumes this
+
+Stated once here so individual rules don't repeat it. Every recipe in `rules/`:
+
+- runs on ONE **paused** GSAP timeline registered on `window.__timelines` (never autoplay, never a second timeline);
+- is **seek-safe both directions**: `fromTo` with explicit from-states (t=0 correct under seek; `immediateRender: false` when re-owning a target), absolute values — never relative `+=` tweens; state readable as a pure function of timeline time, no mutable trackers;
+- is **deterministic**: no `Math.random()`, no `Date.now()` — index-derived pseudo-random and baked schedules only; finite repeats, never `repeat: -1`;
+- animates **transforms and paint-only properties** — `width`/`height`/`top`/`left` tweens are forbidden (use scale/translate proxies, masks, or `anchored-layout-expand`);
+- caps group staggers so an arrival reads as one beat (`items × stagger ≤ ~0.5s`);
+- puts **no CSS `transition`** on animated elements (they interpolate independently of seek and flicker) and hints compositors with `will-change: transform` where many tweens run at once;
+- measures DOM (`offsetHeight`, `getBoundingClientRect`) at build time only in a **single-scene** composition — in a multi-scene montage, later clips may not be laid out yet: use authored CSS-matched constants;
+- lives inside a standard scene clip per `hyperframes-core` (`class="clip"` + `data-*` timing) — rule snippets show mechanism DOM only, not the scene scaffold.
+
+A rule's own **Critical Constraints** section lists only what is SPECIFIC to that rule beyond this contract.
+
+## Text & Typography
+
+<rules>
+<hacker-flip-3d path="rules/hacker-flip-3d.md">Character-level 3D rotation with deterministic glyph substitution (decryption). GSAP `back.out` ease + per-glyph `onUpdate` for the flicker hash. Tags: text, 3d, reveal, decode</hacker-flip-3d>
+<vertical-spring-ticker path="rules/vertical-spring-ticker.md">Slot-machine vertical scrolling using stepped GSAP tweens within a masked column. Tags: text, ticker, scroll, vertical</vertical-spring-ticker>
+<counting-dynamic-scale path="rules/counting-dynamic-scale.md">Counter where transform scale grows with the value for escalating emphasis. A numeric proxy and scale tween share one timeline position. Tags: counter, scale, transform, number, dynamic</counting-dynamic-scale>
+<discrete-text-sequence path="rules/discrete-text-sequence.md">Replace entire text states at time thresholds for non-linear typing (typos, holds, bulk additions, backspaces). GSAP onUpdate-driven reverse search. Tags: text, typing, discrete, threshold, non-linear</discrete-text-sequence>
+<asr-keyword-glow path="rules/asr-keyword-glow.md">Highlight keywords with glow + scale + color synced to ASR word timestamps. Two GSAP tweens per word drive a CSS custom property `--glow` through attack-decay-rest envelope. Tags: asr, audio-sync, highlight, glow, keyword, text</asr-keyword-glow>
+<3d-text-depth-layers path="rules/3d-text-depth-layers.md">Multiple offset text layers (N divs at `(i*dx, i*dy)` with decreasing alpha) create a stacked 3D extrusion illusion on large typography. Tags: text, 3d, depth, layers, shadow, typography, stacked</3d-text-depth-layers>
+<context-sensitive-cursor path="rules/context-sensitive-cursor.md">Typing cursor whose `background-color` switches at segment boundaries plus square-wave blink via `(tl.time() % cycle) < cycle/2`. Tags: cursor, color, context, typewriter, styling, segment</context-sensitive-cursor>
+<dynamic-content-sequencing path="rules/dynamic-content-sequencing.md">Pre-compute a flat `[{startTime, endTime, ...}]` array from a script of `{textMain, textAccent, charSpeed, hold}` entries. Each phrase's window = `chars × charSpeed + hold`. Content-driven duration, no hand-tuned offsets. Tags: timeline, sequencing, dynamic, duration, script-driven</dynamic-content-sequencing>
+<kinetic-beat-slam path="rules/kinetic-beat-slam.md">Percussive kinetic typography — short phrases slam in on ONE shared beat array with DISTINCT per-phrase entrances (scale-slam / side-snap / rise-rotate), optional rhythm chrome (metronome ticks, beat bar), then a locked finale. The recipe for "punchy / rhythmic" taglines. Tags: text, kinetic, typography, beat, rhythm, slam, percussive, punchy</kinetic-beat-slam>
+<gradient-text-sweep path="rules/gradient-text-sweep.md">A gradient tweened THROUGH letterforms — `background-clip: text` + an oversized-background `backgroundPosition` tween. Continuous sweep across a held headline, traveling word-to-word highlight (stacked-copy opacity envelopes), or a hue-sweep that settles to a solid via a pixel-identical twin crossfade. Glyphs never move; finite, seek-safe. Tags: gradient, text, sweep, background-clip, highlight, hue, headline</gradient-text-sweep>
+<chromatic-glitch path="rules/chromatic-glitch.md">RGB-split / slice glitch that snaps sharp — offset color copies jitter on a deterministic hash of QUANTIZED timeline time (never Math.random), or horizontal slice bands displace and converge under a stepped ease; brief vibration, clean resolve, clamped rest state. Entrance stretch, emphasis burst, and slice-reveal forms. Tags: glitch, rgb-split, chromatic, slice, jitter, stutter, snap</chromatic-glitch>
+</rules>
+
+## Data & Stats
+
+<rules>
+<counting-dynamic-scale path="rules/counting-dynamic-scale.md">Counter whose transform scale grows with the value; seek-safe `onUpdate`, `Math.round`, `tabular-nums`, multi-stat chord. (Also listed under Text & Typography.) Tags: counter, number, stat, count-up</counting-dynamic-scale>
+<stat-bars-and-fills path="rules/stat-bars-and-fills.md">Data-viz primitives that pair a number with a graphic — growth bars (CSS `scaleY` stagger), progress fill (bar `scaleX` or measured SVG ring), and fractional star-rating wipe (`clip-path`). Transforms only, seek-safe. Pick single-focus vs split-frame and hold it. Tags: data, stats, chart, bars, progress, ring, stars, rating, infographic</stat-bars-and-fills>
+<chart-scrub-readout path="rules/chart-scrub-readout.md">Cursor/playhead scrubs an already-drawn chart — ONE driver moves a vertical tracking line + marker along a baked data polyline while a date/value tooltip steps through the data array (text writes only on index change); second series can activate on cross. Chart arrival belongs to `stat-bars-and-fills` / `svg-path-draw`; this is the read head. Tags: chart, scrub, tooltip, readout, tracking-line, data, playhead</chart-scrub-readout>
+</rules>
+
+## Camera & Viewport
+
+<rules>
+<coordinate-target-zoom path="rules/coordinate-target-zoom.md">Zoom into non-centered elements via scale (outer wrapper) + counter-translation (inner wrapper). Tags: camera, zoom, scale, translate</coordinate-target-zoom>
+<camera-cursor-tracking path="rules/camera-cursor-tracking.md">Two-phase virtual camera that locks the viewport to a moving focal point (typing cursor) — static initial framing then focal-point-locked tracking. Uses browser-native `getBoundingClientRect()` / `ctx.measureText()` after `document.fonts.ready`. Tags: camera, tracking, viewport, two-phase, typing</camera-cursor-tracking>
+<multi-phase-camera path="rules/multi-phase-camera.md">Sequential camera-zoom system (pull-back / focus / push) plus continuous micro-drift. Tags: camera, zoom, phase, drift, scale, cinematic</multi-phase-camera>
+<viewport-change path="rules/viewport-change.md">Virtual camera — simulate zoom / pan / focus-lock by transforming a single `.world` wrapper containing all scene content. Single-element composite transform `translate(x,y) scale(S)`; counter-translate math is `T = -offset × S` (DIFFERENT from coordinate-target-zoom's `T = -offset`). Tags: viewport, camera, zoom, pan, focus-lock</viewport-change>
+<3d-camera-flight path="rules/3d-camera-flight.md">Perspective camera FLIGHT through a 3D-laid-out world — one static `perspective` stage + `preserve-3d` `.world` whose pose (`translate3d` + `rotateX`/`rotateY`) is tweened leg-by-leg from a single camera state object: dive into an angled grid, tilt-to-flatten pull-back, flight past standing cards, decelerate-into-focus. `power4.out` landings, `power2.inOut` repositioning; DoF via depth-of-field-blur on non-focal planes. The only camera rule that rotates/travels in Z (the other three are 2D scale+translate). Tags: camera, 3d, flight, perspective, rotateX, translateZ, dive, tilt</3d-camera-flight>
+<depth-of-field-blur path="rules/depth-of-field-blur.md">Selective rack-focus — GSAP-tween `filter: blur()` (+ slight opacity dim) on off-focus layers via a `--dof` var while the focal element stays sharp; single pull, two-plane rack, or blur-the-cluster-while-pushing-in. Finite, deterministic, seek-safe. Tags: blur, depth-of-field, focus, rack-focus, dim, spotlight</depth-of-field-blur>
+</rules>
+
+## Layout & Network
+
+<rules>
+<avatar-cloud-network path="rules/avatar-cloud-network.md">Avatars on an elliptical ring with SVG connection lines to a center point, staggered entry. Cloud center coordinates must match the centerpiece element exactly. Tags: avatar, cloud, network, social-proof, stagger</avatar-cloud-network>
+<3d-page-scroll path="rules/3d-page-scroll.md">Full webpage rendered as a tilted 3D card whose internal content scrolls to reveal specific sections. Pair with asr-keyword-glow for on-page keyword highlighting. Tags: 3d, page, scroll, webpage, tilt, perspective, product-demo</3d-page-scroll>
+<center-outward-expansion path="rules/center-outward-expansion.md">Elements start clustered at screen center and expand outward to final positions. Each element gets its target position via CSS once; GSAP tweens transform `x` / `y` offsets to 0 in lockstep with a shared driver. Tags: expansion, scatter, center, reveal, layout, sync</center-outward-expansion>
+<split-tilt-cards path="rules/split-tilt-cards.md">Two cards side-by-side with opposing rotationY tilts (+/- baseTilt) and entry slides from their respective sides. Continuous floating runs in phase opposition (`Math.PI` offset). Tags: 3d, cards, split, tilt, comparison, symmetric</split-tilt-cards>
+<orbit-3d-entry path="rules/orbit-3d-entry.md">Elements flip in from 3D space (`rotateX` + `rotateY` + `translateZ`) then settle into a continuous elliptical orbit. **Critical**: entry MUST flip in-place at the orbital starting position (`gsap.set` BEFORE phase 1), not at scene center. Tags: orbit, 3d, flip, ellipse, circular, icon, entry, continuous</orbit-3d-entry>
+<ai-tracking-box path="rules/ai-tracking-box.md">AI detection overlay — yellow `#facc15` L-bracket corners + confidence label (fluctuating 95-99%) following a target on a sine arc path. Box position recomputed per-frame from target position (never tweened separately). Tags: ai, tracking, bounding-box, detection, corner, ml</ai-tracking-box>
+<depth-scatter-assemble path="rules/depth-scatter-assemble.md">N elements scatter into / reassemble from a rotating 3D depth-cloud — each starts at a deterministic index-derived 3D offset (translateZ + rotateX/Y + scatter) and settles to a clean flat layout; tumble-swap and radial-explode variants. preserve-3d + perspective, transform-only, seek-safe. Tags: 3d, scatter, assemble, tumble, depth, perspective, glyphs</depth-scatter-assemble>
+<anchored-layout-expand path="rules/anchored-layout-expand.md">Edge-pinned container grows/collapses along ONE axis and in-flow content reflows — pill springs open into a dropdown, panel grows a sub-task stack, input card steps taller as typed text wraps, pane expands over a neighbor. Transform-only (layout authored expanded; mask + sheet slide, or proxy-driven scaleY + inverse counter-scale) since width/height tweens are forbidden; the push on following content shares the SAME tween so the seam never separates. Tags: expand, collapse, anchored, dropdown, accordion, panel, reflow, push, mask, counter-scale</anchored-layout-expand>
+</rules>
+
+## SVG & Icons
+
+<rules>
+<svg-icon-enrichment path="rules/svg-icon-enrichment.md">Animate internal SVG elements (rotating hands, oscillating blades, pulsing dots, dash-flow lines) so icons feel alive. **Critical**: use SVG `setAttribute('transform', 'rotate(deg cx cy)')` for explicit center — CSS `transform-origin` + `transform-box: fill-box` interprets origin in bbox-local coords (off-center for thin lines). Tags: svg, icon, animation, micro-animation, rotation, pulse</svg-icon-enrichment>
+<svg-path-draw path="rules/svg-path-draw.md">SVG outline draws itself stroke-by-stroke via `stroke-dasharray` / `stroke-dashoffset`. Measure with `getTotalLength()` at composition setup, set initial dashoffset = length, GSAP tweens to 0. For circular progress rings, rotate the stroke `-90deg` so drawing starts at 12 o'clock. Tags: svg, stroke, draw, vector, path, dasharray</svg-path-draw>
+</rules>
+
+## Idle & Ambient
+
+<rules>
+<sine-wave-loop path="rules/sine-wave-loop.md">Continuous breathing/idle ambient motion. Two forms: GSAP `sine.inOut` yoyo with finite repeats (preferred when standalone) or onUpdate reading `tl.time()` (preferred when multiplying onto another live value). Tags: idle, loop, breathing, sine, ambient</sine-wave-loop>
+<ambient-glow-bloom path="rules/ambient-glow-bloom.md">Un-triggered soft radial glow that blooms in behind a hero element and holds with a bounded idle breathe, or a single-pass traveling sheen across a surface. No click, no word-sync; peak opacity ≤ ~0.45, finite/deterministic. Tags: glow, bloom, ambient, radial, sheen, hero</ambient-glow-bloom>
+</rules>
+
+## Transition & Motion
+
+<rules>
+<reactive-displacement path="rules/reactive-displacement.md">Physical-collision transition where an entering element's GSAP tween drives the exiting element's displacement. Three concurrent tweens at the same timeline position with victim durations 40-50% of the intruder's. Tags: transition, physics, collision, displacement, push</reactive-displacement>
+<press-release-spring path="rules/press-release-spring.md">Tactile button press: linear compression then spring recovery via two adjacent GSAP tweens on the same property. Variations: color transition, shadow depth via CSS vars, release burst, background glow. Tags: spring, press, button, interaction, physics, glow, burst</press-release-spring>
+<physics-press-reaction path="rules/physics-press-reaction.md">Physical click simulation — two sequential GSAP scale tweens (down to 0.9, up to 1.0) approximate a spring with overshoot. Pass a single targets array `["#cta", "#cursor"]` to compress both together for tactile contact feel. Tags: spring, click, physics, press, interaction, cursor</physics-press-reaction>
+<cursor-click-ripple path="rules/cursor-click-ripple.md">Animated cursor moves to a target, depresses cursor + target together on click, emits an expanding ripple with attack-decay opacity envelope. Element lives in DOM from t=0 with `opacity: 0` (no conditional rendering). Tags: cursor, click, ripple, interaction, mouse, button, keyframes</cursor-click-ripple>
+<cursor-drag path="rules/cursor-drag.md">The drag verb for driven cursors — grab (press dip + lift), travel (semi-transparent ghost rides the cursor in exact lockstep via matched tweens), drop-snap into a placed field with selection chrome. Variants: fill-handle auto-fill (linear travel + stepped `tl.set` cell reveals), corner-handle proportional resize (uniform scale, origin at the anchor corner — never width/height), grab-lift-reorder (tilt + shadow, neighbor springs into the vacated slot). Tags: cursor, drag, drop, ghost, handle, resize, reorder, snap, interaction</cursor-drag>
+<multi-cursor-choreography path="rules/multi-cursor-choreography.md">N (2–4) labeled independent cursor actors work one canvas simultaneously — collaborative-canvas ambience. Per-actor deterministic waypoint tables (explicit fromTo legs + rests), name-tag pills in distinct colors, grab/drop/hover actions at chorus intensity on an interleaved beat grid (one payoff at a time, zone-partitioned paths, no collisions); camera locked — any pan is the canvas group translating. Tags: cursor, multi-cursor, collaboration, ensemble, canvas, name-tag, choreography, ambient</multi-cursor-choreography>
+<control-target-sync path="rules/control-target-sync.md">Live-sync couple — a scrubbed/typed/picked control and its bound target change in the SAME beat: readout tween + target transform tween share one timeline label, duration, and ease (continuous scrub), or one threshold state array carries both sides (per-keystroke / dropdown-pick steps). Distinct from `reactive-displacement` (collision physics, one-shot transition). Tags: control, scrub, live-sync, mirror, panel, editor, readout, ui</control-target-sync>
+<scale-swap-transition path="rules/scale-swap-transition.md">Coordinated morph between two DOM elements at the same screen center. Exit cluster shrinks + fades; entrance pops in with `back.out(2)` overshoot. Tags: transition, morph, scale, swap</scale-swap-transition>
+<card-morph-anchor path="rules/card-morph-anchor.md">Container morphs apparent size + corner radius + surface treatment between two shots, then fades to reveal the real target underneath. HyperFrames substitutes uniform `scale` for the forbidden `width`/`height` tween, plus paint-only `borderRadius`/`background`/`boxShadow`. Tags: morph, anchor, transition, border-radius, container, shape, handoff</card-morph-anchor>
+<theme-crossfade-morph path="rules/theme-crossfade-morph.md">Whole-theme in-place morph under a fixed anchor — background, typography, radii, icons, chrome and logos blend simultaneously (~0.3s) through N pre-styled skins while one anchor element never moves. Stacked complete layers + opacity-only crossfade, anchor rendered once on top (or per-layer at identical geometry); static camera. Single container instead → `card-morph-anchor`. Tags: theme, skin, crossfade, morph, anchor, reskin, cycle, ui</theme-crossfade-morph>
+<spring-pop-entrance path="rules/spring-pop-entrance.md">The canonical ENTRANCE pop — an element (or staggered group) arrives by springing `scale: 0 → 1` with `back.out` overshoot, `fromTo` so it's correct at t=0 under seek. Single hero, staggered group (≤500ms cap), overshoot tuned by personality. Distinct from `press-release-spring` (a click/press reaction). Tags: spring, entrance, pop, scale-in, overshoot, stagger, arrival</spring-pop-entrance>
+<motion-blur-streak path="rules/motion-blur-streak.md">Fake directional velocity blur on a fast entrance / camera push-through — blur peaks at max speed, resolves to 0 at the settle. Two paths: SVG `feGaussianBlur` stdDeviation on the motion axis (proxy-tweened), or a deterministic echo/ghost trail that collapses into the lead. Entrances / mid-shot only. Tags: motion-blur, streak, velocity, ghost, echo, fast</motion-blur-streak>
+<waterfall-entry path="rules/waterfall-entry.md">Staggered ARRIVAL cascade — words/elements whip in from below, each starting before the previous settles, an accelerating wave that resolves composed. Title cards, segment openers, list intros. Binary 0→1 opacity via `tl.set` — never fade an arrival. Tags: entrance, cascade, stagger, kinetic-text, title-card, arrival, waterfall</waterfall-entry>
+<particle-burst path="rules/particle-burst.md">Deterministic particle / confetti events — confetti pop that bursts up and drifts down on gravity (optional instant-shrink), dot burst from behind text, glyph dissolve to particles. Fixed pool, index-seeded launch values, one `ease: "none"` driver whose onUpdate computes each particle as a pure ballistic function of time — scrub-safe mid-flight, ≤ ~40 particles. Tags: particles, confetti, burst, dissolve, ballistic, deterministic, punctuation</particle-burst>
+<nudge-curve path="rules/nudge-curve.md">Slow-fast-slow three-phase group slide (power3.in ramp → linear burst → power4.out tail, 10/65/25 distance, tail ≥3× ramp-in) to reposition a composed group and reveal content during the burst. Tags: slide, reposition, group-motion, nudge, slow-fast-slow</nudge-curve>
+</rules>
+
+## Effect Recipes (moved from hyperframes-creative)
+
+<rules>
+<gsap-effects path="rules/gsap-effects.md">Drop-in GSAP timeline patterns — typewriter, audio visualizer, and other reusable choreography blocks. Tags: gsap, recipe, drop-in, typewriter, audio-visualizer</gsap-effects>
+<css-marker-patterns path="rules/css-marker-patterns.md">Pure CSS + GSAP implementations of marker-highlight drawing modes — highlight (yellow sweep), circle (hand-drawn ellipse), burst (radiating lines), scribble (chaotic), sketchout (rough rectangle outline). Tags: css, marker, highlight, text, emphasis</css-marker-patterns>
+</rules>
+
+## See Also
+
+- `blueprints-index.md` — the scene-shape templates (this skill's "blueprints") that compose these rules into full shots
+- `techniques.md` — broader motion-design techniques (SVG path drawing, Canvas 2D, CSS 3D, kinetic type, variable fonts, compositing); a few rules cite it
+- `transitions/` — scene-transition catalog (shared skill; story owns `transition_in`, the harness injects it)