creator-editing-studio 1.0.20260930 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.0.20260930",
+  "version": "1.1.1",
   "description": "Scaffolds a Creator Editing OS studio — components, scripts and rules for editing video from a plain-English brief.",
   "license": "UNLICENSED",
   "type": "module",

package/template/CLAUDE.md

@@ -48,250 +48,257 @@ Everything else in `src/design/` is the system and should be left alone. If a vi
 a colour or a size that is not in tokens.ts, the answer is to add it to tokens.ts, never to
 type it into a component.
 
-## Non-negotiables
-
-1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
-   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
-   exist, add it to the token file (with a comment) instead of inlining a value.
-2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
-   or other elements' timings via helpers — never hand-typed frame numbers.
-3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
-4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
-   without having rendered and viewed the frames.
-
+## Non-negotiables
+
+1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
+   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
+   exist, add it to the token file (with a comment) instead of inlining a value.
+2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
+   or other elements' timings via helpers — never hand-typed frame numbers.
+3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
+4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
+   without having rendered and viewed the frames.
+
 ---
 
-## The 12 motion laws
-
-1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
-2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
-3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
-4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
-5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
-   `OPACITY_LEAD` (60%) of the transform.
-6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
-7. **Blur-in capped at 12px**, fully resolved before the transform ends.
-8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
-9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
-10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
-    across the frame unblurred.
-11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
-12. **Continuity:** every transition inherits the outgoing motion (see below).
-
-### Continuity (what makes it feel connected, not cut together)
-
-- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
-  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
-  eyebrow dot stays on screen and grows into the next card's icon tile.)
-- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
-  direction — `handoff(exitTo)`.
-- **Overlap, never gap.** The next beat starts before the previous one settles —
-  `nextBeatAt(prevSettled)`.
-- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
-  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
-  stay put during a move (shared elements) lives in screen space, outside the camera.
-- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
-  most-staggered exit completes on or before the last frame.
-- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
-  `sfxTailMs` after.
-
+## The 12 motion laws
+
+1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
+2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
+3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
+4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
+5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
+   `OPACITY_LEAD` (60%) of the transform.
+6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
+7. **Blur-in capped at 12px**, fully resolved before the transform ends.
+8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
+9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
+10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
+    across the frame unblurred.
+11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
+12. **Continuity:** every transition inherits the outgoing motion (see below).
+
+### Continuity (what makes it feel connected, not cut together)
+
+- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
+  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
+  eyebrow dot stays on screen and grows into the next card's icon tile.)
+- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
+  direction — `handoff(exitTo)`.
+- **Overlap, never gap.** The next beat starts before the previous one settles —
+  `nextBeatAt(prevSettled)`.
+- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
+  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
+  stay put during a move (shared elements) lives in screen space, outside the camera.
+- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
+  most-staggered exit completes on or before the last frame.
+- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
+  `sfxTailMs` after.
+
 ---
 
-## Smoothness system (every one of these was a real defect found by motion-check)
-
-- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
-  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
-  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
-- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
-  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
-- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
-  a hard `clipPath` edge.
-- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
-  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
-- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
-  on the frame so toggling it never shifts timing). It costs 10x render time while active —
-  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
-  ahead of the frame, so switching it on/off causes a timing hitch.
-- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
-  frames as it slows, which motion-check flags as pops.
-- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
-  position, so settled elements flicker between 4 versions. (Lint enforces this.)
-- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
-  smooth `ScreenView` pan instead, and blur names on the still.
-- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
-  for containers that only fade in, use at least `"base"`.
-- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
-  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
-  and motion-check reports stutters. Run motion-check with the same `--scale`.
-- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
-  All tokens are in ms, so compositions work at either rate.
-
+## Smoothness system (every one of these was a real defect found by motion-check)
+
+- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
+  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
+  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
+- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
+  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
+- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
+  a hard `clipPath` edge.
+- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
+  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
+- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
+  on the frame so toggling it never shifts timing). It costs 10x render time while active —
+  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
+  ahead of the frame, so switching it on/off causes a timing hitch.
+- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
+  frames as it slows, which motion-check flags as pops.
+- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
+  position, so settled elements flicker between 4 versions. (Lint enforces this.)
+- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
+  smooth `ScreenView` pan instead, and blur names on the still.
+- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
+  for containers that only fade in, use at least `"base"`.
+- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
+  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
+  and motion-check reports stutters. Run motion-check with the same `--scale`.
+- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
+  All tokens are in ms, so compositions work at either rate.
+
 ---
 
