creator-editing-studio 1.3.8 → 1.4.0

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/lib/plan-gate.mjs

@@ -0,0 +1,73 @@
+/**
+ * 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} 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) || JSON.parse(readFileSync(previewed, 'utf8')).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.');
+}

package/template/scripts/plan-sheet.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * The motion sheet for a plan: one real rendered frame per beat, numbered and labelled, as one PNG.
+ *
+ *   npm run plan-sheet -- <CompositionId> --beats <beats.json> [--entry src/index.ts] [--public-dir assets]
+ *
+ * beats.json: [{"frame": 105, "says": "same handful of tools", "what": "...", "beat": "Text behind me"}, ...]
+ * (or just a list of frame numbers).
+ *
+ * WHY THIS IS A COMMAND AND NOT A SENTENCE IN THE RULEBOOK. The rule "show a motion sheet with the plan"
+ * existed for weeks, and on 2026-10-22 the plan still went out as a table only — a rule that is only text
+ * gets skipped. This makes the sheet one command, and remotion.config.ts refuses a render until the person
+ * has approved the sheet this command made (scripts/approve.mjs). See "The plan gate" in the rulebook.
+ *
+ * Renders every still in ONE browser session (one copy of the assets — a copy per still filled a disk).
+ * Writes work/plans/<Comp>/motion-sheet.png and work/plans/<Comp>/sheet.json (with the sheet's hash).
+ */
+import {createHash} from 'node:crypto';
+import {existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {dirname, join, resolve} from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {createRequire} from 'node:module';
+import {bundle} from '@remotion/bundler';
+import {openBrowser, renderStill, selectComposition} from '@remotion/renderer';
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => (args.includes(`--${name}`) ? args[args.indexOf(`--${name}`) + 1] : fallback);
+const comp = args.find((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--')));
+const beatsFile = flag('beats', null);
+if (!comp || !beatsFile) {
+  console.error('Usage: npm run plan-sheet -- <CompositionId> --beats <beats.json> [--entry src/index.ts] [--public-dir assets]');
+  process.exit(1);
+}
+const raw = JSON.parse(readFileSync(beatsFile, 'utf8'));
+const beats = raw.map((b) => (typeof b === 'number' ? {frame: b} : b));
+const entry = resolve(flag('entry', 'src/index.ts'));
+const publicDir = resolve(flag('public-dir', 'assets'));
+const dir = resolve('work', 'plans', comp);
+const stillsDir = join(dir, 'stills');
+rmSync(stillsDir, {recursive: true, force: true});
+mkdirSync(stillsDir, {recursive: true});
+
+// The CLI file is not in the package's exports map, so find it next to the package's main entry.
+const CLI = join(dirname(createRequire(import.meta.url).resolve('@remotion/cli')), '..', 'remotion-cli.js');
+const STARTED = Date.now() - 1000;
+/** Remotion copies the media into a fresh temp folder for EVERY still (400 MB each for a long clip) and never
+ *  removes it — 15 stills filled a disk on 2026-10-22. Delete the copies this run made, after each still. */
+const cleanTemp = () => {
+  for (const d of readdirSync(tmpdir())) {
+    const full = join(tmpdir(), d);
+    try {
+      if (/^remotion-v[0-9.]+-assets/.test(d) && statSync(full).mtimeMs >= STARTED) rmSync(full, {recursive: true, force: true});
+    } catch {
+      /* still in use — the next pass gets it */
+    }
+  }
+};
+const tc = (frame, fps) => {
+  const s = frame / fps;
+  return `${Math.floor(s / 60)}:${(s % 60).toFixed(1).padStart(4, '0')}`;
+};
+
+console.log(`Bundling ${entry}…`);
+// Bundles go next to the sheet and are deleted at the end: each one copies the whole assets folder, and
+// leaving them behind is how a nearly full disk ran out mid-render.
+const serveUrl = await bundle({entryPoint: entry, publicDir, outDir: join(dir, '.bundle')});
+const browser = await openBrowser('chrome');
+try {
+  const composition = await selectComposition({serveUrl, id: comp, puppeteerInstance: browser});
+  const tiles = [];
+  for (const [i, b] of beats.entries()) {
+    const file = `s${String(i + 1).padStart(2, '0')}.jpg`;
+    // Each still in its own short process: Remotion copies the media into temp for every still and holds the
+    // copy until the process ends, so one process for all stills piled up 14 x 400 MB and filled the disk.
+    const r = spawnSync(process.execPath, [CLI, 'still', serveUrl, comp, join(stillsDir, file), `--frame=${b.frame}`, '--scale=0.5', '--log=error'], {stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8'});
+    if (r.status !== 0 || !existsSync(join(stillsDir, file))) throw new Error(`still at frame ${b.frame} failed: ${(r.stderr || '').slice(0, 400)}`);
+    cleanTemp();
+    tiles.push({file, n: i + 1, time: tc(b.frame, composition.fps), frame: b.frame, says: b.says, what: b.what, beat: b.beat});
+    console.log(`  ${i + 1}/${beats.length}  frame ${b.frame}`);
+  }
+
+  // The sheet itself, drawn by Remotion with the stills folder as its public dir.
+  const sheetUrl = await bundle({entryPoint: resolve('src/plan/entry.tsx'), publicDir: stillsDir, outDir: join(dir, '.bundle-sheet')});
+  const props = {title: flag('title', comp), subtitle: flag('subtitle', 'One real rendered frame per beat. Point at a number to change it.'), tiles, vertical: composition.height > composition.width};
+  const sheetComp = await selectComposition({serveUrl: sheetUrl, id: 'PlanSheet', inputProps: props, puppeteerInstance: browser});
+  const out = join(dir, 'motion-sheet.png');
+  await renderStill({serveUrl: sheetUrl, composition: sheetComp, frame: 0, output: out, imageFormat: 'png', inputProps: props, puppeteerInstance: browser});
+
+  const hash = createHash('sha256').update(readFileSync(out)).digest('hex').slice(0, 16);
+  writeFileSync(join(dir, 'sheet.json'), JSON.stringify({composition: comp, hash, beats: beats.length, frames: beats.map((b) => b.frame), at: new Date().toISOString()}, null, 2) + '\n');
+  // A new sheet means a new plan: any earlier approval no longer covers it.
+  if (existsSync(join(dir, 'approved.json'))) console.log('A new sheet replaces the approved one — ask for a yes on this sheet before rendering.');
+  console.log(`\nMotion sheet: ${out}\nShow it to them with the plan table, then wait for a yes and record it: npm run approve -- ${comp} --said "<their words>"`);
+} finally {
+  await browser.close({silent: true});
+  for (const b of ['.bundle', '.bundle-sheet']) rmSync(join(dir, b), {recursive: true, force: true});
+  cleanTemp();
+}

package/template/src/components/CommentBox.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import {AbsoluteFill, useCurrentFrame} from 'remotion';
+import {EASE} from '../design/motion';
+import {FONT} from '../design/tokens';
+import {progress} from '../lib/animate';
+
+/**
+ * Comment box — the "comment WORD" call to action as a real comment field: it rises over a soft bottom
+ * gradient, the word types itself in (accent colour), and "Post" lights up when it's complete.
+ * Sound: a key click per letter, a click on Post.
+ *
+ *   <CommentBox from={2474} to={2545} typeAt={2496} word="EDIT" />
+ */
+export const CommentBox: React.FC<{from: number; to: number; typeAt: number; word: string; accent?: string}> = ({from, to, typeAt, word, accent = 'var(--accent, your accent)'}) => {
+  const f = useCurrentFrame();
+  if (f < from || f >= to) return null;
+  const a = progress(f, from, 12, EASE.out);
+  const o = Math.min(a, 1 - progress(f, to - 6, 6, EASE.in));
+  const typed = word.slice(0, Math.max(0, Math.min(word.length, Math.floor((f - typeAt + 3) / 3))));
+  const done = typed.length === word.length;
+  return (
+    <>
+      <AbsoluteFill style={{background: 'linear-gradient(to top, rgba(15,15,13,0.85), rgba(15,15,13,0) 45%)', opacity: o}} />
+      <div style={{position: 'absolute', left: 50, right: 50, bottom: 300 - (1 - a) * 24, opacity: o, borderRadius: 999, padding: '22px 30px', display: 'flex', alignItems: 'center', gap: 18, background: 'rgba(28,28,25,0.92)', border: '1px solid rgba(255,255,255,0.09)', boxShadow: '0 30px 60px rgba(0,0,0,0.45)', fontFamily: FONT.sans}}>
+        <div style={{width: 60, height: 60, borderRadius: 999, background: 'linear-gradient(135deg,#f9ce34,#ee2a7b,#6228d7)'}} />
+        <div style={{flex: 1, fontSize: 52, fontWeight: 800, color: typed ? accent : 'rgba(255,255,255,0.35)', letterSpacing: '0.02em'}}>{typed || 'Add a comment…'}</div>
+        <div style={{fontSize: 34, fontWeight: 700, color: done ? accent : 'rgba(255,255,255,0.3)', transform: `scale(${done ? 1.06 : 1})`}}>Post</div>
+      </div>
+    </>
+  );
+};

package/template/src/components/FilmBurn.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import {AbsoluteFill, interpolate, useCurrentFrame} from 'remotion';
+
+/**
+ * Film burn — a warm light leak that flares across the frame and burns out, the old "end of the reel" flash.
+ * Use it to hide a join or a short pause: the eye goes to the flare, and the shot after it reads as a new one.
+ * First built (2026-10-22) over a 0.3 s hesitation after the hook, with a camera shutter on it.
+ *
+ *   <FilmBurn at={138} frames={20} />          // above the footage and the graphics, below the captions
+ *
+ * Peak brightness lands at 40% of its length — put the join or the pause there. Sound: a shutter click at
+ * `at`, a soft whoosh under the peak.
+ */
+export const FilmBurn: React.FC<{at: number; frames?: number; from?: 'left' | 'right'}> = ({at, frames = 20, from = 'left'}) => {
+  const f = useCurrentFrame();
+  const t = (f - at) / frames;
+  if (t < 0 || t > 1) return null;
+  const peak = 0.4;
+  const a = t < peak ? interpolate(t, [0, peak], [0, 1]) : interpolate(t, [peak, 1], [1, 0]);
+  const ease = a * a * (3 - 2 * a);
+  const dir = from === 'left' ? 1 : -1;
+  // the leak travels across the frame while it burns
+  const x = 50 + dir * interpolate(t, [0, 1], [-45, 45]);
+  return (
+    <AbsoluteFill style={{pointerEvents: 'none'}}>
+      {/* the burn: hot core, orange body, deep red edge — screened onto the picture */}
+      <AbsoluteFill
+        style={{
+          mixBlendMode: 'screen',
+          opacity: ease,
+          background: `radial-gradient(ellipse 55% 70% at ${x}% 45%, rgba(255,246,214,1) 0%, rgba(255,170,70,0.95) 28%, rgba(226,72,24,0.75) 55%, rgba(120,20,10,0) 80%)`,
+          filter: 'blur(18px)',
+        }}
+      />
+      {/* a second, offset flare so it never looks like one clean circle */}
+      <AbsoluteFill
+        style={{
+          mixBlendMode: 'screen',
+          opacity: ease * 0.8,
+          background: `radial-gradient(ellipse 35% 45% at ${100 - x}% 75%, rgba(255,214,140,0.9) 0%, rgba(240,110,40,0.6) 40%, rgba(0,0,0,0) 75%)`,
+          filter: 'blur(28px)',
+        }}
+      />
+      {/* the burnt-out moment: everything goes warm white for a beat */}
+      <AbsoluteFill style={{background: 'rgb(255,236,205)', opacity: Math.max(0, ease - 0.55) * 1.6}} />
+    </AbsoluteFill>
+  );
+};