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

package/dist/assets/design/skills/hyperframes-animation/rules/gradient-text-sweep.md

@@ -0,0 +1,136 @@
+---
+name: gradient-text-sweep
+description: A gradient tweened THROUGH letterforms — background-clip:text + a backgroundPosition tween. Three forms: a continuous horizontal sweep inside a held headline, a traveling word-to-word highlight, and a hue-sweep that settles to a solid. Glyphs never move; finite, deterministic, seek-safe.
+metadata:
+  tags: gradient, text, sweep, background-clip, highlight, hue, typography, headline
+---
+
+# Gradient Text Sweep
+
+Color that lives **inside the glyphs**: the headline's fill is an oversized gradient clipped into the letterforms (`background-clip: text`), and the motion is the gradient sliding **through** the type — the letters never move. Three forms: a **continuous sweep** across a held title card, a **word-to-word highlight** that lights a line left→right, and a **hue-sweep** that settles to a solid.
+
+Boundaries: [asr-keyword-glow.md](asr-keyword-glow.md) is word-timed emphasis railed to ASR timestamps — this rule is a design beat with no audio rail. [ambient-glow-bloom.md](ambient-glow-bloom.md)'s traveling sweep is a sheen riding **over a surface**; here the gradient is masked **into the type** (its "Shimmer sweep" variation is this mechanism re-aimed as a working-state loop). [css-marker-patterns.md](css-marker-patterns.md) draws accents _around_ text, never fills.
+
+## How It Works
+
+The text carries a gradient background **wider than its own box** (`background-size: SWEEP_SPAN 100%`, e.g. `300% 100%`) clipped into the glyphs, so tweening `backgroundPosition` slides the gradient through the visible letterforms. Two gotchas own this rule:
+
+- **`background-position` percentages only produce travel when `background-size` exceeds 100%** — at 100% the image is pinned and the tween is a silent no-op.
+- **The percent axis runs opposite to the perceived travel** — tweening `"100% 50%"` → `"0% 50%"` moves the highlight left→right through the text.
+
+1. **Continuous sweep (held title card)** — one long **linear** `backgroundPosition` tween spanning the hold. First and last color stops equal, so the travel has no visible seam and reads as endless while remaining a single finite tween.
+2. **Word-to-word highlight** — each word is two pixel-identical stacked copies: a base copy in the resting color and a gradient-clipped copy at `opacity: 0`. A per-word opacity envelope (rise, then fall as the next word rises) passes the highlight along on an index-derived stagger — an **envelope, not a moving mask**: no per-word position measurement.
+3. **Hue-sweep → solid** — the gradient holds position while a `filter: hue-rotate()` tween sweeps its hues; the settle is a stacked-copy crossfade to a solid twin — never a color-stop tween (gradients with different stops don't interpolate reliably).
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<!-- Forms A/C: gradient headline; solid twin behind for the Form C settle -->
+<div class="headline-stack">
+  <h1 class="headline solid-twin">{headlineText}</h1>
+  <h1 class="headline gradient-fill" id="headline">{headlineText}</h1>
+</div>
+
+<!-- Form B: per-word stacked copies -->
+<p class="line">
+  <span class="word"><span class="w-base">{word1}</span><span class="w-hot">{word1}</span></span>
+  <span class="word"><span class="w-base">{word2}</span><span class="w-hot">{word2}</span></span>
+</p>
+```
+
+```css
+.headline-stack,
+.word {
+  display: grid; /* twins share one cell — pixel-identical boxes */
+}
+.headline,
+.w-base,
+.w-hot {
+  grid-area: 1 / 1;
+}
+.gradient-fill,
+.w-hot {
+  background-image: {gradient}; /* {sweepGradient} A/C, {highlightGradient} B */
+  background-size: SWEEP_SPAN 100%; /* MUST exceed 100% or the position tween is dead */
+  background-position: 100% 50%; /* start; tween toward 0% for left→right travel */
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+.solid-twin {
+  color: {settleColor};
+}
+.w-base {
+  color: {restColor};
+}
+.w-hot {
+  opacity: 0; /* the envelope raises it as the highlight passes */
+}
+```
+
+```js
+// Form A: continuous sweep. 100% → 0% reads left→right (percent axis inverted);
+// ease "none" — an eased sweep reads as an object, not light.
+tl.fromTo(
+  "#headline",
+  { backgroundPosition: "100% 50%" },
+  { backgroundPosition: "0% 50%", duration: SWEEP_DUR, ease: "none" },
+  SWEEP_START,
+);
+
+// Form B: traveling highlight — per-word rise/fall envelopes, index stagger.
+gsap.utils.toArray(".w-hot").forEach((el, i) => {
+  const at = HIGHLIGHT_START + i * WORD_LAG;
+  tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: HOT_RISE, ease: "power2.out" }, at);
+  tl.to(el, { opacity: 0, duration: HOT_FALL, ease: "power2.in" }, at + WORD_LAG);
+});
+
+// Form C: hue-sweep, then crossfade to the solid twin (never tween color stops).
+tl.fromTo(
+  "#headline",
+  { filter: "hue-rotate(0deg)" },
+  { filter: `hue-rotate(${HUE_RANGE}deg)`, duration: HUE_DUR, ease: "power1.inOut" },
+  HUE_START,
+);
+tl.to(
+  "#headline",
+  { opacity: 0, duration: SETTLE_SNAP_DUR, ease: "power2.in" },
+  HUE_START + HUE_DUR,
+);
+```
+
+## Variations
+
+- **Title-card crawl** — Form A stretched across a long terminal hold (3–8s end card): seamless-ended gradient, `ease: "none"`, `SWEEP_DUR` = the whole hold. One tween, no loop.
+- **One-pass sheen inside type** — gradient is the resting fill everywhere except one narrow highlight band (≤ ~25% of the span); one `backgroundPosition` pass carries the band through and the text returns to rest with no crossfade.
+- **Karaoke settle** — Form B with the fall tweens skipped: the line lights cumulatively left→right and holds fully lit; settle color = the hot state, base copies start dimmer.
+- **Gradient climax word** — one emphasized word (often ~-8° rotated) carries the gradient while the line stays solid; static gradient + a short Form C hue shift on landing, settling to the brand accent. Pairs with a `kinetic-beat-slam` arrival.
+
+## Values
+
+| token               | range                  | notes                                                                                |
+| ------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
+| SWEEP_SPAN          | 200–400%               | must exceed 100%; wider = softer/slower feel, narrower = busier color per glyph      |
+| SWEEP_DUR           | 1.2–3s                 | match the card's hold exactly; slower than ~4s stops registering as motion           |
+| WORD_LAG            | 0.25–0.5s              | HOT_FALL starts exactly WORD_LAG after the rise so envelopes cross — a gap = a blink |
+| HOT_RISE / HOT_FALL | 0.15–0.3s / 0.25–0.45s | fall slightly longer — the highlight "trails"                                        |
+| HUE_RANGE / HUE_DUR | 40–180° / 0.8–1.6s     | past ~180° the palette dissociates from itself mid-sweep                             |
+| SETTLE_SNAP_DUR     | 0.1–0.35s              | the goldens snap (~0.15s)                                                            |
+| {settleColor}       | —                      | one of the gradient's own stops (or the brand ink) so the settle reads as resolution |
+
+## Critical Constraints
+
+- **`background-size` > 100%** on any element whose `backgroundPosition` is tweened — otherwise the tween is a silent no-op.
+- **Percent axis is inverted** — left→right perceived travel is `100% → 0%`.
+- **Both `-webkit-background-clip: text` AND `background-clip: text`, with `color: transparent`** — missing the prefix renders a solid gradient block over the text in the capture browser.
+- **`ease: "none"` on position sweeps** — this is supposed to read as light, not an accelerating object.
+- **Seamless ends for a crawl** — first and last stops equal, or the wrap point flashes a hard edge mid-hold.
+- **Stacked copies pixel-identical** — same box, font, weight, tracking, one grid cell; any metric drift makes the crossfade a double-exposure.
+- **`data-layout-allow-occlusion` on the twin** — pixel-identical stacked copies trip `freecodego_design_lint`'s `text_occluded` gate by construction; the flag is the sanctioned waiver for this mechanism.
+- **Settle by crossfade, never by tweening stops**; and the glyphs never move — if the type must travel, that's a separate rule on the wrapper.
+- **No CSS `@keyframes` shimmer** — wall-clock animation desyncs from seek; every sweep is a timeline tween.
+
+## See also
+
+`kinetic-beat-slam` (slam lands the climax word, hue settle finishes it) · `spring-pop-entrance` (pop in solid, sweep after) · `discrete-text-sequence` (swap-slot under a riding crawl) · `ambient-glow-bloom` (surface-level sibling) · `css-marker-patterns` (strokes around text; fills here).

package/dist/assets/design/skills/hyperframes-animation/rules/gsap-effects.md

@@ -0,0 +1,196 @@
+# GSAP Effects for HyperFrames
+
+Drop-in animation patterns. Snippets show mechanism only, inside a standard scene clip (hyperframes-core); assume `tl` exists.
+
+- [Typewriter](#typewriter) — character-by-character reveal with optional cursor / backspace / word rotation
+- [Audio Visualizer](#audio-visualizer) — pre-extract audio data, drive Canvas/DOM rendering from the timeline
+
+## Typewriter
+
+Requires GSAP's TextPlugin alongside the core script:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/TextPlugin.min.js"></script>
+<script>
+  gsap.registerPlugin(TextPlugin);
+</script>
+```
+
+### Basic
+
+```js
+const text = "Hello, world!";
+const cps = 10; // chars per second — see timing table
+tl.to(
+  "#typed-text",
+  { text: { value: text }, duration: text.length / cps, ease: "none" },
+  startTime,
+);
+```
+
+### Blinking Cursor
+
+Three rules: **one cursor visible at a time** (hide previous before showing next); **cursor must blink when idle** (after typing, during holds); **no gap between text and cursor** (elements flush in HTML).
+
+```html
+<span id="typed-text"></span><span id="cursor" class="cursor-blink">|</span>
+```
+
+```css
+@keyframes blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+.cursor-blink {
+  animation: blink 0.8s step-end infinite;
+}
+.cursor-solid {
+  animation: none;
+  opacity: 1;
+}
+.cursor-hide {
+  animation: none;
+  opacity: 0;
+}
+```
+
+Pattern: blink → solid (typing starts) → type → blink (typing done):
+
+```js
+tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], startTime);
+tl.to("#typed-text", { text: { value: text }, duration: dur, ease: "none" }, startTime);
+tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], startTime + dur);
+```
+
+Multi-line handoff: hide previous cursor → blink new → brief pause (~0.5s) → solid when typing. Never go `hidden → solid` (skips the idle blink).
+
+### Backspacing
+
+TextPlugin removes from the front — wrong for backspace. Use manual substring removal:
+
+```js
+function backspace(tl, selector, word, startTime, cps) {
+  const el = document.querySelector(selector);
+  const interval = 1 / cps;
+  for (let i = word.length - 1; i >= 0; i--) {
+    tl.call(
+      () => (el.textContent = word.slice(0, i)),
+      [],
+      startTime + (word.length - i) * interval,
+    );
+  }
+  return word.length * interval;
+}
+```
+
+### Spacing With Static Text
+
+A typewriter word next to static text (`<span>Ship something</span><span style="margin-left:14px"><span id="word"></span><span id="cursor">|</span></span>` in a baseline-aligned flex row): use `margin-left` on the wrapper span. Don't use flex `gap` (it spaces the cursor from the text) and don't put a trailing space in the static text (it collapses when the dynamic span is empty).
+
+### Word Rotation
+
+Type → hold → backspace → next word; cursor blinks during every idle moment:
+
+```js
+let offset = 0;
+words.forEach((word, i) => {
+  const typeDur = word.length / 10;
+  // cursor: solid while typing, blink during holds (same call pattern as above)
+  tl.to("#typed-text", { text: { value: word }, duration: typeDur, ease: "none" }, offset);
+  offset += typeDur + 1.5; // hold
+  if (i < words.length - 1) offset += backspace(tl, "#typed-text", word, offset, 20) + 0.3;
+});
+```
+
+### Appending Words
+
+Build a sentence word-by-word into the same element: keep an `accumulated` string, each step tweens `text: { value: accumulated + " " + word }` with `duration: newChars / cps`, then advances the offset.
+
+### Timing Guide
+
+| CPS   | Feel             | Good for                   |
+| ----- | ---------------- | -------------------------- |
+| 3-5   | Slow, deliberate | Dramatic reveals, suspense |
+| 8-12  | Natural typing   | Dialogue, narration        |
+| 15-20 | Fast, energetic  | Tech demos, code           |
+| 30+   | Near-instant     | Filling long blocks        |
+
+## Audio Visualizer
+
+Pre-extract audio data, drive Canvas / DOM rendering from the timeline. **Do not use the Web Audio API at render time** — there's no playback during seek.
+
+### Extract Audio Data
+
+Bundled extractor (requires `ffmpeg` + Python `numpy`):
+
+```bash
+python skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 -o audio-data.json
+python skills/hyperframes-creative/scripts/extract-audio-data.py video.mp4 --fps 30 --bands 16 -o audio-data.json
+```
+
+Output: `{ "fps": 30, "totalFrames": 5415, "frames": [{ "time": 0.0, "rms": 0.42, "bands": [0.8, 0.6, 0.3] }] }` — `rms` (0-1) is overall loudness; `bands[]` (0-1) are frequency magnitudes, index 0 = bass, each band normalized independently.
+
+### Loading (Synchronously)
+
+Inline the JSON for small files (< ~500 KB), or sync XHR for large ones:
+
+```js
+const xhr = new XMLHttpRequest();
+xhr.open("GET", "audio-data.json", false); // synchronous — deliberate
+xhr.send();
+const AUDIO_DATA = JSON.parse(xhr.responseText);
+```
+
+**Do NOT use async `fetch()`** — HyperFrames reads `window.__timelines` synchronously after page load; building the timeline inside `.then()` means it isn't ready when capture starts.
+
+### Driving the Timeline
+
+Canvas 2D is the workhorse (bars, waveforms, circles, gradients) — one `tl.call` per frame:
+
+```js
+const ctx = document.getElementById("viz").getContext("2d");
+for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    () => {
+      const frame = AUDIO_DATA.frames[f];
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      // draw using frame.rms and frame.bands
+    },
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+```
+
+WebGL / Three.js: HyperFrames patches `THREE.Clock` for deterministic time — update uniforms from audio data each frame. DOM elements: fine under ~20 elements, slower than Canvas beyond that.
+
+### Smoothing
+
+```js
+let prev = null;
+const smoothing = 0.25; // 0.1-0.2 snappy, 0.3-0.5 flowing
+function smooth(f) {
+  const raw = AUDIO_DATA.frames[f];
+  if (!prev) prev = { rms: raw.rms, bands: [...raw.bands] };
+  else {
+    prev = {
+      rms: prev.rms * smoothing + raw.rms * (1 - smoothing),
+      bands: raw.bands.map((b, i) => prev.bands[i] * smoothing + b * (1 - smoothing)),
+    };
+  }
+  return prev;
+}
+```
+
+### Design Guide
+
+- **Spatial mapping** — horizontal: bass left, treble right; vertical: bass bottom; circular: bass at 12 o'clock, wrap clockwise (mirror for a full circle).
+- **Bass drives big moves** (scale, glow, position); **treble drives detail** (shimmer, flicker, edges); **RMS drives globals** (background brightness, overall energy).
+- Pick 2-3 animated properties — more looks noisy. Keep minimums above zero so quiet sections still have life.
+- **Band count**: 4 = background glow/pulse, 8 = bar charts, 16 = detailed EQ (default), 32 = dense radial layouts.
+- **Layering**: stack canvases with `z-index` — a background layer driven by bass/rms under a foreground layer driven by individual bands gives depth without per-element complexity.

