@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/kinetic-beat-slam.md

@@ -0,0 +1,183 @@
+---
+name: kinetic-beat-slam
+description: Percussive kinetic typography — short phrases slam in on a steady beat with distinct per-phrase entrances, optional rhythm chrome (metronome ticks, beat bar), then a locked finale.
+metadata:
+  tags: text, kinetic, typography, beat, rhythm, slam, percussive, punchy
+---
+
+# Kinetic Beat Slam
+
+Short phrases hit one at a time on a **steady beat**, each with a _different_ entrance, then stack into a locked finale. This is the recipe for "punchy / rhythmic" text-forward pieces (taglines, manifestos, hype intros). The difference between generic and rhythmic is (1) one shared **onset array** driving every element, (2) **distinct** entrances per phrase rather than one reused helper, and (3) optional **rhythm chrome** that visibly keeps the beat.
+
+## How It Works
+
+1. **Define the beat once.** A single `BEATS = [t0, t1, t2, …]` array (seconds) is the rhythmic spine. Every phrase entrance, accent, and chrome tick reads its time from this array — so the whole piece locks to one pulse instead of drifting hand-tuned offsets.
+2. **Vary the entrances.** Phrase 1 slams (scale + blur), phrase 2 snaps from the side, phrase 3 rises and rotates. Same _energy_, different _form_ — reusing one `punchIn()` for all three reads as flat.
+3. **Land a finale.** All phrases lock into a left-aligned or centered stack; an accent underline sweeps in; optionally a continuous low-amplitude pulse holds the last beat.
+
+## Beat & Easing
+
+Pick the entrance easing by attack character (the choice is discrete):
+
+| GSAP ease     | Attack feel                                 |
+| ------------- | ------------------------------------------- |
+| `power4.out`  | Hard slam, fast settle ⭐ default for a hit |
+| `expo.out`    | Hardest snap (side-snaps, whip-ins)         |
+| `back.out(2)` | Overshoot pop — accents, not body words     |
+| `circ.out`    | Heavy rise with momentum                    |
+
+Use **at least 3 distinct easings** across the piece (entrances are its "tone of voice"). Keep durations short — 0.35–0.6s on the hit, ≤0.25s on the exit — so the beat stays percussive.
+
+## HTML
+
+```html
+<section class="clip" data-start="0" data-duration="15" data-track-index="1">
+  <div class="kbs-stage">
+    <div class="kbs-line" id="p1"><span class="verb">Notice</span> more.</div>
+    <div class="kbs-line" id="p2"><span class="verb">Decide</span> faster.</div>
+    <div class="kbs-line" id="p3"><span class="verb">Act</span> now.</div>
+  </div>
+  <!-- optional rhythm chrome -->
+  <div class="kbs-metronome" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></div>
+</section>
+```
+
+## CSS
+
+```css
+.kbs-stage {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 8px;
+  padding: 120px 160px; /* title-safe margin */
+  box-sizing: border-box;
+}
+.kbs-line {
+  font-family: "Archivo Black", "League Gothic", sans-serif; /* embedded display face */
+  font-size: 150px;
+  line-height: 0.96;
+  letter-spacing: -0.03em;
+  color: #f5f5f5;
+  will-change: transform, filter, opacity;
+}
+.kbs-line .verb {
+  color: #ff5b2e;
+} /* one accent hue */
+.kbs-metronome {
+  position: absolute;
+  bottom: 64px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 14px;
+}
+.kbs-metronome i {
+  width: 6px;
+  height: 28px;
+  background: #ff5b2e;
+  opacity: 0.25;
+}
+```
+
+## GSAP Timeline
+
+```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 });
+
+  // ONE tempo grid drives everything — phrases AND the metronome read it (no scattered offsets).
+  const PULSE = 0.4; // seconds per sub-beat (the grid)
+  const BEATS = [PULSE * 1, PULSE * 5, PULSE * 9]; // phrase onsets, on the grid
+
+  // Distinct entrances per phrase (NOT one reused helper).
+  tl.fromTo(
+    "#p1",
+    { scale: 1.5, filter: "blur(16px)", opacity: 0 },
+    { scale: 1, filter: "blur(0px)", opacity: 1, duration: 0.5, ease: "power4.out" },
+    BEATS[0],
+  );
+  tl.fromTo(
+    "#p2",
+    { x: -320, opacity: 0 },
+    { x: 0, opacity: 1, duration: 0.45, ease: "expo.out" },
+    BEATS[1],
+  );
+  tl.fromTo(
+    "#p3",
+    { y: 90, rotation: 6, opacity: 0 },
+    { y: 0, rotation: 0, opacity: 1, duration: 0.55, ease: "circ.out" },
+    BEATS[2],
+  );
+
+  // Rhythm chrome: each metronome tick flashes on the SAME grid (PULSE), not a magic offset.
+  const ticks = gsap.utils.toArray(".kbs-metronome i");
+  ticks.forEach((tick, i) => {
+    tl.to(
+      tick,
+      { opacity: 1, duration: 0.08, yoyo: true, repeat: 1, ease: "none" },
+      PULSE * (i + 1),
+    );
+  });
+
+  // Finale hold: a low-amplitude breath on the locked stack.
+  // floor (not ceil) so the repeat never overshoots data-duration; max(0,…) so a short hold
+  // never yields a negative repeat (GSAP treats negative repeat as -1 = infinite = non-deterministic).
+  const holdStart = BEATS[2] + 0.7,
+    cycle = 1.6,
+    holdDur = 15 - holdStart;
+  tl.to(
+    ".kbs-stage",
+    {
+      scale: 1.01,
+      duration: cycle / 2,
+      ease: "sine.inOut",
+      yoyo: true,
+      repeat: Math.max(0, Math.floor(holdDur / cycle) - 1),
+    },
+    holdStart,
+  );
+
+  window.__timelines["main"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **BEATS spacing** — 1.2–1.8s between hits reads as a confident beat; <0.8s feels frantic, >2.5s loses the pulse. Keep spacing even (it's a _beat_).
+- **Entrance duration** — 0.35–0.6s. The hit must resolve before the next beat.
+- **Distinct entrances** — assign a different transform axis per phrase (scale / x / y+rotate). Reuse the _ease family_, vary the _motion_.
+- **Accent hue** — exactly one (the verbs). The rest is mono white/near-black.
+- **Rhythm chrome** — optional but high-impact for "rhythmic": a 5-tick metronome, a center beat bar, or a `// label` monospace tag pulsing on-beat. Mark any decorative that must survive a shader transition per `../../transitions/overview.md` rules.
+
+## Key Principles
+
+- **One beat array, not scattered offsets** — every element times off `BEATS[]`. This is the single biggest lever for "rhythmic."
+- **Different entrance per phrase** — a reused `punchIn()` for all lines is the flat-but-competent tell.
+- **Short attacks** — percussive means fast in, brief, decisive. Long fades kill the beat.
+- **One accent hue, heavy weight** — embedded display faces (Archivo Black, League Gothic, Oswald) at 150px+; see `hyperframes-creative/references/typography.md`.
+- **Finale earns the hold** — stack + underline sweep + optional breath; don't just leave the last phrase sitting.
+
+## Critical Constraints
+
+- **Timeline paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`.
+- **No infinite repeats** on the hold/chrome — use `repeat: Math.max(0, Math.floor(dur / cycle) - 1)` (no `repeat: -1`). Use **`Math.floor`, not `Math.ceil`** — `ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint rule; the `Math.max(0, …)` guards against a negative repeat (which GSAP reads as `-1` = infinite = non-deterministic) when the hold is shorter than two cycles.
+- **No banned exit animations** between scenes — if this is one of several scenes, the _transition_ is the exit (see `../../transitions/overview.md`); only a final scene may fade out.
+- **Display font must be embedded** or it silently falls back at render (Anton/Bebas-as-literal are NOT embedded — `Bebas Neue` aliases to League Gothic; verify in `typography.md`).
+- **Registry key = `data-composition-id`** on the root.
+
+## Combinations
+
+- [3d-text-depth-layers.md](3d-text-depth-layers.md) — extruded depth on the slammed words
+- [css-marker-patterns.md](css-marker-patterns.md) — underline sweep / circle on the finale
+- [sine-wave-loop.md](sine-wave-loop.md) — the finale breath/pulse
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + easing vocabulary (`../../adapters/gsap-easing-and-stagger.md`)
+- `/hyperframes-creative` — `references/video-composition.md` (foreground rhythm chrome), `references/typography.md` (embedded display fonts)
+- `/hyperframes-core` — composition wiring, determinism (finite repeats)

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

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