-## Design rules
-
-**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
-sound, approved and rejected beats) and wins over anything below or in a reference. Update it
-whenever the user approves or rejects something.
-
-- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
-- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
-  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
-  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
-  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
-  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
-  Radii are generous, shadows soft, buttons/badges pills.
-- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
-- **User style decisions (first project):**
-  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
-    Over the cream background white is invisible, so in card layouts captions go **inside the video
-    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
-  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
-  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
-  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
-    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
-    icon and ask for the official file (Klaviyo is missing).
-  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
-- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
-  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
-  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
-- Keep accent highlights away from the accent background glow so they don't disappear into it.
-- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
-- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
-  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
-  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
-  do not apply.
-- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
-- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
-- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
-  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
-  viewer is meant to look at.
-- Icons: SVG drawn in code or an installed icon library, never image files.
-
+## Design rules
+
+**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
+sound, approved and rejected beats) and wins over anything below or in a reference. Update it
+whenever the user approves or rejects something.
+
+- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
+- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
+  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
+  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
+  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
+  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
+  Radii are generous, shadows soft, buttons/badges pills.
+- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
+- **User style decisions (first project):**
+  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
+    Over the cream background white is invisible, so in card layouts captions go **inside the video
+    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
+  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
+  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
+  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
+    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
+    icon and ask for the official file (Klaviyo is missing).
+  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
+- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
+  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
+  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
+- Keep accent highlights away from the accent background glow so they don't disappear into it.
+- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
+- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
+  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
+  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
+  do not apply.
+- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
+- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
+- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
+  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
+  viewer is meant to look at.
+- Icons: SVG drawn in code or an installed icon library, never image files.
+
 ---
 
