paper-motion 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.3.0 · 2026-11-11
+
+- **Studio**: `pamo studio` serves a local page where the user follows a piece stage by stage (brief, look, structure, parts, assembly, final), watches each stage's renders, approves or asks for changes, and edits the brief, the words on screen (a part's CONFIG texts, re-rendered on the spot), lengths, joins and order (drag and drop). `pieces/<piece>/piece.json` holds the stages and what the user did; `pamo piece init | review | working | status` is the agent's side (`review` hands a stage over and waits for the decision).
+- The studio is the default way to make a piece: `pamo piece init` starts the project's studio in the background (one per project, on the first free port from 4317; `pamo studio --stop` ends it), and the first `pamo piece review` opens it in the user's browser (`--no-open` to skip). `llms.txt` and `make-video` now start every piece there.
+- The studio adapts to tablets and phones.
+- `pamo chain <piece> --drafts [--only dir]` renders each part alone, quickly, for review; `--draft` joins a quick version.
+- **Chains**: `pamo chain init <piece>` installs the blocks of a chosen structure (`--board <id> --option D`, or `--parts id:sec,…`) as one scene each under `pieces/<piece>/` with a `chain.json`; `pamo chain <piece>` renders them in the brand's look and joins them into one video (`whip`, `cut`, `dissolve`, `dip`), keeping each part's sound and setting the loudness once. `--check` warns when a part is cut before its land.
+- Boards: a structure beat may name the block or shot that shows it (`[block-id]` in `--option "@Title | 18 | Hook 0-2 [word-swap] …"`, `id` in the payload, checked against the registry); the board plays that clip for the beat.
+- Scenes expose the gestures they cue (`B.cue`) as `window.__pm.marks`.
+- Blocks with a dark panel keep their type light in light brands (`search-type`, `browser-frame`, `terminal-run`, `light-sweep`); `drag-drop`'s cards follow the brand's mode.
+
+## 0.2.7 · 2026-11-10
+
+- A new resource type, **blocks**: 29 ready-made 4–8 s moments (annotations, interfaces, code, data, type, brand, effects), installed like recipes and customized through their `CONFIG`; each recomposes for 16:9, 9:16 and 1:1.
+- `pamo registry previews` renders blocks; `pamo add --set` writes their values into `CONFIG`.
+
 ## 0.2.6 · 2026-11-10
 
 - `camera()` in `paper-motion/kit`: a 3D world for a piece (`place`, `at`, `travel` with keyframes, `focus` with depth of field and gradual exits). Every recipe is rebuilt on it: a corridor the camera travels (launch, manifesto), a column it descends (three-things), a line it dollies along with a pull-back recap (explainer), a window it tilts into and punches (product-demo), a slab it swings around (before-after), a sleeve it orbits (release).

package/bin/pamo.mjs

