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

package/dist/assets/design/skills/hyperframes-animation/rules/motion-blur-streak.md

@@ -0,0 +1,130 @@
+---
+name: motion-blur-streak
+description: Fake directional velocity blur on a fast entrance or camera push-through — blur peaks at max speed and resolves to 0 at the settle, so the element streaks in then snaps sharp. Two paths — SVG feGaussianBlur on the motion axis, or an echo/ghost trail that collapses into the lead.
+metadata:
+  tags: motion-blur, velocity, streak, entrance, fly-in, ghost, echo, svg-filter, kinetic, camera, snap
+---
+
+# Motion-Blur Streak
+
+Real motion blur isn't available to a seeked renderer (it integrates over shutter time), so this rule **fakes** it for a fast fly-in or hard camera push-through. The whole point is the _coupling_: the blur envelope rides the **same ease and window** as the position tween, so peak blur lands exactly on peak speed and the element is razor-sharp the instant it stops. Two paths:
+
+- **(A) Directional SVG blur** — inline `<feGaussianBlur stdDeviation="X 0">` (X on the motion axis, 0 across it), tweened via a proxy. Cleanest; a true directional smear.
+- **(B) Echo / ghost trail** — 2–4 duplicates at decreasing opacity, offset backward along the motion vector, collapsing into the lead as it settles. No filter cost; a stylized "speed-line" trail.
+
+**Entrances and mid-shot moves only — never a mid-composition exit.** A blurred element fleeing off-frame mid-composition reads as a glitch; a hard exit between scenes is the transition's job (`../transitions/overview.md`). One sanctioned scope extension: the envelope may ride the **camera wrapper** during a travel leg — see the Camera-Travel Carve-Out.
+
+## How It Works
+
+A fast `out`-eased move front-loads velocity — fastest off the start, bleeding to zero at the settle. Map the blur/echo envelope onto that same curve: position travels from an off-frame / pushed-back start to rest over `MOVE_DUR`; in lockstep on the same window and ease the smear goes `PEAK_BLUR → 0` (A) or the ghosts collapse onto the lead (B). By the settle the element is fully crisp and dwells ≥1 s — the contrast between violent streak and still, sharp settle IS the effect. GSAP can't tween an SVG attribute directly: tween a plain `{ v }` proxy and write `setAttribute("stdDeviation", …)` in `onUpdate`, seeding it once at setup so a seek to t=0 shows the streaked start.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip; overflow: hidden on the scene (the smear extends past rest) -->
+<svg width="0" height="0" aria-hidden="true" style="position: absolute">
+  <filter id="streak" x="-50%" y="-50%" width="200%" height="200%">
+    <feGaussianBlur id="streak-blur" in="SourceGraphic" stdDeviation="0 0" />
+  </filter>
+</svg>
+<div class="streak-el" id="streak-el" style="filter: url(#streak)">{phrase}</div>
+<!-- Path B instead: N-1 aria-hidden .streak-ghost duplicates BEHIND the lead, no filter -->
+```
+
+```js
+// Path A — proxy-tweened directional blur.
+const blurNode = document.getElementById("streak-blur");
+const blurProxy = { v: PEAK_BLUR };
+const writeBlur = () => blurNode.setAttribute("stdDeviation", `${blurProxy.v} 0`); // X axis only
+writeBlur(); // seed frame 0 — a seek to t=0 must show the streaked start, not a sharp pre-frame
+
+tl.fromTo(
+  "#streak-el",
+  { x: ENTER_FROM_X, opacity: 0 },
+  { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
+  MOVE_START,
+);
+tl.to(blurProxy, { v: 0, duration: MOVE_DUR, ease: MOVE_EASE, onUpdate: writeBlur }, MOVE_START);
+
+// Path B — ghosts on the SAME window/ease; per-ghost variation by index.
+gsap.utils.toArray(".streak-ghost").forEach((g) => {
+  const i = Number(g.dataset.i); // 1..N-1, set in HTML
+  tl.fromTo(
+    g,
+    { x: ENTER_FROM_X - i * ECHO_STEP_PX, opacity: GHOST_BASE_OPACITY / i },
+    { x: 0, opacity: 0, duration: MOVE_DUR, ease: MOVE_EASE },
+    MOVE_START,
+  );
+});
+```
+
+## Variations
+
+- **Vertical streak** — swap axes: `y`, `stdDeviation="0 Y"`, vertical echo offsets.
+- **Camera push-through** — `scale: SCALE_FROM → 1` with a symmetric `"B B"` envelope (depth-wise smear, not directional): the wordmark punches out of soft focus and snaps crisp at the lock.
+- **Staggered grid streak-in** — each card streaks into its slot at `MOVE_START + i * CARD_STAGGER` with its own blur proxy / ghosts; sharp the instant it lands.
+- **Hold-the-streak** — blur on a marginally slower curve than position (position `expo.out`, blur `power3.out`) so the last wisp resolves just after arrival. Sparingly; default is locked envelopes.
+
+## Camera-Travel Carve-Out
+
+The envelope is also sanctioned at **wrapper level**: on the `.world` / camera wrapper of a virtual-camera scene ([viewport-change.md](viewport-change.md), [multi-phase-camera.md](multi-phase-camera.md), [3d-camera-flight.md](3d-camera-flight.md)) during a **travel leg** — a dive, a whip sweep, a violent final push. This does **not** violate "never a mid-composition exit": the world never leaves frame — the camera travels _through_ it, and every leg ends with the world at rest, sharp, inside the frame. Each leg is an **arrival** at the next pose, so the entrance doctrine applies leg by leg. Three deltas from the element-level recipe:
+
+- **Envelope follows the leg's ease.** An `out` leg (dive, final push) uses the base recipe unchanged. An `inOut` repositioning leg peaks mid-leg: split the envelope at the velocity peak — `0 → PEAK` on the in-half ease over the first half, `PEAK → 0` on the out-half over the second. Seed the proxy at **0** for these (the streaked state lives mid-leg, not at t=0; seed-at-`PEAK_BLUR` belongs to the entrance shape, where the first frame IS the fastest).
+- **Filter placement.** 2D camera: `filter: url(#streak)` on the `.world` wrapper. 3D flight: on the **perspective stage** above the 3D context — a `filter` on a `preserve-3d` element flattens it and collapses every `translateZ`. Never per-element inside the world: one frame-wide envelope, not N desynced ones.
+- **Full-frame blur is heavy** — cap `PEAK_BLUR` ~18–20 at wrapper level (vs 30 for one element); a brief whip may touch ~24. Axis rule as usual: `"X 0"` for a lateral whip/pan, `"B B"` for a dive/push.
+
+### Whip sweep (named composition)
+
+The heavily-blurred lateral whip that resolves into the next region — two rules on one window:
+
+1. **Position** — [nudge-curve.md](nudge-curve.md)'s three-phase chain on the camera state, tuned burst-dominant (tail still ≥3× ramp-in in time).
+2. **Blur** — `0 → PEAK` across the ramp-in, held at `PEAK` through the linear burst (constant velocity = constant smear), `PEAK → 0` across the tail.
+
+Swap or reveal the next region's content DURING the burst — the smear masks the change; the `power4.out` tail lands it sharp. Reveal during the burst, read after the tail.
+
+```js
+tl.to(cam, { x: WHIP_X * 0.1, duration: 0.12, ease: "power3.in", onUpdate: applyCamera }, WHIP_AT);
+tl.to(
+  cam,
+  { x: WHIP_X * 0.75, duration: 0.1, ease: "none", onUpdate: applyCamera },
+  WHIP_AT + 0.12,
+);
+tl.to(
+  cam,
+  { x: WHIP_X, duration: 0.35, ease: "power4.out", onUpdate: applyCamera },
+  WHIP_AT + 0.22,
+);
+
+tl.to(blurProxy, { v: PEAK_BLUR, duration: 0.12, ease: "power3.in", onUpdate: writeBlur }, WHIP_AT);
+// blur holds at PEAK through the linear burst (no tween needed — value rests at PEAK)
+tl.to(blurProxy, { v: 0, duration: 0.35, ease: "power4.out", onUpdate: writeBlur }, WHIP_AT + 0.22);
+```
+
+## Values
+
+| token              | range                                              | notes                                                                                           |
+| ------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| MOVE_EASE          | `expo.out` / `power4.out` (default) / `power3.out` | `out`-family ONLY — `in`/`inOut` puts peak speed in the wrong place; position and blur share it |
+| MOVE_DUR           | 0.25–0.6s                                          | over ~0.7s reads as a focus pull, not velocity                                                  |
+| ENTER_FROM_X/Y     | 40–120% of the element's own dimension             | enough runway for the streak to read                                                            |
+| PEAK_BLUR          | 8–30 (default 18)                                  | >30 erases the glyph at the start; ~18–20 cap at wrapper level                                  |
+| SCALE_FROM         | 1.3–2.5                                            | push-through variation                                                                          |
+| N (ghosts)         | 2–4                                                | >4 reads as strobe, not streak                                                                  |
+| ECHO_STEP_PX       | 12–40px                                            | `N × step ≲ ENTER_FROM` so the furthest ghost starts inside the runway                          |
+| GHOST_BASE_OPACITY | 0.3–0.6                                            | opaque ghosts read as duplicate elements                                                        |
+| CARD_STAGGER       | 0.05–0.12s                                         | one assembling wave, not separate arrivals                                                      |
+
+## Critical Constraints
+
+- Blur peaks at peak speed and resolves to 0 at the settle — share the ease and window between position and envelope. A blur that lingers after the stop reads as a focus pull.
+- Entrances / mid-shot arrivals only — never a mid-composition exit; wrapper-level use only per the carve-out.
+- Seed `stdDeviation` at setup: at `PEAK_BLUR` for the entrance shape, at 0 for a whip / `inOut` leg.
+- Generous filter region (`x="-50%" y="-50%" width="200%" height="200%"`) or the smear clips at the element's box edge.
+- Directional axis: `"X 0"` horizontal, `"0 Y"` vertical, `"B B"` only for a depth/scale move — symmetric blur on a sideways move looks like defocus.
+- Dwell ≥1 s sharp after the snap; a streak landing at the last beat reads as "flashed and gone".
+- Heavy element on a solid field — thin type (< ~120px / 800 weight) or a busy backdrop swallows the smear.
+- `overflow: hidden` on the scene — the smear / furthest ghost extends past the resting position during travel.
+
+## See also
+
+`kinetic-beat-slam` (streak as one beat's entrance) · `center-outward-expansion` (grid streak-in) · `scale-swap-transition` (same-footprint morph — not an arrival) · `nudge-curve` (the whip sweep's position half) · `3d-camera-flight` / `viewport-change` (the carve-out's wrappers).

package/dist/assets/design/skills/hyperframes-animation/rules/multi-cursor-choreography.md

@@ -0,0 +1,133 @@
+---
+name: multi-cursor-choreography
+description: N labeled independent cursor actors work one canvas simultaneously (collaborative-canvas ambience) — per-cursor deterministic waypoint schedules, name-tag pills in distinct colors, grab/drop actions on an interleaved beat grid so paths and actions never collide; the camera stays locked, the liveness itself is the message.
+metadata:
+  tags: cursor, multi-cursor, collaboration, ensemble, canvas, name-tag, choreography, ambient, teamwork
+---
+
+# Multi-Cursor Choreography
+
+> **The camera never chases anyone.** No real camera — any "pan" is the canvas group translating inside a static frame. And per the motion doctrine's idle-motion ban, every cursor must **perform**: travel to a target, act, then rest still. Scheduled rest is stillness; aimless wander loops are wobble.
+
+THE ensemble primitive: **two to four labeled cursor actors** — each an arrow plus a name-tag pill in its own color — work one shared canvas at the same time. No single interaction is the subject; the **simultaneous liveness is** ("a team is in here, working"), usually as ambience under a headline building over the top. Distinct from [cursor-click-ripple.md](cursor-click-ripple.md) and [cursor-drag.md](cursor-drag.md): those are **one protagonist** the viewer follows click-by-click; here the actors are chorus, not lead — each action smaller and quieter than a solo cursor's, the value in the interleaving. Also distinct from [camera-cursor-tracking.md](camera-cursor-tracking.md): that locks the _viewport_ to one focal cursor; this rule forbids exactly that — the frame is static and the eye roams freely.
+
+## How It Works
+
+Everything hangs off one data table:
+
+1. **The actor table** — a literal `ACTORS` array: per actor a name, a color, and a **waypoint schedule** (`{ x, y, at, dur }` legs plus action beats). All coordinates and times are hand-authored constants — the choreography is data: deterministic, seekable, and auditable for collisions before a single frame renders.
+2. **Legs as explicit `fromTo`s** — each leg tweens the actor wrapper from the previous waypoint to the next at an absolute position. Gaps between legs are **rests**: the cursor sits still exactly where it landed.
+3. **Actions** — a leg can end in a grab (press dip; the payload rides the next leg in lockstep — [cursor-drag.md](cursor-drag.md) mechanics at chorus intensity), a drop (`tl.set` identity swap + tiny settle pop), or a hover (a highlight fades in under the tip, once, then holds).
+4. **The interleaved beat grid** — actions land on **alternating beats** (~1.2 / 2.6 / 4.0 s): at any moment at most one action lands while the others glide or rest. Each actor owns a home **zone** of the canvas; only one actor at a time leaves its zone, so paths never cross near-simultaneously. (Short specimens under ~5s can compress beat spacing to ~0.3–0.9s — zones still prevent collisions; the ≥1s spacing is for ambience-length shots.)
+5. **Ambience staging** — cursors may already be mid-canvas at t=0 (the team was working before we arrived — the collaborative-canvas idiom), or enter off-frame on staggered starts. The canvas group may slowly translate-pan under the ensemble (element translate, not a camera).
+
+## Recipe
+
+```html
+<!-- Canvas group (mockups + payload chips) may translate for an ambient pan.
+     One wrapper per actor: arrow + name tag move as ONE object. -->
+<div class="canvas-group" id="canvas-group">
+  <div class="mockup" id="mockup-a">{mockupA}</div>
+  <div class="canvas-chip" id="chip-1">{chipLabel}</div>
+</div>
+<div class="actor" id="actor-1">
+  <svg class="actor-arrow"><!-- arrow path, fill: ACTOR_1_COLOR --></svg>
+  <span class="actor-tag" style="background: ACTOR_1_COLOR">{actorName1}</span>
+</div>
+```
+
+```js
+// The choreography IS this table — all literals; read the `at` columns to
+// verify beats interleave. Each actor owns a zone.
+const ACTORS = [
+  {
+    id: "#actor-1", // zone: left mockup
+    legs: [
+      { from: { x: 180, y: 420 }, to: { x: 320, y: 300 }, at: 0.2, dur: 0.9 },
+      { to: { x: 340, y: 480 }, at: 2.0, dur: 0.8 }, // rest 0.9s between legs
+    ],
+  },
+  {
+    id: "#actor-2", // zone: center mockup
+    legs: [
+      { from: { x: 900, y: 200 }, to: { x: 820, y: 360 }, at: 0.6, dur: 1.0 },
+      { to: { x: 980, y: 380 }, at: 3.4, dur: 0.7 },
+    ],
+  },
+  {
+    id: "#actor-3", // zone: right panel — enters from off-frame
+    legs: [{ from: { x: 1980, y: 520 }, to: { x: 1560, y: 460 }, at: 1.4, dur: 1.1 }],
+  },
+];
+
+ACTORS.forEach((actor) => {
+  let prev = actor.legs[0].from;
+  tl.set(actor.id, { x: prev.x, y: prev.y }, 0); // on stage (or off) from t=0
+  actor.legs.forEach((leg) => {
+    tl.fromTo(
+      actor.id,
+      { x: prev.x, y: prev.y },
+      { x: leg.to.x, y: leg.to.y, duration: leg.dur, ease: "power2.inOut", immediateRender: false },
+      leg.at,
+    );
+    prev = leg.to;
+  });
+});
+
+// Actions at chorus intensity — actor 1 grabs the chip: press dip, then the
+// chip rides leg 2 in lockstep (matched tween: same position, duration, ease).
+tl.to("#actor-1", { scale: 0.88, duration: 0.07, ease: "power2.in", yoyo: true, repeat: 1 }, 1.1);
+tl.fromTo(
+  "#chip-1",
+  { x: 0, y: 0 },
+  { x: CHIP_DX, y: CHIP_DY, duration: 0.8, ease: "power2.inOut", immediateRender: false },
+  2.0, // = actor-1 leg 2 `at` and `dur`, exactly
+);
+// Drop: identity swap + tiny settle — quieter than a solo cursor's snap
+tl.set("#chip-1", { backgroundColor: "{chipSwapColor}" }, 2.8);
+tl.fromTo(
+  "#chip-1",
+  { scale: 1.06 },
+  { scale: 1, duration: 0.2, ease: "power3.out", immediateRender: false },
+  2.8,
+);
+
+// Optional ambient canvas pan (element translate, NOT a camera)
+tl.fromTo("#canvas-group", { x: 0 }, { x: PAN_DX, duration: 6.0, ease: "none" }, 0.3);
+```
+
+## Variations
+
+- **Ambient collaborative canvas (the Hook register)** — the default: actors mid-canvas at t=0, canvas slowly panning, a headline building over the top ([waterfall-entry.md](waterfall-entry.md)). The demo is set-dressing for the words; keep every action small and the beat grid loose.
+- **One labeled editor (N = 1, still ensemble-styled)** — a single labeled teammate cursor performs one visible edit (deletes and retypes a headline word via [discrete-text-sequence.md](discrete-text-sequence.md), or drops one component). The name tag is the point: _a person_ did this.
+- **Featured beat inside the ensemble** — one actor briefly becomes the lead: full [cursor-drag.md](cursor-drag.md) grab-carry-drop with chrome while the others explicitly REST for that window. Freeze the chorus; two things moving with intent at once splits the eye.
+- **Staggered entrances** — cursors enter from off-frame at `ENTER_AT + i * ENTER_STAGGER`, each gliding to its zone ("the team assembles"); entry vectors from different edges, per the house cursor entry law.
+
+## Values
+
+| token               | range                     | notes                                                                                                                        |
+| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| ACTOR_COUNT         | 2–4                       | one is a solo rule's job; five+ reads as noise — no viewer tracks five pointers                                              |
+| leg `dur`           | 0.6–1.2 s, `power2.inOut` | human, considered mouse movement; sub-0.5 s across long distances reads as a teleport                                        |
+| rest gaps           | 0.5–1.5 s                 | rests make the ensemble read as people; zero-rest actors read as screensavers                                                |
+| action beat spacing | ≥ 1.0 s                   | while one acts, others may glide but must not act — audit by sorting all `at` values                                         |
+| zones               | one per actor             | only the acting actor crosses zones; two cursors within ~80 px reads as a glitch — check waypoint pairs at overlapping times |
+| PAN_DX              | ~40–80 px, linear         | parallax life, not a camera move; omit for busier ensembles                                                                  |
+| tag / arrow size    | smaller than a solo lead  | the oversized-cursor treatment is for protagonists; tags must stay legible at render resolution                              |
+| colors              | one saturated hue each    | from the palette's accent range; tag pill and arrow fill share the hue                                                       |
+
+## Critical Constraints
+
+- **The table is the choreography** — all waypoints, times, and actions are literal data. If you can't verify non-collision by reading the `at` columns, the schedule is too clever.
+- **Every leg is an explicit `fromTo`** with the previous waypoint as the from-state, `immediateRender: false` on all but each actor's initial placement — chained `.to()`s on shared properties capture stale starts under seek.
+- **Interleave, never chord** — at most one action landing at any moment; simultaneous travel is fine (that's the liveness), simultaneous _payoffs_ compete.
+- **Chorus intensity** — every action is a quieter version of its solo rule: smaller dips, subtler snaps, no ripple bursts; save full treatment for a featured beat.
+- **Rest is stillness** — between legs a cursor holds exactly where it landed: no idle drift, no yoyo wander on any actor.
+- **Payload lockstep** — a carried chip's tween matches its actor's leg exactly (position, duration, ease), per the cursor-drag law.
+- **The wrapper moves, never the parts** — arrow + name tag are one element; tweening them separately shears the actor apart under seek.
+- **Camera locked** — no viewport zoom/pan tweens; the only large-scale motion is the linear canvas-group translate. Never zoom to an actor (that's a solo-cursor shot).
+- **Actors are people** — human-speed glides, pauses, one thing at a time; `pointer-events: none` on all actors. Check `tl.duration()` — ensembles accumulate long tails from late rests.
+
+## See also
+
+`cursor-drag` (full-treatment featured beat) · `cursor-click-ripple` (chorus click — press only, skip the ripple) · `discrete-text-sequence` (a labeled actor's retype edit) · `viewport-change` (the canvas-group translate math) · `spring-pop-entrance` (components popping in as drop results).

package/dist/assets/design/skills/hyperframes-animation/rules/multi-phase-camera.md

@@ -0,0 +1,129 @@
+---
+name: multi-phase-camera
+description: Sequential camera zoom with 2-3 distinct phases (pull-back / focus / push) plus continuous micro-drift for organic cinematic feel.
+metadata:
+  tags: camera, zoom, phase, drift, scale, cinematic
+---
+
+# Multi-Phase Camera
+
+A camera wrapper around the ENTIRE scene that progresses through discrete zoom phases at scripted triggers, with continuous sine-driven micro-drift overlaid so the camera never feels static between phases. Distinct from a single linear zoom — multi-phase creates cinematic pacing (anticipation → reveal → settle).
+
+## How It Works
+
+The camera is one wrapping `<div>` whose `transform: scale() translate(x, y)` is composed from two channels inside a single `onUpdate` writer:
+
+1. **Phase scale** — a proxy object `{ scale }` stepped through phases at trigger times (`PHASE_1_SCALE` at t=0 → `PHASE_2_SCALE` at `PHASE_2_AT` → `PHASE_3_SCALE` at `PHASE_3_AT`).
+2. **Drift offset** — a continuous sine-based `translateX` / `translateY` (small amplitude, slow frequency) ADDED to the phase transform. X and Y run at slightly different frequencies (`DRIFT_FREQ_RATIO ≈ 1.3`) — equal frequencies produce a perfect diagonal that reads mechanical; ~1.3 gives an organic Lissajous.
+
+## Recipe
+
+```html
+<div class="camera" id="camera">
+  <div class="content">
+    <div class="hero">{Brand}</div>
+    <div class="tagline">{tagline}</div>
+    <div class="cta">{ctaText}</div>
+  </div>
+</div>
+```
+
+```css
+.scene {
+  overflow: hidden; /* REQUIRED — any phase scale < 1 exposes the content's edges */
+  background: {sceneBgColor}; /* background on .scene, NOT .camera — a camera-borne
+     background warps/translates with the transform and reveals the outer void */
+}
+.camera {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  transform-origin: 50% 50%; /* off-center origin creates phase-to-phase drift */
+  will-change: transform;
+}
+```
+
+```js
+const camera = document.getElementById("camera");
+
+// Three-phase scale plan: pullback → focus → push.
+const phase = { scale: PHASE_1_SCALE }; // Phase 1 is the initial value — no tween
+
+// Phase 2 — settle to neutral focus
+tl.to(phase, { scale: PHASE_2_SCALE, duration: PHASE_2_DUR, ease: PHASE_2_EASE }, PHASE_2_AT);
+
+// Phase 3 — slow push-in for the climax
+tl.to(phase, { scale: PHASE_3_SCALE, duration: PHASE_3_DUR, ease: PHASE_3_EASE }, PHASE_3_AT);
+
+// Drift driver — continuous sine motion overlaid on the phase scale.
+// The ONE writer of camera.style.transform.
+const drift = { p: 0 };
+tl.to(
+  drift,
+  {
+    p: Math.PI * 2 * DRIFT_CYCLES,
+    duration: TOTAL_DURATION, // spans the whole composition
+    ease: "none",
+    onUpdate: () => {
+      const dx = Math.sin(drift.p) * DRIFT_AMP_X;
+      const dy = Math.sin(drift.p * DRIFT_FREQ_RATIO) * DRIFT_AMP_Y;
+      camera.style.transform = `scale(${phase.scale}) translate(${dx}px, ${dy}px)`;
+    },
+  },
+  0,
+);
+
+// Content reveals happen INSIDE the camera frame (hero/tagline/cta beats).
+```
+
+## Phase Patterns
+
+| Pattern             | Scale sequence (1 → 2 → 3)        | Feel                            | When to use                   |
+| ------------------- | --------------------------------- | ------------------------------- | ----------------------------- |
+| **Focus-in**        | back → neutral → slight push      | Approach → settle → slight push | Default product reveal        |
+| **Dramatic reveal** | push → neutral → pull             | Wide → focus → settle back      | Hero shot with breathing room |
+| **Steady push**     | neutral → slight push → more push | Gradual forward momentum        | Continuous narrative push     |
+| **Bookend pull**    | neutral → strong push → neutral   | Settle → push → release         | CTA emphasis then release     |
+
+## Variations
+
+- **Phase trigger by content beat**: align a camera tween's start with a content tween's end (entry completes → push begins) rather than a fixed clock value.
+- **Camera shake (panic / impact)**: a brief higher-amplitude, higher-frequency drift tween over a short window — same `drift` mechanism with `SHAKE_AMP` / `SHAKE_CYCLES` / `SHAKE_DUR` at `SHAKE_AT`.
+- **Targeted zoom into an off-center element**: combine scale with counter-translation so the target lands at viewport center — divide the measured offset by the current scale before feeding it into the writer:
+
+```js
+const tRect = document.querySelector(".cta").getBoundingClientRect();
+const offsetX = (STAGE_W / 2 - (tRect.left + tRect.width / 2)) / phase.scale;
+const offsetY = (STAGE_H / 2 - (tRect.top + tRect.height / 2)) / phase.scale;
+// then in onUpdate: translate(offsetX + dx, offsetY + dy)
+```
+
+(Full counter-translate doctrine: [coordinate-target-zoom.md](coordinate-target-zoom.md).)
+
+## Values
+
+| token                       | range                                    | notes                                                                               |
+| --------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
+| PHASE_1 / 2 / 3_SCALE       | 0.88–0.96 / 0.98–1.02 / 1.04–1.15        | tighter spread = subtler camera; scale < 1 REQUIRES `overflow: hidden` on `.scene`  |
+| PHASE_2_AT / PHASE_2_DUR    | 0.3–1.0s / 1.0–1.8s                      | longer DUR = slower settle, more cinematic                                          |
+| PHASE_3_AT / PHASE_3_DUR    | 2.0–4.0s / 1.0–2.0s                      | PHASE_3_AT ≥ PHASE_2_AT + PHASE_2_DUR or focus is preempted                         |
+| PHASE_2_EASE / PHASE_3_EASE | `power2.out` `power3.out` `power2.inOut` | spring/back easing on a camera feels uncomfortable; each later phase settles deeper |
+| TOTAL_DURATION              | = `data-duration`                        | the drift tween must span the whole composition                                     |
+| DRIFT_CYCLES                | 1–3                                      | 1 = one slow breath; high values read as mechanical wobble                          |
+| DRIFT_AMP_X / DRIFT_AMP_Y   | 2–8 px / 1–4 px                          | imperceptible per-frame, visible over time — if it reads as a shake, it's too much  |
+| DRIFT_FREQ_RATIO            | 1.2–1.5                                  | 1.0 = perfect diagonal (mechanical); ~1.3 = organic Lissajous                       |
+| HERO_AT (etc.)              | after Phase-2 settle lands               | a hero fading in mid-pull-back feels like it's flying away                          |
+
+## Critical Constraints
+
+- **Camera wraps EVERYTHING in the scene** — a per-element camera creates parallax bugs and breaks the "one viewpoint" read.
+- **One writer**: phase scale and drift compose inside the single drift `onUpdate`; nothing else touches `camera.style.transform`.
+- **`overflow: hidden` on `.scene`** — required whenever any phase scale < 1.
+- **`transform-origin: 50% 50%` on `.camera`** — off-center origin creates unpredictable phase-to-phase drift.
+- **Scene background on `.scene`, not `.camera`** — otherwise scaling/translating reveals the outer void.
+- **Hero reveal starts AFTER the initial pull-back ease lands** — otherwise the headline feels like it's flying away.
+
+## See also
+
+[coordinate-target-zoom.md](coordinate-target-zoom.md) (counter-translate math for the targeted variation) · [orbit-3d-entry.md](orbit-3d-entry.md) (orbit inside a drifting camera) · [counting-dynamic-scale.md](counting-dynamic-scale.md) (climax push synced to counter peak) · [3d-text-depth-layers.md](3d-text-depth-layers.md) (depth-stacked hero under camera moves) · [sine-wave-loop.md](sine-wave-loop.md) (element idle inside the camera).

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

@@ -0,0 +1,47 @@
+---
+name: nudge-curve
+description: Slow-fast-slow three-phase group slide — reposition a composed group (word rows, card stacks, lists) to reveal content or make room. No single built-in ease produces it; chain power3.in ramp → linear burst → power4.out tail (10/65/25 distance, tail ≥3× ramp-in in time).
+metadata:
+  tags: slide, reposition, group-motion, easing, nudge, slow-fast-slow, reveal, layout
+---
+
+# Nudge Curve
+
+Slow-fast-slow repositioning of a composed group (word rows, card stacks, lists) to
+reveal content or make room. **In-scene group slide — not a seam.** No single built-in
+ease produces it — `power4.inOut` smacks to a stop. Chain three tweens on one property:
+
+| Phase     | Ease            | Distance | Time | Feel                                     |
+| --------- | --------------- | -------- | ---- | ---------------------------------------- |
+| 1 ramp-in | `power3.in`     | ~10%     | ~20% | barely moves — motion registers, no jolt |
+| 2 burst   | `none` (linear) | ~65%     | ~18% | ~2× average px/frame — purposeful        |
+| 3 tail    | `power4.out`    | ~25%     | ~62% | decaying creep to rest — kills the smack |
+
+## Rules
+
+- The tail is ≥3× the ramp-in in TIME. If it still smacks: extend the tail's time (not
+  distance) or use `power5.out`.
+- Phase 2 stays linear — easing it loses the burst contrast.
+- Reveal new content DURING phase 2 — the burst masks its appearance.
+- Same ratios vertical; scale distances proportionally, keep the time ratios.
+- A cascade arrival usually precedes this slide — see [waterfall-entry.md](waterfall-entry.md).
+
+## JS
+
+Reference values for a 270px leftward slide (0.57s total). Scale distances
+proportionally for other travels; preserve the TIME ratios; tail ≥3× ramp-in.
+
+```js
+var t = /* start after content settles */;
+tl.to(".text-row", { x: -30,  duration: 0.12, ease: "power3.in"  }, t);          // ramp-in: 11% dist / 21% time
+tl.to(".text-row", { x: -210, duration: 0.10, ease: "none"       }, t + 0.12);   // burst:   67% dist / 18% time
+tl.to(".text-row", { x: -270, duration: 0.35, ease: "power4.out" }, t + 0.22);   // tail:    22% dist / 61% time
+// vertical: same ratios on y. 150px variant: -15 / -115 / -150 at the same times.
+```
+
+## Anti-patterns
+
+| Don't                                                    | Instead                                  |
+| -------------------------------------------------------- | ---------------------------------------- |
+| Single ease for a group slide (`power4.inOut`, `slow()`) | The three-phase chain above              |
+| Nudge tail shorter than 3× the ramp-in                   | Extend the tail's TIME, not its distance |

package/dist/assets/design/skills/hyperframes-animation/rules/orbit-3d-entry.md

@@ -0,0 +1,148 @@
+---
+name: orbit-3d-entry
+description: Elements flip in from 3D space then settle into continuous elliptical orbit around a focal point.
+metadata:
+  tags: orbit, 3d, flip, ellipse, circular, icon, entry, continuous
+---
+
+# Orbit with 3D Entry
+
+Elements flip in from 3D space (`rotateX` + `rotateY` + negative `z`) then settle into a continuous elliptical orbit around a center label. Distinct from one-shot reveals — the orbit keeps running, driven by a 0→1 progress tween INSIDE the timeline (never rAF).
+
+## How It Works
+
+Per element, two phases: (1) a `back.out` flip from a hidden 3D orientation to flat — **in place at its orbital starting position** (see Critical Constraints); (2) a continuous orbit where `onUpdate` computes `x/y` from `cos/sin(initialAngle + p·2π)` on the ellipse. The stage needs `perspective` on the scene root and `preserve-3d` on stage + items, or the flip flattens to a 2D scale.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="orbit-stage">
+  <div class="orbit-item" data-angle="0">{glyph1}</div>
+  <div class="orbit-item" data-angle="60">{glyph2}</div>
+  <!-- … evenly-spaced angles … -->
+  <div class="orbit-center">{centerLabel}</div>
+</div>
+```
+
+```css
+.scene-root {
+  display: grid;
+  place-items: center;
+  perspective: 1800px; /* REQUIRED */
+}
+.orbit-stage {
+  position: relative;
+  display: grid;
+  place-items: center;
+  transform-style: preserve-3d;
+}
+.orbit-item {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform-style: preserve-3d;
+  will-change: transform;
+}
+.orbit-center {
+  position: relative;
+  transform: translateZ(220px); /* wins paint order inside preserve-3d */
+  z-index: 9999;
+}
+```
+
+```js
+const items = document.querySelectorAll(".orbit-item");
+const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse
+
+items.forEach((el, i) => {
+  const a0 = (Number(el.dataset.angle) / 360) * Math.PI * 2;
+  const startX = Math.cos(a0) * RADIUS_X;
+  const startY = Math.sin(a0) * RADIUS_Y;
+
+  // 1) Park at the orbital position, hidden — BEFORE any tween fires
+  gsap.set(el, {
+    xPercent: -50,
+    yPercent: -50,
+    x: startX,
+    y: startY,
+    rotateX: ROTATE_X_FROM,
+    rotateY: ROTATE_Y_FROM,
+    z: Z_FROM,
+    opacity: 0,
+    scale: SCALE_FROM,
+  });
+
+  // 2) Flip in IN PLACE — rotation/opacity/scale only, never translate
+  tl.to(
+    el,
+    {
+      rotateX: 0,
+      rotateY: 0,
+      z: 0,
+      opacity: 1,
+      scale: 1,
+      duration: ENTRY_DUR,
+      ease: `back.out(${FLIP_BACK})`,
+    },
+    i * STAGGER,
+  );
+
+  // 3) Continuous orbit — each item gets its OWN progress tween (own initialAngle)
+  const orbit = { p: 0 };
+  tl.to(
+    orbit,
+    {
+      p: 1,
+      duration: ORBIT_DURATION,
+      ease: "none",
+      onUpdate: () => {
+        const a = a0 + orbit.p * Math.PI * 2;
+        const x = Math.cos(a) * RADIUS_X;
+        const y = Math.sin(a) * RADIUS_Y;
+        // capped z-index band [1, 50] — see center-label clearance below
+        el.style.zIndex = String(1 + Math.round(((y + RADIUS_Y) / (2 * RADIUS_Y)) * 49));
+        el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
+      },
+    },
+    i * STAGGER + ENTRY_DUR,
+  );
+});
+
+tl.from(
+  ".orbit-center",
+  { opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
+  CENTER_FADE_AT,
+);
+```
+
+## Variations
+
+- **Collapse to center**: a final 1→0 driver multiplies both radii (and item scale) in `onUpdate` — the ring condenses into the center element; pairs with a CTA "click" igniting the collapse.
+- **Tilted orbit plane**: `rotateX(25deg)` on `.orbit-stage` — items visibly arc through the plane.
+
+## Values
+
+| token                   | range                         | notes                                                               |
+| ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
+| RADIUS_X                | 300–900px                     | must also clear the center label horizontally (see below)           |
+| Y_TO_X_RATIO            | 0.4–0.7                       | keep < 1 — a tilted ring, not a frontal halo                        |
+| ORBIT_DURATION          | 4–25s per revolution          | ≥ time on screen, or the tween ends and items freeze                |
+| ENTRY_DUR               | 0.4–0.8s                      |                                                                     |
+| STAGGER                 | 0.06–0.12s                    | below reads "popcorn", above reads plodding                         |
+| FLIP_BACK / CENTER_BACK | 1.2–2.0 / 1.2–1.8             | calm the center pop if both fire close together                     |
+| CENTER_FADE_AT          | after 2–4 items land          | too early competes; too late leaves a hole                          |
+| ROTATE_X/Y_FROM, Z_FROM | ±60–120°, ±45–120°, −200…−400 | one consistent rotation direction across items; mixed signs = noise |
+| SCALE_FROM              | 0.2–0.6                       |                                                                     |
+| item count              | 4–12                          | fewer feels empty, more crowds the center                           |
+
+## Critical Constraints
+
+- ** Entry must flip IN PLACE at the orbital position, NOT at center** — `gsap.set` each item at `(cos(a0)·RADIUS_X, sin(a0)·RADIUS_Y)` with `opacity: 0` BEFORE adding tweens, then phase 1 animates only rotation/opacity/scale. A fromTo that keeps `x/y: 0` flips at the stage center, collides with the center label, then teleports to the orbit when phase 2 starts.
+- ** Center-label clearance** — `z-index` alone is unreliable inside `preserve-3d` (paint order follows actual Z): push the label forward with `translateZ(220px)` + `z-index: 9999`, cap item z-index to `[1, 50]`, AND size the ring so items clear the label horizontally at every angle: `RADIUS_X × min|cos(θ)| ≥ L_w + I_w + breathing_room` (label/item half-widths; for 6 items the worst case is `cos(30°) ≈ 0.866`). A heavier wordmark needs a wider ring.
+- **Each item gets its OWN orbit tween** — a shared `targets: ".orbit-item"` tween can't carry per-item `initialAngle`.
+- **The center element is the headline** — the orbit is ornament; if it dominates, grow the center or fade the items down.
+
+## See also
+
+`center-outward-expansion` (burst entry; reversed driver = the collapse finish) · `cursor-click-ripple` (the click that triggers a collapse) · `depth-scatter-assemble` (3D entrance that resolves flat instead of orbiting).