package/dist/assets/design/skills/hyperframes-animation/rules/hacker-flip-3d.md

@@ -0,0 +1,123 @@
+---
+name: hacker-flip-3d
+description: Character-level 3D rotation with random glyph substitution for a decryption reveal effect.
+metadata:
+  tags: text, 3d, reveal, decode, hacker, randomization, perspective
+---
+
+# Hacker Flip 3D Reveal
+
+Characters flip down from 90° in 3D while cycling through pseudo-random glyphs, then settle on the target character — a "decryption" / airport flap-display reveal. Resolves to a short target word (typically a brand or label).
+
+## How It Works
+
+Each character gets its own per-char tween from `rotateX: 90deg` (hidden, hinged at the bottom edge) to `0deg` (upright), staggered across the word. Below `REVEAL_THRESHOLD` progress the char displays a seeded pseudo-random glyph that reshuffles every few frames; past it, the real target character clicks into place — so the eye catches the right letter just as the flip settles. A hidden ghost copy of the full word reserves layout width so narrow flicker glyphs never shift the line.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="hacker-text-wrap" id="hacker-text" data-target="{phrase}">
+  <!-- ghost row + per-char spans injected by the setup script -->
+</div>
+```
+
+```css
+/* the scene root (or nearest 3D ancestor) MUST set perspective: 1500px */
+.hacker-text-wrap {
+  font-family: {monoFont}; /* monospace so flicker glyphs hold width */
+  font-weight: 900;
+  font-size: HACKER_FONT_SIZE;
+  position: relative; /* ghost stacks absolutely behind the live row */
+}
+.hacker-char {
+  display: inline-block;
+  transform-origin: bottom; /* flap-display hinge */
+  transform-style: preserve-3d;
+}
+.hacker-ghost {
+  opacity: 0;
+  pointer-events: none;
+  position: absolute;
+  inset: 0 auto auto 0;
+}
+```
+
+```js
+const wrap = document.getElementById("hacker-text");
+const targetWord = wrap.dataset.target;
+const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%&*";
+
+// Ghost row (reserves width) + live per-char spans
+const ghost = document.createElement("div");
+ghost.className = "hacker-ghost";
+ghost.textContent = targetWord;
+wrap.appendChild(ghost);
+const charEls = [...targetWord].map((ch) => {
+  const span = document.createElement("span");
+  span.className = "hacker-char";
+  span.textContent = ch === " " ? " " : ch;
+  span.dataset.target = ch;
+  wrap.appendChild(span);
+  return span;
+});
+
+// Index-seeded hash — same frame always yields the same glyph
+function pseudoGlyph(seed) {
+  const h = ((seed * 9301 + 49297) % 233280) / 233280;
+  return GLYPHS[Math.floor(h * GLYPHS.length)];
+}
+
+charEls.forEach((el, i) => {
+  const state = { p: 0 };
+  tl.to(
+    state,
+    {
+      p: 1,
+      duration: FLIP_DURATION,
+      ease: "power3.out",
+      onUpdate: () => {
+        if (state.p < REVEAL_THRESHOLD) {
+          el.textContent = pseudoGlyph(i * 1000 + Math.floor(state.p * 100));
+        } else {
+          el.textContent = el.dataset.target === " " ? " " : el.dataset.target;
+        }
+        el.style.transform = `rotateX(${90 - state.p * 90}deg)`;
+        el.style.opacity = Math.min(1, state.p * 2);
+      },
+    },
+    i * CHAR_STAGGER,
+  );
+});
+```
+
+## Variations
+
+- **Top-down hinge** — `transform-origin: top` for a falling-flap look.
+- **Center spin** — `transform-origin: center` reads as a barrel roll, not a flap.
+- **Number-only pool** — restrict `GLYPHS` to digits for a price / countdown decode.
+- **Two-pass decode** — chain two `FLIP_DURATION` tweens with different glyph pools (symbols → letters → real) for a longer reveal.
+
+## Values
+
+| token            | range                           | notes                                                                              |
+| ---------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| HACKER_FONT_SIZE | 6–10% of viewport min-dimension | the flip IS the focal beat; ghost must use the identical size                      |
+| FLIP_DURATION    | 0.4–1.0s                        | under 0.4s the flicker phase has no time; over 1.0s drags                          |
+| CHAR_STAGGER     | 0.03–0.08s                      | total decode = `CHAR_STAGGER × (chars − 1) + FLIP_DURATION` — fit the phase budget |
+| REVEAL_THRESHOLD | 0.5–0.7                         | lower reveals too early (no tension); higher reads as a hard end-reveal            |
+| FLICKER_RATE     | 3–6 frames per glyph swap       | <3 looks like noise; >6 looks like discrete typing                                 |
+
+Reference: `../examples/proof-logo-chain.html` (163px, 0.55s, 0.033s, 0.6).
+
+## Critical Constraints
+
+- **`perspective` on the scene root REQUIRED** — without parent perspective, `rotateX` renders as a 2D squash, not a 3D flip; `transform-style: preserve-3d` on each char.
+- **Ghost placeholder** with identical content + font must back the live chars — without it, narrow glyphs shift the layout mid-flicker (monospace preferred; the ghost makes a proportional face recoverable).
+- **Flicker seed = char index + quantized progress** — the same frame must show the same glyph.
+- **Flicker rate ≥ ~3 frames per swap**; `onUpdate` work stays O(1) per char per frame.
+- **Center the flip dead-center and add NO decorative chrome** (timestamp lines, "// AUTH" tags, status dots) — the flip is the beat. A necessary secondary label is BIG typography (56–72px caps + tracking) in the same stack, never a tiny corner annotation.
+
+## See also
+
+`card-morph-anchor` (flip reveals a phrase, card morphs into the next shot) · `counting-dynamic-scale` (the numeric counterpart).

package/dist/assets/design/skills/hyperframes-animation/rules/kinetic-beat-slam.md

@@ -0,0 +1,137 @@
+---
+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 — 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
+
+A single tempo grid — `PULSE` seconds per sub-beat, `BEATS = [t0, t1, t2, …]` on that grid — is the rhythmic spine; every phrase entrance, accent, and chrome tick reads its time from it, so the piece locks to one pulse instead of drifting hand-tuned offsets. Each phrase gets a different transform axis (scale+blur slam / side snap / rise+rotate) with short attacks (0.35–0.6s on the hit), then the stack holds with a finite low-amplitude breath.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<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>
+```
+
+```css
+.kbs-stage {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: 120px 160px; /* title-safe margin */
+}
+.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;
+}
+.kbs-line .verb {
+  color: #ff5b2e; /* exactly 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;
+}
+```
+
+```js
+// ONE tempo grid drives everything — phrases AND the metronome read it.
+const PULSE = 0.4; // seconds per sub-beat
+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 tick flashes on the SAME grid, not a magic offset.
+gsap.utils.toArray(".kbs-metronome i").forEach((tick, i) => {
+  tl.to(tick, { opacity: 1, duration: 0.08, yoyo: true, repeat: 1, ease: "none" }, PULSE * (i + 1));
+});
+
+// Finale hold: floor (not ceil) so the repeat never overshoots data-duration;
+// max(0,…) so a short hold never yields a negative repeat (GSAP reads negative as -1 = infinite).
+const holdStart = BEATS[2] + 0.7,
+  cycle = 1.6,
+  holdDur = SCENE_DURATION - 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,
+);
+```
+
+## Variations
+
+- **Entrance easing by attack character** — `power4.out` hard slam default hit · `expo.out` hardest snap (side-snaps, whip-ins) · `back.out(2)` overshoot pop (accents only, not body words) · `circ.out` heavy rise with momentum. Use **at least 3 distinct easings** across the piece.
+- **Rhythm chrome alternatives** — a center beat bar or a `// label` monospace tag pulsing on-beat instead of the 5-tick metronome; mark any decorative that must survive a shader transition per `../transitions/overview.md`.
+- **Finale dressing** — stack + accent underline sweep ([css-marker-patterns](css-marker-patterns.md)); don't just leave the last phrase sitting.
+
+## Values
+
+| token             | range                | notes                                                                                        |
+| ----------------- | -------------------- | -------------------------------------------------------------------------------------------- |
+| BEATS spacing     | 1.2–1.8s             | <0.8s 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; exits ≤0.25s                                      |
+| accent hue        | exactly 1            | the verbs; the rest mono white / near-black                                                  |
+| display face      | 150px+, heavy weight | Archivo Black / League Gothic / Oswald — see `hyperframes-creative/references/typography.md` |
+
+## Critical Constraints
+
+- **One beat array, not scattered offsets** — every element times off `BEATS[]` / `PULSE`; this is the single biggest lever for "rhythmic".
+- **Different entrance per phrase** — a reused `punchIn()` for all lines is the flat-but-competent tell. Vary the motion axis, reuse the ease _family_.
+- **Finale repeat math**: `repeat: Math.max(0, Math.floor(dur / cycle) - 1)` — `Math.ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint rule; a negative repeat is read by GSAP as `-1` (infinite).
+- **No banned exit animations between scenes** — in a montage the _transition_ is the exit (`../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`).
+
+## See also
+
+`3d-text-depth-layers` (extruded depth on the slammed words) · `css-marker-patterns` (finale underline/circle) · `sine-wave-loop` (the finale breath) · `../adapters/gsap-easing-and-stagger.md` (easing vocabulary).