creator-editing-studio 1.3.8 → 1.4.1

package/template/preview/server.mjs

@@ -15,13 +15,13 @@
  * Which video: preview_edit({video}) — or current.json (written by use.mjs) when it is called without one. Nothing listens on any port. stdout belongs to the MCP
  * protocol: every log goes to stderr.
  */
-import {cpSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
 import {registerAppResource, registerAppTool, RESOURCE_MIME_TYPE} from '@modelcontextprotocol/ext-apps/server';
 import {z} from 'zod';
-import {buildManifest, compileEdit, configFor, HERE, playerHtml, SRC} from './lib.mjs';
+import {buildManifest, checkPage, compileEdit, configFor, HERE, PAGE_LIMIT, PUBLIC, playerHtml, PROXY_TIERS, SRC, STUDIO} from './lib.mjs';
 
 const CONFIG = join(HERE, 'current.json');
 const cfg = () => JSON.parse(readFileSync(CONFIG, 'utf8'));
@@ -72,8 +72,65 @@ let uiHtml = '';
 let uiSig = '';
 const media = new Map(); // hash → data URL, so unchanged footage is encoded once
 
-/** The player page with the current edit and its footage inside it. */
-async function page() {
+/**
+ * The page preview_edit built and checked, served to the chat as is. Building it again on the chat's read could
+ * differ from what was checked; it is dropped as soon as the edit changes (the next preview_edit builds anew).
+ */
+let ready = null;
+/**
+ * The data inside the newest built page and inside `ready`, and the file hashes of the page the chat last fetched.
+ * The chat shows the page it fetched when the person last wrote, not this open's — so each result also carries the
+ * edit (_meta.lp): the code plus the files that fetched page lacks, and the card plays that (ui/app.tsx connectApp).
+ */
+let lastBuilt = null;
+let readyBuilt = null;
+let pageHashes = {};
+const deltaFor = (b) => b && {...b.data, files: Object.fromEntries(Object.entries(b.data.files).filter(([k]) => pageHashes[k] !== b.hashes[k]))};
+/** The newest preview_edit call. Each page carries the open that made it, so old players can see they are old. */
+let opens = 0;
+let latest = null;
+
+/**
+ * Build the page, then play it headless (#lpcheck) before the chat sees it. Files the edit asked for that exist but
+ * weren't packed are added and the page is built again once; anything still wrong goes back to Claude in the tool
+ * result, so it is fixed before the person ever sees a blank or a black frame.
+ */
+async function preparePage() {
+  // The chat gives a tool call about 60 s. A first build that made the preview copies can take most of that, so
+  // the check only runs when there is time left — a skipped check never holds the preview back.
+  const t0 = Date.now();
+  const left = () => 50000 - (Date.now() - t0);
+  let html = await page();
+  let report = left() > 20000 ? await checkPage(html, left() - 5000).catch(() => null) : null;
+  const packable = (report?.missing ?? []).filter((f) => existsSync(join(PUBLIC, f)));
+  if (packable.length && left() > 25000) {
+    html = await page(packable);
+    report = await checkPage(html, left() - 5000).catch(() => null);
+  }
+  ready = html;
+  readyBuilt = lastBuilt;
+  log(`check: ${report ? JSON.stringify(report) : 'skipped (no time left after building, or no headless browser)'}`);
+  return {html, report};
+}
+
+/** One plain line for Claude about the check, or '' when all is well. */
+function checkNote(report) {
+  if (!report || report.ok) return report ? ' Checked before opening: every file is inside and it plays start to end.' : '';
+  const parts = [];
+  if (report.missing?.length) parts.push(`these files the edit uses are not under assets/, so they will show blank: ${report.missing.join(', ')} — fix the path in the edit or put the file there`);
+  if (report.errors?.length) parts.push(`it does not play cleanly: ${report.errors.map((e) => e.replace(/\.\s*$/, '')).join(' | ')}`);
+  return ` PROBLEM found by the check before opening — ${parts.join('; ')}. Fix it, then call preview_edit again; tell the person in one line what you fixed.`;
+}
+
+/** The page the app loads at startup, before any open: no video, only a line saying the preview opens below. */
+async function startupPage() {
+  if (!uiHtml) [uiHtml, uiSig] = [await playerHtml(), 'built'];
+  const data = {open: null, version: 0, canUndo: false, project: '', edit: '', composition: '', error: 'Opening the preview… it appears in the next card below.', code: null, files: {}};
+  return uiHtml.replace('<head>', `<head><script>window.__LP_DATA=${JSON.stringify(data)}</script>`);
+}
+
+/** The player page with the current edit and its footage inside it. `extra`: more files under assets/ to pack. */
+async function page(extra = []) {
   const c = cfg();
   const UI = join(HERE, 'ui');
   const sig = existsSync(UI) ? readdirSync(UI).map((f) => `${f}:${statSync(join(UI, f)).mtimeMs}`).join('|') : 'built';
@@ -87,27 +144,77 @@ async function page() {
   } catch (e) {
     error = String(e.message ?? e);
   }
-  const files = {};
-  for (const a of buildManifest(c)) {
-    if (!media.has(a.hash)) {
-      // Remotion's font loader reads the type from the text after the last dot, so fonts get it as a fragment.
-      const ext = /\.(ttf|otf|woff2?)$/i.exec(a.name)?.[1];
-      media.set(a.hash, `data:${a.mime};base64,${readFileSync(a.file).toString('base64')}${ext ? `#.${ext}` : ''}`);
+  const build = (tier) => {
+    const files = {};
+    const hashes = {};
+    for (const a of buildManifest(c, tier, code ?? '', extra)) {
+      if (!media.has(a.hash)) {
+        // Remotion's font loader reads the type from the text after the last dot, so fonts get it as a fragment.
+        const ext = /\.(ttf|otf|woff2?)$/i.exec(a.name)?.[1];
+        media.set(a.hash, `data:${a.mime};base64,${readFileSync(a.file).toString('base64')}${ext ? `#.${ext}` : ''}`);
+      }
+      files[a.name] = media.get(a.hash);
+      hashes[a.name] = a.hash;
     }
-    files[a.name] = media.get(a.hash);
+    const data = {open: latest, version, canUndo: versions(c.project).length > 1, project: c.project, edit: c.edit, composition: c.composition, error, code, files};
+    lastBuilt = {data, hashes};
+    return uiHtml.replace('<head>', `<head><script>window.__LP_DATA=${JSON.stringify(data).replace(/</g, '\\u003c')}</script>`);
+  };
+  // Over the limit the page never reaches the chat (and an older one shows instead) — so shrink, or say so.
+  let tier = 0;
+  let html = build(tier);
+  while (html.length > PAGE_LIMIT && tier < PROXY_TIERS.length - 1) html = build(++tier);
+  if (html.length > PAGE_LIMIT) {
+    const mb = (html.length / 1e6).toFixed(1);
+    error = `This edit's preview is ${mb} MB even with small copies — the chat can only take ${PAGE_LIMIT / 1e6} MB. Use fewer cutout frames or shorter clips in the edit, then open the preview again.`;
+    code = null;
+    html = uiHtml.replace('<head>', `<head><script>window.__LP_DATA=${JSON.stringify({open: latest, version, canUndo: false, project: c.project, edit: c.edit, composition: c.composition, error, code, files: {}}).replace(/</g, '\\u003c')}</script>`);
   }
-  const data = {version, canUndo: versions(c.project).length > 1, project: c.project, edit: c.edit, composition: c.composition, error, code, files};
-  const html = uiHtml.replace('<head>', `<head><script>window.__LP_DATA=${JSON.stringify(data).replace(/</g, '\\u003c')}</script>`);
-  log(`page for ${c.project} version ${version}: ${(html.length / 1e6).toFixed(1)} MB${error ? ' (the edit does not compile)' : ''}`);
+  const mb = (html.length / 1e6).toFixed(1);
+  log(`page for ${c.project} version ${version}: ${mb} MB (copies: ${tier ? 'small' : 'normal'})${error ? ` — ${error}` : ''}`);
+  // stderr is not kept after startup, so page loads are also written here — the proof the chat asked for a fresh page.
+  appendFileSync(join(HERE, '.reads.log'), `${new Date().toISOString()} ${c.project} v${version} ${mb}MB tier${tier}${error ? ' ERROR' : ''}\n`);
   return html;
 }
 
 /* ----------------------------------------------------------------------------- MCP */
 
-const URI = 'ui://editing-os/live-preview.html';
+/*
+ * A NEW PAGE ADDRESS FOR EVERY OPEN. The Claude desktop app keeps the page it got for an address and shows that
+ * copy again when the same address comes back — on 2026-10-22 three opens of an updated edit all showed the
+ * first version (no buttons, black at 0:35) and this server was never asked for the page. So each open gets its
+ * own address: the tool names slot n, and after each call the next slot is registered and the tool re-points to it.
+ */
+const BOOT = Date.now().toString(36);
+const uriFor = (n) => `ui://editing-os/live-preview-${BOOT}-${n}.html`;
+let slot = 0;
+// Slots the chat actually fetched. On 2026-11-01 an older chat kept showing its first page after a new open (the
+// page was built, never fetched) and he saw "no change at all" — so the next open says so instead of staying silent.
+const fetched = new Set();
+const uiMeta = (n) => ({ui: {resourceUri: uriFor(n)}, 'ui/resourceUri': uriFor(n)});
+const addPage = (n) =>
+  registerAppResource(server, `Live preview ${n}`, uriFor(n), {description: 'Player and beat breakdown for the current edit'}, async () => ({
+    contents: [
+      {
+        uri: uriFor(n),
+        mimeType: RESOURCE_MIME_TYPE,
+        // The build is logged when preview_edit makes it; this line is the proof the chat itself fetched the page.
+        text: await (async () => {
+          // Before any open, the only fetch is the app's own at startup, and it keeps that copy for the first open of
+          // the chat — so it must never be a video (2026-11-05: a different video showed twice for the edit asked for).
+          const html = !opens ? await startupPage() : (ready ?? (await page()));
+          pageHashes = !opens ? {} : ((ready ? readyBuilt : lastBuilt)?.hashes ?? {});
+          fetched.add(n);
+          appendFileSync(join(HERE, '.reads.log'), `${new Date().toISOString()} FETCHED by the chat: slot ${n}, ${(html.length / 1e6).toFixed(1)}MB\n`);
+          return html;
+        })(),
+        _meta: {ui: {prefersBorder: false}},
+      },
+    ],
+  }));
 const server = new McpServer({name: 'editing-os-live-preview', version: '0.1.0'});
 
-registerAppTool(
+const previewTool = registerAppTool(
   server,
   'preview_edit',
   {
@@ -117,15 +224,43 @@ registerAppTool(
       'OPEN IT YOURSELF as a step of the work — right after the person approves the plan, and again after every change you make to the edit — never wait to be asked. ' +
       'Changes typed in the preview arrive as chat messages: change only that beat in the edit file, then call preview_edit again so the updated preview appears. ' +
       'Render the final video only when they press "Render final video", and give the estimated render time only then.',
-    inputSchema: {video: z.string().optional().describe('The video folder name (src/videos/<video>). Needed the first time for each video.')},
-    _meta: {ui: {resourceUri: URI}},
+    inputSchema: {
+      video: z.string().optional().describe('The video folder name (src/videos/<video>). Needed the first time for each video.'),
+      again: z.boolean().optional().describe('Only when the previous open failed or showed the wrong video: open again within 30 s anyway.'),
+    },
+    _meta: {ui: {resourceUri: uriFor(0)}},
   },
-  async ({video}) => {
+  async ({video, again}) => {
+    // ONE PLAYER PER REPLY: two opens in one reply put two players in the chat and the person watched the wrong one
+    // (2026-11-03). A real change round takes longer than 30 s, so an open that soon after the last is refused.
+    const since = latest ? Date.now() - Date.parse(latest.at) : Infinity;
+    if (since < 30000 && !again)
+      return {
+        content: [{type: 'text', text: `Not opened: a preview (${latest.project} version ${latest.version}) opened ${Math.round(since / 1000)} s ago, and two players in one reply confuse the person. Open only the one they are reviewing; if that last open was the wrong video or failed, call preview_edit again with again: true.`}],
+        isError: true,
+      };
     if (video) writeFileSync(CONFIG, JSON.stringify(configFor(video), null, 2) + '\n');
     if (!existsSync(CONFIG)) return {content: [{type: 'text', text: 'Which video? Call preview_edit with {video: "<folder name in src/videos>"}.'}], isError: true};
     const c = cfg();
     const v = saveVersion(c.project);
-    return {content: [{type: 'text', text: `Live preview of ${c.project} (version ${v}) is showing in the chat.`}], structuredContent: {project: c.project, version: v}};
+    // The card may get a page the app fetched earlier (at startup, or when the person last wrote) — that's fine now:
+    // this result carries the edit itself (_meta.lp) and the card plays that. See deltaFor and ui/app.tsx connectApp.
+    latest = {n: ++opens, boot: BOOT, at: new Date().toISOString(), project: c.project, version: v};
+    const {report} = await preparePage();
+
+    // The plan gate (scripts/lib/plan-gate.mjs): a render needs this preview to have been shown AFTER the yes.
+    if (c.composition) {
+      const dir = join(STUDIO, 'work', 'plans', c.composition);
+      mkdirSync(dir, {recursive: true});
+      writeFileSync(join(dir, 'previewed.json'), JSON.stringify({composition: c.composition, project: c.project, version: v, at: new Date().toISOString()}, null, 2));
+    }
+    // The next open gets a fresh address (after this result is out, so this open still finds its own page).
+    setTimeout(() => {
+      slot += 1;
+      addPage(slot);
+      previewTool.update({_meta: uiMeta(slot)});
+    }, 50);
+    return {content: [{type: 'text', text: `Live preview of ${c.project} (version ${v}) sent to the chat, with this version's edit inside the result.${checkNote(report)} Before telling the person it's ready, check read_widget_context says "${c.project} v${v}".`}], structuredContent: {project: c.project, version: v, check: report, open: latest}, _meta: {lp: deltaFor(readyBuilt)}};
   },
 );
 
@@ -153,9 +288,97 @@ server.registerTool(
   },
 );
 
-registerAppResource(server, 'Live preview', URI, {description: 'Player and beat breakdown for the current edit'}, async () => ({
-  contents: [{uri: URI, mimeType: RESOURCE_MIME_TYPE, text: await page(), _meta: {ui: {prefersBorder: false}}}],
-}));
+// Asked by every open player (never by Claude): which open is the newest? An older player switches itself off.
+registerAppTool(
+  server,
+  'preview_latest',
+  {title: 'Newest preview', description: 'Used by the live preview player only.', inputSchema: {}, _meta: {ui: {resourceUri: uriFor(0), visibility: ['app']}}},
+  async () => ({content: [{type: 'text', text: latest ? `Newest preview: open ${latest.n}, ${latest.project} version ${latest.version}` : 'No preview opened yet.'}], structuredContent: {latest}}),
+);
+
+addPage(0);
+
+/* ----------------------------------------------------------------------------- the browser editor (editor/) */
+
+const editorInfo = (video) => {
+  const f = join(STUDIO, 'work', video, 'editor.json');
+  return existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : null;
+};
+const alive = async (url) => {
+  try {
+    return (await fetch(`${url}api/state`, {signal: AbortSignal.timeout(1500)})).ok;
+  } catch {
+    return false;
+  }
+};
+
+// The browser editor is PARKED and not shipped (his call, 2026-11-05: "don't do the browser editor" in 1.4.0) — a
+// studio without editor/ never offers its tools.
+const HAS_EDITOR = existsSync(join(STUDIO, 'editor', 'server.mjs'));
+if (HAS_EDITOR) server.registerTool(
+  'editor_open',
+  {
+    title: 'Open the browser editor',
+    description:
+      "Open the edit in the person's browser: the real video with their footage, every on-screen piece draggable and resizable, effect dropdowns, and a Render button with progress. Changes save the moment they're made (layout.json) — no chat needed. " +
+      'Things they type under "Ask Claude" wait in a list; when they say "apply", call editor_requests. Use this instead of preview_edit whenever the edit is big or they want to move things around.',
+    inputSchema: {video: z.string().describe('The video folder name (src/videos/<video>).')},
+  },
+  async ({video}) => {
+    configFor(video); // throws a readable error if the video isn't set up for the editor
+    const info = editorInfo(video);
+    if (info && (await alive(info.url))) {
+      const {spawn} = await import('node:child_process');
+      const opener = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', info.url]] : process.platform === 'darwin' ? ['open', [info.url]] : ['xdg-open', [info.url]];
+      spawn(opener[0], opener[1], {detached: true, stdio: 'ignore'}).unref();
+      return {content: [{type: 'text', text: `The editor for ${video} was already running — opened it again in the browser: ${info.url}`}]};
+    }
+    const {spawn} = await import('node:child_process');
+    const started = Date.now();
+    spawn(process.execPath, [join(STUDIO, 'editor', 'server.mjs'), video], {cwd: STUDIO, detached: true, stdio: 'ignore'}).unref();
+    for (let i = 0; i < 60; i++) {
+      await new Promise((ok) => setTimeout(ok, 250));
+      const now = editorInfo(video);
+      if (now && Date.parse(now.at) >= started - 1000 && (await alive(now.url)))
+        return {content: [{type: 'text', text: `The editor for ${video} is open in the browser: ${now.url}\nTell them: drag anything to move it, the corner to resize, switch effects on the right, and press Render when it's right. For anything else, type it under "Ask Claude" and then say "apply" here.`}]};
+    }
+    return {content: [{type: 'text', text: `The editor did not start within 15 s. Run it yourself to see why: npm run editor -- ${video}`}], isError: true};
+  },
+);
+
+if (HAS_EDITOR) server.registerTool(
+  'editor_requests',
+  {
+    title: 'Read what they asked for in the browser editor',
+    description:
+      'The changes the person typed under "Ask Claude" in the browser editor, each with the moment in the video it is about (time, frame, beat) and any screenshots. Call it when they say "apply". ' +
+      'Make each change in the edit (the open editor reloads by itself), then call this again with done: [ids] to tick them off.',
+    inputSchema: {
+      video: z.string().optional().describe('The video folder name; defaults to the one the preview/editor last showed.'),
+      done: z.array(z.string()).optional().describe('Request ids you have finished — marks them done.'),
+    },
+  },
+  async ({video, done}) => {
+    const v = video ?? cfg().project;
+    const file = join(STUDIO, 'work', v, 'editor-requests.json');
+    const list = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : [];
+    if (done?.length) {
+      for (const r of list) if (done.includes(r.id)) r.status = 'done';
+      writeFileSync(file, JSON.stringify(list, null, 2) + '\n');
+    }
+    const waiting = list.filter((r) => r.status === 'waiting');
+    if (!waiting.length) return {content: [{type: 'text', text: done?.length ? `Marked ${done.length} done. Nothing else is waiting.` : `Nothing is waiting in the editor for ${v}.`}]};
+    const lines = waiting.map((r) => `- [${r.id}] at ${r.time} (frame ${r.frame}, beat ${r.beat}): "${r.text}"${r.images.length ? ` — screenshots: ${r.images.join(', ')} (open them with Read)` : ''}`);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `${waiting.length} change(s) waiting for ${v}:\n${lines.join('\n')}\n\nThe person's own on-screen adjustments (moved/resized pieces, chosen effects) are in src/videos/${v}/layout.json — keep them. Make each change in the edit, then call editor_requests with done: [ids].`,
+        },
+      ],
+    };
+  },
+);
 
 await server.connect(new StdioServerTransport());
 log('MCP server ready');

package/template/remotion.config.ts

@@ -1,4 +1,9 @@
 import {Config} from '@remotion/cli/config';
+// @ts-expect-error -- plain JS module (scripts/ ships as .mjs only); checkPlanGate(argv: string[]): void
+import {checkPlanGate} from './scripts/lib/plan-gate.mjs';
+
+// Every render of a video waits for the person's yes to its plan (motion sheet). See scripts/lib/plan-gate.mjs.
+checkPlanGate(process.argv.slice(2));
 
 Config.setEntryPoint('./src/index.ts');
 // Everything in assets/ is reachable with staticFile('footage/clip.mp4') etc.

package/template/scripts/approve.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Record the person's yes to a plan, so the render gate (remotion.config.ts) lets that composition render.
+ *
+ *   npm run approve -- <CompositionId> --said "go ahead"                 approves the current motion sheet
+ *   npm run approve -- <CompositionId> --said "just render it" --skip-plan   they chose to skip the plan
+ *
+ * --said is THEIR words, copied from the chat — never yours, never a paraphrase. It is the record of who
+ * decided. Only run this after they have actually said yes; silence is not a yes.
+ *
+ * The approval covers that sheet. Fixes to an approved edit render without a new approval; a NEW sheet
+ * (npm run plan-sheet) means a new plan, and the gate asks for a new yes.
+ */
+import {createHash} from 'node:crypto';
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {join, resolve} from 'node:path';
+
+const args = process.argv.slice(2);
+const flag = (name) => (args.includes(`--${name}`) ? args[args.indexOf(`--${name}`) + 1] : null);
+const comp = args.find((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1] === '--said'));
+const said = flag('said');
+const skip = args.includes('--skip-plan');
+if (!comp || !said) {
+  console.error('Usage: npm run approve -- <CompositionId> --said "<their exact words>" [--skip-plan]');
+  process.exit(1);
+}
+const dir = resolve('work', 'plans', comp);
+mkdirSync(dir, {recursive: true});
+let sheetHash = null;
+if (!skip) {
+  const sheet = join(dir, 'motion-sheet.png');
+  if (!existsSync(sheet)) {
+    console.error(`No motion sheet for ${comp}. Make it first (npm run plan-sheet -- ${comp} --beats <beats.json>), show it, then ask.\nIf they explicitly said to skip the plan, add --skip-plan.`);
+    process.exit(1);
+  }
+  sheetHash = createHash('sha256').update(readFileSync(sheet)).digest('hex').slice(0, 16);
+}
+writeFileSync(join(dir, 'approved.json'), JSON.stringify({composition: comp, said, skipPlan: skip, sheetHash, at: new Date().toISOString()}, null, 2) + '\n');
+console.log(skip ? `Recorded: they chose to skip the plan for ${comp} ("${said}").` : `Approved ${comp} on its motion sheet ("${said}"). Rendering is unlocked.`);

package/template/scripts/final-check.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Check the FINISHED file — after every render, before saying it is done.
+ *
+ *   npm run final-check -- out/my-video/final.mp4 [--fps=30] [--frames=871]
+ *
+ * Writes <file>.check.jpg: one tile per second of the delivered video, so a word that is missing,
+ * cut off or pushed off-screen by a camera move shows up (it did, 2026-11-05: a word behind the
+ * speaker was scaled off the top by the push-in and appeared for 8 frames — no still of the edit
+ * showed it, only the finished file did). Then reports and fails on:
+ *   - frame count (against --frames when given) and a video + audio stream being present
+ *   - loudness outside -17…-15 LUFS, true peak above -0.9 dBTP
+ *   - silent gaps over 0.6 s while the video is still running (a dropped voice join)
+ * Look at the contact sheet: the numbers cannot see a misplaced word.
+ */
+import {existsSync} from 'node:fs';
+import {FFMPEG, FFPROBE, run} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+const opt = (k) => args.find((a) => a.startsWith(`--${k}=`))?.split('=')[1];
+if (!file || !existsSync(file)) {
+  console.error('Usage: npm run final-check -- <rendered.mp4> [--frames=<expected>]');
+  process.exit(1);
+}
+const problems = [];
+
+// streams
+const info = JSON.parse(run(FFPROBE, ['-v', 'error', '-count_frames', '-show_entries', 'stream=codec_type,width,height,nb_read_frames,r_frame_rate:format=duration', '-of', 'json', file]).out);
+const v = info.streams.find((s) => s.codec_type === 'video');
+const a = info.streams.find((s) => s.codec_type === 'audio');
+const dur = +info.format.duration;
+if (!v) problems.push('no video stream');
+if (!a) problems.push('no audio stream');
+const frames = v ? +v.nb_read_frames : 0;
+const want = opt('frames') ? +opt('frames') : null;
+if (want && frames !== want) problems.push(`${frames} frames, expected ${want}`);
+console.log(`video  ${v ? `${v.width}×${v.height}, ${frames} frames, ${v.r_frame_rate} fps` : '—'} · ${dur.toFixed(2)} s`);
+
+// loudness + true peak
+if (a) {
+  const out = run(FFMPEG, ['-hide_banner', '-nostats', '-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-']).err;
+  const tail = out.slice(out.lastIndexOf('Summary:'));
+  const I = +(/I:\s+(-?[\d.]+) LUFS/.exec(tail)?.[1] ?? NaN);
+  const TP = +(/Peak:\s+(-?[\d.]+) dBFS/.exec(tail)?.[1] ?? NaN);
+  console.log(`audio  ${I} LUFS integrated · true peak ${TP} dBTP`);
+  if (!(I >= -17 && I <= -15)) problems.push(`loudness ${I} LUFS (deliver at -16)`);
+  if (!(TP <= -0.9)) problems.push(`true peak ${TP} dBTP (keep at or under -1)`);
+
+  // silences while the picture still runs (the last 4 s may be a silent end card)
+  const sil = run(FFMPEG, ['-hide_banner', '-nostats', '-i', file, '-af', 'silencedetect=n=-45dB:d=0.6', '-f', 'null', '-']).err;
+  const gaps = [...sil.matchAll(/silence_start: ([\d.]+)/g)].map((m) => +m[1]).filter((t) => t > 0.3 && t < dur - 4);
+  if (gaps.length) problems.push(`silent gap at ${gaps.map((t) => t.toFixed(2) + ' s').join(', ')} — check the voice joins`);
+}
+
+// contact sheet: one tile per second, 8 across, read left to right (tile n = second n; no burned-in
+// timestamps — ffmpeg's drawtext needs a fontconfig most Windows machines lack)
+const sheet = file.replace(/\.[^.]+$/, '') + '.check.jpg';
+const tiles = Math.ceil(dur);
+const rows = Math.ceil(tiles / 8);
+const made = run(FFMPEG, ['-y', '-v', 'error', '-i', file, '-vf', `fps=1,scale=240:-1,tile=8x${rows}`, '-frames:v', '1', sheet]);
+if (!made.ok) problems.push('contact sheet failed: ' + made.err.trim());
+console.log(`sheet  ${sheet} (${tiles} tiles) — LOOK AT IT before reporting`);
+
+if (problems.length) {
+  console.error('\n✗ Not ready:\n  - ' + problems.join('\n  - '));
+  process.exit(1);
+}
+console.log('\n✓ File checks pass. Now read the contact sheet.');

package/template/scripts/lib/plan-gate.mjs

@@ -0,0 +1,99 @@
+/**
+ * THE PLAN GATE — called from remotion.config.ts, which every `remotion render` loads first.
+ *
+ * A render of a video is refused until the person has approved its plan:
+ *   - a motion sheet exists for that composition (npm run plan-sheet), AND they said yes to THAT sheet
+ *     (npm run approve -- <Comp> --said "…"), and then the LIVE PREVIEW has been opened for it after that
+ *     yes (preview/server.mjs records it), or
+ *   - they explicitly chose to skip the plan (npm run approve -- <Comp> --said "…" --skip-plan).
+ *
+ * Why it exists: on 2026-10-22 a plan went out as a table only, without the motion sheet, against a rule
+ * that had been in the rulebook for weeks. A rule that is only text gets skipped — on our machine and so on
+ * every customer's. This makes the step impossible to skip by accident, without adding work for the person:
+ * they still just look at the sheet and say "go ahead".
+ *
+ * Not gated: test and sample compositions (…Test, …Board, Sample, PlanSheet), stills, the live preview.
+ * Fixes to an approved edit render freely; only a NEW sheet (a new plan) asks for a new yes.
+ */
+import {createHash} from 'node:crypto';
+import {existsSync, readFileSync, readdirSync, statSync} from 'node:fs';
+import {join, resolve} from 'node:path';
+
+const EXEMPT = /(Test|Board|Sheet)$|^Sample$/;
+// Flags that take a separate value — their value is not the composition id.
+const VALUE_FLAGS = new Set(['--codec', '--props', '--frames', '--concurrency', '--crf', '--pixel-format', '--image-format', '--jpeg-quality', '--quality', '--browser-executable', '--gl', '--log', '--every-nth-frame', '--audio-codec', '--audio-bitrate', '--video-bitrate', '--public-dir', '--config', '--env-file', '--height', '--width', '--scale', '--port', '--timeout', '--muted', '--bundle-cache', '--output', '--sequence', '--color-space', '--x264-preset']);
+
+/** The composition id from `remotion render [entry] <comp> [output] [flags]`, or null. */
+export function renderedComposition(argv = process.argv.slice(2)) {
+  const i = argv.indexOf('render');
+  if (i < 0) return null;
+  const positional = [];
+  for (let k = i + 1; k < argv.length; k++) {
+    const a = argv[k];
+    if (a.startsWith('-')) {
+      if (VALUE_FLAGS.has(a) && !a.includes('=')) k++;
+      continue;
+    }
+    positional.push(a);
+  }
+  // Entry files and output paths have a path separator or an extension; the composition id has neither.
+  return positional.find((p) => !/[\\/]/.test(p) && !/\.[a-z0-9]{2,4}$/i.test(p)) ?? null;
+}
+
+export function checkPlanGate(argv) {
+  const comp = renderedComposition(argv);
+  if (!comp || EXEMPT.test(comp)) return;
+  // the editor's low-res PLAYBACK copy (editor/server.mjs, smooth preview) is part of the live preview, not a
+  // deliverable: it never leaves work/<video>/preview/
+  if (process.env.STUDIO_PREVIEW_RENDER === '1') return;
+  const dir = resolve('work', 'plans', comp);
+  const approvedFile = join(dir, 'approved.json');
+  const refuse = (why) => {
+    console.error(
+      `\n✋ Not rendering ${comp}: ${why}\n\n` +
+        'The plan comes first: show the plan table AND the motion sheet, wait for their yes, then record it.\n' +
+        `  1. npm run plan-sheet -- ${comp} --beats <beats.json>     (one real frame per beat → work/plans/${comp}/motion-sheet.png)\n` +
+        `  2. show the table + sheet, and wait for "go ahead"\n` +
+        `  3. npm run approve -- ${comp} --said "<their exact words>"\n` +
+        `  4. open the live preview (preview_edit) and render only when they press Render\n` +
+        `If they explicitly said to skip the plan: npm run approve -- ${comp} --said "<their words>" --skip-plan\n`,
+    );
+    process.exit(1);
+  };
+  if (!existsSync(approvedFile)) refuse('nobody has approved its plan yet.');
+  const approved = JSON.parse(readFileSync(approvedFile, 'utf8'));
+  if (approved.skipPlan) return;
+  const sheet = join(dir, 'motion-sheet.png');
+  if (!existsSync(sheet)) refuse('the approved motion sheet is missing.');
+  const hash = createHash('sha256').update(readFileSync(sheet)).digest('hex').slice(0, 16);
+  if (hash !== approved.sheetHash) refuse('the motion sheet changed after it was approved — that is a new plan, and it needs a new yes.');
+  // Then they must have SEEN it move: the live preview, opened after the yes (preview/server.mjs writes this).
+  const previewed = join(dir, 'previewed.json');
+  if (!existsSync(previewed)) refuse('they approved the plan but have not seen it in the live preview since — open it (preview_edit) and render only when they press Render.');
+  const seen = JSON.parse(readFileSync(previewed, 'utf8'));
+  if (seen.at < approved.at) refuse('they approved the plan but have not seen it in the live preview since — open it (preview_edit) and render only when they press Render.');
+  // A hard gate on the CURRENT edit, not just the plan (2026-11-05): any change to the video's files after the last
+  // preview means they have not seen what would render. tweaks.json is excluded — the preview itself writes it.
+  const changed = seen.project ? newestChange(resolve('src', 'videos', seen.project)) : null;
+  if (changed && changed.at > Date.parse(seen.at)) {
+    refuse(`the edit changed after they last saw it (${changed.file}) — open the live preview again (preview_edit) so they see this version, and render only when they press Render.`);
+  }
+}
+
+/** The most recently changed file of a video's source folder, ignoring the preview's own tweaks.json. */
+function newestChange(dir) {
+  if (!existsSync(dir)) return null;
+  let best = null;
+  const walk = (d) => {
+    for (const e of readdirSync(d, {withFileTypes: true})) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name !== 'tweaks.json') {
+        const at = statSync(p).mtimeMs;
+        if (!best || at > best.at) best = {file: p, at};
+      }
+    }
+  };
+  walk(dir);
+  return best;
+}