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

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

@@ -0,0 +1,149 @@
+---
+name: particle-burst
+description: Deterministic particle / confetti events — a confetti pop that bursts up and drifts down (optionally instant-shrinking away), a dot burst from behind text, or a glyph dissolving to particles. Every particle's state is a pure ballistic function of timeline time from index-seeded values, so a scrub to any t shows the correct mid-flight frame.
+metadata:
+  tags: particles, confetti, burst, dissolve, celebration, ballistic, deterministic, punctuation
+---
+
+# Particle Burst
+
+Discrete flying particles as a one-shot event: a **confetti pop** that erupts upward and drifts back down on gravity, a **dot burst** radiating from behind a landing word, or a **glyph dissolve** where text breaks into particles that scatter and die. Particles are ephemeral garnish — born from a beat, fly, gone; they never become layout.
+
+Boundaries: [css-marker-patterns.md](css-marker-patterns.md)'s burst mode is radiating **drawn lines** — a static accent, no flight. [press-release-spring.md](press-release-spring.md)'s release burst is **one blurred radial layer** faking an explosion — enough when a single glow pop will do. [center-outward-expansion.md](center-outward-expansion.md) moves **real layout elements** to final resting slots; particles have no destination, only physics and a death.
+
+## How It Works
+
+The whole event is **one driver tween and one formula**:
+
+1. **Seeded setup** — a fixed pool of `PARTICLE_COUNT` small divs is created once at composition setup (a deterministic loop — setup-time generation is fine; per-frame DOM creation is not). Each particle `i` derives everything from a pure hash:
+
+   ```js
+   // angle, speed, size, spin, color (palette[i % palette.length]) — all from prand(i * k)
+   const prand = (n) => {
+     const x = Math.sin(n * 127.1 + 311.7) * 43758.5453;
+     return x - Math.floor(x); // 0..1, pure function of n
+   };
+   ```
+
+2. **Ballistic formula** — a proxy tween advances `T: 0 → 1` over `FLIGHT_DUR` with `ease: "none"`; `onUpdate` positions every particle as a **pure function of T**:
+
+   ```
+   x(T) = vx · T·FLIGHT_DUR
+   y(T) = vy · T·FLIGHT_DUR + ½ · G · (T·FLIGHT_DUR)²
+   rot(T) = spin · T·FLIGHT_DUR
+   ```
+
+   Gravity `G` supplies the rise-decelerate-fall arc for free. Because position is computed from `T` (never accumulated per frame), a seek to any moment renders the exact mid-flight state — this is what makes DOM particles seek-safe. The driver's `ease: "none"` is load-bearing: the physics lives in the formula; an eased driver warps gravity and the arc stops reading as thrown objects.
+
+3. **Death** — an opacity tail inside the same formula (fade over the last `FADE_FRAC` of flight), or the confetti signature: a separate **instant-shrink** tween scaling the pool to 0 in a blink at flight end. Either way the particles end invisible and stay invisible.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="burst-stage">
+  <div class="particle-field" id="particle-field"></div>
+  <div class="burst-hero" id="burst-hero">{heroWord}</div>
+</div>
+```
+
+```css
+/* .burst-stage: position: relative; display: grid; place-items: center.
+   .burst-hero: z-index: 2 — particles fly BEHIND the word. */
+.particle-field {
+  position: absolute;
+  z-index: 1;
+  left: 50%;
+  top: 50%; /* the launch origin — offset to taste (e.g. the word's baseline) */
+  width: 0;
+  height: 0;
+}
+.particle {
+  position: absolute;
+  left: 0;
+  top: 0;
+  border-radius: 2px; /* confetti chip; 50% for dots */
+  opacity: 0; /* invisible until the event fires */
+  will-change: transform, opacity;
+}
+```
+
+```js
+// Setup: deterministic pool, generated ONCE.
+const field = document.getElementById("particle-field");
+const palette = ["{accentA}", "{accentB}", "{accentC}"]; // 3-5 brand tokens
+const parts = [];
+for (let i = 0; i < PARTICLE_COUNT; i++) {
+  const el = document.createElement("div");
+  el.className = "particle";
+  const size = SIZE_MIN + prand(i * 3 + 1) * (SIZE_MAX - SIZE_MIN);
+  el.style.width = `${size}px`;
+  el.style.height = `${size * 0.7}px`; // slightly oblong = confetti chip
+  el.style.background = palette[i % palette.length];
+  field.appendChild(el);
+  // Index-seeded launch parameters — the particle's whole life, fixed here.
+  const angle = -Math.PI / 2 + (prand(i * 5 + 2) * 2 - 1) * CONE; // upward cone
+  const speed = SPEED_MIN + prand(i * 7 + 3) * (SPEED_MAX - SPEED_MIN);
+  parts.push({
+    el,
+    vx: Math.cos(angle) * speed,
+    vy: Math.sin(angle) * speed, // negative = up
+    spin: (prand(i * 11 + 4) * 2 - 1) * SPIN_MAX,
+  });
+}
+
+// Confetti pop — one driver, pure ballistic formula.
+const drive = { T: 0 };
+tl.fromTo(
+  drive,
+  { T: 0 },
+  {
+    T: 1,
+    duration: FLIGHT_DUR,
+    ease: "none", // physics lives in the formula, not the ease
+    onUpdate: () => {
+      const t = drive.T * FLIGHT_DUR; // seconds of flight — pure function of T
+      const fade = Math.min(1, (1 - drive.T) / FADE_FRAC); // opacity tail
+      parts.forEach((p) => {
+        const x = p.vx * t;
+        const y = p.vy * t + 0.5 * G * t * t; // rise, stall, drift down
+        p.el.style.transform = `translate(${x}px, ${y}px) rotate(${p.spin * t}deg)`;
+        p.el.style.opacity = String(drive.T === 0 ? 0 : fade); // T===0 guard covers seeks before the event
+      });
+    },
+  },
+  BURST_AT,
+);
+```
+
+## Variations
+
+- **Confetti pop, then instant-shrink** — the playful signature: full burst, gravity drift, then every chip scales to 0 in a blink: `FADE_FRAC` near 0, plus `tl.to(".particle", { scale: 0, duration: SHRINK_DUR, ease: "power2.in" }, BURST_AT + FLIGHT_DUR - SHRINK_DUR)` with `SHRINK_DUR` 0.15–0.25s. Keep the whole event tiny relative to the subject — a garnish measured in a few dozen pixels, not a screen-filling cannon.
+- **Dot burst behind a landing word** — radial instead of a cone: `angle = prand(i) * Math.PI * 2`, `G` near 0, short flight (0.4–0.7s), round dots (`border-radius: 50%`), pool z-indexed behind the word. Fire at the word's settle frame.
+- **Glyph dissolve** — seed each particle's **origin** across the glyph block's box (`ox = (prand(i*13) - 0.5) * BLOCK_W`, same for `oy`, added inside the transform), gentle outward drift with low `G`; text fades out over the first ~30% of flight while particles fade in from its silhouette. Color every particle `{textColor}` so the swarm reads as the text's own material. (True per-pixel dissolves are Canvas-2D territory — `techniques.md`; this DOM version sells it up to ~40 particles.)
+- **Two-stage burst (pop + stragglers)** — split the pool: 70% on the main driver, 30% on a second driver ~0.12s later with lower speeds; the split is index-derived (`i % 10 < 3`). Same formula, two windows.
+
+## Values
+
+| token                 | range                                        | notes                                                                           |
+| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------- | --- | ----------------------- |
+| PARTICLE_COUNT        | 10–18 pop/dots; 24–40 dissolve               | **cap ~40** — per-frame style writes; past that, seek perf and register degrade |
+| G                     | 900–1600 px/s² confetti; 0–200 dots/dissolve | natural fall vs drift                                                           |
+| SPEED_MIN / SPEED_MAX | 250–700 px/s                                 | per-particle via `prand`, never uniform                                         |
+| CONE                  | 0.35–0.8 rad (~20–45°)                       | wider = splash, narrower = fountain                                             |
+| FLIGHT_DUR            | 0.7–1.4s                                     | arc should peak ~35–45% of flight: check `                                      | vy  | / G ≈ 0.4 × FLIGHT_DUR` |
+| SIZE_MIN / SIZE_MAX   | 5–14px chips; 4–8px dots                     | on a 1080p frame                                                                |
+| SPIN_MAX              | 180–720 deg/s confetti; 0 dots               | tumble                                                                          |
+| FADE_FRAC             | 0.2–0.35                                     | near 0 when using instant-shrink                                                |
+| BURST_AT              | on a cause                                   | the word's settle, a click, a lockup completing — an uncaused burst is noise    |
+
+## Critical Constraints
+
+- **Position is a pure function of time, driver ease `"none"`** — `x(T)`, `y(T)`, `rot(T)` computed from the driver value every frame, never accumulated (`+=`) per tick (accumulation breaks the moment the renderer seeks); gravity is the ease — an eased driver bends the parabola.
+- **Fixed pool, no per-frame DOM** — all particles exist after setup with `opacity: 0`; the event only writes `transform` / `opacity`. **`PARTICLE_COUNT ≤ ~40`** — per-frame style writes scale linearly; keep the event cheap.
+- **Particles start AND end at `opacity: 0`** — the `drive.T === 0` guard covers seeks to before the event; the tail/shrink covers after. A chip frozen mid-air at driver end is a bug every subsequent frame.
+- **Particles are punctuation** — one event per beat, fired on a cause, small relative to the subject, dead before the next beat; z-ordered behind or around the word it celebrates, never over it. A persistent particle system is a background, and that's not this rule.
+
+## See also
+
+`spring-pop-entrance` (confetti fires on the hero's settle frame) · `kinetic-beat-slam` (one beat earns the confetti payoff) · `press-release-spring` (single-layer glow alternative, or compose both) · `css-marker-patterns` (drawn-line burst when the accent should feel hand-annotated) · `scale-swap-transition` (glyph dissolve covers the exit).

package/dist/assets/design/skills/hyperframes-animation/rules/physics-press-reaction.md

@@ -0,0 +1,101 @@
+---
+name: physics-press-reaction
+description: Cursor + element synchronized press via subtractive spring forces — cursor lands on element, both compress together, then release. Distinct from press-release-spring (which has no cursor).
+metadata:
+  tags: spring, click, physics, cursor, subtractive, interaction, synchronized
+---
+
+# Physics Press Reaction (Cursor + Element Synced)
+
+Models a real click: a cursor approaches a button, lands, and both compress IN SYNC, then release together. Distinct from [press-release-spring.md](press-release-spring.md) (no cursor — just a press happening); this rule is the COMBINED cursor + element behavior. A single `PRESS_INTENSITY` drives both: press down compresses both to `1 - PRESS_INTENSITY` via **one targets array**, release springs both back to 1.0 with overshoot. The cursor translates to the button's center BEFORE the press starts; after release it may move on or hold.
+
+## Recipe
+
+```html
+<button class="btn" id="btn">{ctaCopy}</button>
+<!-- Cursor at scene-root level so it translates freely; arrow TIP is the click
+     point, so transform-origin: 0 0 — scaling around the tip keeps it stable. -->
+<svg class="cursor" id="cursor" style="pointer-events: none; transform-origin: 0 0">…</svg>
+```
+
+```js
+gsap.set("#cursor", { x: CURSOR_START_X, y: CURSOR_START_Y }); // off-screen / far corner
+
+// Phase 1 — approach
+tl.to(
+  "#cursor",
+  { x: BUTTON_CENTER_X, y: BUTTON_CENTER_Y, duration: APPROACH_DUR, ease: "power2.inOut" },
+  APPROACH_START,
+);
+
+// Phase 2 — coordinated press down: ONE targets array, same scale
+tl.to(
+  ["#btn", "#cursor"],
+  { scale: 1 - PRESS_INTENSITY, duration: PRESS_DOWN_DUR, ease: "power1.in" },
+  PRESS_DOWN_AT,
+);
+
+// Phase 3 — release: both spring back together
+tl.to(
+  ["#btn", "#cursor"],
+  { scale: 1, duration: RELEASE_DUR, ease: `back.out(${BOUNCE_FACTOR})` },
+  RELEASE_AT,
+);
+
+// Phase 4 — inner glow during press, resting shadow on release (contact confirmation)
+tl.to(
+  "#btn",
+  { boxShadow: "{btnPressedShadow}", duration: PRESS_DOWN_DUR, ease: "power1.in" },
+  PRESS_DOWN_AT,
+);
+tl.to(
+  "#btn",
+  { boxShadow: "{btnRestingShadow}", duration: RELEASE_DUR, ease: "power2.out" },
+  RELEASE_AT,
+);
+
+// Cursor optionally exits after the press settles
+tl.to(
+  "#cursor",
+  { x: CURSOR_EXIT_X, y: CURSOR_EXIT_Y, duration: CURSOR_EXIT_DUR, ease: "power2.out" },
+  CURSOR_EXIT_AT,
+);
+```
+
+## Variations
+
+- **Multiple-element chain press** — press button A → A triggers a swap → cursor moves to button B → presses again; each press is one full down-release sub-routine.
+- **Hold press (continuous pressure)** — insert a `HOLD_DUR` window between press-down and release: both scales stay at `1 - PRESS_INTENSITY`, inner glow stays on. Suggests "thinking" or "loading."
+- **Synchronized inner-glow pulse** — during the hold, pulse the inset glow with a sine driver: a `{ p: 0 }` proxy tweened to `Math.PI * GLOW_PULSE_CYCLES * 2` on `ease: "none"`, `onUpdate` writing `boxShadow` with `alpha = GLOW_BASE_ALPHA + sin(p) * GLOW_PULSE_AMP`. Suggests "processing."
+
+## Values
+
+| token               | range / rule                             | notes                                                                                  |
+| ------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
+| APPROACH_START      | 0–0.3 s                                  | long delays read as a dead frame                                                       |
+| APPROACH_DUR        | 0.7–1.3 s                                | faster = urgent, slower = deliberate                                                   |
+| PRESS_DOWN_AT       | `= APPROACH_START + APPROACH_DUR`        | cursor arrives exactly as the press begins — avoids "tapping on air"                   |
+| PRESS_DOWN_DUR      | 0.1–0.25 s                               |                                                                                        |
+| RELEASE_AT          | > `PRESS_DOWN_AT + PRESS_DOWN_DUR`       | optional 0.05–0.4 s hold (or `HOLD_DUR` 0.3–0.8 s) for "thinking" interactions         |
+| RELEASE_DUR         | 0.4–0.7 s                                | long enough for the overshoot to settle                                                |
+| PRESS_INTENSITY     | 0.05 subtle · 0.10 standard · 0.15 heavy | applied to both cursor and button via the single targets array                         |
+| BOUNCE_FACTOR       | 1.6 soft · 2.0 firm · 2.4 cartoony       |                                                                                        |
+| CURSOR_START / EXIT | off-screen or far corner                 | the approach must read as motion-in, not a teleport; exit ≥ `RELEASE_AT + RELEASE_DUR` |
+| BUTTON_CENTER       | measured                                 | for `place-items: center` at 1920×1080: `(960, 540)`                                   |
+| BRAND_REVEAL_AT     | < `PRESS_DOWN_AT`                        | context precedes interaction                                                           |
+| glow pulse          | 1–4 cycles; base α 0.15–0.3; amp 0.1–0.2 | `GLOW_BASE_ALPHA − GLOW_PULSE_AMP ≥ 0`                                                 |
+| CURSOR_SIZE         | 48–96 px at 1080p                        |                                                                                        |
+
+## Critical Constraints
+
+- **Same press scale on cursor AND button** (one targets array) — only the button scaling makes the cursor "tap on air"; only the cursor scaling makes the button feel disconnected.
+- **Cursor arrives BEFORE the press starts** — a clear "cursor over target" moment, or the press is unattributed.
+- **`back.out(BOUNCE_FACTOR)` on the release, for both together** — a linear release loses the tactile feel; release MUST come after press.
+- **Inner glow appears DURING press, fades on release** — outer shadow shrinks (pushed in), inner glow appears (energy concentrated).
+- **Cursor `transform-origin: 0 0`** — the arrow's tip is the click point; scale around the tip keeps it stable. `pointer-events: none` on the cursor.
+- **Climax dwell ≥ 1 s** — after release the composition must continue ≥ 1 s; the press is a beat, the viewer needs time to see the result.
+- **No real `mouseenter` / `click` events** — HF is a render context; everything runs via the timeline.
+
+## See also
+
+`press-release-spring` (the BUTTON-only press; this rule layers the cursor on top) · `cursor-click-ripple` (adds a ripple at the click point) · `scale-swap-transition` (the press TRIGGERS the swap).

package/dist/assets/design/skills/hyperframes-animation/rules/press-release-spring.md

@@ -0,0 +1,108 @@
+---
+name: press-release-spring
+description: Tactile button press with linear compression, spring-based elastic recovery, and layered visual feedback (shadow shrink + release burst + background glow).
+metadata:
+  tags: spring, press, interaction, button, physics, glow, burst, ui
+---
+
+# Press-Release Spring Chain
+
+Separates input (linear compression) from output (spring recovery) to create tactile feel: the overshoot is a natural byproduct of the spring config, not manually coded, with secondary motion (shadow shrink, release burst, background glow) layered on the same trigger frame. This is a **reaction on an element already resting on screen** — an arrival that springs in from nothing is [spring-pop-entrance.md](spring-pop-entrance.md); add a visible cursor actor and it becomes [physics-press-reaction.md](physics-press-reaction.md).
+
+Two phases split at the **release**:
+
+1. **Press**: linear ease → compression (`scale: 1 → PRESS_SCALE`, shadow shrinks). Linear, not spring — the dip must read as instant/tactile, not squishy.
+2. **Release**: `back.out(BOUNCE_FACTOR)` spring back to 1.0. Optional burst glow ring expands behind the button; optional environmental glow fades in.
+
+State continuity is critical: the release tween's start value MUST equal the press tween's end value, or the spring snaps to a different position. GSAP threads this automatically when both tweens target the same property at **adjacent positions** — `RELEASE_START = PRESS_START + PRESS_DUR`; a gap or overlap breaks it.
+
+## Recipe
+
+```html
+<div class="press-stage">
+  <div class="bg-glow" id="bg-glow"></div>
+  <!-- Burst sits BEHIND the button (z-index 1 vs 2), same footprint, blurred
+       radial gradient, opacity 0. bg-glow is a full-stage radial at negative
+       inset so it extends past the stage edges. -->
+  <div class="burst" id="burst"></div>
+  <button class="btn" id="btn">{buttonLabel}</button>
+</div>
+```
+
+```js
+// Phase 1 — press (linear compression)
+tl.to(
+  "#btn",
+  { scale: PRESS_SCALE, boxShadow: "{btnPressedShadow}", duration: PRESS_DUR, ease: "power1.in" },
+  PRESS_START,
+);
+
+// Phase 2 — release (spring back; start scale == PRESS_SCALE by adjacency)
+tl.to(
+  "#btn",
+  {
+    scale: 1,
+    boxShadow: "{btnRestShadow}",
+    duration: RELEASE_DUR,
+    ease: `back.out(${BOUNCE_FACTOR})`,
+  },
+  RELEASE_START,
+);
+
+// Phase 3 — burst glow pops behind the button, then fades
+tl.fromTo(
+  "#burst",
+  { scale: 1, opacity: 0 },
+  {
+    scale: BURST_PEAK_SCALE,
+    opacity: BURST_PEAK_OPACITY,
+    duration: BURST_GROW_DUR,
+    ease: "power2.out",
+  },
+  RELEASE_START,
+);
+tl.to("#burst", { opacity: 0, duration: BURST_FADE_DUR, ease: "power2.in" }, BURST_FADE_START);
+
+// Phase 4 — environmental glow fades in after release
+tl.to(
+  "#bg-glow",
+  { opacity: BG_GLOW_PEAK_OPACITY, duration: BG_GLOW_FADE_DUR, ease: "power2.out" },
+  RELEASE_START,
+);
+```
+
+## Variations
+
+- **Subtle press** (status save / muted CTA): `PRESS_SCALE` ~0.96, `BOUNCE_FACTOR` ~1.4, burst scale/opacity reduced.
+- **Dramatic press** (hero CTA / "ship it"): `PRESS_SCALE` ~0.88, `BOUNCE_FACTOR` ~2.5, burst maxed.
+- **Color shift during press** — darken mid-press, return on release; interpolated `backgroundColor` at the same timeline positions as the scale tweens. Same state-continuity rule.
+- **State change at release** (approve / confirm) — instead of returning to the rest color, swap to `{successColor}` at `RELEASE_START` and pop a checkmark via a separate `back.out(CHECK_BOUNCE)` tween (1.4–2.0, firmer than the button's bounce — a punctuating "stamp"; pop 0.3–0.6 s) at the same position. The button is now terminal — no further presses expected.
+
+## Values
+
+| token                | range                                      | notes                                                                                      |
+| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| button footprint     | ≥ 3–5% of canvas area                      | a 320×68 button at 1080p is ~1% and the press reads as visually insignificant              |
+| PRESS_SCALE          | 0.88 dramatic · 0.92 default · 0.96 subtle | never <0.85 (broken) or >0.98 (no perceptible dip)                                         |
+| PRESS_DUR            | 0.10–0.30 s                                | shorter = snappier; must be shorter than `RELEASE_DUR` (input faster than spring recovery) |
+| RELEASE_DUR          | 0.40–0.90 s                                | shorter = tight pop; longer = loose, wobbly settle                                         |
+| BOUNCE_FACTOR        | 1.4 soft · 2.0 firm · 2.8 cartoony         | or `elastic.out(amplitude, period)` for a rubbery oscillation instead of one overshoot     |
+| RELEASE_START        | `= PRESS_START + PRESS_DUR`                | adjacency = automatic state continuity                                                     |
+| BURST_PEAK_SCALE     | 3 subtle · 6 default · 8 max               | beyond ~8 the radial gradient pixelates visibly                                            |
+| BURST_PEAK_OPACITY   | 0.4–1.0                                    | grow ≈ fade, 0.4–0.7 s each; blur 40–100 px (hard ring → ambient haze)                     |
+| BG_GLOW_PEAK_OPACITY | 0.1 subtle · 0.25 default · 0.45 max       | higher washes the whole composition; fade-in 0.6–1.0 s; inset −300…−500 px at 1080p        |
+
+Color tokens: pressed surface darker than rest; rest shadow large + diffuse, pressed small + tight (the button "sinks toward the surface"); burst gradient darker + more saturated than `{btnBg}` — same-color glow looks washed out; bg glow a low-opacity tint of the button's hue family.
+
+## Critical Constraints
+
+- **State continuity** — release start value exactly equals press end value; enforced by same-property adjacency at `RELEASE_START = PRESS_START + PRESS_DUR`.
+- **Linear press, spring release** — both spring → squishy; both linear → mechanical, no overshoot punch.
+- **Anchor compression on center** (`transform-origin: 50% 50%`) or the button collapses asymmetrically.
+- **Burst behind, not in front** — burst `z-index: 1`, button `z-index: 2`; in front it occludes the button at peak opacity.
+- **Don't tween `boxShadow` and `filter` on the same element** — they compete in the layout pipeline; shadow on the button, blur on the separate burst layer.
+- **Climax dwell** — after the burst peak + reveal, the composition must run ≥ 1 s more (≥ 2 s for dramatic variants); a reveal at `t = DURATION − 0.2 s` reads as "flashed and gone."
+
+## See also
+
+`spring-pop-entrance` (the ENTRANCE counterpart — arrival, not reaction) · `physics-press-reaction` (this press with a visible cursor actor) · `cursor-click-ripple` (the cursor click that triggers the press) · `sine-wave-loop` (idle micro-float BEFORE the press) · `center-outward-expansion` (badge burst synced to the release).

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

@@ -0,0 +1,92 @@
+---
+name: reactive-displacement
+description: Physical collision where an entering element's spring drives the exiting element's displacement — single source of truth makes the motion causally linked.
+metadata:
+  tags: transition, physics, collision, displacement, spring, causal
+---
+
+# Reactive Displacement
+
+Exit animation of element A is mathematically DERIVED from the entry spring of element B — a causal link: "A moves _because_ B hit it." Distinct from [scale-swap-transition.md](scale-swap-transition.md) (which overlaps but isn't causal) and [card-morph-anchor.md](card-morph-anchor.md) (one container morphing).
+
+A single 0→1 driver tween (the "entry spring") feeds three concurrent derived motions in one `onUpdate`:
+
+- **Intruder** (B, entering): position interpolated off-stage → settled over the full driver, plus tilt settling to 0° and a sharp early opacity reveal.
+- **Victim** (A, exiting): position interpolated settled → off-stage in the OPPOSITE direction, completing at `VICTIM_FRACTION` (~0.4–0.5) of the driver — NOT 1.0.
+
+The victim finishing BEFORE the intruder's entry creates the "hit then settle" rhythm; sharing one eased driver makes the impact moment mathematically synchronized.
+
+## Recipe
+
+```js
+// Both cards absolutely centered; overflow: hidden on the scene (off-stage travel);
+// will-change: transform, opacity on both; intruder z-index ABOVE victim.
+const INTRUDER_START_X = STAGE_W; // off-stage right
+const VICTIM_END_X = -STAGE_W; // off-stage left — SAME axis, opposite direction
+
+gsap.set("#victim", { x: 0, opacity: 1, rotation: 0 });
+gsap.set("#intruder", { x: INTRUDER_START_X, opacity: 0, rotation: -INTRUDER_TILT });
+
+const driver = { p: 0 };
+tl.to(
+  driver,
+  {
+    p: 1,
+    duration: DRIVER_DUR,
+    ease: `back.out(${BOUNCE_FACTOR})`, // the intruder spring
+    onUpdate: () => {
+      // Intruder: full 0→1 progress maps enter (off-stage → center)
+      const intruderX = INTRUDER_START_X * (1 - driver.p);
+      const intruderOpacity = Math.min(1, driver.p * FADE_IN_SHARPNESS);
+      const intruderRot = -INTRUDER_TILT * (1 - driver.p); // settles to 0°
+      const intruder = document.getElementById("intruder");
+      intruder.style.transform = `translate(-50%, -50%) translateX(${intruderX}px) rotate(${intruderRot}deg)`;
+      intruder.style.opacity = String(intruderOpacity);
+
+      // Victim: completes its exit at VICTIM_FRACTION of the driver — by the
+      // time the intruder centers, the victim is already off-stage.
+      const victimP = Math.min(1, driver.p / VICTIM_FRACTION);
+      const victimX = VICTIM_END_X * victimP;
+      const victim = document.getElementById("victim");
+      victim.style.transform = `translate(-50%, -50%) translateX(${victimX}px)`;
+      victim.style.opacity = String(1 - victimP);
+    },
+  },
+  DRIVER_AT,
+);
+// Climax dwell — intruder holds centered for ≥ DWELL_MIN before the scene ends.
+```
+
+## Variations
+
+- **Impact rotation on victim** — the victim also rotates as it slides: `const victimRot = victimP * -VICTIM_KICK_DEG;` appended to its transform. `VICTIM_KICK_DEG` 15–25°, magnitude matched to the perceived intruder weight.
+- **Vertical collision** — intruder from top, victim displaced downward; same math on Y. Reads as "weight dropped on it."
+- **Wobble after settle** — after the intruder centers, a damped sine wobble (`±WOBBLE_AMP_DEG` rotation, linearly decaying over `WOBBLE_DUR` via a second `ease: "none"` driver at `DRIVER_AT + DRIVER_DUR`) before stillness — "impact aftermath."
+- **Multi-victim ripple** — the intruder displaces multiple aligned cards, each victim's `victimP` on a slightly offset driver phase (cascade ripple).
+
+## Values
+
+| token             | range                  | notes                                                                                                      |
+| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
+| DRIVER_AT         | phase-dependent        | after the prior reading beat resolves; must leave ≥ DWELL_MIN of climax dwell before the scene ends        |
+| DRIVER_DUR        | 0.6–1.4 s              | short = zippy punch, long = heavy landed impact; higher bounce on long durations reads as floaty           |
+| BOUNCE_FACTOR     | 1.2–2.0 (typ. 1.4–1.6) | stay in the `back.out` family (or `elastic.out` for oscillation) — changing family rewrites the feel       |
+| VICTIM_FRACTION   | 0.4–0.5                | <0.4 the victim disappears before the impact reads; >0.5 feels parallel, not causal; hard cap ~0.6         |
+| STAGE_W           | ≥ composition width    | smaller leaves the off-stage element partially visible at start                                            |
+| INTRUDER_TILT     | 5–15° (typ. ~10°)      | low = clean glide, high = "spin-and-plant"; sign consistent with entry direction (momentum transfer)       |
+| FADE_IN_SHARPNESS | 3–8                    | intruder reaches opacity 1 at `1/FADE_IN_SHARPNESS` of progress; must be > 1 or it's transparent at center |
+| DWELL_MIN         | ≥ 1.0 s (typ. 1.0–1.5) | post-impact dwell is where the new content gets read — do not skip                                         |
+
+## Critical Constraints
+
+- **Single driver = single source of truth** — both motions computed inside ONE driver's `onUpdate`, never separate `tl.to()` calls per element; independent tweens destroy the causal link (they'd merely be near each other in time).
+- **Victim completes at a fraction of the driver** — the "hit" is the overlap moment; after it the victim is just vacating space the intruder will fill.
+- **Directional momentum transfer** — same axis, opposite directions; different axes read as passing, not colliding.
+- **Intruder z-index above victim** — explicit, not DOM order; otherwise the victim looks like it tunneled through.
+- **Intruder enters tilted, settles flat** — small initial tilt → 0° reads as "spinning in then planting."
+- **Climax dwell after impact** — the impact is the headline beat; hold the settled intruder ≥ DWELL_MIN.
+- **`overflow: hidden` on the scene** — off-stage motion exceeds the frame.
+
+## See also
+
+`control-target-sync` (the live-editing mirror — repeated coupled edits, nothing exits) · `hacker-flip-3d` (intruder text reveal during entry) · `sine-wave-loop` (idle breathing during the dwell) · `vertical-spring-ticker` (a ticker that "shoves" the previous content out).

package/dist/assets/design/skills/hyperframes-animation/rules/scale-swap-transition.md

@@ -0,0 +1,88 @@
+---
+name: scale-swap-transition
+description: Coordinated shrink-out + spring pop-in morph-like transition between two elements — no SVG path interpolation needed.
+metadata:
+  tags: transition, morph, scale, swap, spring, pop
+---
+
+# Scale-Swap Transition
+
+Simulates a "morph" between two DOM elements by overlapping exit and entrance scale animations. Lighter weight than [card-morph-anchor.md](card-morph-anchor.md) (which morphs container dimensions — use that for SHAPE changes; this rule is for SAME-shape state swaps) and easier than SVG path interpolation.
+
+At a single trigger, two coordinated tweens fire:
+
+1. **Outgoing**: scale `1.0 → EXIT_SCALE` + opacity `1 → 0`, fast `power2.in` (rushing away).
+2. **Incoming**: scale `EXIT_SCALE → 1.0` + opacity `0 → 1`, `back.out(BOUNCE_FACTOR)` (arriving with weight).
+
+A small `OVERLAP` window during which both are mid-tween creates the morph illusion; the incoming sits on top via z-index so the outgoing's fade-tail doesn't bleed through.
+
+## Recipe
+
+```html
+<!-- Both cards position: absolute; inset: 0 in one fixed-size wrapper — same
+     footprint, same transform-origin: 50% 50%. Incoming starts opacity: 0,
+     transform: scale(EXIT_SCALE), z-index above the outgoing. -->
+<div class="swap-wrap">
+  <div class="card outgoing" id="outgoing">{outgoingIcon} {outgoingLabel}</div>
+  <div class="card incoming" id="incoming">
+    {incomingIcon} {incomingLabel}
+    <div class="sub" id="sub">{incomingSubline}</div>
+  </div>
+</div>
+```
+
+```js
+// Outgoing: shrink + fade fast
+tl.to(
+  "#outgoing",
+  { scale: EXIT_SCALE, opacity: 0, duration: EXIT_DUR, ease: "power2.in" },
+  TRIGGER,
+);
+
+// Incoming: pops in with overshoot, starting OVERLAP before the exit finishes
+tl.to(
+  "#incoming",
+  { scale: 1.0, opacity: 1, duration: ENTER_DUR, ease: `back.out(${BOUNCE_FACTOR})` },
+  TRIGGER + EXIT_DUR - OVERLAP,
+);
+
+// Inner content reveals AFTER the incoming settles
+tl.fromTo(
+  "#sub",
+  { opacity: 0, y: SUB_REVEAL_Y_PX },
+  { opacity: 1, y: 0, duration: SUB_REVEAL_DUR, ease: "power3.out" },
+  TRIGGER + EXIT_DUR + SUB_REVEAL_DELAY,
+);
+```
+
+## Variations
+
+- **Delayed inner content reveal** — the classic pattern above: morph the container, then reveal inner text once it settles; the 0.2–0.4 s gap lets the eye land on the new shape before reading.
+- **Triple swap (3-state cycle)** — chain A→B→C with triggers `TRIGGER_AB` / `TRIGGER_BC`; each transition is its own tween pair, the previous incoming becoming the next outgoing. State-evolution narratives (early → mid → final labels).
+- **Color-shift transition (no scale)** — for a flat morph between same-shape states, drop the scale and keep opacity + a brief background hue tween; less dramatic, more product-UI tone.
+
+## Values
+
+| token            | range                                 | notes                                                                                                  |
+| ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| TRIGGER          | ≥ outgoing settled + a presence-dwell | the outgoing must "land" before transforming                                                           |
+| EXIT_DUR         | 0.3–0.5 s                             |                                                                                                        |
+| ENTER_DUR        | 0.45–0.7 s                            | longer than `EXIT_DUR` so the overshoot can settle                                                     |
+| OVERLAP          | 0.1–0.2 s                             | >0.3 s both are clearly visible together (no morph); <0.05 s leaves a visible empty gap                |
+| EXIT_SCALE       | 0.6–0.8                               | smaller exits feel dramatic but risk reading as "vanish" instead of "morph"                            |
+| BOUNCE_FACTOR    | 1.4 soft · 1.8 firm · 2.2 cartoony    |                                                                                                        |
+| SUB_REVEAL_DELAY | 0.2–0.4 s                             | reveals during the morph compete with the swap for attention                                           |
+| BRAND_REVEAL_AT  | < TRIGGER                             | context (brand, eyebrow) sets the stage early; revealed AT the swap it competes with the headline beat |
+
+## Critical Constraints
+
+- **Incoming z-index ABOVE outgoing** — otherwise the outgoing's fade-tail (opacity 0.3–0.5) bleeds through and double-exposes the frame.
+- **Both elements share `transform-origin: 50% 50%`** — different origins make the morph read as one thing teleporting elsewhere.
+- **Bouncy ease ONLY on the incoming** — outgoing `power2.in`, incoming `back.out`; reversed, the swap feels mechanical.
+- **Both cards `position: absolute; inset: 0`** in the same fixed-size wrapper (sized to fit both states; the wrap never resizes).
+- **Don't `display: none` the outgoing** after the fade — leave it at `opacity: 0` so layout doesn't reflow.
+- **Inner content reveals after the container settles**; **climax dwell ≥ 1 s** after the final state + subline land.
+
+## See also
+
+`press-release-spring` (a button press TRIGGERS the swap — cause and effect) · `card-morph-anchor` (shape-changing alternative) · `reactive-displacement` (when the replacement should read as a causal collision) · `sine-wave-loop` (idle breathing on the final state).

package/dist/assets/design/skills/hyperframes-animation/rules/sine-wave-loop.md

@@ -0,0 +1,85 @@
+---
+name: sine-wave-loop
+description: Bounded sine-driven idle — subtle jitter or a single genuinely-needed bounded ambient breath on a held element. De-emphasized: circular breathing as "aliveness" is cheap; prefer sequential reveal timed to the VO, then subtle jitter, before reaching here.
+metadata:
+  tags: idle, jitter, bounded-ambient, sine, trigonometry, low-amplitude, post-entry
+---
+
+# Sine Wave Loop (subtle jitter / bounded ambient)
+
+> **Reach for this last.** Per the motion doctrine (`references/motion-language.md`): circular breathing — scaling text/cards up and down to look "alive" — is cheap, the agent's reflexive cheat, and reads weak. "I'd rather have NO motion than BAD motion." First fill the back of a shot with **sequential reveal timed to the VO**; if a frame has genuinely settled and still needs life, the **sanctioned move is subtle jitter** — this rule at the LOW end of its amplitude range. A full breathing loop is the rare last resort on a single held hero, never stamped on every element.
+
+Keeps a settled element from feeling dead using `Math.sin` on the timeline clock. Two forms:
+
+- **Yoyo form** — one `sine.inOut` tween with `yoyo: true` and a **finite** `repeat` count. Preferred when the idle stands alone on a property nothing else touches.
+- **onUpdate form** — one long `ease: "none"` tween drives a `phase` proxy `0 → 2π·CYCLES`; `onUpdate` maps `Math.sin(phase)` into the transform. Required when the offset multiplies/adds onto another live value (compound transforms, amplitude envelopes, multi-octave).
+
+Either way, idle begins where the entry settled: at `phase = 0`, `sin(0) = 0` — the offset is zero, so there is no jump from the entry's resting state.
+
+## Recipe
+
+```js
+// onUpdate form — phase-driven, composable.
+const phase = { p: 0 };
+tl.to(
+  phase,
+  {
+    p: Math.PI * 2 * CYCLES,
+    duration: IDLE_DUR,
+    ease: "none", // sine provides the easing; a non-linear phase tween distorts the wave
+    onUpdate: () => {
+      const s = Math.sin(phase.p);
+      hero.style.transform = `translateY(${s * Y_AMP_PX}px) scale(${1 + s * SCALE_AMP})`;
+      // secondary elements: offset by Math.PI / 2 — synced motion looks mechanical
+      dot.style.transform = `scale(${1 + Math.sin(phase.p + Math.PI / 2) * DOT_SCALE_AMP})`;
+    },
+  },
+  IDLE_START_TIME,
+);
+
+// Yoyo form — standalone property, finite repeats.
+tl.to(
+  "#badge",
+  { y: -Y_AMP_PX, duration: PERIOD / 2, ease: "sine.inOut", yoyo: true, repeat: REPEATS },
+  IDLE_START_TIME,
+);
+```
+
+## Variations
+
+- **Multi-octave** (organic): stack a higher-frequency overlay — `1 + Math.sin(p) * AMP_PRIMARY + Math.sin(p * OCTAVE_RATIO) * AMP_SECONDARY`, with `AMP_SECONDARY < AMP_PRIMARY` and the combined max inside the normal SCALE_AMP range.
+- **Settle and fade** (strongly recommended when `IDLE_DUR > 6s`): ramp amplitude to zero over the last ~20% of idle so the scene visibly settles before the inter-scene transition, instead of handing off mid-drift:
+
+```js
+const t = phase.p / (Math.PI * 2 * CYCLES); // 0 → 1 across idle
+const env = t < 1 - FADE_FRAC ? 1 : (1 - t) / FADE_FRAC; // FADE_FRAC ≈ 0.2
+const scale = 1 + Math.sin(phase.p) * SCALE_AMP * env;
+```
+
+This is the single biggest fix when finalize snapshots show "everything's still moving at the end"; it pairs naturally with break-boundary transitions (the outgoing visual is static when the crossfade/push begins).
+
+## Values
+
+| token           | range / default                      | notes                                                                      |
+| --------------- | ------------------------------------ | -------------------------------------------------------------------------- |
+| SCALE_AMP       | **0.008–0.015 default**              | push to 0.02–0.04 only when isolated on canvas / scene <6s / kinetic brief |
+| Y_AMP_PX        | **2–3px default**                    | 4–6px only under the same gating; rotation ±0.3–0.8° rarely needed at all  |
+| period          | 1.5–3s (2.5–4s when idle is long)    | <1.5s frantic; >4s lifeless in a short window                              |
+| CYCLES          | `IDLE_DUR/3 ≤ CYCLES ≤ IDLE_DUR/1.5` | derive from the period, not the other way round                            |
+| IDLE_START_TIME | ≥ entry settle + ~0.1s               | `sin(0)=0` at this moment → no jump off the entry tail                     |
+| IDLE_DUR        | `TOTAL_DURATION − IDLE_START_TIME`   | one long tween fills the hold — never restarted                            |
+| DOT_SCALE_AMP   | 0.04–0.12                            | small accents tolerate more than the hero                                  |
+| OCTAVE_RATIO    | 2.0–4.0                              | integer-ish reads musical; non-integer reads organic                       |
+
+## Critical Constraints
+
+- **Prefer reveal, then jitter, then breath** — the doctrine order above; default to the LOW end of every amplitude range. At the upper end across 5+ consecutive scenes the whole film reads as "shimmering".
+- **Long idle window** (`IDLE_DUR > 6s` OR idle > 30% of composition): halve `SCALE_AMP` / `Y_AMP_PX`, slow the period to 3–4s, and add the settle-and-fade tail.
+- **Concurrent idle on N elements** (columns, card grid, stat row): per-element amplitude ≤ default `/ √N`, AND stagger the periods (2.1s / 1.9s / 2.4s). Three columns at ±6px compound to ±18px of competing motion; three at ±2–3px read as one collective breath.
+- **Compose, don't replace** — idle ADDS to the element's resting transform; never overwrite the entry's final translation.
+- **Phase tween `ease: "none"`** — sine itself is the curve.
+- **No CSS `@keyframes` for idle** — CSS animation runs on the browser's render clock, independent of the HF seek clock; a CSS-driven idle flickers/desyncs. Drive idle inside the timeline.
+
+## See also
+
+`ambient-glow-bloom` (the glow-layer counterpart, same bounded-breathe discipline) · `press-release-spring` / `counting-dynamic-scale` / `card-morph-anchor` / `orbit-3d-entry` (settled elements this can follow) · `spring-pop-entrance` (the arrival that precedes any idle).