creator-editing-studio 1.4.0 → 1.4.2

package/template/CLAUDE.md

@@ -144,16 +144,23 @@ a new yes; making a NEW sheet means a new plan and needs a new yes. Never run ap
 
 Once they approve, build the edit and **open the live preview yourself** — `preview_edit({video})`. They must
 never have to ask for it, and never get a draft MP4 instead of it. It plays the edit in the chat, and they change
-it right on the video at no message cost: drag to move, corner to resize, a bar for text colour, in front of /
-behind them, and hide. See `preview/README.md` for what each video needs (`preview.tsx`, `TweaksProvider`).
+it right on the video at no message cost: drag to move, corner to resize, and a bar on whatever they click —
+the font of that text (brand fonts first; this graphic or the whole video), swap an icon from ~6,000, replace an
+image or clip (another from this video or one from their computer), colours, in front of / behind them, hide.
+Draw icons as inline `<svg>` so they can be swapped. See `preview/README.md` for what each video needs (`preview.tsx`, `TweaksProvider`).
 **Every graphic must be draggable:** wrap each headline word, caption layer, icon, logo, image and card in its own
 `<Part id="…">` (never the speaker, the background, or a full-screen card that hides a cut), and with a cut-out
 of the speaker put `<Layer name="behind" />` / `<Layer name="front" />` just before / after it.
 
 - A change typed in the preview arrives as a chat message: change only that beat, then call `preview_edit`
   again so the updated preview opens below. **Undo** = `preview_undo`, then `preview_edit`.
-- **Save** and **Render** arrive as one message each, carrying their adjustments as JSON for the video's
-  `tweaks.json` — write it exactly.
+- The player saves the person's on-video changes (fonts, colours, icons, moves) itself when the chat lets it.
+  When it can't, its message asks you to call **`preview_save`** with the adjustments JSON and names a
+  fingerprint: pass the JSON exactly, and if the answer's fingerprint differs, call it again. Never hand-write
+  `tweaks.json`. The next preview shows the person "✓ kept" or "didn't save", so a skipped save is seen.
+- A **replaced file** comes with old → new names (and, for one from their computer, its name and size — find
+  it in their usual folders and copy it into `assets/` at the given path): change the name in the edit's code,
+  then call `preview_save` with the JSON the message gives (the same adjustments without the replaced files).
 - Render only when they press **Render final video**, and give the estimated render time only then.
 - If the preview tool is missing (not switched on yet), say so in one line and fall back to rendering with
   the time estimate. Never send them off to fix it mid-edit.
@@ -458,6 +465,16 @@ background plate (designed, or the original footage)
 - 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.
+- **A word behind the subject is ALL CAPS and genuinely behind him:** the head covers the lower
+  ~20–30% of the letters. A word floating clear above the head is not "behind", it is a headline.
+  No full stop on it.
+- **Text inside a camera move scales with it.** If the shot is pushed in (scale 1.2–1.3 from near
+  the bottom, say), a word at y 225 lands off the top of the screen. Place behind-text by where it
+  LANDS after the push, and check a still at the END of the push as well as the start, inside the
+  safe zone (x 60–960, y 220–1500).
+- **Never show the same word big and in the captions at the same time.** Keep the one that reads
+  better (usually the big word) and drop the other: pass the big words to the captions as `skip`
+  (`<StyledCaptions skip={[{text: 'simpler', from: 14.5, to: 16}]} … />`, seconds).
 
 ---
 
