creator-editing-studio 1.1.3 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.1.3",
+  "version": "1.2.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/scripts/refs.mjs

@@ -16,7 +16,12 @@ import {spawnSync} from 'node:child_process';
 import {existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync} from 'node:fs';
 import {basename, extname, join} from 'node:path';
 
-const FFMPEG = 'D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe';
+// Never hardcode a tool path. media.mjs finds the ffmpeg that ships with the studio
+// (ffmpeg-static, pulled in by npm install) before it looks at PATH, which is what lets this
+// run on a machine that has never had ffmpeg installed on it. A hardcoded path failed
+// silently here: the sheets were simply never generated and nothing said why.
+import {FFMPEG} from './lib/media.mjs';
+
 const REF_DIR = 'references';
 const OUT = join('work', 'refs');
 const all = process.argv.includes('--all');

package/template/scripts/stills.mjs

@@ -13,7 +13,10 @@ import {spawnSync} from 'node:child_process';
 import {mkdirSync, rmSync, writeFileSync} from 'node:fs';
 import {join, resolve} from 'node:path';
 
-const FFMPEG = 'D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe';
+// Never hardcode a tool path. media.mjs finds the ffmpeg that ships with the studio
+// (ffmpeg-static, pulled in by npm install) before it looks at PATH, which is what lets this
+// run on a machine that has never had ffmpeg installed on it.
+import {FFMPEG} from './lib/media.mjs';
 
 const args = process.argv.slice(2);
 const id = args.find((a) => !a.startsWith('--'));