@@ -45,6 +45,30 @@ Usage: pamo <command> [options]   (pamo = npx paper-motion, or node packages/eng
                                      --cols 1 stacks options full width (judge type at real size)
                                      --sequence plays the clips one after another, with their sound
                                      (for choices you hear: sound palettes, typing)
+  chain init <piece> (--board <id|link> [--option D] | --parts id:sec,id:sec,…) [--format 1920x1080]
+        [--join whip|cut|dissolve|dip] [--title "…"] [--force]
+                                     a piece made of blocks: installs each part as its own scene under
+                                     pieces/<piece>/<nn>-<id>/ (edit each CONFIG) and writes chain.json;
+                                     --board takes the structure the user chose on a board; with neither,
+                                     installs parts you added to chain.json and keeps the rest
+  chain <piece> [--out file.mp4] [--motion-blur 5] [--audio music.wav] [--no-sfx] [--dpr 1] [--check]
+        [--drafts [--only dir,…]] [--draft]
+                                     renders every part in the brand's look and joins them into one
+                                     video (run from the project root); --check only plans and warns;
+                                     --drafts renders each part alone, quickly, for the studio's Parts
+                                     stage; --draft joins a quick version for its Assembly stage
+  piece init <piece> [--title "…"] [--what "…"] [--who "…"] [--format "…"] [--tone "…"] [--action "…"]
+        [--no-studio]                start tracking a piece stage by stage (pieces/<piece>/piece.json)
+                                     and start this project's studio in the background
+  piece review <piece> <stage> [--wait 30] [--no-wait] [--no-open]
+                                     hand a stage to the user in the studio (brief, look, structure,
+                                     parts, assembly, final) and wait for their decision; prints it.
+                                     Starts the studio if needed; the first time, opens it for them
+  piece working <piece> <stage>      mark a stage as yours again (after changes were asked)
+  piece status <piece>               where the piece is, and what the user did that you haven't read
+  studio [--port 4317] [--open] [--stop]
+                                     the local studio: the user follows each piece, approves, edits
+                                     (one per project; --stop ends the one running in the background)
   wordmark <text> --family <name> [--css <url> | --file <font>] [--weight 400] [--tracking -0.02em]
          [--color #fff] [--size 400] [--pad 0] [--out wordmark.png]
                                      the name set in its typeface, as a transparent PNG
@@ -327,13 +351,13 @@ async function main() {
         const { parseSet, setArgs } = await import('../lib/customize.mjs');
         const reg = resolveRegistry(args.registry), { items } = await getIndex(reg), index = Object.fromEntries(items.map((i) => [i.id, i]));
         const opts = process.argv.flatMap((a, i, all) => (a === '--option' ? [all[i + 1]] : a.startsWith('--option=') ? [a.slice(9)] : [])).filter(Boolean);
-        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette,font] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url]\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 one line; Proof 2-12 three shots; Close 12-18 the action".\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, --no-wait returns at once) and prints the reply line, the same one they could paste. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
+        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette,font] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url]\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 [word-swap] one line; Proof 2-12 [browser-frame] three shots; Close 12-18 [svg-logo] the action" (a [block-id] makes the board play that clip for the beat).\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, --no-wait returns at once) and prints the reply line, the same one they could paste. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
         const LABELS = ['A', 'B', 'C', 'D'];
         const parseOne = async (spec) => {
           if (spec.startsWith('@')) {
             // a structure of the agent's own: "@Title | 18 | Hook 0-2 one line; Proof 2-12 three shots; Close 12-18 the action"
             const [title, dur, beatsSpec] = spec.slice(1).split('|').map((x) => x.trim());
-            const beats = (beatsSpec ?? '').split(';').map((x) => x.trim()).filter(Boolean).map((x) => { const m = x.match(/^(.+?)\s+(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)\s+(.+)$/); if (!m) throw new Error(`structure beat "${x}" must read "Name from-to what"`); return { name: m[1], from: Number(m[2]), to: Number(m[3]), what: m[4] }; });
+            const beats = (beatsSpec ?? '').split(';').map((x) => x.trim()).filter(Boolean).map((x) => { const m = x.match(/^(.+?)\s+(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)\s+(.+)$/); if (!m) throw new Error(`structure beat "${x}" must read "Name from-to [block-id] what"`); const sh = m[4].match(/^\[([\w-]+)\]\s*(.+)$/); return { name: m[1], from: Number(m[2]), to: Number(m[3]), what: sh ? sh[2] : m[4], ...(sh ? { id: sh[1] } : {}) }; });
             return { structure: { title, duration: Number(dur), beats } };
           }
           const [id, kv] = spec.split(':'), it = index[id];
@@ -417,6 +441,103 @@ async function main() {
       break;
     }
 
+    case 'chain': {
+      const sub = args._[1] === 'init' ? 'init' : 'render';
+      const piece = sub === 'init' ? args._[2] : args._[1];
+      if (!piece || args.help) { console.error('Usage: chain init <piece> [--board <id|link> [--option D] | --parts id:sec,…] [--format 1920x1080] [--join whip|cut|dissolve|dip] [--force]\n       chain <piece> [--out file.mp4] [--motion-blur 5] [--audio music.wav] [--no-sfx] [--check]'); process.exit(args.help ? 0 : 1); }
+      const chainLib = await import('../lib/chain.mjs');
+      if (sub === 'init') {
+        const { SITE } = await import('../lib/registry.mjs');
+        let src;
+        if (args.board) src = await chainLib.structureFromBoard(String(args.board), typeof args.option === 'string' ? args.option : undefined, { site: typeof args.site === 'string' ? args.site : SITE });
+        else if (typeof args.parts === 'string') src = { parts: chainLib.partsFromList(args.parts) };
+        else src = {};   // no source: sync an existing chain.json (install parts added since)
+        const r = await chainLib.initChain({ piece, title: typeof args.title === 'string' ? args.title : src.title, parts: src.parts, format: typeof args.format === 'string' ? args.format : undefined, join: typeof args.join === 'string' ? args.join : undefined, registry: args.registry, force: !!args.force });
+        console.log(`✓ ${path.relative(process.cwd(), r.dir)}/chain.json · "${r.chain.title}" · ${r.chain.parts.length} parts, ${r.chain.format}`);
+        for (const p of r.chain.parts) console.log(`  ${p.dir ?? '(no block)'}${p.name ? ` · ${p.name}` : ''}${p.seconds ? ` · ${p.seconds} s` : ''}${p.what ? `  — ${p.what}` : ''}`);
+        for (const n of r.notes) console.log(`  ! ${n}`);
+        console.log(`\nNext: write each part's text and data into its CONFIG (the "what" above is the brief), then:\n  npx paper-motion chain ${piece} --motion-blur 5`);
+        break;
+      }
+      await ensureDeps();
+      if (args.check) {
+        const r = await chainLib.checkChain({ piece });
+        for (const p of r.parts) console.log(`  ${p.dir} · ${p.join} · ${p.from}–${+(p.from + p.seconds).toFixed(2)} s of ${p.D}`);
+        for (const w of r.warnings) console.log(`  ! ${w}`);
+        console.log(`${r.total.toFixed(1)} s in all`);
+        break;
+      }
+      if (args.drafts) {
+        const only = typeof args.only === 'string' ? args.only.split(',').map((x) => x.trim()) : undefined;
+        const r = await chainLib.renderDrafts({ piece, only, onStep: (e) => { if (e.warning) console.log(`  ! ${e.warning}`); else process.stdout.write(`\rdraft ${e.part}/${e.of} · ${e.dir}            `); } });
+        console.log(`\r✓ ${r.rendered.length} draft${r.rendered.length === 1 ? '' : 's'} in ${path.relative(process.cwd(), path.join(chainLib.pieceDir(piece), 'drafts')) || '.'}${r.rendered.length ? '' : ' (every part is approved; --only <dir> to redo one)'}          `);
+        break;
+      }
+      const blur = args['motion-blur'] ? Number(args['motion-blur'] === true ? 5 : args['motion-blur']) : 1;
+      const r = await chainLib.renderChain({ draft: !!args.draft, piece, out: typeof args.out === 'string' ? args.out : undefined, motionBlur: blur, dpr: Number(args.dpr ?? 1), audio: typeof args.audio === 'string' ? args.audio : undefined, sfx: !args['no-sfx'],
+        onStep: (e) => { if (e.warning) console.log(`  ! ${e.warning}`); else if (e.part) process.stdout.write(`\rpart ${e.part}/${e.of} · ${e.dir}            `); else if (e.joining) process.stdout.write('\rjoining…                              '); } });
+      console.log(`\r✓ ${path.relative(process.cwd(), r.out)} — ${r.parts} parts, ${r.total.toFixed(1)} s, ${r.W}×${r.H}`);
+      break;
+    }
+
+    case 'piece': {
+      const sub = args._[1], piece = args._[2];
+      if (!['init', 'review', 'working', 'status'].includes(sub) || !piece || args.help) { console.error('Usage: piece init <piece> [--title "…"] [--what …] [--who …] [--format …] [--tone …] [--action …]\n       piece review <piece> <stage> [--wait 30] [--no-wait]\n       piece working <piece> <stage>\n       piece status <piece>'); process.exit(args.help ? 0 : 1); }
+      const P = await import('../lib/piece.mjs');
+      const { pieceDir } = await import('../lib/chain.mjs');
+      const dir = pieceDir(piece), studioLib = await import('../lib/studio.mjs'), q = `?p=${encodeURIComponent(path.basename(dir))}`;
+      const studio = async () => (args.studio === false || args['no-studio'] ? null : studioLib.ensureStudio(process.cwd(), { bin: fileURLToPath(import.meta.url) }));
+      if (sub === 'init') {
+        const brief = Object.fromEntries(P.BRIEF_KEYS.filter((k) => typeof args[k] === 'string').map((k) => [k, args[k]]));
+        const p = P.initPiece({ piece, title: typeof args.title === 'string' ? args.title : undefined, brief, force: !!args.force });
+        console.log(`✓ ${path.relative(process.cwd(), dir)}/piece.json · "${p.title}" · stage ${p.stage}`);
+        const missing = P.BRIEF_KEYS.filter((k) => !p.brief[k]);
+        if (missing.length) console.log(`  brief still empty: ${missing.join(', ')} (pass them, or write piece.json)`);
+        const s = await studio().catch((e) => { console.log(`  ! ${e.message}`); return null; });
+        if (s) console.log(`  studio: ${s.url}${q}${s.started ? ' (started in the background; npx paper-motion studio --stop ends it)' : ''}`);
+        console.log(`\nNext: npx paper-motion piece review ${piece} brief   (opens the studio for the user and waits for their decision)`);
+        break;
+      }
+      if (sub === 'status') {
+        const p = P.readPiece(dir); if (!p) { console.error(`no piece.json in ${path.relative(process.cwd(), dir)}`); process.exit(1); }
+        for (const s of P.STAGES) console.log(`${s === p.stage ? '›' : ' '} ${s.padEnd(10)} ${p.stages[s].status}${p.stages[s].note ? `  “${p.stages[s].note}”` : ''}`);
+        for (const [d, x] of Object.entries(p.parts)) console.log(`    ${d.padEnd(22)} ${x.status}${x.note ? `  “${x.note}”` : ''}`);
+        const fresh = p.events.filter((e) => e.n > (p.seen ?? 0));
+        if (fresh.length) { console.log(`\n${fresh.length} unread:`); for (const e of fresh) console.log(P.eventLine(p, e)); }
+        break;
+      }
+      const stage = args._[3];
+      if (!P.STAGES.includes(stage)) { console.error(`piece ${sub}: give a stage (${P.STAGES.join(', ')})`); process.exit(1); }
+      if (sub === 'working') { P.updatePiece(dir, (p) => { p.stage = stage; p.stages[stage] = { ...p.stages[stage], status: 'working' }; }); console.log(`✓ ${stage}: working`); break; }
+      // review: hand the stage over and wait for the user's decision in the studio
+      P.toReview(dir, stage);
+      const s = await studio();
+      const url = s ? `${s.url}${q}` : null;
+      // the first hand-over opens the studio in the user's browser; after that the open page follows the piece
+      let opened = false;
+      if (url && !args['no-open'] && !P.readPiece(dir).opened) { opened = await studioLib.openInBrowser(url); if (opened) P.updatePiece(dir, (p) => { p.opened = true; }); }
+      console.log(`${stage} is ready for the user${url ? `: ${url}${opened ? ' (opened in their browser)' : ' (tell them to open it)'}` : ' (no studio: --no-studio)'}`);
+      if (args['no-wait']) { const r = P.unseen(dir); for (const e of r.events) console.log(P.eventLine(r.piece, e)); break; }
+      console.log('Waiting for their decision…');
+      const r = await P.awaitDecision(dir, stage, { timeout: Number(args.wait ?? 30) * 60 * 1000 });
+      for (const l of r.lines) console.log(l);
+      if (!r.done) { console.log(`(no decision yet: run piece review ${piece} ${stage} again, or piece status ${piece})`); process.exit(3); }
+      break;
+    }
+
+    case 'studio': {
+      const { startStudio, listPieces, findStudio, openInBrowser } = await import('../lib/studio.mjs');
+      const running = await findStudio(process.cwd());
+      if (args.stop) { if (running) { process.kill(running.pid); console.log(`stopped the studio on port ${running.port}`); } else console.log('no studio running for this project'); break; }
+      if (running) { console.log(`studio already running: ${running.url}`); if (args.open) await openInBrowser(running.url); break; }
+      const s = await startStudio({ port: Number(args.port ?? 4317) });
+      if (args.open) await openInBrowser(`http://127.0.0.1:${s.port}/`);
+      const list = listPieces(process.cwd());
+      console.log(`studio: http://127.0.0.1:${s.port}/${list.length === 1 ? `?p=${encodeURIComponent(list[0].piece)}` : ''}  (${list.length} piece${list.length === 1 ? '' : 's'}; ctrl-c to stop)`);
+      await new Promise(() => {});
+      break;
+    }
+
     case 'wordmark': {
       await ensureDeps();
       const text = args._[1];
@@ -647,15 +768,15 @@ async function main() {
         const only = typeof args.only === 'string' ? args.only.split(',') : null;
         const out = path.resolve(args.out ?? path.join(reg.dir, '..', 'apps', 'web', 'public', 'previews'));
         fs.mkdirSync(out, { recursive: true });
-        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe', 'shot'].includes(i.type) && (!only || only.includes(i.id)));
-        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5, shot: 1.8 };
+        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe', 'shot', 'block'].includes(i.type) && (!only || only.includes(i.id)));
+        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5, shot: 1.8, block: 2.5 };
         const demo = path.join(reg.dir, '_demo', 'index.html');
         const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-previews-'));
         try {
           for (const [k, it] of items.entries()) {
             process.stdout.write(`\r${k + 1}/${items.length} ${it.id.padEnd(16)}`);
             const mp4 = path.join(tmp, `${it.id}.mp4`);
-            if (it.type === 'recipe' || it.type === 'shot') {
+            if (it.type === 'recipe' || it.type === 'shot' || it.type === 'block') {
               // a recipe renders whole, wired to the demo brand in registry/_demo/brand (served as /brand)
               const here = process.cwd(), copy = path.join(reg.dir, '_demo', `.${it.id}.recipe.html`);
               // the demo brand's copy goes in through the same generator `pamo add --set` uses (preview.values)

package/lib/chain.mjs

@@ -0,0 +1,298 @@
+// A chain: several blocks (or shots, recipes) rendered in the brand's look and joined into one piece.
+//
+//   pieces/<piece>/chain.json         what plays, how long, and how each part comes in
+//   pieces/<piece>/01-search-type/    each part is an ordinary installed scene: edit its CONFIG
+//
+// chain.json:
+//   { "title": "…", "format": "1920x1080", "join": "whip",
+//     "parts": [ { "id": "search-type", "dir": "01-search-type", "name": "Búsqueda", "seconds": 2.5 },
+//                { "id": "bar-grow", "dir": "02-bar-grow", "seconds": 3.2, "join": "dissolve", "from": 0 } ] }
+//
+// `join` on a part is how it comes in (the first part's is ignored); the chain's `join` is the default.
+//   cut       a straight cut
+//   whip      the frame slides out sideways with a motion smear and the next slides in (0.35 s, the default)
+//   dissolve  a cross-fade (0.5 s)
+//   dip       out to the brand's ground color and back in (0.5 s)
+// Each part plays from `from` (default 0) for `seconds` (default: the whole scene). A part cut before its
+// land (the beat a block declares with B.cue(s, 'land', t)) gets a warning with the length that keeps it.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+export const JOINS = { cut: 0, whip: 0.35, dissolve: 0.5, dip: 0.5 };
+const OVERLAP = new Set(['whip', 'dissolve']);   // joins that need the outgoing part to run on under the next
+const LAND_HOLD = 0.6;                           // seconds after a land for the hit to read
+
+const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+const pad = (i) => String(i + 1).padStart(2, '0');
+
+/** Where a piece lives: a name (pieces/<name>) or a folder that holds chain.json. */
+export function pieceDir(piece, cwd = process.cwd()) {
+  const asDir = path.resolve(cwd, piece);
+  if (fs.existsSync(path.join(asDir, 'chain.json')) || piece.includes(path.sep) || piece.startsWith('.')) return asDir;
+  return path.join(cwd, 'pieces', piece);
+}
+
+/** Parts from a structure (a board option): one part per beat, its block from the beat's id. */
+export function partsFromStructure(st) {
+  return st.beats.map((b) => ({ id: b.id ?? null, name: b.name, seconds: +(b.to - b.from).toFixed(2), what: b.what }));
+}
+
+/** Parts from "search-type:2.5,browser-frame:3,bar-grow". */
+export function partsFromList(list) {
+  return String(list).split(',').map((x) => x.trim()).filter(Boolean).map((x) => {
+    const [id, sec] = x.split(':');
+    return { id, ...(sec ? { seconds: Number(sec) } : {}) };
+  });
+}
+
+/** A board's structure option, from a short id, a /b/<id> link or a long link (#fragment). */
+export async function structureFromBoard(ref, option, { site }) {
+  const { decodeBoard } = await import('./live-board.js');
+  let board;
+  if (String(ref).includes('#')) board = await decodeBoard(String(ref).slice(String(ref).indexOf('#') + 1));
+  else {
+    const id = String(ref).replace(/\/$/, '').split('/').pop();
+    const res = await fetch(`${site}/api/boards/${id}`);
+    if (!res.ok) throw new Error(`board ${id}: ${res.status} from ${site} (expired, or a long link is needed)`);
+    board = (await res.json()).board;
+  }
+  const opts = board?.options ?? [];
+  // --option takes the letter from the reply line (D), or a structure's title; without it, the board's structure
+  const letter = option && /^[a-z]$/i.test(option) ? option.toUpperCase() : null;
+  const i = letter ? opts.findIndex((o, k) => (o.label ?? String.fromCharCode(65 + k)) === letter)
+    : option ? opts.findIndex((o) => o.structure?.title === option) : opts.findIndex((o) => o.structure);
+  const o = opts[i];
+  if (!o) throw new Error(`board: no option ${option ?? 'with a structure'} (it has ${opts.length})`);
+  if (o.structure) return { title: o.structure.title, parts: partsFromStructure(o.structure) };
+  return { title: board.title, parts: [{ id: o.id }] };   // a single block or recipe chosen: a chain of one
+}
+
+/**
+ * Installs each part as its own scene under pieces/<piece>/<nn>-<id>/ (in the requested format) and writes
+ * chain.json. Parts with no block (a beat the agent didn't name) are listed with id null for the agent to fill.
+ * Without parts, it syncs an existing chain.json: parts whose scene is missing are installed, the rest is kept.
+ */
+export async function initChain({ cwd = process.cwd(), piece, title, parts, format, join, registry, force = false }) {
+  const { add, getItem, resolveRegistry } = await import('./registry.mjs');
+  const reg = resolveRegistry(registry);
+  const dir = pieceDir(piece, cwd), rel = path.relative(path.join(cwd, 'pieces'), dir), file = path.join(dir, 'chain.json');
+  const old = readJson(file, null);
+  if (old && parts && !force) throw new Error(`${path.relative(cwd, file)} exists: run init without --board/--parts to install parts you added, or --force to start over`);
+  if (!old && !parts) throw new Error(`no ${path.relative(cwd, file)} yet: give --board or --parts`);
+  const base = parts ? null : old;
+  format = format ?? base?.format ?? '1920x1080'; join = join ?? base?.join ?? 'whip';
+  if (!JOINS.hasOwnProperty(join)) throw new Error(`join "${join}": use ${Object.keys(JOINS).join(', ')}`);
+  const out = [], notes = [];
+  for (const [i, p] of (parts ?? old.parts).entries()) {
+    if (!p.id) { out.push({ ...p, id: null, dir: null }); notes.push(`part ${i + 1} "${p.name ?? '?'}" has no block yet: set its id in chain.json and run chain init ${piece} again`); continue; }
+    const sub = p.dir && p.dir.endsWith(`-${p.id}`) ? p.dir : `${pad(i)}-${p.id}`;
+    if (base && fs.existsSync(path.join(dir, sub, 'scene.html'))) { out.push({ ...p, dir: sub }); continue; }   // installed already: your edits stay
+    const it = await getItem(p.id, reg);
+    if (it.install?.kind !== 'scene') throw new Error(`${p.id} is a ${it.type}, not a scene (chains take blocks, shots and recipes)`);
+    const hasFormat = (it.params ?? []).some((x) => x.name === 'format');
+    await add([p.id], { cwd, registry, force, name: path.join(rel, sub), set: hasFormat ? [`format=${format}`] : [] });
+    if (!hasFormat && format !== '1920x1080') notes.push(`${p.id} has no format param: it renders at its own size`);
+    const { id, name, seconds, what, dir: _, ...rest } = p;   // rest: from, join, anything the agent added
+    out.push({ id, dir: sub, ...(name ? { name } : {}), ...(seconds ? { seconds } : {}), ...(what ? { what } : {}), ...rest });
+  }
+  const chain = { ...(base ?? {}), title: title ?? base?.title ?? piece, format, join, parts: out };
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(chain, null, 2) + '\n');
+  const { readPiece, updatePiece } = await import('./piece.mjs');
+  if (readPiece(dir)) updatePiece(dir, (p) => {
+    const keep = new Set(out.map((x) => x.dir).filter(Boolean));
+    for (const d of Object.keys(p.parts)) if (!keep.has(d)) delete p.parts[d];
+    for (const d of keep) p.parts[d] ??= { status: 'queued' };
+  });
+  return { dir, chain, notes };
+}
+
+function run(bin, argv) {
+  return new Promise((res, rej) => {
+    const p = spawn(bin, argv, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let err = '';
+    p.stderr.on('data', (d) => { err += d; });
+    p.on('error', rej);
+    p.on('close', (c) => (c === 0 ? res() : rej(new Error(`${bin} failed (${c}): ${err.trim().split('\n').slice(-6).join('\n')}`))));
+  });
+}
+const FF = () => process.env.PAPER_MOTION_FFMPEG || 'ffmpeg';
+function probe(file) {
+  const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration:stream=codec_type', '-of', 'json', file], { encoding: 'utf8' });
+  const j = JSON.parse(r.stdout || '{}');
+  return { duration: Number(j.format?.duration ?? 0), audio: (j.streams ?? []).some((s) => s.codec_type === 'audio') };
+}
+
+/** What a scene declares: its config and the gestures it marks (land, transition, text). */
+async function sceneInfo(browser, url) {
+  const { openScene } = await import('./browser.mjs');
+  const s = await openScene(browser, url);
+  const marks = await s.page.evaluate(() => window.__pm.marks ?? []);
+  await s.close();
+  return { config: s.config, marks };
+}
+
+/** Checks a chain and works out each part's window, without rendering. */
+export function plan(chain, infos) {
+  const warnings = [];
+  const parts = chain.parts.map((p, i) => {
+    const info = infos[i], D = info.config.duration, from = p.from ?? 0;
+    const join = i === 0 ? 'cut' : (p.join ?? chain.join ?? 'whip');
+    if (!JOINS.hasOwnProperty(join)) throw new Error(`part ${i + 1}: join "${join}" (use ${Object.keys(JOINS).join(', ')})`);
+    let seconds = p.seconds ?? D - from;
+    if (from + seconds > D + 1e-6) { warnings.push(`${p.dir}: ${seconds} s from ${from} runs past its end (${D} s); it plays ${+(D - from).toFixed(2)} s`); seconds = D - from; }
+    const lands = info.marks.filter((m) => m.gesture === 'land').map((m) => m.t).filter((t) => t >= from);
+    const land = lands.length ? Math.max(...lands) : null;
+    if (land !== null && from + seconds < land + LAND_HOLD) warnings.push(`${p.dir}: cut at ${seconds} s loses its land at ${+(land - from).toFixed(2)} s; give it at least ${+(land - from + LAND_HOLD).toFixed(1)} s`);
+    return { ...p, from, seconds, join, D };
+  });
+  // the outgoing part runs on under an overlapping join, as far as it can
+  for (const [i, p] of parts.entries()) {
+    const next = parts[i + 1], d = next && OVERLAP.has(next.join) ? JOINS[next.join] : 0;
+    p.to = Math.min(p.D, p.from + p.seconds + d);
+  }
+  return { parts, warnings, total: parts.reduce((a, p) => a + p.seconds, 0) };
+}
+
+/**
+ * Renders every part in the brand's look and joins them into one file.
+ * Must run from the project root (where brand/ is): scenes load the brand from /brand.
+ */
+export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur = 1, dpr = 1, audio, sfx = true, draft = false, onStep = () => {} }) {
+  if (draft) { dpr = 0.5; motionBlur = 1; }
+  return withChain({ cwd, piece }, async ({ dir, url, parts, warnings, total, config }) => {
+    const { renderVideo } = await import('./render.mjs');
+    for (const w of warnings) onStep({ warning: w });
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-chain-'));
+    try {
+      const files = [];
+      for (const [i, p] of parts.entries()) {
+        onStep({ part: i + 1, of: parts.length, dir: p.dir });
+        const f = path.join(tmp, `${pad(i)}.mov`);
+        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.to, sfx, motionBlur, dpr });
+        files.push(f);
+      }
+      const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {}), sound = readJson(path.join(cwd, 'brand/sound.json'), {});
+      const ground = (tokens.colors?.ground?.hex ?? '#000000').replace('#', '0x');
+      const { width: W, height: H, fps } = config;
+      out = path.resolve(cwd, out ?? path.join(dir, 'renders', `${path.basename(dir)}${draft ? '-draft' : ''}.mp4`));
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      onStep({ joining: true });
+      const j = await join({ files, parts, out, ground, fps, music: audio, lufs: sound.loudness ?? -16 });
+      return { out, total: j.seconds, planned: total, parts: parts.length, warnings, W, H };
+    } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+  });
+}
+
+/**
+ * Renders parts on their own, quickly (half resolution, no motion blur), to pieces/<piece>/drafts/<dir>.mp4: what
+ * the user reviews part by part in the studio. Skips approved parts unless named in `only`. Tracks status in piece.json.
+ */
+export async function renderDrafts({ cwd = process.cwd(), piece, only, onStep = () => {} }) {
+  const { readPiece, updatePiece } = await import('./piece.mjs');
+  return withChain({ cwd, piece }, async ({ dir, url, parts, warnings }) => {
+    const { renderVideo } = await import('./render.mjs');
+    for (const w of warnings) onStep({ warning: w });
+    const tracked = !!readPiece(dir), mark = (d, patch) => tracked && updatePiece(dir, (p) => { p.parts[d] = { ...(p.parts[d] ?? {}), ...patch }; });
+    const todo = parts.filter((p) => (only?.length ? only.some((o) => p.dir === o || p.id === o || p.dir.startsWith(`${o}-`)) : (readPiece(dir)?.parts?.[p.dir]?.status ?? 'queued') !== 'approved'));
+    for (const p of todo) mark(p.dir, { status: 'queued' });
+    fs.mkdirSync(path.join(dir, 'drafts'), { recursive: true });
+    const done = [];
+    for (const [i, p] of todo.entries()) {
+      onStep({ part: i + 1, of: todo.length, dir: p.dir });
+      mark(p.dir, { status: 'rendering' });
+      const out = path.join(dir, 'drafts', `${p.dir}.mp4`);
+      try {
+        await renderVideo({ url: url(p), out, from: p.from, to: p.from + p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
+      } catch (e) { mark(p.dir, { status: 'review', error: String(e.message ?? e).slice(0, 300) }); throw e; }
+      const v = (readPiece(dir)?.parts?.[p.dir]?.v ?? 0) + 1;
+      mark(p.dir, { status: 'review', v, error: undefined, note: undefined });
+      done.push(out);
+    }
+    return { rendered: done, warnings };
+  });
+}
+
+/** Plans a chain without rendering: each part's window, its join, and the warnings. */
+export const checkChain = ({ cwd = process.cwd(), piece }) => withChain({ cwd, piece }, async (r) => r);
+
+// Serves the project, opens each part once to read its size, duration and marks, and plans the chain.
+async function withChain({ cwd, piece }, fn) {
+  const dir = pieceDir(piece, cwd), chain = readJson(path.join(dir, 'chain.json'), null);
+  if (!chain) throw new Error(`no chain.json in ${path.relative(cwd, dir) || '.'} (pamo chain init first)`);
+  if (!chain.parts?.length) throw new Error('chain.json has no parts');
+  const missing = chain.parts.filter((p) => !p.id || !p.dir || !fs.existsSync(path.join(dir, p.dir, 'scene.html')));
+  if (missing.length) throw new Error(`parts without a scene: ${missing.map((p) => p.name ?? p.id ?? '?').join(', ')} (set their id in chain.json and run chain init again)`);
+  if (!fs.existsSync(path.join(cwd, 'brand'))) throw new Error('no brand/ here: run chain from the project root');
+  const { startServer } = await import('./server.mjs');
+  const { launch } = await import('./browser.mjs');
+  const server = await startServer({ root: cwd });
+  const url = (p) => `http://127.0.0.1:${server.port}/${path.relative(cwd, path.join(dir, p.dir, 'scene.html')).split(path.sep).map(encodeURIComponent).join('/')}?render`;
+  try {
+    const browser = await launch(), infos = [];
+    try { for (const p of chain.parts) infos.push(await sceneInfo(browser, url(p))); } finally { await browser.close(); }
+    const sizes = new Set(infos.map((x) => `${x.config.width}x${x.config.height}`));
+    if (sizes.size > 1) throw new Error(`parts come in different sizes (${[...sizes].join(', ')}): set the same format in each CONFIG`);
+    return await fn({ dir, chain, url, config: infos[0].config, ...plan(chain, infos) });
+  } finally { await server.close(); }
+}
+
+/** The ffmpeg graph: each part's join applied in turn, sound carried along, loudness set once at the end. */
+async function join({ files, parts, out, ground, fps, music, lufs }) {
+  const lens = files.map((f) => probe(f));
+  const inputs = files.flatMap((f) => ['-i', f]);
+  const g = [];
+  // every part gets a sound track (silent if it declares none) so the audio chain lines up
+  const A = lens.map((l, i) => {
+    if (l.audio) { g.push(`[${i}:a]aformat=sample_rates=48000:channel_layouts=stereo,atrim=0:${l.duration.toFixed(3)},asetpts=PTS-STARTPTS[a${i}]`); return `[a${i}]`; }
+    g.push(`anullsrc=r=48000:cl=stereo,atrim=0:${l.duration.toFixed(3)}[a${i}]`); return `[a${i}]`;
+  });
+  // a dip fades the parts on either side into the ground color
+  const V = parts.map((p, i) => {
+    const f = [`fps=${fps}`, 'format=yuv444p10le', 'settb=AVTB', 'setpts=PTS-STARTPTS'];
+    const half = JOINS.dip / 2;
+    if (parts[i + 1]?.join === 'dip') f.push(`fade=t=out:st=${(lens[i].duration - half).toFixed(3)}:d=${half}:color=${ground}`);
+    if (p.join === 'dip') f.push(`fade=t=in:st=0:d=${half}:color=${ground}`);
+    g.push(`[${i}:v]${f.join(',')}[v${i}]`);
+    return `[v${i}]`;
+  });
+  let v = V[0], a = A[0], len = lens[0].duration;
+  const smears = [];
+  for (let i = 1; i < parts.length; i++) {
+    const j = parts[i].join, d = JOINS[j];
+    if (OVERLAP.has(j)) {
+      const off = Math.max(0, len - d);
+      g.push(`${v}${V[i]}xfade=transition=${j === 'whip' ? 'slideleft' : 'fade'}:duration=${d}:offset=${off.toFixed(3)}[x${i}]`);
+      g.push(`${a}${A[i]}acrossfade=d=${d}:c1=tri:c2=tri[y${i}]`);
+      if (j === 'whip') smears.push([off + d * 0.12, off + d * 0.88]);
+      len = off + lens[i].duration;
+    } else {
+      g.push(`${v}${V[i]}concat=n=2:v=1:a=0[x${i}]`);
+      g.push(`${a}${A[i]}concat=n=2:v=0:a=1[y${i}]`);
+      len += lens[i].duration;
+    }
+    v = `[x${i}]`; a = `[y${i}]`;
+  }
+  // the whip's smear: a horizontal blur over the middle of each slide
+  if (smears.length) {
+    const on = smears.map(([s, e]) => `between(t\\,${s.toFixed(3)}\\,${e.toFixed(3)})`).join('+');
+    g.push(`${v}split[sa][sb];[sb]gblur=sigma=${48}:sigmaV=0.5[sc];[sa][sc]overlay=enable='${on}'[vs]`);
+    v = '[vs]';
+  }
+  const extra = [];
+  if (music) {
+    extra.push('-i', path.resolve(music));
+    const m = files.length;
+    g.push(`[${m}:a]aformat=sample_rates=48000:channel_layouts=stereo,atrim=0:${len.toFixed(3)},afade=t=out:st=${Math.max(0, len - 1).toFixed(3)}:d=1[mu]`);
+    g.push(`${a}[mu]amix=inputs=2:normalize=0[am]`);
+    a = '[am]';
+  }
+  g.push(`${a}loudnorm=I=${lufs}:TP=-2:LRA=11,aresample=48000[aout]`);
+  g.push(`${v}scale=out_color_matrix=bt709:out_range=tv,format=yuv420p[vout]`);
+  await run(FF(), ['-hide_banner', '-y', ...inputs, ...extra, '-filter_complex', g.join(';'), '-map', '[vout]', '-map', '[aout]',
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', '16', '-x264-params', 'aq-mode=3', '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709',
+    '-c:a', 'aac', '-b:a', '320k', '-movflags', '+faststart', '-t', len.toFixed(3), out]);
+  return { out, seconds: len };
+}

package/lib/customize.mjs

@@ -138,6 +138,9 @@ function fontTokens(item, values) {
 }
 
 /** A recipe's CONFIG object from flat values (proof1Title… → proof[0].title, "1920x1080" → [1920, 1080]). */
+// resources whose file is a whole scene, customized through its CONFIG
+const SCENE_TYPES = ['recipe', 'shot', 'block'];
+
 function recipeConfig(values) {
   const cfg = {}, groups = {};
   for (const [k, v] of Object.entries(values)) {
@@ -182,7 +185,7 @@ export function apply(item, values) {
   const files = (item.files ?? []).map((f) => {
     if (f.content === undefined) return f;
     if (MOVE_TYPES.includes(item.type)) return { ...f, content: moveFile(item, f.content, v) };
-    if ((item.type === 'recipe' || item.type === 'shot') && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
+    if (SCENE_TYPES.includes(item.type) && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
     return f;
   });
   let entry = item.install?.entry;
@@ -227,7 +230,7 @@ export function code(item, values, { showAll = false, site = 'https://paper-moti
       { key: 'tokens', label: 'tokens.json', lang: 'json', code: JSON.stringify(e, null, 2) },
       { key: 'css', label: 'CSS variables', lang: 'css', code: `${Object.values(f).map((x) => `@import url('${x.css}');`).filter((x, i, a) => a.indexOf(x) === i).join('\n')}\n\n:root {\n${Object.entries(f).map(([r, x]) => `  --font-${r}: '${x.family}', ${cat(x.family)};`).join('\n')}\n  --display-weight: ${e.type.display.weight};\n  --display-tracking: ${e.type.display.tracking};\n}` },
     ];
-  } else if (item.type === 'recipe' || item.type === 'shot') {
+  } else if (SCENE_TYPES.includes(item.type)) {
     const scene = out.files.find((f) => /scene\.html$/.test(f.path));
     tabs = [{ key: 'scene', label: 'scene.html', lang: 'html', code: scene?.content ?? '' }];
   }

package/lib/live-board.js

@@ -9,15 +9,16 @@
 export const BOARD_VERSION = 1;
 export const MAX_PAYLOAD = 8 * 1024;
 const LABELS = ['A', 'B', 'C', 'D'];
-const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot'];
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot', 'block'];
 
 /**
  * @typedef {{ v: 1, kind: 'resource'|'kit', title: string, ask?: string, reply?: string,
  *   look?: { palette?: { id: string, values?: object }, font?: { id: string, values?: object } },
  *   choose?: number | [number, number],   // how many options the user may pick: 1 (default), 3, or [min, max]
  *   options: Array<{ label: string, id?: string, values?: object, items?: Array<{ id: string, values?: object }>, note?: string,
- *     structure?: { title: string, duration: number, beats: Array<{ name: string, from: number, to: number, what: string }> } }> }} Board
+ *     structure?: { title: string, duration: number, beats: Array<{ name: string, from: number, to: number, what: string, id?: string }> } }> }} Board
  * An option with `structure` (recipe boards only) is a structure the agent proposes for this brief instead of a recipe.
+ * A beat's `id` names the block or shot that shows it, so the board plays that clip for the beat instead of a sketch.
  */
 
 /** Checks a board's shape; returns a list of problems (empty when valid). `index` (registry items by id) adds id checks. */
@@ -43,6 +44,7 @@ export function validateBoard(b, index) {
         if (!(Number(st.duration) > 0)) errs.push(`${at}.structure.duration (seconds) is required`);
         if (!Array.isArray(st.beats) || st.beats.length < 2 || st.beats.length > 8) errs.push(`${at}.structure.beats: 2 to 8 beats`);
         for (const [j, bt] of (st.beats ?? []).entries()) if (!bt?.name || typeof bt.from !== 'number' || typeof bt.to !== 'number' || bt.to <= bt.from || !bt.what) errs.push(`${at}.structure.beats[${j}] needs name, from < to (seconds) and what`);
+        for (const [j, bt] of (st.beats ?? []).entries()) if (bt?.id != null && (typeof bt.id !== 'string' || (index && !index[bt.id]))) errs.push(`${at}.structure.beats[${j}].id "${bt.id}" is not in the registry`);
       } else if (!o.id) errs.push(`${at}.id is required`);
       else if (index && !index[o.id]) errs.push(`${at}.id "${o.id}" is not in the registry`);
     } else {