-## Compositing: text behind the subject
-
-Layer order, bottom to top:
-
-```
-background plate (designed, or the original footage)
-  text / graphics          <- 1–3px blur to sit on the background's focal plane
-    subject cutout         <- same clip, frame-aligned
-      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
-        grain + grade      <- applied over everything so layers share one look
-```
-
-- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
-  combine a cutout from one take with footage from another.
-- **Green screen:** key once to a transparent intermediate in `work/` (not per render). Clean up
-  with spill suppression, ~0.5px choke, 0.5–1px feather. Temporal smoothing on the alpha
-  prevents edge flicker.
-- **Paired clips (the user's standard delivery):** Video 1 = original; Video 2 = the same clip with the
-  background replaced by flat green. Use Video 2 **only to build the matte (alpha)** and take the
-  subject's colour from Video 1 — this removes green fringe/spill entirely, because the subject pixels
-  never touched green. Before building, verify the pair: identical duration, fps, resolution and
-  frame count, and that the subject lines up on the same frame (a 1-frame offset makes a halo or ghost).
-  Any VFR conform must be applied identically to both. If the background-removal tool can export real
-  transparency, that is even better than green.
-- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
-  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
-- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
-- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
-- Text should animate in while already partly occluded, not appear fully and then get covered.
-- Pull text colour toward the footage's black/white points; pure white over graded footage looks
-  pasted on.
-
+## Compositing: text behind the subject
+
+Layer order, bottom to top:
+
+```
+background plate (designed, or the original footage)
+  text / graphics          <- 1–3px blur to sit on the background's focal plane
+    subject cutout         <- same clip, frame-aligned
+      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
+        grain + grade      <- applied over everything so layers share one look
+```
+
+- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
+  combine a cutout from one take with footage from another.
+- **Green screen:** key once to a transparent intermediate in `work/` (not per render). Clean up
+  with spill suppression, ~0.5px choke, 0.5–1px feather. Temporal smoothing on the alpha
+  prevents edge flicker.
+- **Paired clips (the user's standard delivery):** Video 1 = original; Video 2 = the same clip with the
+  background replaced by flat green. Use Video 2 **only to build the matte (alpha)** and take the
+  subject's colour from Video 1 — this removes green fringe/spill entirely, because the subject pixels
+  never touched green. Before building, verify the pair: identical duration, fps, resolution and
+  frame count, and that the subject lines up on the same frame (a 1-frame offset makes a halo or ghost).
+  Any VFR conform must be applied identically to both. If the background-removal tool can export real
+  transparency, that is even better than green.
+- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
+  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
+- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
+- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
+- Text should animate in while already partly occluded, not appear fully and then get covered.
+- Pull text colour toward the footage's black/white points; pure white over graded footage looks
+  pasted on.
+
 ---
 
-## Per-video pipeline
-
-1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
-   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
-     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
-   - Conform everything to one fps. Never mix frame rates.
-2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
-   Cut pauses/filler from word gaps. All animation timing reads from the spine.
-   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
-     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
-     directly — they are line-level and padded for readability, not word-accurate.
-   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
-3. **Cutouts:** key green screen or validate supplied cutouts (see above).
-4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
-   moment gets which treatment — and confirm with the user before building.
-5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
-6. **Verify** (below), then show the user.
-7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
-   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
-   they can place sounds quickly. Render without music unless asked.
-8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
-
+## Per-video pipeline
+
+1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
+   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
+     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
+   - Conform everything to one fps. Never mix frame rates.
+2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
+   Cut pauses/filler from word gaps. All animation timing reads from the spine.
+   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
+     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
+     directly — they are line-level and padded for readability, not word-accurate.
+   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
+3. **Cutouts:** key green screen or validate supplied cutouts (see above).
+4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
+   moment gets which treatment — and confirm with the user before building.
+   - **Read their saved references first** (`editing_os_references`). They are the whole reason
+     the edit should look like theirs rather than like the defaults, and a plan written without
+     them is a plan written for anybody. Say which reference each decision came from, so the
+     user can see their own taste being applied and correct it when it is being misread.
+   - Where references are silent, the defaults in STYLE.md apply. Where references and defaults
+     disagree, the reference wins — it is a real preference, and the default is only a sensible
+     starting point.
+5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
+6. **Verify** (below), then show the user.
+7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
+   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
+   they can place sounds quickly. Render without music unless asked.
+8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
+
 ---
 
-## Audio standard (audio is half the reel — the user will not accept a bad mix)
-
-What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
-but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
-wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
-
-1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
-   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
-   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
-2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
-   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
-   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
-3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
-   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
-4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
-   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
-   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
-   AAC encode at 256k.
-5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
-   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
-   minutes. Picture-only MP4 alongside.
-6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
-   timecoded audio notes on the first draft.
-
+## Audio standard (audio is half the reel — the user will not accept a bad mix)
+
+What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
+but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
+wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
+
+1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
+   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
+   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
+2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
+   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
+   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
+3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
+   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
+4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
+   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
+   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
+   AAC encode at 256k.
+5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
+   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
+   minutes. Picture-only MP4 alongside.
+6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
+   timecoded audio notes on the first draft.
+
 ---
 
-## Verification (required before saying anything is done)
-
-Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
-final call at playback speed. Be explicit about that when reporting.
-
-1. `npm run check` passes.
-2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
-   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
-   edge is blurred. Read the motion timeline for dead air and rhythm.
-3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
-   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
-4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
-   no clipped descenders (g, p, y, commas) in masked text.
-5. Report what was verified and what still needs the user's eyes at full speed.
-
+## Verification (required before saying anything is done)
+
+Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
+final call at playback speed. Be explicit about that when reporting.
+
+1. `npm run check` passes.
+2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
+   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
+   edge is blurred. Read the motion timeline for dead air and rhythm.
+3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
+   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
+4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
+   no clipped descenders (g, p, y, commas) in masked text.
+5. Report what was verified and what still needs the user's eyes at full speed.
+
 ---
 
-## Remotion gotchas
-
-- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
-- Never use `Math.random()` — use `random(seed)` from `remotion`.
-- Never use `will-change` (render-tab flicker, see Smoothness system).
-- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
-  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
-  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
-  never faded).
-- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
-  on the container, or word gaps collapse.
-- Masked text needs travel > 100% and container padding, or descenders stay visible.
-- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
-
+## Remotion gotchas
+
+- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
+- Never use `Math.random()` — use `random(seed)` from `remotion`.
+- Never use `will-change` (render-tab flicker, see Smoothness system).
+- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
+  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
+  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
+  never faded).
+- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
+  on the container, or word gaps collapse.
+- Masked text needs travel > 100% and container padding, or descenders stay visible.
+- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
+
 ---
 
-## Feedback format from the user
-
-Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
-Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
-
+## Feedback format from the user
+
+Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
+Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
+
 ---
 
 ## What is already installed