package/template/scripts/takes.mjs

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+/**
+ * Best-take selection: turn a script plus a messy take into a clean cut plan.
+ *
+ *   npm run takes -- <script.md|txt> <words.json> [--project <name>] [--out <file>]
+ *                    [--fps 30] [--gap-keep 0.18] [--min-coverage 0.6] [--loose]
+ *
+ * THE PROBLEM THIS SOLVES. A talking head is read from a script, so the speaker fumbles and
+ * says a sentence again. `trim.mjs` removes silence and filler, but it keeps every attempt —
+ * so the cut contains the stumble AND the fix, and someone watches the whole thing to find
+ * them. On the setup video that meant 16 drop ranges chosen by hand, several missed, and a
+ * trip to CapCut to take out repeats nobody caught.
+ *
+ * WHY NOT JUST HUNT FOR REPEATS. Repeat-hunting is a filter: it finds duplicates it recognises
+ * and misses the rest. Anchoring to the script is a constructor: each sentence of the script is
+ * an atom, every atom gets exactly one span of audio, and anything that is not the winning span
+ * for some atom never enters the cut. Repeats are not removed — they are impossible. Filler,
+ * half-sentences, asides and dead air are gone for the same reason, without a rule for each.
+ *
+ * It also fails loudly. If a script sentence has no usable take, the build stops and names the
+ * line, instead of handing over a cut with a hole for someone to find on playback.
+ *
+ * WHAT IT WRITES  work/<project>/<stem>.takes.json
+ *   keep[]      {from, to, atom}   source seconds to use, in order
+ *   dropped[]   {from, to, reason, text}
+ *   atoms[]     every script sentence, its chosen take and the attempts that lost
+ *   checks{}    the verification results, all of which must pass
+ *
+ * The shape of `keep[]` matches `trim.mjs`, so the rest of the pipeline is unchanged.
+ */
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {basename, dirname, join} from 'node:path';
+
+/* ------------------------------------------------------------------------ args */
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? fallback : args[i + 1];
+};
+const has = (name) => args.includes(`--${name}`);
+const positional = args.filter((a, i) => !a.startsWith('--') && !String(args[i - 1] ?? '').startsWith('--'));
+
+const [scriptPath, wordsPath] = positional;
+if (!scriptPath || !wordsPath) {
+  console.error('usage: npm run takes -- <script.md|txt> <words.json> [--project <name>]');
+  process.exit(1);
+}
+
+const FPS = Number(flag('fps', 30));
+/** A gap longer than this between kept spans is collapsed down to it. */
+const GAP_KEEP = Number(flag('gap-keep', 0.18));
+/** Below this share of an atom's words matched, a span is not a take of that atom at all. */
+const MIN_COVERAGE = Number(flag('min-coverage', 0.6));
+/** Padding kept around a span so cuts do not clip the first and last phoneme. */
+const PAD = 0.06;
+
+/* ------------------------------------------------------------- script and words */
+
+/**
+ * The script as atoms.
+ *
+ * A sentence is the right unit: small enough that one fumble does not cost a paragraph, big
+ * enough to identify uniquely in the transcript. Markdown furniture and the BRIEF.md comment
+ * blocks are stripped — they are instructions to the writer, never spoken.
+ */
+const atomise = (raw) =>
+  raw
+    // Everything above the first `---` is front matter or a note to whoever wrote the script.
+    // It is never spoken, and counting it as missing dialogue buries the lines that really are.
+    .split(/^---\s*$/m)
+    .slice(1)
+    .join('\n')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^#.*$/gm, '')
+    .replace(/^[-*|>].*$/gm, '')
+    .replace(/`[^`]*`/g, ' ')
+    .split(/(?<=[.?!])\s+/)
+    .map((s) => s.replace(/\s+/g, ' ').trim())
+    .filter((s) => s.split(/\s+/).filter(Boolean).length >= 3);
+
+/** Comparable key for a word. Mirrors align_script.py so both agree on what "same" means. */
+/**
+ * Spellings that mean the same word.
+ *
+ * The script is written in British English and the recogniser answers in American. Without this,
+ * "licence" never matches "license" and a correctly spoken sentence is reported as missing while
+ * the audio for it is thrown away as off-script. That is a worse failure than a repeat.
+ */
+const SPELLING = new Map(Object.entries({
+  license: 'licence', color: 'colour', colors: 'colours', favorite: 'favourite',
+  realize: 'realise', organize: 'organise', gray: 'grey', analyze: 'analyse',
+}));
+
+const key = (token) => {
+  const bare = token.toLowerCase().replace(/['‘’]/g, '').replace(/[^a-z0-9]/g, '');
+  return SPELLING.get(bare) ?? bare;
+};
+
+/**
+ * Contractions, expanded.
+ *
+ * The script says "it'll" and the speaker says "it will" — or the other way round, depending on
+ * the day and the recogniser. Both sides expand to the same pair of words so they compare equal.
+ * Only forms carrying an apostrophe are touched, so "well" is never mistaken for "we will".
+ */
+const CONTRACTION = new Map(Object.entries({
+  itll: ['it', 'will'], theyll: ['they', 'will'], youll: ['you', 'will'], well: ['we', 'will'],
+  itsa: ['it', 'is', 'a'], its: ['it', 'is'], thats: ['that', 'is'], whats: ['what', 'is'],
+  theres: ['there', 'is'], heres: ['here', 'is'], lets: ['let', 'us'], youre: ['you', 'are'],
+  theyre: ['they', 'are'], weve: ['we', 'have'], youve: ['you', 'have'], ive: ['i', 'have'],
+  dont: ['do', 'not'], doesnt: ['does', 'not'], didnt: ['did', 'not'], isnt: ['is', 'not'],
+  wasnt: ['was', 'not'], arent: ['are', 'not'], wont: ['will', 'not'], cant: ['can', 'not'],
+  couldnt: ['could', 'not'], wouldnt: ['would', 'not'], shouldnt: ['should', 'not'],
+  youd: ['you', 'would'], id: ['i', 'would'], wed: ['we', 'would'], ill: ['i', 'will'],
+}));
+
+/** One spoken or written word becomes the one or more keys it is equivalent to. */
+const keysOfWord = (token) => {
+  const k = key(token);
+  if (!k) return [];
+  // Only expand when the original actually had an apostrophe, so ordinary words are left alone.
+  if (/['‘’]/.test(token) && CONTRACTION.has(k)) return CONTRACTION.get(k);
+  return [k];
+};
+
+const keysOf = (text) => text.split(/[\s\-/]+/).flatMap(keysOfWord);
+
+/**
+ * Filler. Deliberately short.
+ *
+ * Stripping every "so" and "you know" makes speech sound sanded down, which reads as
+ * over-edited and is its own kind of amateur. These are only ever used to PENALISE a take,
+ * never to cut inside a winning one — if the best attempt at a line contains an "um", the line
+ * keeps its "um" and sounds like a person.
+ */
+const FILLER = new Set(['um', 'uh', 'uhh', 'umm', 'erm', 'hmm', 'mmm', 'ah', 'eh']);
+
+const words = JSON.parse(readFileSync(wordsPath, 'utf8')).words.filter((w) => w.start != null && w.end != null);
+const rawScript = readFileSync(scriptPath, 'utf8');
+// A plain .txt script has no `---` rule, so give it one — atomise() always drops what is above
+// the first rule, and without this a bare script would come back empty.
+const atoms = atomise(/^---\s*$/m.test(rawScript) ? rawScript : `---\n${rawScript}`);
+/** Each spoken word as the list of keys it is equivalent to. Index stays 1:1 with `words`. */
+const tokenKeys = words.map((w) => {
+  const ks = keysOfWord(w.word);
+  return ks.length ? ks : ['\u0000'];
+});
+const tokens = tokenKeys.map((ks) => ks[0]);
+
+if (!atoms.length) {
+  console.error(`No script sentences found in ${scriptPath}.`);
+  process.exit(1);
+}
+
+/* --------------------------------------------------------------- finding takes */
+
+/**
+ * Every span of transcript that is a plausible attempt at `atom`.
+ *
+ * Greedy forward alignment from each position whose word matches the atom's first word, allowing
+ * the speaker to skip, swap or insert a few words. A take is scored on how much of the sentence
+ * actually made it out, how sure the aligner was, and whether it ran smoothly — a long pause or
+ * an "um" inside a sentence is exactly what a fumbled attempt sounds like.
+ */
+const findTakes = (atom, atomIndex) => {
+  const want = keysOf(atom);
+  if (!want.length) return [];
+  const out = [];
+  /** How far past the sentence the speaker may wander before the attempt is abandoned. */
+  const window = Math.ceil(want.length * 2.2) + 6;
+
+  /**
+   * A take may begin on any of the sentence's first three words.
+   *
+   * Anchoring only on the first word loses a whole sentence to a single swapped article — the
+   * script says "This system gets better", the speaker says "The system gets better", and the
+   * line is reported missing while its audio is discarded. Coverage still has to clear the
+   * threshold, so a take that drops its opening words scores lower rather than passing free.
+   */
+  const anchors = want.slice(0, 3);
+
+  for (let start = 0; start < tokens.length; start++) {
+    const anchorAt = anchors.indexOf(tokens[start]);
+    if (anchorAt === -1) continue;
+
+    let wi = anchorAt;
+    let matched = anchorAt;
+    let last = start;
+    let extras = 0;
+    for (let ti = start; ti < Math.min(tokens.length, start + window) && wi < want.length; ti++) {
+      // A contraction covers more than one script word, so consume as many as it supplies.
+      let consumed = 0;
+      while (consumed < tokenKeys[ti].length && wi + consumed < want.length && tokenKeys[ti][consumed] === want[wi + consumed]) consumed++;
+      if (consumed > 0) {
+        matched += consumed;
+        wi += consumed;
+        last = ti;
+      } else if (want.indexOf(tokens[ti], wi) !== -1 && want.indexOf(tokens[ti], wi) - wi <= 3) {
+        // The speaker skipped a word or two and carried on; follow them.
+        wi = want.indexOf(tokens[ti], wi) + 1;
+        matched++;
+        last = ti;
+      } else {
+        extras++;
+      }
+    }
+
+    const coverage = matched / want.length;
+    if (coverage < MIN_COVERAGE) continue;
+
+    const from = words[start].start;
+    const to = words[last].end;
+    const span = words.slice(start, last + 1);
+
+    let worstGap = 0;
+    for (let i = 1; i < span.length; i++) worstGap = Math.max(worstGap, span[i].start - span[i - 1].end);
+    const fillerInside = span.filter((w) => FILLER.has(key(w.word))).length;
+    const confidence = span.reduce((a, w) => a + (w.score ?? 0.8), 0) / span.length;
+
+    out.push({
+      atomIndex,
+      startIndex: start,
+      endIndex: last,
+      from,
+      to,
+      coverage,
+      confidence,
+      worstGap,
+      fillerInside,
+      extras,
+      text: span.map((w) => w.word).join(' '),
+      /**
+       * One number, so the chooser has something to maximise.
+       *
+       * Coverage dominates: a complete sentence beats a smooth fragment every time. The small
+       * bonus for starting later is there because when someone fumbles they fix it on the next
+       * try, so with two otherwise equal attempts the second is the keeper.
+       */
+      score:
+        coverage * 10 +
+        confidence * 2 -
+        Math.max(0, worstGap - 0.4) * 3 -
+        fillerInside * 0.8 -
+        (extras / want.length) * 1.5 +
+        (start / tokens.length) * 0.3,
+    });
+
+    start = last; // attempts cannot overlap each other
+  }
+  return out;
+};
+
+const takesPerAtom = atoms.map((atom, i) => findTakes(atom, i));
+
+/* -------------------------------------------------------------- choosing takes */
+
+/**
+ * One take per atom, in script order, never overlapping.
+ *
+ * Greedy picking of each atom's best take breaks as soon as the best take of sentence 4 sits
+ * earlier in the tape than the chosen take of sentence 5. This is weighted interval scheduling
+ * over the atoms in order: for each candidate, the best total reachable while ending before the
+ * next atom starts. Small enough to be exact rather than heuristic.
+ */
+const NEG = -1e9;
+const best = takesPerAtom.map((takes) => takes.map(() => ({total: NEG, prev: -1})));
+
+for (let a = 0; a < atoms.length; a++) {
+  const takes = takesPerAtom[a];
+  for (let c = 0; c < takes.length; c++) {
+    if (a === 0) {
+      best[a][c] = {total: takes[c].score, prev: -1};
+      continue;
+    }
+    let bestPrev = NEG;
+    let bestPrevIndex = -1;
+    for (let p = 0; p < takesPerAtom[a - 1].length; p++) {
+      if (best[a - 1][p].total === NEG) continue;
+      if (takesPerAtom[a - 1][p].endIndex >= takes[c].startIndex) continue;
+      if (best[a - 1][p].total > bestPrev) {
+        bestPrev = best[a - 1][p].total;
+        bestPrevIndex = p;
+      }
+    }
+    // An atom with no reachable predecessor can still start a run; the coverage check below
+    // is what decides whether the result is acceptable, not this.
+    best[a][c] =
+      bestPrevIndex === -1
+        ? {total: takes[c].score, prev: -1}
+        : {total: bestPrev + takes[c].score, prev: bestPrevIndex};
+  }
+}
+
+const chosen = new Array(atoms.length).fill(null);
+let cursor = -1;
+for (let a = atoms.length - 1; a >= 0; a--) {
+  const takes = takesPerAtom[a];
+  if (!takes.length) continue;
+  let pick = cursor;
+  if (pick === -1) {
+    let top = NEG;
+    for (let c = 0; c < takes.length; c++)
+      if (best[a][c].total > top) {
+        top = best[a][c].total;
+        pick = c;
+      }
+  }
+  if (pick === -1 || !takes[pick]) continue;
+  chosen[a] = takes[pick];
+  cursor = best[a][pick].prev;
+}
+
+/* ------------------------------------------------------------------ the result */
+
+const missing = [];
+atoms.forEach((atom, i) => {
+  if (!chosen[i]) missing.push({index: i, text: atom, attempts: takesPerAtom[i].length});
+});
+
+const keep = chosen
+  .filter(Boolean)
+  .map((t) => ({from: Math.max(0, t.from - PAD), to: t.to + PAD, atom: t.atomIndex, text: t.text}))
+  .sort((a, b) => a.from - b.from);
+
+// Overlapping padding between neighbours would double a word; meet in the middle instead.
+for (let i = 1; i < keep.length; i++) {
+  if (keep[i].from < keep[i - 1].to) {
+    const mid = (keep[i].from + keep[i - 1].to) / 2;
+    keep[i - 1].to = mid;
+    keep[i].from = mid;
+  }
+}
+
+const keptIndexes = new Set();
+chosen.filter(Boolean).forEach((t) => {
+  for (let i = t.startIndex; i <= t.endIndex; i++) keptIndexes.add(i);
+});
+
+const dropped = [];
+let runStart = null;
+for (let i = 0; i < words.length; i++) {
+  const inCut = keptIndexes.has(i);
+  if (!inCut && runStart === null) runStart = i;
+  if ((inCut || i === words.length - 1) && runStart !== null) {
+    const end = inCut ? i - 1 : i;
+    const text = words.slice(runStart, end + 1).map((w) => w.word).join(' ');
+    const alsoKept = chosen.filter(Boolean).some((t) => keysOf(t.text).join(' ').includes(keysOf(text).join(' ')));
+    dropped.push({
+      from: words[runStart].start,
+      to: words[end].end,
+      reason: alsoKept ? 'retake' : text.split(/\s+/).length <= 2 ? 'filler' : 'off-script',
+      text,
+    });
+    runStart = null;
+  }
+}
+
+/* ----------------------------------------------------------------- verification
+ * Run on the transcript the cut WILL have, worked out from the spans kept, so there is no
+ * second transcription and no waiting. Every one of these must pass; a build that fails here
+ * is a build that would have sent someone to CapCut. */
+
+const outWords = [...keptIndexes].sort((a, b) => a - b).map((i) => words[i]);
+const outKeys = outWords.map((w) => key(w.word)).filter(Boolean);
+
+const N = 4;
+
+/**
+ * How often the SCRIPT says each phrase.
+ *
+ * "go to the code tab" appears twice in this script on purpose, and so does "I like how the".
+ * Flagging every repeated phrase would report both as stutters. A repeat is only a fault when
+ * the cut says something more often than the script does.
+ */
+const scriptGrams = new Map();
+{
+  const sk = atoms.flatMap((a) => keysOf(a));
+  for (let i = 0; i + N <= sk.length; i++) {
+    const gram = sk.slice(i, i + N).join(' ');
+    scriptGrams.set(gram, (scriptGrams.get(gram) ?? 0) + 1);
+  }
+}
+
+const repeats = [];
+const seen = new Map();
+for (let i = 0; i + N <= outKeys.length; i++) {
+  const gram = outKeys.slice(i, i + N).join(' ');
+  const at = outWords[i].start;
+  const previous = seen.get(gram) ?? [];
+  if (previous.length >= (scriptGrams.get(gram) ?? 0) && previous.some((t) => at - t < 20)) {
+    repeats.push({gram, first: Number(previous[previous.length - 1].toFixed(2)), again: Number(at.toFixed(2))});
+  }
+  seen.set(gram, [...previous, at]);
+}
+
+const survivingFiller = outWords.filter((w) => FILLER.has(key(w.word))).map((w) => ({
+  word: w.word,
+  at: Number(w.start.toFixed(2)),
+}));
+
+const checks = {
+  everyAtomPlaced: missing.length === 0,
+  noRepeatedPhrase: repeats.length === 0,
+  fillerLeftInside: survivingFiller.length,
+  atoms: atoms.length,
+  placed: atoms.length - missing.length,
+  keptSeconds: Number(keep.reduce((a, k) => a + (k.to - k.from), 0).toFixed(2)),
+  sourceSeconds: Number((words[words.length - 1].end - words[0].start).toFixed(2)),
+};
+
+/* ---------------------------------------------------------------------- output */
+
+const stem = basename(wordsPath).replace(/\.words\.json$|\.json$/, '');
+const project = flag('project', null);
+const outPath =
+  flag('out', null) ??
+  (project ? join('work', project, `${stem}.takes.json`) : join(dirname(wordsPath), `${stem}.takes.json`));
+mkdirSync(dirname(outPath), {recursive: true});
+
+writeFileSync(
+  outPath,
+  JSON.stringify(
+    {
+      fps: FPS,
+      gapKeep: GAP_KEEP,
+      checks,
+      keep,
+      dropped,
+      repeats,
+      missing,
+      atoms: atoms.map((text, i) => ({
+        text,
+        chosen: chosen[i] ? {from: chosen[i].from, to: chosen[i].to, coverage: Number(chosen[i].coverage.toFixed(2))} : null,
+        attempts: takesPerAtom[i].length,
+      })),
+    },
+    null,
+    2,
+  ),
+);
+
+const pct = ((checks.keptSeconds / checks.sourceSeconds) * 100).toFixed(0);
+console.log(`${outPath}`);
+console.log(`  ${checks.placed}/${checks.atoms} script sentences placed`);
+console.log(`  ${checks.keptSeconds}s kept of ${checks.sourceSeconds}s (${pct}%)`);
+console.log(`  ${dropped.filter((d) => d.reason === 'retake').length} retakes, ${dropped.filter((d) => d.reason === 'off-script').length} off-script, ${dropped.filter((d) => d.reason === 'filler').length} filler dropped`);
+
+let failed = false;
+if (!checks.everyAtomPlaced) {
+  failed = true;
+  console.error(`\n${missing.length} script sentence(s) have no usable take:`);
+  for (const m of missing.slice(0, 10)) console.error(`  - "${m.text.slice(0, 70)}" (${m.attempts} attempts found)`);
+  console.error('  Re-record these lines, or re-run with --loose to lower the match threshold.');
+}
+if (repeats.length) {
+  failed = true;
+  console.error(`\n${repeats.length} phrase(s) still repeat in the cut:`);
+  for (const r of repeats.slice(0, 10)) console.error(`  - "${r.gram}" at ${r.first}s and again at ${r.again}s`);
+}
+if (survivingFiller.length) {
+  console.log(`\n  ${survivingFiller.length} filler word(s) kept inside winning takes — left in on purpose.`);
+}
+
+if (failed && !has('loose')) process.exit(1);

package/template/src/components/CommandCard.tsx

@@ -0,0 +1,228 @@
+import React from 'react';
+import {useCurrentFrame, useVideoConfig} from 'remotion';
+import {COLOR, FONT, PALETTE, RADIUS, SHADOW, SPACE, TYPE, WEIGHT} from '../design/tokens';
+import {EASE} from '../design/motion';
+import {progress} from '../lib/animate';
+
+/**
+ * A command, typed out, as a designed graphic rather than a screen recording.
+ *
+ * Why this exists instead of zooming into the capture: the connect command carries the buyer's
+ * licence key, and the key IS the URL — anyone who can read it has a free studio. Blurring it in
+ * the capture is fragile, because the chat scrolls and the bubble moves, so a static mask misses
+ * it and a tracked one drifts. Rebuilding the command as type means there is nothing to miss: the
+ * key is never on screen in the first place, it is drawn as a redaction by design.
+ *
+ * It also reads better. A 1080p capture punched in to fill a 1920 frame is soft; this is sharp at
+ * any zoom, in the brand's own colours, and the Mac and Windows variants can sit side by side,
+ * which is impossible with one person's screen.
+ *
+ * MONOSPACE IS A DELIBERATE EXCEPTION. The design system says one family at every weight, and that
+ * holds everywhere except here: a command is code, and proportional type makes a URL ambiguous at
+ * exactly the moment someone is trying to read one. Nowhere else in the system gets this.
+ */
+
+export const MONO = 'ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+
+export type Segment =
+  /** Ordinary command text. */
+  | {kind: 'plain'; text: string}
+  /** Flags and switches — dimmed, because nobody needs to read them to follow along. */
+  | {kind: 'flag'; text: string}
+  /** The part that matters, in the accent. */
+  | {kind: 'accent'; text: string}
+  /**
+   * A secret. Never pass the real value: `text` is only used for its LENGTH, so the redaction
+   * is the right width. Pass dummy characters.
+   */
+  | {kind: 'redacted'; text: string; label?: string};
+
+const COLOR_FOR: Record<Segment['kind'], string> = {
+  plain: PALETTE.stone100,
+  flag: PALETTE.stone400,
+  accent: COLOR.accent,
+  redacted: 'transparent',
+};
+
+/** How long the typing takes, from how much there is to type. Long commands do not crawl. */
+const typeFrames = (chars: number, fps: number) => Math.round((chars / 42) * fps);
+
+const Redaction: React.FC<{width: number; label?: string}> = ({width, label}) => (
+  <span
+    style={{
+      position: 'relative',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width,
+      height: '1.15em',
+      verticalAlign: 'middle',
+      borderRadius: RADIUS.sm / 2,
+      // Accent at low alpha, not a grey smear: it reads as a deliberate mark rather than a mistake.
+      backgroundColor: `${PALETTE.lime400}2e`,
+      border: `2px solid ${PALETTE.lime400}66`,
+    }}
+  >
+    <span
+      style={{
+        fontFamily: FONT.sans,
+        fontSize: '0.56em',
+        fontWeight: WEIGHT.semibold,
+        letterSpacing: '0.08em',
+        textTransform: 'uppercase',
+        color: COLOR.accent,
+        whiteSpace: 'nowrap',
+      }}
+    >
+      {label ?? 'your key'}
+    </span>
+  </span>
+);
+
+export const CommandCard: React.FC<{
+  segments: Segment[];
+  /** Frame the card lands on. Typing starts once it has settled. */
+  at: number;
+  /** Shown in the title bar. Omit for a card that is the same on both platforms. */
+  platform?: 'windows' | 'mac';
+  /** Replaces the platform chip — e.g. "same on Mac and Windows". */
+  note?: string;
+  fontSize?: number;
+  width?: number;
+}> = ({segments, at, platform, note, fontSize = 34, width}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  // The card arrives, THEN types. Typing while the card is still moving reads as two
+  // competing animations and the eye does not know where to settle.
+  const land = progress(frame, at, Math.round(0.4 * fps), EASE.out);
+
+  const total = segments.reduce((n, s) => n + s.text.length, 0);
+  const typed = progress(frame, at + Math.round(0.3 * fps), typeFrames(total, fps), EASE.inOut);
+  const shown = Math.floor(typed * total);
+
+  // A caret that blinks only once typing has finished, the way a real prompt does.
+  const done = typed >= 1;
+  const caretOn = !done || Math.floor((frame / fps) * 2) % 2 === 0;
+
+  let consumed = 0;
+
+  return (
+    <div
+      style={{
+        width,
+        maxWidth: '100%',
+        borderRadius: RADIUS.md,
+        backgroundColor: PALETTE.ink900,
+        boxShadow: SHADOW.pop,
+        overflow: 'hidden',
+        opacity: land,
+        transform: `translateY(${(1 - land) * 28}px)`,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: SPACE[2],
+          padding: `${SPACE[2]}px ${SPACE[3]}px`,
+          backgroundColor: PALETTE.ink800,
+          borderBottom: `2px solid ${PALETTE.ink700}`,
+        }}
+      >
+        {[PALETTE.stone600, PALETTE.stone600, PALETTE.stone600].map((c, i) => (
+          <span key={i} style={{width: 14, height: 14, borderRadius: RADIUS.pill, backgroundColor: c}} />
+        ))}
+        <span style={{flex: 1}} />
+        <span
+          style={{
+            fontFamily: FONT.sans,
+            fontSize: TYPE.eyebrow.size * 0.62,
+            fontWeight: WEIGHT.medium,
+            letterSpacing: TYPE.eyebrow.tracking,
+            textTransform: 'uppercase',
+            color: note ? COLOR.accent : PALETTE.stone400,
+          }}
+        >
+          {note ?? (platform === 'mac' ? 'macOS' : platform === 'windows' ? 'Windows' : '')}
+        </span>
+      </div>
+
+      <div
+        style={{
+          padding: `${SPACE[4]}px ${SPACE[4]}px ${SPACE[4]}px`,
+          fontFamily: MONO,
+          fontSize,
+          lineHeight: 1.65,
+          letterSpacing: '-0.01em',
+          color: PALETTE.stone100,
+          wordBreak: 'break-word',
+        }}
+      >
+        {segments.map((seg, i) => {
+          const start = consumed;
+          consumed += seg.text.length;
+          const visible = Math.max(0, Math.min(seg.text.length, shown - start));
+          if (visible === 0) return null;
+
+          if (seg.kind === 'redacted') {
+            // Reveal the redaction as one block once typing reaches it, rather than growing it
+            // character by character, which would look like the secret is being drawn in.
+            const w = seg.text.length * fontSize * 0.6;
+            return <Redaction key={i} width={w} label={seg.label} />;
+          }
+
+          return (
+            <span key={i} style={{color: COLOR_FOR[seg.kind]}}>
+              {seg.text.slice(0, visible)}
+            </span>
+          );
+        })}
+        <span
+          style={{
+            display: 'inline-block',
+            width: fontSize * 0.55,
+            height: '1.05em',
+            marginLeft: 4,
+            verticalAlign: 'text-bottom',
+            backgroundColor: COLOR.accent,
+            opacity: caretOn ? 1 : 0,
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+
+/* ------------------------------------------------------------------ the real commands */
+
+/**
+ * The connect line. Identical on Mac and Windows, which is worth SAYING rather than showing
+ * twice: a Mac viewer watching a Windows walkthrough is waiting to find out what is different
+ * for them, and "nothing, here" is the answer that keeps them watching.
+ */
+export const CONNECT_SEGMENTS: Segment[] = [
+  {kind: 'plain', text: 'claude mcp add '},
+  {kind: 'flag', text: '--scope user --transport http '},
+  {kind: 'accent', text: 'creator-editing-os'},
+  {kind: 'plain', text: ' https://creator-editing-os.mahipal-231.workers.dev/mcp/'},
+  {kind: 'redacted', text: 'XXXX-XXXX-XXXX-XXXX'},
+];
+
+/** Where the two platforms genuinely differ: installing Node when it is missing. */
+export const NODE_INSTALL = {
+  windows: [
+    {kind: 'plain', text: 'winget install '},
+    {kind: 'accent', text: 'OpenJS.NodeJS.LTS'},
+  ] as Segment[],
+  mac: [
+    {kind: 'plain', text: 'brew install '},
+    {kind: 'accent', text: 'node'},
+  ] as Segment[],
+};
+
+/** And where the studio lands. */
+export const STUDIO_PATH = {
+  windows: [{kind: 'plain', text: 'C:\\Users\\you\\'}, {kind: 'accent', text: 'VideoStudio'}] as Segment[],
+  mac: [{kind: 'plain', text: '/Users/you/'}, {kind: 'accent', text: 'VideoStudio'}] as Segment[],
+};

package/template/src/components/CornerMark.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import {Img, staticFile, useCurrentFrame, useVideoConfig} from 'remotion';
+import {PALETTE, RADIUS, SHADOW} from '../design/tokens';
+import {EASE} from '../design/motion';
+import {progress} from '../lib/animate';
+
+/**
+ * The corner bug, which exists to cover the teleprompter app's "RECORDED ON BIGVU" watermark
+ * burnt into the bottom-right of every frame of the talking head.
+ *
+ * Measured off the source at 1920x1080: the watermark sits at roughly x 1780-1900, y 962-1060.
+ * WATERMARK below is that box plus a margin, and the badge is sized from it rather than from
+ * taste, so the cover is guaranteed rather than eyeballed. If the footage is ever re-shot at a
+ * different size, re-measure and change this one constant.
+ *
+ * IT LIVES IN SCREEN SPACE, NOT FOOTAGE SPACE. Any push-in or reframe must be applied to the
+ * video underneath this, never to this badge — scale the badge with the footage and it slides
+ * off the thing it is covering, which is the one failure that matters here. The alternative,
+ * when a shot is punched in far enough, is to crop the watermark out of frame entirely and let
+ * the badge ride along as ordinary branding.
+ */
+const WATERMARK = {left: 1770, top: 952, right: 1910, bottom: 1068} as const;
+
+export const CornerMark: React.FC<{
+  /** Frame it fades in on. It then stays for the rest of the shot. */
+  at?: number;
+  /** Canvas width/height the measurements were taken against. */
+  canvas?: {width: number; height: number};
+}> = ({at = 0, canvas = {width: 1920, height: 1080}}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  /**
+   * Flush to the corner, rounded on the inner corner only.
+   *
+   * A pill was the obvious choice and it does not work: the watermark reaches to within 10px of
+   * the frame edge, so the cap's curve cuts across its corners and leaves white slivers showing.
+   * Covering those with a pill needs the badge to extend past x=1937 on a 1920 frame. Running
+   * the badge into the corner instead covers to both edges by construction, and one generous
+   * inner radius keeps it in the brand's geometry rather than looking like a crop.
+   */
+  const height = canvas.height - WATERMARK.top;
+  const minWidth = canvas.width - WATERMARK.left;
+
+  const show = progress(frame, at, Math.round(0.4 * fps), EASE.out);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        right: 0,
+        bottom: 0,
+        height,
+        minWidth,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 18,
+        // Extra padding on the right and bottom keeps the type off the frame edge even though
+        // the panel itself runs into it.
+        padding: '0 40px 18px 34px',
+        borderTopLeftRadius: RADIUS.lg,
+        // The supplied mark is black letterforms with a accent bar: it is drawn for a light
+        // background and disappears entirely on ink. So the badge is paper, not ink. It also
+        // sits more quietly over the light wall behind him than a black tab would.
+        backgroundColor: PALETTE.paper,
+        boxShadow: SHADOW.card,
+        opacity: show,
+        transform: `translateY(${(1 - show) * 12}px)`,
+      }}
+    >
+      <Img src={staticFile('setup/ceos.svg')} style={{width: 150, display: 'block'}} />
+    </div>
+  );
+};

package/template/src/components/Cursor.tsx

@@ -1,93 +1,153 @@
-import React from 'react';
-import {useCurrentFrame, useVideoConfig} from 'remotion';
-import {EASE} from '../design/motion';
-import {COLOR, RADIUS} from '../design/tokens';
-import {durFrames, perFrame, progress, travelFrames} from '../lib/animate';
-import {Presence} from './Presence';
-import {VelocityBlur} from './VelocityBlur';
-
-/** A point the cursor ARRIVES at by frame `at` (the tip of the arrow). */
-export type CursorStop = {at: number; x: number; y: number; click?: boolean};
-
-const CLICK_FRAMES = 6;
-/** Pointer size and where its tip sits inside the 64px artwork. */
-const POINTER = 68;
-const TIP = 6 * (POINTER / 64);
-
-/**
- * An arrow cursor that guides the eye: travels between stops on gentle arcs,
- * arriving exactly on time, and clicks with a press + ripple.
- */
-export const Cursor: React.FC<{stops: CursorStop[]; hideAt: number}> = ({stops, hideAt}) => {
-  const frame = useCurrentFrame();
-  const {fps} = useVideoConfig();
-
-  const positionAt = (f: number) => {
-    let x = stops[0].x;
-    let y = stops[0].y;
-    for (let i = 1; i < stops.length; i++) {
-      const from = stops[i - 1];
-      const to = stops[i];
-      const distance = Math.hypot(to.x - from.x, to.y - from.y);
-      const travel = Math.min(travelFrames(distance, fps), Math.max(1, to.at - from.at));
-      const depart = to.at - travel;
-      if (f <= depart) break;
-      const t = progress(f, depart, travel, EASE.inOut);
-      // Arc: bulge perpendicular to the path, peaking mid-way.
-      const bulge = Math.sin(Math.PI * t) * distance * 0.1;
-      const nx = distance ? -(to.y - from.y) / distance : 0;
-      const ny = distance ? (to.x - from.x) / distance : 0;
-      x = from.x + (to.x - from.x) * t + nx * bulge;
-      y = from.y + (to.y - from.y) * t + ny * bulge;
-    }
-    return {x, y};
-  };
-
-  const {x, y} = positionAt(frame);
-  const click = stops.find((s) => s.click && frame >= s.at && frame < s.at + durFrames('slow', fps));
-  const pressT = click ? progress(frame, click.at, CLICK_FRAMES, EASE.inOut) : 0;
-  const press = 1 - 0.14 * Math.sin(Math.PI * pressT);
-  const ripple = click ? progress(frame, click.at, durFrames('slow', fps)) : 0;
-
-  return (
-    <Presence at={stops[0].at} until={hideAt} dur="fast" from="none" style={{position: 'absolute', inset: 0}}>
-      {click ? (
-        <div
-          style={{
-            position: 'absolute',
-            left: click.x - 70 * ripple,
-            top: click.y - 70 * ripple,
-            width: 140 * ripple,
-            height: 140 * ripple,
-            borderRadius: RADIUS.pill,
-            border: `4px solid ${COLOR.accent}`,
-            opacity: 1 - ripple,
-          }}
-        />
-      ) : null}
-      <VelocityBlur
-        vx={perFrame((f) => positionAt(f).x, frame)}
-        vy={perFrame((f) => positionAt(f).y, frame)}
-        style={{
-          position: 'absolute',
-          left: x - TIP,
-          top: y - TIP,
-          transformOrigin: `${TIP}px ${TIP}px`,
-          transform: `scale(${press.toFixed(4)})`,
-          filter: `drop-shadow(0 8px 14px ${COLOR.fg}66)`,
-        }}
-      >
-        {/* Solid pointer (as in the reference): tip top-left, notched tail. */}
-        <svg width={POINTER} height={POINTER} viewBox="0 0 64 64">
-          <path
-            d="M6 6 L58 26 Q60 27 58 28 L35 35 L28 58 Q27 60 26 58 Z"
-            fill={COLOR.accent}
-            stroke={COLOR.fg}
-            strokeWidth={3}
-            strokeLinejoin="round"
-          />
-        </svg>
-      </VelocityBlur>
-    </Presence>
-  );
-};
+import React from 'react';
+import {useCurrentFrame, useVideoConfig} from 'remotion';
+import {EASE} from '../design/motion';
+import {COLOR, FONT, RADIUS, WEIGHT} from '../design/tokens';
+import {durFrames, perFrame, progress, travelFrames} from '../lib/animate';
+import {Presence} from './Presence';
+import {VelocityBlur} from './VelocityBlur';
+
+/** A point the cursor ARRIVES at by frame `at` (the tip of the arrow). */
+export type CursorStop = {at: number; x: number; y: number; click?: boolean};
+
+const CLICK_FRAMES = 6;
+/** Pointer size and where its tip sits inside the 64px artwork. */
+const POINTER = 68;
+const TIP = 6 * (POINTER / 64);
+
+/**
+ * An arrow cursor that guides the eye: travels between stops on gentle arcs,
+ * arriving exactly on time, and clicks with a press + ripple.
+ */
+export const Cursor: React.FC<{
+  stops: CursorStop[];
+  hideAt: number;
+  /**
+   * A name tag riding behind the arrow, the way a collaborator's cursor is labelled in Figma.
+   * Optional and additive: every existing use renders exactly as before without it.
+   *
+   * Pass a function of the frame to change the word mid-move — "copy" becoming "copied" the
+   * instant the click lands reads as the action succeeding, with no second element needed.
+   */
+  label?: string | ((frame: number) => string);
+  /**
+   * Arrow colour. Defaults to the brand accent, which is what every earlier use gets.
+   *
+   * The setup walkthrough passes ink instead, asked for directly ("the arrow should be black"):
+   * over a white email and a light desktop a accent arrow reads as a graphic sitting on the shot,
+   * where a black one reads as the viewer's own pointer.
+   */
+  fill?: string;
+  /** Tag colour, as a function of the frame where it changes state mid-move. */
+  tagColour?: string | ((frame: number) => string);
+  /** Tag text colour, for tags too dark for ink to read on. */
+  tagText?: string | ((frame: number) => string);
+}> = ({
+  stops,
+  hideAt,
+  label,
+  fill = COLOR.accent,
+  tagColour = COLOR.accent,
+  tagText = COLOR.fg,
+}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  const positionAt = (f: number) => {
+    let x = stops[0].x;
+    let y = stops[0].y;
+    for (let i = 1; i < stops.length; i++) {
+      const from = stops[i - 1];
+      const to = stops[i];
+      const distance = Math.hypot(to.x - from.x, to.y - from.y);
+      const travel = Math.min(travelFrames(distance, fps), Math.max(1, to.at - from.at));
+      const depart = to.at - travel;
+      if (f <= depart) break;
+      const t = progress(f, depart, travel, EASE.inOut);
+      // Arc: bulge perpendicular to the path, peaking mid-way.
+      const bulge = Math.sin(Math.PI * t) * distance * 0.1;
+      const nx = distance ? -(to.y - from.y) / distance : 0;
+      const ny = distance ? (to.x - from.x) / distance : 0;
+      x = from.x + (to.x - from.x) * t + nx * bulge;
+      y = from.y + (to.y - from.y) * t + ny * bulge;
+    }
+    return {x, y};
+  };
+
+  const {x, y} = positionAt(frame);
+  const click = stops.find((s) => s.click && frame >= s.at && frame < s.at + durFrames('slow', fps));
+  const pressT = click ? progress(frame, click.at, CLICK_FRAMES, EASE.inOut) : 0;
+  const press = 1 - 0.14 * Math.sin(Math.PI * pressT);
+  const ripple = click ? progress(frame, click.at, durFrames('slow', fps)) : 0;
+
+  // Resolved first so a label that returns an empty string removes the tag outright, which is
+  // how "copied" disappears once the line has been pasted.
+  const labelText = typeof label === 'function' ? label(frame) : label;
+
+  return (
+    <Presence at={stops[0].at} until={hideAt} dur="fast" from="none" style={{position: 'absolute', inset: 0}}>
+      {click ? (
+        <div
+          style={{
+            position: 'absolute',
+            left: click.x - 70 * ripple,
+            top: click.y - 70 * ripple,
+            width: 140 * ripple,
+            height: 140 * ripple,
+            borderRadius: RADIUS.pill,
+            border: `4px solid ${fill}`,
+            opacity: 1 - ripple,
+          }}
+        />
+      ) : null}
+      <VelocityBlur
+        vx={perFrame((f) => positionAt(f).x, frame)}
+        vy={perFrame((f) => positionAt(f).y, frame)}
+        style={{
+          position: 'absolute',
+          left: x - TIP,
+          top: y - TIP,
+          transformOrigin: `${TIP}px ${TIP}px`,
+          transform: `scale(${press.toFixed(4)})`,
+          filter: `drop-shadow(0 8px 14px ${COLOR.fg}66)`,
+        }}
+      >
+        {/* Solid pointer (as in the reference): tip top-left, notched tail. */}
+        <svg width={POINTER} height={POINTER} viewBox="0 0 64 64">
+          <path
+            d="M6 6 L58 26 Q60 27 58 28 L35 35 L28 58 Q27 60 26 58 Z"
+            fill={fill}
+            stroke={COLOR.fg}
+            strokeWidth={3}
+            strokeLinejoin="round"
+          />
+        </svg>
+      </VelocityBlur>
+
+      {labelText ? (
+        <div
+          style={{
+            position: 'absolute',
+            // Sits behind and below the tip, where a Figma cursor label sits, so it never
+            // covers the thing being pointed at.
+            left: x + POINTER * 0.42,
+            top: y + POINTER * 0.52,
+            display: 'flex',
+            alignItems: 'center',
+            padding: '7px 16px',
+            borderRadius: RADIUS.pill,
+            backgroundColor: typeof tagColour === 'function' ? tagColour(frame) : tagColour,
+            fontFamily: FONT.sans,
+            fontSize: 26,
+            fontWeight: WEIGHT.semibold,
+            letterSpacing: '-0.015em',
+            color: typeof tagText === 'function' ? tagText(frame) : tagText,
+            whiteSpace: 'nowrap',
+            boxShadow: `0 6px 16px ${COLOR.fg}33`,
+          }}
+        >
+          {labelText}
+        </div>
+      ) : null}
+    </Presence>
+  );
+};