takomi 2.1.45 → 2.5.4

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

@@ -1,328 +1,328 @@
----
-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 per-frame motion blur isn't available to a seeked renderer (it integrates over shutter time, which a paused timeline has no concept of), so this rule **fakes** it for a fast element fly-in or a hard camera push-through. The blur **peaks at maximum velocity and resolves to 0 at the settle** — the element reads as streaking in then snapping sharp on arrival. 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 implementation paths, both finite, deterministic, and seek-safe:
-
-- **(A) Directional SVG blur** — an inline `<filter>` with `<feGaussianBlur stdDeviation="X 0">` (X on the axis of motion, 0 across it). GSAP tweens `X` from high → 0 through a proxy that calls `setAttribute` each frame. Cleanest, one element, true directional smear.
-- **(B) Echo / ghost trail** — 2–4 duplicate copies at decreasing opacity, offset backward along the motion vector, collapsing into the lead element as it settles. No filter cost; reads as a "speed-line" stutter trail. Better when you want the streak _colored_ or _stylized_ rather than a literal optical blur.
-
-This is for **entrances and mid-shot moves only** — a fast arrival, a beat that zooms past camera, a card slamming into a grid slot, a logo punching through into a lockup. **Never an exit on a non-final frame** (a blurred element fleeing off-frame mid-composition reads as a glitch, and a hard exit between scenes is the transition's job, not a per-element blur).
-
-## How It Works
-
-A fast move has a velocity profile: it accelerates off the start, peaks, then decelerates into the settle. An `out` ease (`expo.out`, `power4.out`) front-loads that — velocity is highest right at the start and bleeds to zero at the end. The fake works by mapping a **blur (or echo) envelope onto that same curve**:
-
-1. **Position tween** — the element travels from an off-frame / pushed-back start to its resting transform (`x`/`y` for a fly-in, `scale` for a push-through) on a fast `out` ease over `MOVE_DUR`.
-2. **Blur envelope** — in lockstep over the **same window and ease**, the smear goes from `PEAK_BLUR` → `0`. Because the ease front-loads velocity and the envelope shares it, max blur coincides with max speed, and blur hits exactly `0` as the element lands.
-3. **Settle is sharp** — by `MOVE_START + MOVE_DUR` the element is at its resting transform with blur `0` (path A) or all echoes collapsed onto the lead (path B). It then holds, fully crisp, for the climax dwell.
-
-Path A tweens the filter's `stdDeviation` attribute (a non-DOM-style numeric attribute) via a **proxy object** — GSAP can't tween an SVG attribute directly, so you tween a plain `{ v: PEAK_BLUR }` and write it back with `setAttribute` in `onUpdate`. Path B places the ghosts at deterministic backward offsets (`i * ECHO_STEP_PX`) and fades/collapses them on the same envelope.
-
-## HTML
-
-### Path A — directional SVG blur (recommended default)
-
-```html
-<div
-  class="scene"
-  id="streak-scene"
-  data-composition-id="streak-scene"
-  data-start="0"
-  data-duration="DURATION"
-  data-track-index="0"
->
-  <!-- Inline filter: blur on the X axis only (stdDeviation="X 0"); 0 on Y keeps it a clean horizontal smear. -->
-  <svg width="0" height="0" aria-hidden="true" style="position: absolute">
-    <defs>
-      <filter id="streak" x="-50%" y="-50%" width="200%" height="200%">
-        <feGaussianBlur id="streak-blur" in="SourceGraphic" stdDeviation="0 0" />
-      </filter>
-    </defs>
-  </svg>
-
-  <div class="streak-stage">
-    <div class="streak-el" id="streak-el">{phrase}</div>
-  </div>
-</div>
-```
-
-### Path B — echo / ghost trail
-
-```html
-<div
-  class="scene"
-  id="streak-scene"
-  data-composition-id="streak-scene"
-  data-start="0"
-  data-duration="DURATION"
-  data-track-index="0"
->
-  <div class="streak-stage">
-    <!-- N-1 ghosts BEHIND the lead, then the lead on top. Ghosts are aria-hidden duplicates. -->
-    <div class="streak-ghost" data-i="3" aria-hidden="true">{phrase}</div>
-    <div class="streak-ghost" data-i="2" aria-hidden="true">{phrase}</div>
-    <div class="streak-ghost" data-i="1" aria-hidden="true">{phrase}</div>
-    <div class="streak-el" id="streak-el">{phrase}</div>
-  </div>
-</div>
-```
-
-## CSS
-
-```css
-.scene {
-  position: relative;
-  width: 100%;
-  height: 100%;
-  display: grid;
-  place-items: center;
-  background: {sceneBg};
-  font-family: {font};
-  overflow: hidden; /* the smear/echo extends past the resting position before settling */
-}
-.streak-stage {
-  position: relative;
-  display: grid;
-  place-items: center;
-}
-.streak-el {
-  position: relative;
-  z-index: 2;
-  font-size: EL_FONT_SIZE;
-  font-weight: 900;
-  letter-spacing: EL_TRACKING;
-  color: {textColor};
-  /* Path A only — reference the directional filter. (Omit for Path B.) */
-  filter: url(#streak);
-  will-change: transform, filter;
-}
-
-/* Path B ghosts — identical glyphs behind the lead, decreasing opacity */
-.streak-ghost {
-  position: absolute;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  z-index: 1;
-  font-size: EL_FONT_SIZE;
-  font-weight: 900;
-  letter-spacing: EL_TRACKING;
-  color: {textColor};
-  opacity: 0;
-  will-change: transform, opacity;
-  pointer-events: none;
-}
-```
-
-## GSAP Timeline
-
-### Path A — directional SVG blur
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-<script>
-  window.__timelines = window.__timelines || {};
-  const tl = gsap.timeline({ paused: true });
-
-  // GSAP can't tween an SVG attribute directly — tween a proxy and write it back each frame.
-  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 so a seek to t=0 shows the streaked start, not a sharp pre-frame
-
-  // Position: travel from off-frame to rest on a fast `out` ease (velocity front-loaded).
-  tl.fromTo(
-    "#streak-el",
-    { x: ENTER_FROM_X, opacity: 0 },
-    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
-    MOVE_START,
-  );
-
-  // Blur envelope: SAME window + SAME ease so peak-blur == peak-speed, resolving to 0 at the settle.
-  tl.to(blurProxy, { v: 0, duration: MOVE_DUR, ease: MOVE_EASE, onUpdate: writeBlur }, MOVE_START);
-
-  window.__timelines["streak-scene"] = tl;
-</script>
-```
-
-### Path B — echo / ghost trail
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-<script>
-  window.__timelines = window.__timelines || {};
-  const tl = gsap.timeline({ paused: true });
-
-  // Lead element: same fast `out` move as Path A.
-  tl.fromTo(
-    "#streak-el",
-    { x: ENTER_FROM_X, opacity: 0 },
-    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
-    MOVE_START,
-  );
-
-  // Ghosts: each starts FURTHER back along the motion vector (deterministic, by index),
-  // dimmer, and collapses onto the lead — all on the SAME ease/window so they vanish at the settle.
-  const ghosts = gsap.utils.toArray(".streak-ghost");
-  ghosts.forEach((g) => {
-    const i = Number(g.dataset.i); // 1..N-1, set in HTML (no Math.random)
-    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,
-    );
-  });
-
-  window.__timelines["streak-scene"] = tl;
-</script>
-```
-
-## Variations
-
-### Vertical streak (rise / drop-in)
-
-Swap the motion axis: use `y` instead of `x` for the position tween, `stdDeviation="0 Y"` for Path A (blur on Y, 0 on X), and `ENTER_FROM_Y` / vertical echo offsets for Path B. A phrase that streaks _up_ into place pairs with `kinetic-type-beats`' rise-rotate beat.
-
-### Camera push-through (scale streak into a lockup)
-
-Instead of translating, the element rushes the camera: `scale: SCALE_FROM → 1` on the fast `out` ease, with a **radial / zoom blur** feel approximated by a symmetric `stdDeviation="B B"` envelope (blur on both axes since the smear is depth-wise, not directional). This is the `logo-assemble-lockup` push-through — the wordmark punches forward out of soft focus and snaps crisp at the lock.
-
-```js
-tl.fromTo(
-  "#streak-el",
-  { scale: SCALE_FROM, opacity: 0 },
-  { scale: 1, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
-  MOVE_START,
-);
-tl.to(
-  blurProxy,
-  {
-    v: 0,
-    duration: MOVE_DUR,
-    ease: MOVE_EASE,
-    onUpdate: () => blurNode.setAttribute("stdDeviation", `${blurProxy.v} ${blurProxy.v}`),
-  },
-  MOVE_START,
-);
-```
-
-### Staggered grid streak-in (cards assemble)
-
-For `grid-card-assemble`: each card streaks into its slot from its own backward offset, staggered. Drive every card off the same ease/window with a per-index delay; derive the entrance offset and start time from the card's index (no `Math.random`). Each card is sharp the instant it lands in its slot.
-
-```js
-gsap.utils.toArray(".grid-card").forEach((card, i) => {
-  const at = MOVE_START + i * CARD_STAGGER;
-  tl.fromTo(
-    card,
-    { x: ENTER_FROM_X, opacity: 0 },
-    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
-    at,
-  );
-  // + a per-card blur proxy tween at the same `at` (Path A), or per-card ghosts (Path B)
-});
-```
-
-### Hold-the-streak (whip emphasis on a single beat)
-
-For a single kinetic phrase that "zooms past," keep the streak slightly visible a frame or two longer by easing the blur on a marginally _slower_ curve than the position (e.g. position `expo.out`, blur `power3.out`) — the element arrives, then the last wisp of smear resolves. Use sparingly; the default is locked envelopes.
-
-## How to Choose Values
-
-### Motion
-
-- **MOVE_EASE** — shared ease for position and blur/echo.
-  - Range: `expo.out` (hardest snap), `power4.out` (hard slam, default), `power3.out` (firm but softer)
-  - Effects: harder `out` → velocity more front-loaded → blur reads as a sharper streak that resolves later in the window
-  - Constraints: must be an `out`-family ease (velocity front-loaded). An `inOut` or `in` ease puts peak speed mid/late and the blur-speed coupling breaks. **Position and blur must use the SAME ease** (except the deliberate Hold-the-streak variation).
-- **MOVE_DUR** — travel + blur-resolve duration.
-  - Range: 0.25–0.6 s
-  - Effects: shorter → more violent whip; longer → a glide, the streak loses punch
-  - Constraints: a streak is _fast_ — over ~0.7 s it stops reading as velocity blur and looks like a focus pull
-- **MOVE_START** — timeline position of the entrance.
-  - Constraints: leave **≥1 s of dwell** after `MOVE_START + MOVE_DUR` before the composition ends (climax dwell — a streak that lands at `t = DURATION − 0.2 s` reads as "flashed and gone")
-- **ENTER_FROM_X / ENTER_FROM_Y** — off-frame start offset along the motion axis.
-  - Range: 40–120% of the element's own dimension on that axis (far enough to read as "came from off-frame")
-  - Effects: larger → longer travel → the streak has more runway to read; too small and there's no sense of speed
-
-### Path A — SVG blur
-
-- **PEAK_BLUR** — `stdDeviation` at maximum velocity (start of the window).
-  - Range: 8 (subtle) → 18 (default) → 30 (extreme whip)
-  - Effects: higher → heavier smear at peak speed; too high erases the glyph entirely at the start frame
-  - Constraints: ≤ ~30 — beyond that the element is unreadable for the first several frames and reads as "missing then appearing"; the filter region (`x/y/width/height` on `<filter>`) must be large enough (≥`-50% … 200%`) or the smear clips at the box edge
-- **SCALE_FROM** (push-through variation) — starting scale for a camera push.
-  - Range: 1.3 (gentle push) → 2.5 (aggressive punch-through)
-
-### Path B — echo trail
-
-- **N (ghost count)** — number of ghosts behind the lead (set by how many `.streak-ghost` you author).
-  - Range: 2–4
-  - Effects: more ghosts → a longer, smoother smear; >4 reads as a stutter / strobe rather than a streak
-- **ECHO_STEP_PX** — backward offset per ghost along the motion vector.
-  - Range: 12–40 px
-  - Effects: larger → a more spread-out, visible trail; smaller → a tight blur-like cluster
-  - Constraints: `(N) × ECHO_STEP_PX` should be ≲ `ENTER_FROM_X` so the furthest ghost still starts within the travel runway
-- **GHOST_BASE_OPACITY** — opacity of the nearest ghost (`i = 1`); falls off as `BASE / i`.
-  - Range: 0.3 (faint) → 0.6 (pronounced)
-  - Constraints: ≤ ~0.6 — opaque ghosts read as duplicate elements, not a trail
-
-### Layout & type
-
-- **EL_FONT_SIZE / EL_TRACKING** — the streaking element's type weight (when it's a phrase).
-  - Constraints: heavy display weight (≥120 px at 1080p, ≥800 weight) so the smear has mass to streak; thin type smears into invisibility
-- **CARD_STAGGER** (grid variation) — delay between consecutive cards.
-  - Range: 0.05–0.12 s — tight enough to read as one assembling wave, not separate arrivals
-
-### Tokens
-
-- **{sceneBg}** — background; a streak reads best against a solid / low-detail field (a busy bg fights the smear)
-- **{font}** — typographic stack (embedded display face if the streaking element is text — see typography reference)
-- **{textColor}** — element color; for Path B the ghosts inherit this, so a slightly desaturated trail can be had by tinting `.streak-ghost` separately
-- **{phrase}** — the word / glyph / wordmark that streaks in
-
-## Key Principles
-
-- **Blur peaks at peak speed, resolves to 0 at the settle** — this is the whole rule. Share the ease and window between the position tween and the blur/echo envelope so they're locked. A blur that lingers after the element stops, or peaks after it's already slow, reads as a focus pull, not velocity.
-- **`out`-family ease, always** — velocity must be front-loaded (fast off the start, decelerating in). `expo.out` / `power4.out` / `power3.out`. An `in` or `inOut` ease puts peak speed in the wrong place and the coupling falls apart.
-- **Directional blur on the motion axis** (Path A) — `stdDeviation="X 0"` for horizontal, `"0 Y"` for vertical, `"B B"` only for a depth/scale push. A symmetric blur on a sideways move looks like defocus, not speed.
-- **Tween a proxy, write the attribute** (Path A) — GSAP tweens the plain `{ v }` object; `onUpdate` calls `setAttribute("stdDeviation", …)`. You cannot tween the SVG attribute directly, and you must **seed it once at setup** so a seek to `t=0` shows the streaked start.
-- **Ghosts are deterministic, by index** (Path B) — offset `i * ECHO_STEP_PX`, opacity `BASE / i`. Never `Math.random` for the trail; index drives all per-ghost variation so every seek is identical.
-- **Entrances only, never a mid-composition exit** — a streak is an _arrival_. A blurred element leaving on a non-final frame reads as a glitch; scene-to-scene exits are the transition's job (see `../../transitions/overview.md`).
-- **Earn the sharp hold** — after the snap, the crisp element must dwell ≥1 s. The contrast between the violent streak and the still, sharp settle _is_ the effect.
-- **Heavy element, solid background** — thin type or a busy backdrop both swallow the smear. Big bold mass on a clean field reads.
-
-## Critical Constraints
-
-- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`.
-- **Registry key = `data-composition-id`** on the root.
-- **No CSS `transition`** on the streaking element (or ghosts) — it interpolates independently of HF seek and causes flicker. Only GSAP drives the move and the blur.
-- **No `repeat` / `yoyo` / infinite** — a streak is a single finite arrival. Finite tweens only.
-- **No `Math.random` / `Date.now`** — ghost offsets/opacities and any stagger derive from the element index; deterministic every seek.
-- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation`. Never tween `width` / `height` / `left` / `top`. Tweening `filter` (the proxy → `stdDeviation`) and `opacity` is seek-safe and fine.
-- **Seed the SVG `stdDeviation` at setup** (Path A) — write it once before play so a seek to the first frame renders the streaked start, not a momentarily-sharp pre-frame.
-- **Filter region must be generous** (Path A) — `<filter x="-50%" y="-50%" width="200%" height="200%">` so the smear doesn't clip at the element's box edge.
-- **`overflow: hidden` on the scene** — the smear / furthest ghost extends past the resting position during travel; contain it so it doesn't bleed outside the frame.
-
-## Combinations
-
-- [kinetic-beat-slam.md](kinetic-beat-slam.md) — use this streak as the entrance for one phrase in a beat sequence (the scale-slam beat _is_ a motion-blur fly-in); reads its onset from the shared `BEATS[]` array
-- [center-outward-expansion.md](center-outward-expansion.md) — the grid streak-in is center-expansion with a velocity-blur envelope on each element's travel
-- [3d-text-depth-layers.md](3d-text-depth-layers.md) — extruded depth on the phrase that streaks in (depth layers ride the lead's transform)
-- [scale-swap-transition.md](scale-swap-transition.md) — alternative for a SAME-footprint state swap (this rule is for a fast ARRIVAL from off-frame / depth, not a morph)
-
-## Pairs with HF skills
-
-- `/hyperframes-animation` — `out`-family easing, proxy-driven `onUpdate` attribute tweens, and locked-envelope coordination (`../../adapters/gsap-easing-and-stagger.md`)
-- `/hyperframes-creative` — `references/typography.md` (embedded display face for a text streak), `references/video-composition.md` (solid field behind the smear)
-- `/hyperframes-core` — composition wiring, determinism (finite tweens, no `Math.random`)
-- `/hyperframes-cli` — `hyperframes lint` / `hyperframes validate` (validate catches a missing `#streak-blur` node or an unreferenced filter)
+---
+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 per-frame motion blur isn't available to a seeked renderer (it integrates over shutter time, which a paused timeline has no concept of), so this rule **fakes** it for a fast element fly-in or a hard camera push-through. The blur **peaks at maximum velocity and resolves to 0 at the settle** — the element reads as streaking in then snapping sharp on arrival. 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 implementation paths, both finite, deterministic, and seek-safe:
+
+- **(A) Directional SVG blur** — an inline `<filter>` with `<feGaussianBlur stdDeviation="X 0">` (X on the axis of motion, 0 across it). GSAP tweens `X` from high → 0 through a proxy that calls `setAttribute` each frame. Cleanest, one element, true directional smear.
+- **(B) Echo / ghost trail** — 2–4 duplicate copies at decreasing opacity, offset backward along the motion vector, collapsing into the lead element as it settles. No filter cost; reads as a "speed-line" stutter trail. Better when you want the streak _colored_ or _stylized_ rather than a literal optical blur.
+
+This is for **entrances and mid-shot moves only** — a fast arrival, a beat that zooms past camera, a card slamming into a grid slot, a logo punching through into a lockup. **Never an exit on a non-final frame** (a blurred element fleeing off-frame mid-composition reads as a glitch, and a hard exit between scenes is the transition's job, not a per-element blur).
+
+## How It Works
+
+A fast move has a velocity profile: it accelerates off the start, peaks, then decelerates into the settle. An `out` ease (`expo.out`, `power4.out`) front-loads that — velocity is highest right at the start and bleeds to zero at the end. The fake works by mapping a **blur (or echo) envelope onto that same curve**:
+
+1. **Position tween** — the element travels from an off-frame / pushed-back start to its resting transform (`x`/`y` for a fly-in, `scale` for a push-through) on a fast `out` ease over `MOVE_DUR`.
+2. **Blur envelope** — in lockstep over the **same window and ease**, the smear goes from `PEAK_BLUR` → `0`. Because the ease front-loads velocity and the envelope shares it, max blur coincides with max speed, and blur hits exactly `0` as the element lands.
+3. **Settle is sharp** — by `MOVE_START + MOVE_DUR` the element is at its resting transform with blur `0` (path A) or all echoes collapsed onto the lead (path B). It then holds, fully crisp, for the climax dwell.
+
+Path A tweens the filter's `stdDeviation` attribute (a non-DOM-style numeric attribute) via a **proxy object** — GSAP can't tween an SVG attribute directly, so you tween a plain `{ v: PEAK_BLUR }` and write it back with `setAttribute` in `onUpdate`. Path B places the ghosts at deterministic backward offsets (`i * ECHO_STEP_PX`) and fades/collapses them on the same envelope.
+
+## HTML
+
+### Path A — directional SVG blur (recommended default)
+
+```html
+<div
+  class="scene"
+  id="streak-scene"
+  data-composition-id="streak-scene"
+  data-start="0"
+  data-duration="DURATION"
+  data-track-index="0"
+>
+  <!-- Inline filter: blur on the X axis only (stdDeviation="X 0"); 0 on Y keeps it a clean horizontal smear. -->
+  <svg width="0" height="0" aria-hidden="true" style="position: absolute">
+    <defs>
+      <filter id="streak" x="-50%" y="-50%" width="200%" height="200%">
+        <feGaussianBlur id="streak-blur" in="SourceGraphic" stdDeviation="0 0" />
+      </filter>
+    </defs>
+  </svg>
+
+  <div class="streak-stage">
+    <div class="streak-el" id="streak-el">{phrase}</div>
+  </div>
+</div>
+```
+
+### Path B — echo / ghost trail
+
+```html
+<div
+  class="scene"
+  id="streak-scene"
+  data-composition-id="streak-scene"
+  data-start="0"
+  data-duration="DURATION"
+  data-track-index="0"
+>
+  <div class="streak-stage">
+    <!-- N-1 ghosts BEHIND the lead, then the lead on top. Ghosts are aria-hidden duplicates. -->
+    <div class="streak-ghost" data-i="3" aria-hidden="true">{phrase}</div>
+    <div class="streak-ghost" data-i="2" aria-hidden="true">{phrase}</div>
+    <div class="streak-ghost" data-i="1" aria-hidden="true">{phrase}</div>
+    <div class="streak-el" id="streak-el">{phrase}</div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {sceneBg};
+  font-family: {font};
+  overflow: hidden; /* the smear/echo extends past the resting position before settling */
+}
+.streak-stage {
+  position: relative;
+  display: grid;
+  place-items: center;
+}
+.streak-el {
+  position: relative;
+  z-index: 2;
+  font-size: EL_FONT_SIZE;
+  font-weight: 900;
+  letter-spacing: EL_TRACKING;
+  color: {textColor};
+  /* Path A only — reference the directional filter. (Omit for Path B.) */
+  filter: url(#streak);
+  will-change: transform, filter;
+}
+
+/* Path B ghosts — identical glyphs behind the lead, decreasing opacity */
+.streak-ghost {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  z-index: 1;
+  font-size: EL_FONT_SIZE;
+  font-weight: 900;
+  letter-spacing: EL_TRACKING;
+  color: {textColor};
+  opacity: 0;
+  will-change: transform, opacity;
+  pointer-events: none;
+}
+```
+
+## GSAP Timeline
+
+### Path A — directional SVG blur
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // GSAP can't tween an SVG attribute directly — tween a proxy and write it back each frame.
+  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 so a seek to t=0 shows the streaked start, not a sharp pre-frame
+
+  // Position: travel from off-frame to rest on a fast `out` ease (velocity front-loaded).
+  tl.fromTo(
+    "#streak-el",
+    { x: ENTER_FROM_X, opacity: 0 },
+    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
+    MOVE_START,
+  );
+
+  // Blur envelope: SAME window + SAME ease so peak-blur == peak-speed, resolving to 0 at the settle.
+  tl.to(blurProxy, { v: 0, duration: MOVE_DUR, ease: MOVE_EASE, onUpdate: writeBlur }, MOVE_START);
+
+  window.__timelines["streak-scene"] = tl;
+</script>
+```
+
+### Path B — echo / ghost trail
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // Lead element: same fast `out` move as Path A.
+  tl.fromTo(
+    "#streak-el",
+    { x: ENTER_FROM_X, opacity: 0 },
+    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
+    MOVE_START,
+  );
+
+  // Ghosts: each starts FURTHER back along the motion vector (deterministic, by index),
+  // dimmer, and collapses onto the lead — all on the SAME ease/window so they vanish at the settle.
+  const ghosts = gsap.utils.toArray(".streak-ghost");
+  ghosts.forEach((g) => {
+    const i = Number(g.dataset.i); // 1..N-1, set in HTML (no Math.random)
+    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,
+    );
+  });
+
+  window.__timelines["streak-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Vertical streak (rise / drop-in)
+
+Swap the motion axis: use `y` instead of `x` for the position tween, `stdDeviation="0 Y"` for Path A (blur on Y, 0 on X), and `ENTER_FROM_Y` / vertical echo offsets for Path B. A phrase that streaks _up_ into place pairs with `kinetic-type-beats`' rise-rotate beat.
+
+### Camera push-through (scale streak into a lockup)
+
+Instead of translating, the element rushes the camera: `scale: SCALE_FROM → 1` on the fast `out` ease, with a **radial / zoom blur** feel approximated by a symmetric `stdDeviation="B B"` envelope (blur on both axes since the smear is depth-wise, not directional). This is the `logo-assemble-lockup` push-through — the wordmark punches forward out of soft focus and snaps crisp at the lock.
+
+```js
+tl.fromTo(
+  "#streak-el",
+  { scale: SCALE_FROM, opacity: 0 },
+  { scale: 1, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
+  MOVE_START,
+);
+tl.to(
+  blurProxy,
+  {
+    v: 0,
+    duration: MOVE_DUR,
+    ease: MOVE_EASE,
+    onUpdate: () => blurNode.setAttribute("stdDeviation", `${blurProxy.v} ${blurProxy.v}`),
+  },
+  MOVE_START,
+);
+```
+
+### Staggered grid streak-in (cards assemble)
+
+For `grid-card-assemble`: each card streaks into its slot from its own backward offset, staggered. Drive every card off the same ease/window with a per-index delay; derive the entrance offset and start time from the card's index (no `Math.random`). Each card is sharp the instant it lands in its slot.
+
+```js
+gsap.utils.toArray(".grid-card").forEach((card, i) => {
+  const at = MOVE_START + i * CARD_STAGGER;
+  tl.fromTo(
+    card,
+    { x: ENTER_FROM_X, opacity: 0 },
+    { x: 0, opacity: 1, duration: MOVE_DUR, ease: MOVE_EASE },
+    at,
+  );
+  // + a per-card blur proxy tween at the same `at` (Path A), or per-card ghosts (Path B)
+});
+```
+
+### Hold-the-streak (whip emphasis on a single beat)
+
+For a single kinetic phrase that "zooms past," keep the streak slightly visible a frame or two longer by easing the blur on a marginally _slower_ curve than the position (e.g. position `expo.out`, blur `power3.out`) — the element arrives, then the last wisp of smear resolves. Use sparingly; the default is locked envelopes.
+
+## How to Choose Values
+
+### Motion
+
+- **MOVE_EASE** — shared ease for position and blur/echo.
+  - Range: `expo.out` (hardest snap), `power4.out` (hard slam, default), `power3.out` (firm but softer)
+  - Effects: harder `out` → velocity more front-loaded → blur reads as a sharper streak that resolves later in the window
+  - Constraints: must be an `out`-family ease (velocity front-loaded). An `inOut` or `in` ease puts peak speed mid/late and the blur-speed coupling breaks. **Position and blur must use the SAME ease** (except the deliberate Hold-the-streak variation).
+- **MOVE_DUR** — travel + blur-resolve duration.
+  - Range: 0.25–0.6 s
+  - Effects: shorter → more violent whip; longer → a glide, the streak loses punch
+  - Constraints: a streak is _fast_ — over ~0.7 s it stops reading as velocity blur and looks like a focus pull
+- **MOVE_START** — timeline position of the entrance.
+  - Constraints: leave **≥1 s of dwell** after `MOVE_START + MOVE_DUR` before the composition ends (climax dwell — a streak that lands at `t = DURATION − 0.2 s` reads as "flashed and gone")
+- **ENTER_FROM_X / ENTER_FROM_Y** — off-frame start offset along the motion axis.
+  - Range: 40–120% of the element's own dimension on that axis (far enough to read as "came from off-frame")
+  - Effects: larger → longer travel → the streak has more runway to read; too small and there's no sense of speed
+
+### Path A — SVG blur
+
+- **PEAK_BLUR** — `stdDeviation` at maximum velocity (start of the window).
+  - Range: 8 (subtle) → 18 (default) → 30 (extreme whip)
+  - Effects: higher → heavier smear at peak speed; too high erases the glyph entirely at the start frame
+  - Constraints: ≤ ~30 — beyond that the element is unreadable for the first several frames and reads as "missing then appearing"; the filter region (`x/y/width/height` on `<filter>`) must be large enough (≥`-50% … 200%`) or the smear clips at the box edge
+- **SCALE_FROM** (push-through variation) — starting scale for a camera push.
+  - Range: 1.3 (gentle push) → 2.5 (aggressive punch-through)
+
+### Path B — echo trail
+
+- **N (ghost count)** — number of ghosts behind the lead (set by how many `.streak-ghost` you author).
+  - Range: 2–4
+  - Effects: more ghosts → a longer, smoother smear; >4 reads as a stutter / strobe rather than a streak
+- **ECHO_STEP_PX** — backward offset per ghost along the motion vector.
+  - Range: 12–40 px
+  - Effects: larger → a more spread-out, visible trail; smaller → a tight blur-like cluster
+  - Constraints: `(N) × ECHO_STEP_PX` should be ≲ `ENTER_FROM_X` so the furthest ghost still starts within the travel runway
+- **GHOST_BASE_OPACITY** — opacity of the nearest ghost (`i = 1`); falls off as `BASE / i`.
+  - Range: 0.3 (faint) → 0.6 (pronounced)
+  - Constraints: ≤ ~0.6 — opaque ghosts read as duplicate elements, not a trail
+
+### Layout & type
+
+- **EL_FONT_SIZE / EL_TRACKING** — the streaking element's type weight (when it's a phrase).
+  - Constraints: heavy display weight (≥120 px at 1080p, ≥800 weight) so the smear has mass to streak; thin type smears into invisibility
+- **CARD_STAGGER** (grid variation) — delay between consecutive cards.
+  - Range: 0.05–0.12 s — tight enough to read as one assembling wave, not separate arrivals
+
+### Tokens
+
+- **{sceneBg}** — background; a streak reads best against a solid / low-detail field (a busy bg fights the smear)
+- **{font}** — typographic stack (embedded display face if the streaking element is text — see typography reference)
+- **{textColor}** — element color; for Path B the ghosts inherit this, so a slightly desaturated trail can be had by tinting `.streak-ghost` separately
+- **{phrase}** — the word / glyph / wordmark that streaks in
+
+## Key Principles
+
+- **Blur peaks at peak speed, resolves to 0 at the settle** — this is the whole rule. Share the ease and window between the position tween and the blur/echo envelope so they're locked. A blur that lingers after the element stops, or peaks after it's already slow, reads as a focus pull, not velocity.
+- **`out`-family ease, always** — velocity must be front-loaded (fast off the start, decelerating in). `expo.out` / `power4.out` / `power3.out`. An `in` or `inOut` ease puts peak speed in the wrong place and the coupling falls apart.
+- **Directional blur on the motion axis** (Path A) — `stdDeviation="X 0"` for horizontal, `"0 Y"` for vertical, `"B B"` only for a depth/scale push. A symmetric blur on a sideways move looks like defocus, not speed.
+- **Tween a proxy, write the attribute** (Path A) — GSAP tweens the plain `{ v }` object; `onUpdate` calls `setAttribute("stdDeviation", …)`. You cannot tween the SVG attribute directly, and you must **seed it once at setup** so a seek to `t=0` shows the streaked start.
+- **Ghosts are deterministic, by index** (Path B) — offset `i * ECHO_STEP_PX`, opacity `BASE / i`. Never `Math.random` for the trail; index drives all per-ghost variation so every seek is identical.
+- **Entrances only, never a mid-composition exit** — a streak is an _arrival_. A blurred element leaving on a non-final frame reads as a glitch; scene-to-scene exits are the transition's job (see `../../transitions/overview.md`).
+- **Earn the sharp hold** — after the snap, the crisp element must dwell ≥1 s. The contrast between the violent streak and the still, sharp settle _is_ the effect.
+- **Heavy element, solid background** — thin type or a busy backdrop both swallow the smear. Big bold mass on a clean field reads.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`.
+- **Registry key = `data-composition-id`** on the root.
+- **No CSS `transition`** on the streaking element (or ghosts) — it interpolates independently of HF seek and causes flicker. Only GSAP drives the move and the blur.
+- **No `repeat` / `yoyo` / infinite** — a streak is a single finite arrival. Finite tweens only.
+- **No `Math.random` / `Date.now`** — ghost offsets/opacities and any stagger derive from the element index; deterministic every seek.
+- **GSAP transform aliases only**: `x`, `y`, `scale`, `rotation`. Never tween `width` / `height` / `left` / `top`. Tweening `filter` (the proxy → `stdDeviation`) and `opacity` is seek-safe and fine.
+- **Seed the SVG `stdDeviation` at setup** (Path A) — write it once before play so a seek to the first frame renders the streaked start, not a momentarily-sharp pre-frame.
+- **Filter region must be generous** (Path A) — `<filter x="-50%" y="-50%" width="200%" height="200%">` so the smear doesn't clip at the element's box edge.
+- **`overflow: hidden` on the scene** — the smear / furthest ghost extends past the resting position during travel; contain it so it doesn't bleed outside the frame.
+
+## Combinations
+
+- [kinetic-beat-slam.md](kinetic-beat-slam.md) — use this streak as the entrance for one phrase in a beat sequence (the scale-slam beat _is_ a motion-blur fly-in); reads its onset from the shared `BEATS[]` array
+- [center-outward-expansion.md](center-outward-expansion.md) — the grid streak-in is center-expansion with a velocity-blur envelope on each element's travel
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — extruded depth on the phrase that streaks in (depth layers ride the lead's transform)
+- [scale-swap-transition.md](scale-swap-transition.md) — alternative for a SAME-footprint state swap (this rule is for a fast ARRIVAL from off-frame / depth, not a morph)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — `out`-family easing, proxy-driven `onUpdate` attribute tweens, and locked-envelope coordination (`../../adapters/gsap-easing-and-stagger.md`)
+- `/hyperframes-creative` — `references/typography.md` (embedded display face for a text streak), `references/video-composition.md` (solid field behind the smear)
+- `/hyperframes-core` — composition wiring, determinism (finite tweens, no `Math.random`)
+- `/hyperframes-cli` — `hyperframes lint` / `hyperframes validate` (validate catches a missing `#streak-blur` node or an unreferenced filter)