creator-editing-studio 1.0.20260930

package/README.md

@@ -0,0 +1,15 @@
+# Creator Editing OS — studio
+
+Scaffolds the studio into a folder:
+
+```bash
+npx creator-editing-studio init my-studio
+cd my-studio
+npm install
+```
+
+Existing files are never overwritten. Everything it writes is plain source you can read
+before running it — the components, the scripts and the rulebook the studio edits by.
+
+Setup is normally driven for you by the Creator Editing OS assistant; this package is the
+part that puts the files on disk.

package/bin/init.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Scaffold a Creator Editing OS studio into a folder.
+ *
+ *   npx @yonkomedia/creator-editing-studio init [folder]
+ *
+ * This exists because the previous delivery — the MCP server handing an assistant 300KB
+ * of source as a JSON blob to write to disk and then execute — is exactly the pattern
+ * coding agents block as untrusted code integration. It is a fair block, and no amount of
+ * rewording gets past it, because the objection is to the shape of the thing rather than
+ * to what it says.
+ *
+ * A published npm package is the channel this is supposed to travel down: a version
+ * number, a public page, a tarball anyone can inspect before it runs. Same files, an
+ * audit trail, and nothing to argue with.
+ *
+ * Existing files are never overwritten. Run it twice and the second run reports what is
+ * already there and changes nothing.
+ */
+import {cpSync, existsSync, mkdirSync, readdirSync, statSync} from 'node:fs';
+import {dirname, join, relative, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE = resolve(HERE, '..', 'template');
+
+const args = process.argv.slice(2);
+const command = args[0] === 'init' ? args.slice(1) : args;
+const target = resolve(process.cwd(), command[0] || '.');
+const force = args.includes('--force');
+
+if (!existsSync(TEMPLATE)) {
+  console.error('This package is missing its template files — please report it.');
+  process.exit(1);
+}
+
+const walk = (dir) =>
+  readdirSync(dir, {withFileTypes: true}).flatMap((entry) => {
+    const p = join(dir, entry.name);
+    return entry.isDirectory() ? walk(p) : [p];
+  });
+
+const files = walk(TEMPLATE).map((p) => relative(TEMPLATE, p).split('\\').join('/'));
+
+mkdirSync(target, {recursive: true});
+
+const written = [];
+const skipped = [];
+
+for (const rel of files) {
+  const from = join(TEMPLATE, rel);
+  const to = join(target, rel);
+  if (existsSync(to) && !force) {
+    skipped.push(rel);
+    continue;
+  }
+  mkdirSync(dirname(to), {recursive: true});
+  cpSync(from, to);
+  written.push(rel);
+}
+
+const kb = (n) => `${Math.round(n / 1024)} KB`;
+const bytes = written.reduce((sum, rel) => sum + statSync(join(target, rel)).size, 0);
+
+console.log(`\nCreator Editing OS — studio files\n`);
+console.log(`  into   ${target}`);
+console.log(`  wrote  ${written.length} files (${kb(bytes)})`);
+if (skipped.length) {
+  console.log(`  kept   ${skipped.length} existing file(s) — nothing was overwritten`);
+  console.log(`         (use --force to replace them)`);
+}
+console.log(`\nNext:  npm install\n`);

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "creator-editing-studio",
+  "version": "1.0.20260930",
+  "description": "Scaffolds a Creator Editing OS studio — components, scripts and rules for editing video from a plain-English brief.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "creator-editing-studio": "bin/init.mjs"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,341 @@
+# Editing studio — rulebook
+
+Read this at the start of every session. It is how this studio edits, and it is not
+optional. Quality lives in the system — the tokens, the components, the lint, the
+frame-by-frame checks — never in one-off hacks. Never bypass the system to get something
+on screen faster; that is the one habit that makes every later video worse.
+
+## Project map
+
+```
+src/design/        tokens.ts is the look — colour, type, layout. Everything visual reads from it.
+                   motion.ts is the timing. presets.ts is the named transitions and caption looks.
+                   overlays.ts is the film looks. Only tokens.ts is yours to change freely.
+src/lib/           animate, continuity, camera, spine, project — the helpers every video uses.
+src/components/    the effects library, as real components. Captions, Transition, Stage, and the rest.
+src/compositions/  PresetTest and FilmTest — reference comps showing every preset side by side.
+src/videos/<name>/ one folder per video. This is where your work goes.
+scripts/           the tools: prep, beats, trim, assemble, sound, and the two checks.
+assets/            footage, screenshots, audio, fonts. Reachable as staticFile('footage/clip.mp4').
+work/<name>/       everything the scripts produce: transcripts, beat maps, cut lists, cue sheets.
+out/               finished renders.
+```
+
+## Commands
+
+- `npm run studio` — preview everything
+- `npm run new-video -- <name>` — create a video's folders and its BRIEF.md
+- `npm run prep -- <name>` — probe and conform footage, transcribe, align the script, find jump cuts
+- `npm run trim -- <clip> [--words <words.json>]` — cut silence and filler, assign punch-in framings
+- `npm run beats -- <music>` — tempo, beat, downbeat and onset map
+- `npm run assemble -- --beats <beats.json> --clips <dir>` — build a cut off the music
+- `npm run sound -- --cuts <cut list>` — place whooshes, impacts and risers, ducked under the voice
+- `npm run ramp -- <clip> --ramp "3-5:1->0.4"` — eased speed ramps
+- `npm run sync -- <a> <b>` — line up a second angle or a separate mic
+- `npm run refstyle -- <reference clip>` — measure a reference edit's pacing and colour
+- `npm run stills -- <Comp> --every=45` — many stills at once, with contact sheets
+- `npm run check` — typecheck plus motion lint. Must pass.
+- `npm run motion-check -- <Comp> --scale=2` — frame-by-frame POP / CUT / STUTTER detection
+- `npm run render <Comp> out/video.mp4` — render
+
+## Your look comes first
+
+`src/design/tokens.ts` ships with neutral placeholder values. Before making anything real,
+set it up — ask *"build my design system from &lt;url&gt;"* and point it at a brand you
+like, or hand over your own colours, fonts and sizes. Put font files in `assets/fonts/`.
+
+Everything else in `src/design/` is the system and should be left alone. If a video needs
+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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## What is already installed
+
+Everything needed to cut, render, handle footage and mix audio arrived with the studio.
+Nothing else to set up, and nothing for the customer to think about.
+
+## The transcriber — installed on first use, not before
+
+Word-by-word captions need a transcriber, and it is a large download. It is deliberately
+**not** part of setup, because most people's first video does not need it and it would
+double the time before they see something working.
+
+The first time a video needs captions on the exact word, install it then — say plainly that
+it is a one-time download of a couple of GB and will take a few minutes:
+
+```bash
+python --version          # needs 3.11 or 3.12 — not the newest, it is unsupported
+pip install whisperx
+```
+
+If Python is missing: **python.org/downloads**, version 3.11 or 3.12, and on Windows tick
+**"Add Python to PATH"** on the first screen — missing that tickbox is the single most
+common failure.
+
+**How captions actually work, and why this matters:** transcribe to find out what was *said*,
+then force-align the customer's written *script* to that audio. Never use the raw transcript's
+timings — the script is what goes on screen, and the alignment is what makes each word land
+on the exact frame it is spoken.
+
+## Hardware
+
+Rendering is CPU-heavy and transcription is slower the first time while the model loads.
+On a laptop, expect a 60-second video to take a few minutes to render at `--scale=2`.
+If a render is too slow, drop to `--scale=1` while you are still judging the edit, and
+only supersample for the final.
+
+## When you are stuck
+
+Every named effect lives in `src/components/` and every one of them is real, working code —
+read it before inventing anything. If something you want is not there, ask for a reference
+clip and a timecode, work out the technique, build it as a component in `src/components/`,
+and add its name to `templates/BRIEF.md` so it can be asked for by name next time.
+
+The studio gets updates. When new components, scripts or rules ship, run `editing_os_update`
+and they are written into this project alongside your own work, which is never touched.
+

package/template/STYLE.md

@@ -0,0 +1,165 @@
+<!-- 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 | — |

package/template/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "my-editing-studio",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "doctor": "node scripts/doctor.mjs",
+    "studio": "remotion studio",
+    "still": "remotion still",
+    "render": "remotion render",
+    "typecheck": "tsc --noEmit",
+    "lint:motion": "node scripts/motion-lint.mjs",
+    "check": "npm run typecheck && npm run lint:motion",
+    "motion-check": "node scripts/motion-check.mjs",
+    "new-video": "node scripts/new-video.mjs",
+    "prep": "node scripts/prep.mjs",
+    "stills": "node scripts/stills.mjs",
+    "refs": "node scripts/refs.mjs",
+    "refstyle": "node scripts/refstyle.mjs",
+    "beats": "node scripts/beats.mjs",
+    "sync": "node scripts/sync-audio.mjs",
+    "ramp": "node scripts/ramp.mjs",
+    "trim": "node scripts/trim.mjs",
+    "assemble": "node scripts/assemble.mjs",
+    "sound": "node scripts/sounddesign.mjs"
+  },
+  "dependencies": {
+    "ffmpeg-static": "5.3.0",
+    "ffprobe-static": "3.1.0",
+    "@remotion/cli": "4.0.525",
+    "@remotion/fonts": "4.0.525",
+    "@remotion/google-fonts": "4.0.525",
+    "@remotion/media-utils": "4.0.525",
+    "@remotion/motion-blur": "4.0.525",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "remotion": "4.0.525"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "pngjs": "7.0.0",
+    "typescript": "5.9.2"
+  }
+}