package/template/STYLE.md

@@ -1,165 +1,179 @@
-<!-- This is YOUR style guide. It starts as craft rules that hold for any brand; as you
-     approve and reject things, write them down here so every future video inherits the
-     decision instead of re-litigating it. -->
-
-# House style
-
-The look and feel every edit must have. Built from the user's own decisions on real videos. CLAUDE.md says *how* to build; this file says *what it must look,
-move and sound like*. When a decision here conflicts with a reference, this file wins unless the
-user says otherwise. Add to it whenever the user approves or rejects something.
-
-The user has a design background: judge every frame as a designer would. **Clean, calm, intentional —
-never a video that looks stitched together.**
-
----
-
-## 1. Identity
-
-- **Brand:** Your own design system, defined in `src/design/tokens.ts`.
-- **Type:** your display typeface only. Weight 800 for headlines, numbers and hero words; 600–700 for labels and pointers.
-- **Colour:** your accent colour, ink, cream/white. No other accent colours.
-  - On footage: accent text with the soft accent glow (`heroGlow()`).
-  - On cream: ink text; emphasis with the accent marker (`HighlightMark`).
-  - Solid screens: accent background with ink text, or ink background with accent text.
-
-## 2. Type scale (restrained — oversized text was rejected as "not aesthetic")
-
-| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
-|---|---|---|---|
-| Hero word (one per beat: STOP, FIRST) | 200–320px | 130–220px | Only one hero on screen at a time |
-| Headline (SAME SCRIPT, DIFFERENT PERSON, REINVENT) | ~116px | ~100px | Tracking -0.03em |
-| Big number (counter, stat) | ~170px | ~150px | Tabular digits while counting |
-| Label (VIEWS, COMMENT, THE WHEEL, eyebrows) | ~40px | ~32px | Uppercase, tracking 0.14em, weight 600 |
-| Pointer / list item | ~42px | ~36px | Accent check icon ~40px |
-| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
-
-If a word needs to be bigger than this to feel important, the layout is wrong, not the size.
-
-## 3. Layout
-
-- **The speaker stays full screen by default.** No rounded boxes or frames around the talking head
-  just to make room ("looks very off"). A card is only allowed as a *transition* (the card swap).
-- Put text in the clear space the shot gives you (sky, trees, empty wall), or **behind the subject**
-  when a green-screen twin exists. Check where the head goes on every jump cut.
-- The head may cover at most the lower ~20–30% of a word behind it, and the word must still read.
-- Captions live in one consistent zone per layout, over a dark area. They hide while the same words
-  are on screen as a graphic, and never linger into the next scene.
-- Graphics are made of type, numbers, real screenshots and real clips. **No decorative gimmicks**
-  (a glowing wheel behind the speaker was rejected as a "weird vibe").
-
-## 4. Motion
-
-- The 12 motion laws in CLAUDE.md, always. Smooth, eased, motion-blurred, nothing pops.
-- **Jump cuts: zoom through them** (Stage `cutZoom`). The same settle when footage returns after a
-  full-screen graphic. Never a jittery snap.
-- **Hard cuts only as a deliberate burst** (colour flip): a few beats of solid screens synced to the
-  phrases and sound, then back to smooth. Everything else morphs from one state to the next.
-- **Cover anything off-camera** (reading from an iPad, looking away) with a graphic or a cut.
-- Counters only go up and start from 0 — no grey placeholder digits.
-
-## 5. Sound (audio is half the reel)
-
-- The voice is never processed — see the Audio standard in CLAUDE.md.
-- Sound effects are short (whoosh 0.4–0.8s, hits 0.3–0.6s), faded, and sit in the gaps between words.
-- Every new visual gets its own fitting sound; don't reuse a sound that belonged to a different look.
-- Subtle beats loud: cinematic impacts on text were "way too impactful". Whooshes on big moves must
-  still be clearly audible.
-- Always hand over voice + SFX stems and a numbered, timecoded SFX folder with a cue sheet.
-
-## 5b. Colour (the look is shot, then graded)
-
-Target look (user's references, Sep 2026): warm golden light, olive-yellow greens, soft contrast,
-creamy skin, shallow depth of field — sunlit / window-lit.
-
-- **~80% of this look comes from the shoot**: golden hour or a single side window, the sun or light
-  behind/beside the subject, a warm/green background 3+ m away, a fast lens (EF 50mm f/1.8 at f/2–2.8),
-  white balance fixed (Daylight 5200K outdoors — never Auto, it removes the gold).
-- Canon 200D: Neutral picture style (sharpness 0–1, contrast -2, saturation -1), 25fps + 1/50 under
-  50Hz lighting (flicker), 30fps + 1/60 outdoors, ISO 100–400, expose skin bright but unclipped.
-- **Automated LUT grading (`scripts/grade.py`) is a starting point only** and only when the footage's
-  light already resembles the reference. On mismatched footage (overcast rooftop vs sunlit refs) the
-  user judged it "very bad, nowhere near". Never present an auto-grade as a match; judge colour by
-  the user's eye, not by Claude's thumbnails. Final grading: DaVinci Resolve / Lumetri, shot by shot,
-  reference on split screen.
-- Ask for a 20s test clip at the planned location/time before a graded shoot; check exposure,
-  clipping, white balance and flicker numerically.
-
-## 5c. Transitions and caption looks (presets)
-
-Named in `src/design/presets.ts`. Ask for them by name in a brief.
-
-| Transition | When |
-|---|---|
-| whipPan | Between unrelated shots. Never twice in a row. |
-| push | Moving forward through a list or sequence. |
-| maskWipe | Calm reveal. Pairs with a soft sound. |
-| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
-| matchCut | Only when both shots share a shape or direction. |
-| dip | Changing subject without drama. |
-
-| Caption look | When |
-|---|---|
-| clean | Default. Works over almost anything. |
-| block | Busy or bright footage, where white alone gets lost. |
-| highlight | Keeps the eye on the word being said. |
-| pop | Fast edits. Not over heavy motion. |
-
-Speed ramps: eased only (`npm run ramp`), never a hard speed switch. Below 0.4x needs 50fps+ footage.
-
-## 5d. Film looks (overlays)
-
-Named in `src/design/overlays.ts`, applied with `<FilmOverlay look="film">`. Reference
-composition: `FilmTest`. The test is that the footage looks richer, never that it looks
-filtered — if a viewer can name the effect, it is too strong.
-
-| Look | When |
-|---|---|
-| none | Graphics, screen recordings, anything with text as the subject. |
-| clean | Default for talking head. Just enough grain to stop flat areas banding. |
-| film | B-roll and travel. The one to reach for first. |
-| super8 | Memory / nostalgia moments only. Never a whole video. |
-| cinema | A held, wide, quiet shot. Bars plus bloom, nothing that moves. |
-
-Three things that were measured, and must not be quietly undone:
-
-- Grain composites **normally**, not with `overlay`. On cream and ink there are no midtones,
-  and overlay grain measured 0.000 stddev on a flat area — the layer did nothing at all.
-- Grain is paid for in black level (blacks measured 18 → 25 at `medium`). Turn it up per shot
-  with the `grain` prop when a nostalgia moment is worth milkier blacks; never raise the default.
-- Halation blooms **highlights only** — the plate is crushed to black before it is blurred and
-  screened back, so the darks come through untouched. Without the crush a cream-heavy frame
-  blooms end to end and the blacks lift to brown.
-
-Grain reseeds every frame. Holding a seed makes the frame byte-identical to the last one, which
-motion-check reports as a STUTTER, so a grainy video would fail its own verification gate.
-
-## 6. Approved beats (the effects library)
-
-Names match `templates/BRIEF.md`. "Source" is where the user approved it.
-
-| Beat | What it is | Source |
-|---|---|---|
-| Text behind me | Headline behind the head (green-screen twin) | — |
-| Card swap | Speaker shrinks into a card, becomes a creator clip mid-shrink, a row of clips slides in and drifts while the voice continues | approved as "perfect" |
-| Colour flip | Solid accent/ink screens per phrase; a word rolls into the next and the colours swap | — |
-| Counter race | Number races from 0 and lands (1,000,000+), then footage slams back | — |
-| Zoom-through cut | Push-in through every jump cut | — |
-| Gradient CTA | Bottom gradient, small label + big typed word, then ticked pointers after it leaves | — |
-| Browser mockup | Screenshots in a clean browser window, panned and zoomed | — |
-| Pointer click | Solid accent arrow glides and clicks with a ripple | — |
-| Rolling number | Digits roll between values | — |
-| Headline to pill | Big headline shrinks into a corner tag; removed when back to full screen | — |
-| Word-by-word captions | Default | both |
-
-## 7. Rejected (don't do these again)
-
-| What | Why | Video |
-|---|---|---|
-| Rounded card around the talking head at the end | "looks very off" | — |
-| Glowing wheel graphic behind the speaker | "weird vibe" | — |
-| Footage behind the colour-flip screens | "loses the impact" | — |
-| Text at 190–280px | "way too big, not aesthetic" | — |
-| Big cinematic impact on the hook word | "way too impactful" | — |
-| Grey placeholder digits in a counter | "not coming out nicely" | — |
-| Long whoosh / riser tails under speech | made the voice sound wrong | — |
-| Black text with a white glow for captions | replaced by crisp white | — |
+<!-- This is YOUR style guide, and it starts deliberately half-empty.
+
+     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
+     measured rather than argued. Leave them alone until you have a reason not to, and
+     your edits will come out clean rather than random.
+
+     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
+     write it down there. That is the half that makes edits look like YOURS instead of
+     merely competent, and it is the half nobody can hand you. -->
+
+# House style
+
+What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
+file says *what it must come out like*.
+
+When this file and a reference disagree, this file wins unless you say otherwise.
+
+---
+
+## 1. Your identity
+
+Everything visual comes from `src/design/tokens.ts`. That file is the single source of
+your typeface, your colours, your spacing and your type scale — change it there and every
+video changes with it. Never hard-code a colour or a font family into a composition.
+
+- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
+  medium for labels and pointers.
+- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
+  accents read as a template, one reads as a brand.
+- On footage: accent text, with a soft glow so it survives a busy frame.
+- On a light ground: ink text, with the accent used only to mark the word that matters.
+
+## 2. Type scale
+
+Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
+
+| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
+|---|---|---|---|
+| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
+| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
+| Big number | ~170px | ~150px | Tabular digits while a counter runs |
+| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
+| Pointer / list item | ~42px | ~36px | |
+| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
+
+**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
+not the size.** Oversized type is the most common way an edit starts looking amateur.
+
+## 3. Layout
+
+- **The speaker stays full screen by default.** Rounded cards and frames around a talking
+  head make the edit look assembled rather than shot. A card is fine as a *transition*,
+  not as a container.
+- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
+  background. Check where the head lands on every cut before committing a position.
+- Captions live in one consistent zone per layout, over a dark area. They hide while the
+  same words are on screen as a graphic, and never linger into the next scene.
+- Graphics are built from type, numbers, real screenshots and real footage. Decorative
+  shapes that mean nothing age badly and read as filler.
+
+## 4. Motion
+
+- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
+- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
+- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
+  words, then back to smooth. Everything else morphs from one state to the next.
+- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
+- Counters start at zero and only go up. No grey placeholder digits.
+- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
+  an edit was made by a machine rather than by someone making decisions.
+
+## 5. Sound (half the reel)
+
+- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
+- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
+  gaps between words rather than under them.
+- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
+  different look is the audio version of a template.
+- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
+- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
+
+## 6. Colour, film looks and presets
+
+**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
+light behind or beside the subject, background well behind the subject, white balance
+fixed rather than auto. Automated grading is a starting point and only when the footage's
+light already resembles the reference — on mismatched light it will look wrong, and you
+should trust your eye over any automatic match.
+
+| Transition | When |
+|---|---|
+| whipPan | Between unrelated shots. Never twice in a row. |
+| push | Moving forward through a list or a sequence. |
+| maskWipe | A calm reveal. Pairs with a soft sound. |
+| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
+| matchCut | Only when both shots share a shape or a direction. |
+| dip | Changing subject without drama. |
+
+| Caption look | When |
+|---|---|
+| clean | Default. Works over almost anything. |
+| block | Busy or bright footage, where white alone gets lost. |
+| highlight | Keeps the eye on the word being spoken. |
+| pop | Fast edits. Not over heavy motion. |
+
+| Film look | When |
+|---|---|
+| none | Graphics, screen recordings, anything where text is the subject. |
+| clean | Default for a talking head. Enough grain to stop flat areas banding. |
+| film | B-roll and travel. The one to reach for first. |
+| super8 | Memory and nostalgia moments only. Never a whole video. |
+| cinema | A held, wide, quiet shot. |
+
+**Three things here were measured, not guessed. Do not quietly undo them:**
+
+- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
+  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
+- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
+  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
+- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
+  and screened back. Without that crush, a bright frame blooms end to end and the blacks
+  go brown.
+
+Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
+footage — you cannot rescue slow motion that was not shot for it.
+
+---
+
+## 7. Where these defaults end and you begin
+
+The sections above are **defaults**: a starting point tuned so that a video made on day one,
+before you have told the system anything, comes out clean rather than embarrassing. Captions
+sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
+is untouched.
+
+Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
+Three things move an edit from the default toward yours, in increasing order of power:
+
+**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
+This makes an edit *yours to look at* immediately.
+
+**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
+on what you like about that exact moment. These are read before the plan for every video, and
+they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
+a reference is a fact about you.
+
+Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
+**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
+start looking authored.
+
+**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
+competitor can copy, because they are a record of decisions only you have made. Every entry
+narrows the next edit toward what you actually want.
+
+Nothing here learns on its own. It gets better because the brief gets richer — so the ten
+minutes spent writing down why you rejected something is the highest-return ten minutes
+available to you.
+
+---
+
+## 8. Approved (your effects library)
+
+<!-- Empty on purpose. When something works, write it down here: what it is, and where
+     you approved it. Next time you can ask for it by name instead of describing it
+     again, and every future video inherits the decision. -->
+
+| Beat | What it is | Where you approved it |
+|---|---|---|
+| | | |
+
+## 9. Rejected (don't do these again)
+
+<!-- This table is worth more than the one above. A list of things you have ruled out is
+     the fastest way to stop an edit drifting back toward generic, because it removes
+     options rather than adding them. Add a line every time you say "not that". -->
+
+| What | Why | Where |
+|---|---|---|
+| | | |

package/template/src/videos/sample/Sample.tsx

@@ -36,7 +36,26 @@ export const Sample: React.FC = () => {
         Your studio <HighlightMark at={headlineAt}>works</HighlightMark>
       </span>
 
-      <div style={{marginTop: 60, display: 'flex', alignItems: 'baseline', gap: 20}}>
+      {/* RollingNumber inherits its type from this parent and offsets each digit by sizePx.
+          Without a fontSize here the digits inherit the browser default 16px while the roll
+          still moves them by sizePx, so they slide clean out of the clip window and the
+          counter renders as two tiny motionless zeros. The component says as much —
+          "set font styles on the parent; sizePx must equal its font size" — and the sample
+          ignored it, which made every first render look broken. */}
+      <div
+        style={{
+          marginTop: 60,
+          display: 'flex',
+          alignItems: 'baseline',
+          gap: 20,
+          fontFamily: FONT.sans,
+          fontSize: TYPE.stat.size,
+          fontWeight: TYPE.stat.weight,
+          lineHeight: TYPE.stat.lineHeight,
+          letterSpacing: TYPE.stat.tracking,
+          color: COLOR.fg,
+        }}
+      >
         {/* No `from` — digits roll up from zero on their own. from="0" against value="100"
             throws, because RollingNumber requires both to have the same shape. */}
         <RollingNumber value="100" at={numberAt} sizePx={TYPE.stat.size} />

package/template/templates/STYLE.md

@@ -0,0 +1,179 @@
+<!-- This is YOUR style guide, and it starts deliberately half-empty.
+
+     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
+     measured rather than argued. Leave them alone until you have a reason not to, and
+     your edits will come out clean rather than random.
+
+     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
+     write it down there. That is the half that makes edits look like YOURS instead of
+     merely competent, and it is the half nobody can hand you. -->
+
+# House style
+
+What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
+file says *what it must come out like*.
+
+When this file and a reference disagree, this file wins unless you say otherwise.
+
+---
+
+## 1. Your identity
+
+Everything visual comes from `src/design/tokens.ts`. That file is the single source of
+your typeface, your colours, your spacing and your type scale — change it there and every
+video changes with it. Never hard-code a colour or a font family into a composition.
+
+- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
+  medium for labels and pointers.
+- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
+  accents read as a template, one reads as a brand.
+- On footage: accent text, with a soft glow so it survives a busy frame.
+- On a light ground: ink text, with the accent used only to mark the word that matters.
+
+## 2. Type scale
+
+Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
+
+| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
+|---|---|---|---|
+| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
+| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
+| Big number | ~170px | ~150px | Tabular digits while a counter runs |
+| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
+| Pointer / list item | ~42px | ~36px | |
+| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
+
+**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
+not the size.** Oversized type is the most common way an edit starts looking amateur.
+
+## 3. Layout
+
+- **The speaker stays full screen by default.** Rounded cards and frames around a talking
+  head make the edit look assembled rather than shot. A card is fine as a *transition*,
+  not as a container.
+- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
+  background. Check where the head lands on every cut before committing a position.
+- Captions live in one consistent zone per layout, over a dark area. They hide while the
+  same words are on screen as a graphic, and never linger into the next scene.
+- Graphics are built from type, numbers, real screenshots and real footage. Decorative
+  shapes that mean nothing age badly and read as filler.
+
+## 4. Motion
+
+- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
+- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
+- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
+  words, then back to smooth. Everything else morphs from one state to the next.
+- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
+- Counters start at zero and only go up. No grey placeholder digits.
+- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
+  an edit was made by a machine rather than by someone making decisions.
+
+## 5. Sound (half the reel)
+
+- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
+- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
+  gaps between words rather than under them.
+- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
+  different look is the audio version of a template.
+- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
+- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
+
+## 6. Colour, film looks and presets
+
+**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
+light behind or beside the subject, background well behind the subject, white balance
+fixed rather than auto. Automated grading is a starting point and only when the footage's
+light already resembles the reference — on mismatched light it will look wrong, and you
+should trust your eye over any automatic match.
+
+| Transition | When |
+|---|---|
+| whipPan | Between unrelated shots. Never twice in a row. |
+| push | Moving forward through a list or a sequence. |
+| maskWipe | A calm reveal. Pairs with a soft sound. |
+| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
+| matchCut | Only when both shots share a shape or a direction. |
+| dip | Changing subject without drama. |
+
+| Caption look | When |
+|---|---|
+| clean | Default. Works over almost anything. |
+| block | Busy or bright footage, where white alone gets lost. |
+| highlight | Keeps the eye on the word being spoken. |
+| pop | Fast edits. Not over heavy motion. |
+
+| Film look | When |
+|---|---|
+| none | Graphics, screen recordings, anything where text is the subject. |
+| clean | Default for a talking head. Enough grain to stop flat areas banding. |
+| film | B-roll and travel. The one to reach for first. |
+| super8 | Memory and nostalgia moments only. Never a whole video. |
+| cinema | A held, wide, quiet shot. |
+
+**Three things here were measured, not guessed. Do not quietly undo them:**
+
+- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
+  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
+- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
+  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
+- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
+  and screened back. Without that crush, a bright frame blooms end to end and the blacks
+  go brown.
+
+Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
+footage — you cannot rescue slow motion that was not shot for it.
+
+---
+
+## 7. Where these defaults end and you begin
+
+The sections above are **defaults**: a starting point tuned so that a video made on day one,
+before you have told the system anything, comes out clean rather than embarrassing. Captions
+sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
+is untouched.
+
+Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
+Three things move an edit from the default toward yours, in increasing order of power:
+
+**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
+This makes an edit *yours to look at* immediately.
+
+**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
+on what you like about that exact moment. These are read before the plan for every video, and
+they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
+a reference is a fact about you.
+
+Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
+**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
+start looking authored.
+
+**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
+competitor can copy, because they are a record of decisions only you have made. Every entry
+narrows the next edit toward what you actually want.
+
+Nothing here learns on its own. It gets better because the brief gets richer — so the ten
+minutes spent writing down why you rejected something is the highest-return ten minutes
+available to you.
+
+---
+
+## 8. Approved (your effects library)
+
+<!-- Empty on purpose. When something works, write it down here: what it is, and where
+     you approved it. Next time you can ask for it by name instead of describing it
+     again, and every future video inherits the decision. -->
+
+| Beat | What it is | Where you approved it |
+|---|---|---|
+| | | |
+
+## 9. Rejected (don't do these again)
+
+<!-- This table is worth more than the one above. A list of things you have ruled out is
+     the fastest way to stop an edit drifting back toward generic, because it removes
+     options rather than adding them. Add a line every time you say "not that". -->
+
+| What | Why | Where |
+|---|---|---|
+| | | |