dsh-hyperframes 0.9.0 → 0.9.2

package/skills/hyperframes-animation/rules/particle-burst.md

@@ -1,149 +0,0 @@
----
-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/skills/hyperframes-animation/rules/physics-press-reaction.md

@@ -1,101 +0,0 @@
----
-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/skills/hyperframes-animation/rules/press-release-spring.md

@@ -1,108 +0,0 @@
----
-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/skills/hyperframes-animation/rules/reactive-displacement.md

@@ -1,92 +0,0 @@
----
-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/skills/hyperframes-animation/rules/scale-swap-transition.md

@@ -1,88 +0,0 @@
----
-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/skills/hyperframes-animation/rules/sine-wave-loop.md

@@ -1,85 +0,0 @@
----
-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).