@@ -531,7 +548,11 @@ final call at playback speed. Be explicit about that when reporting.
    (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.
+5. **After every render, check the finished file itself:** `npm run final-check -- <out.mp4>`.
+   It writes a contact sheet (one tile per second) and reports frame count, loudness, true peak
+   and silent gaps. **Look at the sheet** — a word that is missing, cut off or pushed off-screen
+   shows there and in no still of the edit. Not done until it passes and the sheet is read.
+6. Report what was verified and what still needs the user's eyes at full speed.
 
 ---
 

package/template/package.json

@@ -15,6 +15,7 @@
     "new-video": "node scripts/new-video.mjs",
     "prep": "node scripts/prep.mjs",
     "stills": "node scripts/stills.mjs",
+    "final-check": "node scripts/final-check.mjs",
     "refs": "node scripts/refs.mjs",
     "refstyle": "node scripts/refstyle.mjs",
     "refmotion": "node scripts/refmotion.mjs",

package/template/preview/lib.mjs

@@ -28,7 +28,7 @@ const {FFMPEG} = await import(pathToFileURL(join(STUDIO, 'scripts', 'lib', 'medi
 
 /**
  * Everything the preview needs to know about one video, read from its own folder:
- * src/videos/<name>/preview.tsx, the *Edit.tsx beside it, the asset folders its code mentions, its stems.
+ * src/videos/<name>/preview.tsx, the edit beside it (and its id in Root.tsx), the asset folders its code mentions, its stems.
  */
 export function configFor(name) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(name ?? '')) throw new Error(`"${name}" is not a video name (lowercase letters, digits, dashes)`);
@@ -61,19 +61,88 @@ export function configFor(name) {
       if (m) stems[m[1]] = `out/${name}/${f}`;
     }
 
-  // The edit is the file named *Edit.tsx; its composition id is that name (as registered in Root.tsx).
-  const editFile = readdirSync(code).find((f) => /Edit\.tsx$/.test(f));
+  const {editFile, composition} = editAndComposition(name, code);
   return {
     project: name,
     preview: `src/videos/${name}/preview.tsx`,
     edit: `src/videos/${name}/${editFile ?? 'preview.tsx'}`,
-    composition: editFile?.replace(/\.tsx$/, '') ?? null,
+    composition,
     assets: [...folders],
     fonts,
     stems,
   };
 }
 
+/**
+ * Which file is the edit, and the composition id it renders as — the id the plan gate checks (work/plans/<id>/).
+ *
+ * The id is what Root.tsx registers, not the file name: the rulebook never told agents to name the edit *Edit.tsx
+ * (the shipped sample is Sample.tsx), and with no *Edit.tsx the id was null, previewed.json was never written and the
+ * plan gate refused every render even after "Render final video" (an edit named src/videos/<name>/<Name>.tsx, 2026-11-06).
+ *
+ * Order: the <Composition> in Root.tsx whose component comes from this video's folder — preferring the component
+ * preview.tsx plays, then a *Edit.tsx file, then the only one. Not registered: the file preview.tsx imports, then
+ * *Edit.tsx, then the only .tsx, named by its file.
+ */
+function editAndComposition(name, code) {
+  const tsx = readdirSync(code).filter((f) => f.endsWith('.tsx') && f !== 'preview.tsx');
+  const fileOf = (from) => {
+    const m = from.match(/^\.\/([\w.-]+?)(?:\.tsx)?$/);
+    return m && tsx.includes(`${m[1]}.tsx`) ? `${m[1]}.tsx` : null;
+  };
+  // What preview.tsx imports from beside it: {ident -> file}
+  const played = new Map();
+  for (const {names, from} of importsOf(readFileSync(join(code, 'preview.tsx'), 'utf8'))) {
+    const f = fileOf(from);
+    if (f) for (const n of names) played.set(n, f);
+  }
+  const playedFiles = new Set(played.values());
+
+  const ours = registered().filter((c) => c.from.startsWith(`./videos/${name}/`));
+  const rank = (c) => (played.get(c.component) === c.file ? 0 : playedFiles.has(c.file) ? 1 : /Edit\.tsx$/.test(c.file ?? '') ? 2 : 3);
+  const pick = ours.filter((c) => c.file).sort((a, b) => rank(a) - rank(b));
+  if (pick.length && (rank(pick[0]) < 3 || pick.length === 1)) return {editFile: pick[0].file, composition: pick[0].id};
+
+  const editFile =
+    [...playedFiles][0] ?? tsx.find((f) => /Edit\.tsx$/.test(f)) ?? (tsx.length === 1 ? tsx[0] : undefined);
+  return {editFile, composition: editFile?.replace(/\.tsx$/, '') ?? null};
+}
+
+/** `import {A, B as C} from './x'` → [{names: ['A', 'C'], from: './x'}] (default imports too). */
+function importsOf(text) {
+  const out = [];
+  for (const m of text.matchAll(/import\s+(?:type\s+)?([\w$]+)?\s*,?\s*(?:\{([^}]*)\})?\s*from\s*['"]([^'"]+)['"]/g)) {
+    const names = [];
+    if (m[1]) names.push(m[1]);
+    for (const part of (m[2] ?? '').split(',')) {
+      const n = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop();
+      if (n) names.push(n);
+    }
+    out.push({names, from: m[3]});
+  }
+  return out;
+}
+
+/** Every <Composition id="…" component={…}> in src/Root.tsx, with the import its component comes from. */
+function registered() {
+  const root = join(SRC, 'Root.tsx');
+  if (!existsSync(root)) return [];
+  const text = readFileSync(root, 'utf8');
+  const from = new Map();
+  for (const {names, from: f} of importsOf(text)) for (const n of names) from.set(n, f);
+  const out = [];
+  for (const chunk of text.split(/<Composition\b/).slice(1)) {
+    const tag = chunk.slice(0, chunk.indexOf('/>') + 1 || undefined);
+    const id = tag.match(/\bid=(?:\{\s*)?["'`]([^"'`]+)["'`]/)?.[1];
+    const component = tag.match(/\bcomponent=\{\s*([\w$]+)\s*\}/)?.[1];
+    if (!id || !component || !from.has(component)) continue;
+    const f = from.get(component);
+    const file = f.match(/\/([\w.-]+?)(?:\.tsx)?$/)?.[1];
+    out.push({id, component, from: f, file: file ? `${file}.tsx` : null});
+  }
+  return out;
+}
+
 /* ----------------------------------------------------------------------------- the footage */
 
 const MEDIA = /\.(mp4|mov|webm|png|jpe?g|webp|gif|svg|mp3|wav|m4a|ttf|otf|woff2?)$/i;
@@ -315,8 +384,42 @@ export async function playerHtml() {
 }
 
 export async function buildUi() {
-  const r = await esbuild.build({...common, entryPoints: [join(HERE, 'ui', 'app.tsx')], format: 'iife', write: false, minify: true, define: {'process.env.NODE_ENV': '"production"'}});
+  // the fonts and icon sets the bar offers travel inside the player (ui/make-assets.mjs)
+  const assets = await import(pathToFileURL(join(HERE, 'ui', 'make-assets.mjs')).href);
+  if (assets.stale()) assets.make();
+  // The build stamp shows on every card ("Player 6 Nov 10:40 · edit v5"), so a stale player can never pass unseen.
+  const define = {'process.env.NODE_ENV': '"production"', __LP_BUILD__: JSON.stringify(new Date().toISOString())};
+  const r = await esbuild.build({...common, entryPoints: [join(HERE, 'ui', 'app.tsx')], format: 'iife', write: false, minify: true, define});
   const js = r.outputFiles[0].text;
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
-<body><div id="root"></div><script>${js.replace(/<\/script>/g, '<\\/script>')}</script></body></html>`;
+  return wrapJs(js);
+}
+
+const CLOSE = /<\/script>/g;
+const CLOSE_ESC = /<\\\/script>/g;
+const wrapJs = (js) => `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
+<body><div id="root"></div><script>${js.replace(CLOSE, '<\\/script>')}</script></body></html>`;
+
+/** The player's own script, out of the player page — it travels inside every preview_edit result (see shellHtml). */
+export const playerJs = (html) => {
+  // The page's own marker — the player's code itself contains the text "<script>".
+  const OPEN = '<div id="root"></div><script>';
+  const at = html.indexOf(OPEN);
+  return html.slice(at + OPEN.length, html.lastIndexOf('</script>')).replace(CLOSE_ESC, '</script>');
+};
+
+/**
+ * THE SHELL (2026-11-06). The chat card's page is this small, never-changing shell: it waits for its own tool
+ * result and runs the player that came inside it. The Claude app shows a page it fetched earlier (at startup, or
+ * when the person last wrote), so a player inside the page was always one version behind — now the page holds no
+ * player at all, and every card plays the newest one. Customers get it pre-built (shell.html).
+ */
+export async function shellHtml() {
+  const built = join(HERE, 'shell.html');
+  if (existsSync(built) && !existsSync(join(HERE, 'ui', 'shell.ts'))) return readFileSync(built, 'utf8');
+  return buildShell();
+}
+
+export async function buildShell() {
+  const r = await esbuild.build({...common, entryPoints: [join(HERE, 'ui', 'shell.ts')], format: 'iife', write: false, minify: true, define: {'process.env.NODE_ENV': '"production"'}});
+  return wrapJs(r.outputFiles[0].text);
 }