paper-motion 0.3.0 → 0.4.1

package/lib/studio.mjs

@@ -5,22 +5,30 @@
 //   GET  /api/pieces               pieces in this project that have a piece.json
 //   GET  /api/piece?p=<piece>      everything the page shows: piece.json + chain + look + media
 //   POST /api/piece?p=<piece>      an action: { type, … } (see act())
+//   POST /api/focus?p=<piece>      brings the agent's app to the front (the app the CLI found itself running in)
 //   GET  /files/<path>             files under the project (renders, drafts), with byte ranges for video
 //
 // Edits that need no judgment are applied here: a text goes into the part's CONFIG and the part re-renders as a
-// draft; lengths, joins and order go into chain.json. Everything the user does is also an event in piece.json,
-// which `pamo piece review` hands to the agent.
+// draft; lengths, joins and order go into chain.json; and when the piece already has a joined draft, the studio
+// joins it again by itself. Everything the user does is also an event in piece.json, which `pamo piece review`
+// hands to the agent.
+//
+// The page always says whose turn it is: /api/piece carries whether a command of the agent is waiting on the piece
+// (`agent.listening`), a question it asked in the chat (`ask`), the join in progress (`job`), and whether the
+// joined draft or the final were made from something that has changed since (`media.assemblyStale`, `finalStale`).
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { pieceDir, JOINS } from './chain.mjs';
-import { STAGES, BRIEF_KEYS, readPiece, updatePiece, addEvent, eventLine, sceneTexts, setSceneText } from './piece.mjs';
+import { pieceDir, JOINS, chainSig, readSigs, readJob } from './chain.mjs';
+import { STAGES, BRIEF_KEYS, readPiece, updatePiece, addEvent, eventLine, sceneTexts, setSceneText, listening } from './piece.mjs';
+import { videoView, editVideo, styleView, editStyle, undo, canUndo } from './edit.mjs';
+import { KINDS, EDITABLE, ADDABLE, MULTI, PLAIN, GROUPS, listText, loadRaw, normalize, candidates, scenesOf, describe, applyEdit, evalFill, fillConfig } from './inventory.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PAGE = path.join(HERE, '..', 'studio', 'index.html');
 const SITE = (process.env.PAPER_MOTION_SITE ?? 'https://paper-motion.vercel.app').replace(/\/$/, '');
-const TYPES = { '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.gif': 'image/gif', '.png': 'image/png', '.jpg': 'image/jpeg', '.json': 'application/json', '.html': 'text/html; charset=utf-8', '.css': 'text/css', '.js': 'text/javascript' };
+const TYPES = { '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.gif': 'image/gif', '.png': 'image/png', '.jpg': 'image/jpeg', '.json': 'application/json', '.html': 'text/html; charset=utf-8', '.css': 'text/css', '.js': 'text/javascript', '.woff2': 'font/woff2' };
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 
 /** Pieces in the project that the studio can show. */
@@ -38,6 +46,111 @@ const fileUrl = (cwd, f) => {
   return `/files/${path.relative(cwd, f).split(path.sep).map(encodeURIComponent).join('/')}?v=${Math.round(fs.statSync(f).mtimeMs)}`;
 };
 
+/** Whether the piece's joined draft and final still show what the piece is now, and the join running on it. */
+export function filmState(cwd, dir) {
+  const name = path.basename(dir), sigs = readSigs(dir), sig = chainSig(cwd, dir), renders = path.join(dir, 'renders');
+  const has = (f) => fs.existsSync(path.join(renders, f));
+  const stale = (f) => has(f) && !!sigs[f]?.sig && sigs[f].sig !== sig;   // a render with no record is taken as current
+  const job = readJob(dir);
+  return {
+    draft: has(`${name}-draft.mp4`), final: has(`${name}.mp4`), opts: sigs[`${name}-draft.mp4`] ?? {},
+    assemblyStale: stale(`${name}-draft.mp4`), finalStale: stale(`${name}.mp4`),
+    job: job ? { kind: job.kind, part: job.part ?? null, of: job.of ?? null, joining: !!job.joining } : null,
+  };
+}
+const joinErrors = new Map();   // piece folder → why the studio's last join failed
+
+// the blocks and shots that show content and the library's backgrounds, read once when the studio starts (the
+// registry may be the site); LIVE is the scene server the page's live previews play from
+let SCENES = [], BACKGROUNDS = [], TITLES = new Map(), PALETTES = [], FONTPAIRS = [], LIVE = null;
+const building = new Set(), rendering = new Map();   // pieces whose first version or final is being made by the studio
+// a resource's sample (clip and still): the repo's own when the studio runs inside it (new blocks show before the
+// site has them), else the site's
+const LOCAL_PREVIEWS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../apps/web/public/previews');
+const preview = (id, ext) => (fs.existsSync(path.join(LOCAL_PREVIEWS, `${id}.${ext}`)) ? `/previews/${id}.${ext}` : `${SITE}/previews/${id}.${ext}`);
+
+// What of a block a person may tune: its numbers and its either/or choices (its words come from the content).
+const NOT_TUNED = new Set(['format', 'background', 'fps', 'codec', 'winner', 'mark', 'detail', 'highlight']);
+function tunables(block, filled, values = {}) {
+  return (block.params ?? []).filter((p) => !filled.has(p.name) && !NOT_TUNED.has(p.name) && (p.type === 'enum' || p.type === 'number')).map((p) => {
+    const d = p.default, num = p.type === 'number';
+    const min = num ? p.min ?? +(d * 0.4).toFixed(2) : null, max = num ? p.max ?? +(d * 1.8).toFixed(2) : null;
+    // a setting whose every choice has its own sample (a sentence's entrance) is chosen by watching them
+    const demos = block.repeat?.param === p.name && block.repeat.previews ? (p.options ?? []).map((o) => { const r = block.repeat.previews[o]; return { value: o, title: TITLES.get(r) ?? o, clip: r ? preview(r, 'webm') : null, poster: r ? preview(r, 'jpg') : null }; }) : null;
+    return { name: p.name, label: (p.description ?? p.name).replace(/^./, (c) => c.toUpperCase()), kind: num ? 'number' : 'enum', options: p.options ?? null, min, max, step: num ? +(Math.max((max - min) / 40, 0.01)).toFixed(2) : null, default: d, value: values[p.name] ?? d, set: p.name in values, demos, varies: block.repeat?.param === p.name };
+  });
+}
+// the blocks that can show an item, in the order the page offers them: one that can play several times first
+const ways = (it) => [...candidates(it, SCENES)].sort((a, b) => (b.repeat ? 1 : 0) - (a.repeat ? 1 : 0));
+const filledBy = (block) => new Set(block.needs.flatMap((n) => Object.keys(n.fill ?? {})));
+// the brand's own backgrounds (shader entries, not image filters), as the page shows them
+const brandBackgrounds = (cwd) => (readJson(path.join(cwd, 'brand/shader-set/set.json'), {}).entries ?? []).filter((e) => e.shader && !e.image).map((e) => ({ id: e.id, title: e.id, colors: (e.props?.colors ?? [e.props?.colorBack, e.props?.colorFront]).filter((c) => /^#[0-9a-f]{6}/i.test(c ?? '')).slice(0, 5), entry: { shader: e.shader, props: e.props, background: e.background } }));
+
+/**
+ * A block as it will really play for one item: installed under pieces/<piece>/.try/, its CONFIG filled with the
+ * item's content and the user's tuning, in the brand's look. Returns the address the page plays it from.
+ */
+async function tryScene(cwd, piece, itemId, blockId) {
+  if (!LIVE) throw new Error('the live preview is not ready yet');
+  const dir = pieceDir(piece, cwd), p = readPiece(dir), all = normalize(loadRaw(dir), { cwd }).all;
+  const it = all.find((i) => i.id === itemId), b = SCENES.find((x) => x.id === blockId);
+  if (!it || !b) throw new Error('no such item or block');
+  const need = b.needs[0], fits = (i) => i.kind === need.kind && i.status !== 'removed' && (need.has ?? []).every((f) => i[f] !== undefined && i[f] !== '') && Object.entries(need.where ?? {}).every(([k, v]) => i[k] === v);
+  const group = [it, ...all.filter((i) => i !== it && fits(i))].slice(0, need.count ?? 1);
+  const fill = { ...evalFill(need.fill, group, p?.brief ?? {}) };
+  for (const n of b.needs.slice(1)) if (n.kind === 'name') Object.assign(fill, evalFill(n.fill, [], p?.brief ?? {}));
+  Object.assign(fill, it.tune ?? {});
+  const sub = path.join('.try', `${it.id}--${b.id}`), file = path.join(dir, sub, 'scene.html');
+  if (!fs.existsSync(file)) {
+    const { add } = await import('./registry.mjs');
+    const f = String(p?.brief?.format ?? ''), format = /9\s*:\s*16/.test(f) ? '1080x1920' : /1\s*:\s*1/.test(f) ? '1080x1080' : '1920x1080';
+    await add([b.id], { cwd, force: true, name: path.join(path.relative(path.join(cwd, 'pieces'), dir), sub), set: (b.params ?? []).some((x) => x.name === 'format') ? [`format=${format}`] : [] });
+  }
+  fs.writeFileSync(file, fillConfig(fs.readFileSync(file, 'utf8'), fill));
+  return { url: `${LIVE}/${path.relative(cwd, file).split(path.sep).map(encodeURIComponent).join('/')}?embed&v=${Date.now()}` };
+}
+/** The piece's inventory for the page: every item with where it stands, what can show it and what it lacks. */
+function inventoryView(cwd, dir) {
+  // the page speaks the user's language: everyday names, the fields a person would recognise, labelled
+  const kinds = Object.fromEntries(ADDABLE.map((k) => [k, { name: PLAIN[k].name, fields: EDITABLE[k].filter((f) => PLAIN[k].fields[f]).map((f) => [f, PLAIN[k].fields[f], KINDS[k].needs.includes(f)]) }]));
+  let raw = [], all = [];
+  try { raw = loadRaw(dir); all = normalize(raw, { cwd }).all; } catch (e) { return { items: [], kinds, groups: GROUPS, error: e.message }; }
+  const byId = new Map(raw.map((r) => [r.id, r]));
+  const mine = brandBackgrounds(cwd), have = new Set(mine.map((m) => m.id));
+  // about how many moments the length in the brief holds (a block runs about four seconds, the close is one of them)
+  const secs = Number(String(readPiece(dir)?.brief?.format ?? '').match(/(\d+(?:\.\d+)?)\s*(?:s\b|sec|seconds?)/i)?.[1]) || null;
+  return { kinds, groups: GROUPS, live: LIVE, moments: secs ? Math.max(2, Math.round((secs - 4) / 4.2) + 1) : null, seconds: secs, backgrounds: { mine, library: BACKGROUNDS.filter((b) => !have.has(b.id)) }, items: all.map((it) => {
+    const K = KINDS[it.kind], r = byId.get(it.id) ?? {}, H = PLAIN[it.kind] ?? { name: it.kind, group: 'show', fields: {} };
+    const how = (f) => MULTI[it.kind]?.[f] ?? 'text';
+    return {
+      id: it.id, kind: it.kind, name: H.name, group: H.group, status: it.status, must: !!it.must, what: { line: it.text, voice: it.script, command: it.command }[it.kind] ?? describe(it), source: it.source ?? '',   // a sentence or a command is shown whole
+      missing: (it.missing ?? []).map((f) => H.fields[f] ?? f),
+      // how it could look: the library's own samples of the blocks that show this kind of thing
+      // a block that can play several times (a sentence, arriving its own way each time) is the first way to show it
+      looks: ways(it).map((b) => ({ id: b.id, title: b.title ?? b.id, summary: b.summary ?? '', poster: preview(b.id, 'jpg'), clip: preview(b.id, 'webm') })),
+      // the block the user picked for it (or none: the plan picks), and what of that block they may tune
+      show: ways(it).some((b) => b.id === it.show) ? it.show : null, tune: it.tune ?? {},
+      tunable: (() => { const c = ways(it), b = c.find((x) => x.id === it.show) ?? c[0]; return b ? tunables(b, filledBy(b), it.tune ?? {}) : []; })(),
+      shown: K.role === 'bed' || it.kind === 'logo' ? 'always' : null,
+      thumb: it.image ? fileUrl(cwd, path.join(cwd, it.image.replace(/^\//, ''))) : null,
+      // [field, value as text, needed, how it is edited, its label]: only what a person would recognise
+      fields: Object.entries(H.fields).map(([f, label]) => [f, how(f) === 'text' ? r[f] ?? '' : listText(r[f], how(f)), K.needs.includes(f), how(f), label]),
+    };
+  }) };
+}
+
+// What can be added to a video, by what the user wants to do, each named by what it does; and the transitions.
+const INTENTS = [['say', 'Say something'], ['show', 'Show the product'], ['prove', 'Prove it'], ['how', 'How it works'], ['end', 'End']];
+const JOIN_NAMES = { whip: 'Fast slide', crossfade: 'Soft fade', wipe: 'Wipe', push: 'Push', iris: 'Circle opens', 'zoom-through': 'Zoom through', flash: 'Flash', cells: 'Squares', slices: 'Strips', glitch: 'Glitch', 'flip-3d': 'Card flip', cut: 'Straight cut', dissolve: 'Dissolve', dip: 'Dip to your colour', 'mask-reveal': 'Mask', 'scan-reveal': 'Scan line', 'whip-pan': 'Whip pan' };
+function libraryView() {
+  const group = (b) => { const k = b.needs?.[0]?.kind; return !b.needs?.length ? null : k === 'name' || k === 'logo' ? 'end' : PLAIN[k]?.group === 'brand' ? 'end' : PLAIN[k]?.group ?? null; };
+  const blocks = SCENES.map((b) => ({ id: b.id, title: b.title, summary: b.summary ?? '', group: group(b), poster: preview(b.id, 'jpg'), clip: preview(b.id, 'webm') })).filter((b) => b.group);
+  return {
+    intents: INTENTS.map(([id, title]) => ({ id, title, blocks: blocks.filter((b) => b.group === id) })).filter((g) => g.blocks.length),
+    joins: Object.keys(JOINS).filter((j) => j !== 'dip' && j !== 'dissolve' || true).map((id) => ({ id, title: JOIN_NAMES[id] ?? id, poster: TITLES.has(id) ? preview(id, 'jpg') : null, clip: TITLES.has(id) ? preview(id, 'webm') : null })),
+  };
+}
+
 /** What the page shows for one piece. */
 export function view(cwd, piece) {
   const dir = pieceDir(piece, cwd), p = readPiece(dir);
@@ -54,42 +167,90 @@ export function view(cwd, piece) {
       ...(p.parts?.[c.dir] ?? { status: 'queued' }),
     };
   });
-  const renders = path.join(dir, 'renders'), name = path.basename(dir);
+  const renders = path.join(dir, 'renders'), name = path.basename(dir), film = filmState(cwd, dir);
   const outputs = fs.existsSync(renders) ? fs.readdirSync(renders).filter((f) => !f.startsWith('.') && !f.includes('-draft')).map((f) => ({ file: f, url: fileUrl(cwd, path.join(renders, f)), bytes: fs.statSync(path.join(renders, f)).size })) : [];
   return {
-    ...p, dir: path.relative(cwd, dir), format: chain.format ?? null, join: chain.join ?? 'whip', joins: Object.keys(JOINS),
+    ...p, boards: p.boards ?? [], dir: path.relative(cwd, dir), format: chain.format ?? null, join: chain.join ?? 'whip', joins: Object.keys(JOINS),
     parts,
+    inventory: inventoryView(cwd, dir),
+    // Your video: the parts as the editor shows them, each playing live from the project, and what can be added
+    video: (() => {
+      const v = videoView(cwd, dir, SCENES); if (!v) return null;
+      const rel = path.relative(cwd, dir).split(path.sep).map(encodeURIComponent).join('/');
+      for (const x of v.parts) { x.live = LIVE ? `${LIVE}/${rel}/${encodeURIComponent(x.dir)}/scene.html?embed&rate=${x.rate}&v=${x.mtime}-${styleView(cwd).stamp}` : null; x.poster = preview(x.id, 'jpg'); x.clip = preview(x.id, 'webm');
+        if (x.motion) x.motion.demos = x.motion.options.map((o) => ({ value: o, title: TITLES.get(x.motion.previews[o]) ?? o, poster: x.motion.previews[o] ? preview(x.motion.previews[o], 'jpg') : null, clip: x.motion.previews[o] ? preview(x.motion.previews[o], 'webm') : null })); }
+      return v;
+    })(),
+    building: building.has(dir), rendering: rendering.get(dir) ?? null, undo: canUndo(dir),
+    library: libraryView(),
+    style: { ...styleView(cwd), palettes: PALETTES, fontpairs: FONTPAIRS },
     look: {
       colors: Object.entries(tokens.colors ?? {}).map(([k, v]) => [k, v?.hex ?? v]),
-      fonts: Object.entries(tokens.fonts ?? {}).map(([k, v]) => [k, v?.family ?? v]),
+      fonts: Object.entries(tokens.fonts ?? {}).map(([k, v]) => [k, v?.family ?? v, v?.css ?? null]),
       backgrounds: (set.entries ?? []).map((e) => e.id),
       moves: fs.existsSync(movesDir) ? fs.readdirSync(movesDir).filter((f) => f.endsWith('.js')).map((f) => f.replace(/\.js$/, '')) : [],
     },
-    media: { assembly: fileUrl(cwd, path.join(renders, `${name}-draft.mp4`)), final: fileUrl(cwd, path.join(renders, `${name}.mp4`)), outputs },
+    media: { assembly: fileUrl(cwd, path.join(renders, `${name}-draft.mp4`)), final: fileUrl(cwd, path.join(renders, `${name}.mp4`)), outputs,
+      assemblyStale: film.assemblyStale, finalStale: film.finalStale, error: joinErrors.get(dir) ?? null },
+    job: film.job,
+    ask: p.ask ?? null,
+    // is a command of the agent waiting on this piece, how many of the user's moves it hasn't read, and the way back to it
+    agent: { listening: !!listening(dir), app: p.agent?.app ?? null, focus: process.platform === 'darwin' && !!p.agent?.path, url: p.agent?.url ?? null },
+    unread: p.events.filter((e) => e.n > (p.seen ?? 0)).length,
   };
 }
 
+// boards still waiting: ask the site (at most every 4 s per board) whether the user chose, so the studio shows it
+const asked = new Map();
+async function refreshBoards(cwd, piece) {
+  const dir = pieceDir(piece, cwd), p = readPiece(dir);
+  for (const b of p?.boards ?? []) {
+    if (b.status !== 'waiting' || !b.id || Date.now() - (asked.get(b.id) ?? 0) < 4000) continue;
+    asked.set(b.id, Date.now());
+    try {
+      const res = await fetch(`${SITE}/api/boards/${b.id}/choice`, { signal: AbortSignal.timeout(2500) });
+      if (res.status === 200) { const { line } = await res.json(); updatePiece(dir, (q) => { const x = q.boards.find((y) => y.id === b.id); if (x) { x.status = 'chosen'; x.line = line; } }); }
+    } catch { /* offline: the agent's own wait still gets it */ }
+  }
+}
+
 // ── actions from the page ───────────────────────────────────────────────────────────────────
 function act(cwd, piece, a, queue) {
   const dir = pieceDir(piece, cwd), chainFile = path.join(dir, 'chain.json');
   const chain = () => readJson(chainFile, { parts: [] }), saveChain = (c) => fs.writeFileSync(chainFile, JSON.stringify(c, null, 2) + '\n');
   const text = (v) => String(v ?? '').trim();
-  let rerender = null;
+  const film = filmState(cwd, dir), past = (p, stage) => STAGES.indexOf(p.stage) > STAGES.indexOf(stage);
+  let rerender = null, keep = false;
+  // an edit by hand re-renders a part; one that was approved, in a piece already past Parts, stays approved
+  const redo = (p, part) => { keep = p.parts[part]?.status === 'approved' && past(p, 'parts'); p.parts[part] = { ...(p.parts[part] ?? {}), status: 'queued' }; rerender = part; };
   updatePiece(dir, (p) => {
     switch (a.type) {
       case 'approve': {   // a stage
         if (!STAGES.includes(a.stage)) throw new Error('bad stage');
         if (a.stage === 'parts' && Object.values(p.parts).some((x) => x.status !== 'approved')) throw new Error('approve every part first');
+        if (a.stage === 'inventory') {
+          const inv = loadRaw(dir);
+          if (inv.some((i) => i.status === 'proposed')) throw new Error('keep or remove every proposal first');
+          if (!inv.some((i) => !i.status || i.status === 'kept')) throw new Error('there is nothing to show yet');
+          const short = normalize(inv, { cwd }).items.filter((i) => i.missing.length);
+          if (short.length) throw new Error(`${short[0].id} still needs ${short[0].missing.join(', ')}: fill it in or remove it`);
+        }
+        // never approve a film that no longer shows the piece as it is
+        if (a.stage === 'video' && !fs.existsSync(path.join(dir, 'chain.json'))) throw new Error('there is no video yet');
+        if (['assembly', 'final'].includes(a.stage)) {
+          if (film.job?.kind === a.stage || film[`${a.stage}Stale`]) throw new Error('this video is being updated: wait for the new one');
+          if (Object.values(p.parts).some((x) => ['changes', 'queued', 'rendering'].includes(x.status))) throw new Error('a part is still changing: wait for the new video');
+        }
         p.stages[a.stage] = { status: 'approved', at: new Date().toISOString() };
         const next = STAGES[STAGES.indexOf(a.stage) + 1];
-        if (next) { p.stage = next; if (p.stages[next].status === 'pending') p.stages[next] = { status: 'working' }; }
+        if (next) { p.stage = next; if (p.stages[next].status === 'pending') p.stages[next] = { status: 'working', since: new Date().toISOString() }; }
         addEvent(p, { kind: 'approve', stage: a.stage });
         break;
       }
       case 'changes': {   // a stage, or a part when a.part
         const t = text(a.text); if (!t) throw new Error('say what to change');
         if (a.part) { p.parts[a.part] = { ...(p.parts[a.part] ?? {}), status: 'changes', note: t }; addEvent(p, { kind: 'changes', stage: 'parts', part: a.part, text: t }); }
-        else { p.stages[a.stage] = { status: 'changes', note: t }; p.stage = a.stage; addEvent(p, { kind: 'changes', stage: a.stage, text: t }); }
+        else { p.stages[a.stage] = { status: 'changes', note: t, since: new Date().toISOString() }; p.stage = a.stage; addEvent(p, { kind: 'changes', stage: a.stage, text: t }); }
         break;
       }
       case 'reopen': { p.stages[a.stage] = { status: 'review' }; addEvent(p, { kind: 'reopen', stage: a.stage }); break; }
@@ -103,6 +264,33 @@ function act(cwd, piece, a, queue) {
         addEvent(p, { kind: 'edit', stage: 'brief', key: a.key, text: t });
         break;
       }
+      case 'inv-show': case 'inv-tune': {   // how an item is shown: the block, its settings, its background
+        const it = normalize(loadRaw(dir), { cwd }).all.find((i) => i.id === a.id); if (!it) throw new Error('no such item');
+        const c = ways(it);
+        if (a.type === 'inv-show') { const b = c.find((x) => x.id === a.value); if (a.value && !b) throw new Error('that block cannot show this'); a.title = b?.title; }
+        else {
+          const b = c.find((x) => x.id === (a.block ?? it.show)) ?? c[0]; if (!b) throw new Error('nothing shows this item yet');
+          if (a.key === 'background') { if (a.value && !brandBackgrounds(cwd).some((m) => m.id === a.value)) throw new Error('that background is not in your brand yet: add it first'); a.label = 'background'; }
+          else {
+            const t = tunables(b, filledBy(b)).find((x) => x.name === a.key); if (!t) throw new Error(`"${a.key}" is not a setting of ${b.title ?? b.id}`);
+            if (a.value !== '' && a.value != null) { if (t.kind === 'number') { const n = Number(a.value); if (!Number.isFinite(n)) throw new Error('a number, please'); a.value = Math.min(t.max, Math.max(t.min, n)); } else if (!t.options.includes(a.value)) throw new Error('not one of the choices'); }
+            a.label = t.label;
+            // tuning a block means wanting that block: it stays the one that shows this item
+            if (it.show !== b.id) applyEdit(dir, { type: 'inv-show', id: it.id, value: b.id, title: b.title });
+          }
+        }
+        const said = applyEdit(dir, a);
+        if (p.stages.inventory.status === 'approved') p.stages.inventory = { status: 'review', note: 'edited by hand' };
+        addEvent(p, { kind: 'edit', stage: 'inventory', key: said.key, text: said.text, say: said.human });
+        break;
+      }
+      case 'inv-status': case 'inv-rest': case 'inv-must': case 'inv-field': case 'inv-add': {   // the inventory, by hand
+        const said = applyEdit(dir, a);
+        // an approved inventory that changes comes back for the user to confirm (and the plan made from it is old)
+        if (p.stages.inventory.status === 'approved') p.stages.inventory = { status: 'review', note: 'edited by hand' };
+        addEvent(p, { kind: 'edit', stage: 'inventory', key: said.key, text: said.text, say: said.human });   // `say`: the same, in the user's words, for the page
+        break;
+      }
       case 'what': {   // a part's description: a note for the agent, kept in chain.json
         const c = chain(), part = c.parts.find((x) => x.dir === a.part); if (!part) throw new Error('no such part');
         part.what = text(a.value); saveChain(c);
@@ -112,15 +300,18 @@ function act(cwd, piece, a, queue) {
       case 'text': {   // a word on screen: straight into the scene's CONFIG, then a fresh draft
         const f = path.join(dir, a.part, 'scene.html');
         fs.writeFileSync(f, setSceneText(fs.readFileSync(f, 'utf8'), a.key, text(a.value)));
-        p.parts[a.part] = { ...(p.parts[a.part] ?? {}), status: 'queued' };
+        redo(p, a.part);
         addEvent(p, { kind: 'edit', stage: 'parts', part: a.part, key: a.key, text: text(a.value), rerendered: true });
-        rerender = a.part;
         break;
       }
       case 'seconds':
       case 'join': {
         const c = chain(), part = c.parts.find((x) => x.dir === a.part); if (!part) throw new Error('no such part');
-        if (a.type === 'seconds') { part.seconds = Math.max(0.5, Math.min(30, Number(a.value))); rerender = a.part; p.parts[a.part] = { ...(p.parts[a.part] ?? {}), status: 'queued' }; }
+        if (a.type === 'seconds') {
+          const n = Number(a.value);
+          if (!String(a.value ?? '').trim() || !Number.isFinite(n)) throw new Error('give a length in seconds');
+          part.seconds = Math.max(0.5, Math.min(30, n)); redo(p, a.part);
+        }
         else { if (!(a.value in JOINS)) throw new Error('bad join'); part.join = a.value; }
         saveChain(c);
         addEvent(p, { kind: 'edit', stage: 'parts', part: a.part, key: a.type, text: String(a.type === 'seconds' ? part.seconds : part.join), rerendered: a.type === 'seconds' });
@@ -136,33 +327,106 @@ function act(cwd, piece, a, queue) {
       default: throw new Error(`unknown action ${a.type}`);
     }
   });
-  // in Assembly, a new order, length or join means the joined version is stale: hand it back to the agent
-  if (['order', 'seconds', 'join'].includes(a.type)) updatePiece(dir, (p) => {
-    if (p.stage !== 'assembly') return;
-    p.stages.assembly = { status: 'changes', note: 'edited by hand: join the parts again' };
-    p.events.at(-1).rejoin = true;
-  });
-  if (rerender) queue(piece, rerender);
+  // An edit by hand changes what the joined video shows. A draft that exists is joined again here, by the studio
+  // (no judgment needed, so no waiting for the agent). The full-quality final is the agent's: it goes back to it.
+  if (['text', 'order', 'seconds', 'join'].includes(a.type)) {
+    updatePiece(dir, (p) => {
+      const ev = p.events.at(-1);
+      if (film.draft) ev.rejoined = true;
+      if (p.stages.final.status !== 'pending') {   // the final was reached: it no longer shows the piece
+        p.stages.final = { status: 'changes', note: 'You edited the piece by hand, so the final needs a new render.', since: new Date().toISOString() };
+        ev.refinal = true;
+      }
+    });
+    joinErrors.delete(dir);
+  }
+  if (rerender) queue.part(piece, rerender, keep);
+  if (film.draft && ['text', 'order', 'seconds', 'join'].includes(a.type)) queue.join(piece);
   const p = readPiece(dir);
   return { ok: true, line: eventLine(p, p.events.at(-1)) };
 }
 
-/** One part at a time re-renders as a draft after an edit (the engine needs no agent for that). */
+// ── Your video: edits that need no judgment, made here; each reaches the agent as one line ──────────────────────
+async function actVideo(cwd, piece, a, log) {
+  const dir = pieceDir(piece, cwd), p = readPiece(dir); if (!p) throw new Error('no such piece');
+  let said;
+  if (a.type === 'undo') said = { say: `Undid ${undo(cwd, dir)}` };
+  else if (a.type === 'render') { renderFinal(cwd, piece, log); said = { say: 'Rendering the final' }; }
+  else if (a.type.startsWith('style-')) said = await editStyle(cwd, dir, { ...a, type: a.type.slice(6) });
+  else said = await editVideo(cwd, dir, { ...a, type: a.type.slice(2) }, SCENES, { ...p.brief, title: p.title });
+  updatePiece(dir, (q) => {
+    // an edit to a video already approved sends it back to the user, and a final made before it is out of date
+    if (a.type !== 'render') {
+      if (q.stages.video?.status === 'approved') q.stages.video = { status: 'review', note: 'edited by hand' };
+      if (q.stages.final?.status && q.stages.final.status !== 'pending') q.stages.final = { status: 'changes', note: 'You changed the video, so the final needs a new render.', since: new Date().toISOString() };
+    }
+    addEvent(q, { kind: 'edit', stage: 'video', key: a.type, text: said.say, say: said.say });
+  });
+  return { ok: true, ...said };
+}
+function buildFirst(cwd, piece, log) {
+  const dir = pieceDir(piece, cwd);
+  if (fs.existsSync(path.join(dir, 'chain.json')) || building.has(dir)) return;
+  building.add(dir);
+  const p = readPiece(dir);
+  editVideo(cwd, dir, { type: 'build' }, SCENES, { ...p.brief, title: p.title })
+    .then((r) => updatePiece(dir, (q) => { q.stage = 'video'; q.stages.video = { status: 'review', since: new Date().toISOString() }; addEvent(q, { kind: 'edit', stage: 'video', key: 'build', text: r.say, say: r.say }); }))
+    .catch((e) => { log(`✗ building ${piece}: ${e.message}`); joinErrors.set(dir, e.message.split('\n')[0]); })
+    .finally(() => building.delete(dir));
+}
+function renderFinal(cwd, piece, log) {
+  const dir = pieceDir(piece, cwd); if (rendering.has(dir)) return;
+  rendering.set(dir, { started: Date.now() });
+  import('./chain.mjs').then((c) => c.renderChain({ cwd, piece, motionBlur: 5, onStep: (e) => { if (e.part) rendering.set(dir, { started: rendering.get(dir)?.started, part: e.part, of: e.of }); else if (e.joining) rendering.set(dir, { started: rendering.get(dir)?.started, joining: true }); } }))
+    .then((r) => updatePiece(dir, (q) => { q.stage = 'final'; q.stages.final = { status: 'review', since: new Date().toISOString() }; addEvent(q, { kind: 'edit', stage: 'final', key: 'render', text: `rendered ${path.basename(r.out)}`, say: 'The final is ready' }); }))
+    .catch((e) => { log(`✗ final ${piece}: ${e.message}`); joinErrors.set(dir, e.message.split('\n')[0]); })
+    .finally(() => rendering.delete(dir));
+}
+
+/**
+ * The studio's own renders after an edit by hand, one at a time: parts first (each as a draft), then, once no part
+ * is left, the joined draft again with the sound it was made with. The engine needs no agent for either.
+ */
 function renderQueue(cwd, log) {
-  const q = [];
+  const parts = [], joins = new Set();
   let busy = false;
   const next = async () => {
-    if (busy || !q.length) return;
+    if (busy || (!parts.length && !joins.size)) return;
     busy = true;
-    const [piece, part] = q.shift();
-    try {
-      const { renderDrafts } = await import('./chain.mjs');
-      await renderDrafts({ cwd, piece, only: [part] });
-      log(`re-rendered ${piece}/${part}`);
-    } catch (e) { log(`✗ ${piece}/${part}: ${e.message}`); }
+    const chainLib = await import('./chain.mjs');
+    if (parts.length) {
+      const [piece, part, keep] = parts.shift(), dir = pieceDir(piece, cwd);
+      try {
+        await chainLib.renderDrafts({ cwd, piece, only: [part] });
+        if (keep) updatePiece(dir, (p) => { if (p.parts[part]?.status === 'review' && !p.parts[part].error) p.parts[part].status = 'approved'; });
+        log(`re-rendered ${piece}/${part}`);
+      } catch (e) { log(`✗ ${piece}/${part}: ${e.message}`); }
+    } else {
+      const piece = joins.values().next().value, dir = pieceDir(piece, cwd);
+      joins.delete(piece);
+      try {
+        // a join the agent already started covers this edit only if it began after it: wait for it, then look again
+        while (chainLib.readJob(dir)?.kind === 'assembly') await new Promise((r) => setTimeout(r, 1000));
+        const film = filmState(cwd, dir);
+        if (film.assemblyStale || !film.opts.sig) {
+          await chainLib.renderChain({ cwd, piece, draft: true, sfx: film.opts.sfx ?? true, audio: film.opts.audio });
+          log(`joined ${piece} again`);
+        }
+        joinErrors.delete(dir);
+      } catch (e) {
+        // the studio could not: say so on the page and hand the join to the agent
+        const why = String(e.message ?? e).split('\n')[0].slice(0, 240);
+        log(`✗ join ${piece}: ${why}`);
+        joinErrors.set(dir, why);
+        try { updatePiece(dir, (p) => { addEvent(p, { kind: 'failed', stage: 'assembly', text: why, rejoin: true }); }); } catch { /* the piece is gone */ }
+      }
+    }
     busy = false; next();
   };
-  return (piece, part) => { if (!q.some(([a, b]) => a === piece && b === part)) q.push([piece, part]); next(); };
+  return {
+    part: (piece, part, keep = false) => { if (!parts.some(([a, b]) => a === piece && b === part)) parts.push([piece, part, keep]); next(); },
+    join: (piece) => { joins.add(piece); next(); },
+  };
 }
 
 function sendFile(req, res, f) {
@@ -180,22 +444,72 @@ function sendFile(req, res, f) {
 
 export function startStudio({ cwd = process.cwd(), port = 4317, log = console.log } = {}) {
   const queue = renderQueue(cwd, log);
+  import('./registry.mjs').then((r) => r.getIndex()).then((i) => {   // offline: items show without their blocks
+    SCENES = scenesOf(i); TITLES = new Map((i.items ?? []).map((x) => [x.id, x.title]));
+    PALETTES = (i.items ?? []).filter((x) => x.type === 'palette').map((x) => ({ id: x.id, title: x.title, colors: x.colors ?? [] }));
+    FONTPAIRS = (i.items ?? []).filter((x) => x.type === 'font-pair').map((x) => ({ id: x.id, title: x.title }));
+    BACKGROUNDS = (i.items ?? []).filter((x) => x.type === 'background' && x.install?.entry?.shader && !x.install.entry.image).map((x) => ({ id: x.id, title: x.title, colors: x.colors ?? [], entry: { shader: x.install.entry.shader, props: x.install.entry.props, background: x.install.entry.background } }));
+  }).catch(() => {});
+  // the page's live previews (a block with the user's content, a background) play from a scene server on this project
+  import('./server.mjs').then((m) => m.startServer({ root: cwd })).then((sv) => { LIVE = `http://127.0.0.1:${sv.port}`; }).catch((e) => log(`live previews are off: ${e.message}`));
   const json = (res, code, body) => { res.writeHead(code, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }); res.end(JSON.stringify(body)); };
   const server = http.createServer(async (req, res) => {
     const u = new URL(req.url, 'http://x');
     try {
       if (u.pathname === '/' || u.pathname === '/index.html') { res.writeHead(200, { 'Content-Type': TYPES['.html'], 'Cache-Control': 'no-store' }); return res.end(fs.readFileSync(PAGE)); }
+      if (u.pathname.startsWith('/fonts/')) {   // the studio's own typefaces, served locally so it works offline
+        const f = path.join(path.dirname(PAGE), 'fonts', path.basename(u.pathname));
+        if (!fs.existsSync(f)) { res.writeHead(404); return res.end(); }
+        res.writeHead(200, { 'Content-Type': TYPES[path.extname(f)] ?? 'application/octet-stream', 'Cache-Control': 'max-age=86400' });
+        return res.end(fs.readFileSync(f));
+      }
       if (u.pathname === '/api/pieces') return json(res, 200, listPieces(cwd));
       if (u.pathname === '/api/info') return json(res, 200, { app: 'paper-motion-studio', cwd: path.resolve(cwd), pid: process.pid });
       if (u.pathname === '/api/piece') {
         const piece = u.searchParams.get('p');
         if (req.method === 'POST') {
           let body = ''; for await (const c of req) body += c;
-          try { return json(res, 200, act(cwd, piece, JSON.parse(body || '{}'), queue)); } catch (e) { return json(res, 400, { error: e.message }); }
+          try {
+            const a = JSON.parse(body || '{}');
+            if (/^(v-|style-)|^undo$|^render$/.test(a.type)) return json(res, 200, await actVideo(cwd, piece, a, log));
+            const r = act(cwd, piece, a, queue);
+            // keeping the content builds the first version of the video, by itself: the user lands on something to edit
+            if (a.type === 'approve' && a.stage === 'inventory') buildFirst(cwd, piece, log);
+            return json(res, 200, r);
+          } catch (e) { return json(res, 400, { error: e.message.split('\n')[0] }); }
         }
+        await refreshBoards(cwd, piece);
         const v = view(cwd, piece);
         return v ? json(res, 200, v) : json(res, 404, { error: `no piece "${piece}"` });
       }
+      if (u.pathname.startsWith('/previews/')) {   // the repo's own samples (see preview())
+        const f = path.join(LOCAL_PREVIEWS, path.basename(u.pathname));
+        if (!fs.existsSync(f)) { res.writeHead(404); return res.end(); }
+        return sendFile(req, res, f);
+      }
+      if (u.pathname === '/api/try' && req.method === 'POST') {   // a block playing live with one item's content
+        let body = ''; for await (const c of req) body += c;
+        try { const a = JSON.parse(body || '{}'); return json(res, 200, await tryScene(cwd, u.searchParams.get('p'), a.id, a.block)); } catch (e) { return json(res, 400, { error: e.message.split('\n')[0] }); }
+      }
+      if (u.pathname === '/api/background' && req.method === 'POST') {   // a library background into the brand, in its colours
+        let body = ''; for await (const c of req) body += c;
+        try {
+          const a = JSON.parse(body || '{}'), b = BACKGROUNDS.find((x) => x.id === a.id); if (!b) throw new Error('no such background');
+          const { add } = await import('./registry.mjs');
+          await add([b.id], { cwd, palette: 'brand' });
+          const dir = pieceDir(u.searchParams.get('p'), cwd);
+          updatePiece(dir, (p) => { addEvent(p, { kind: 'edit', stage: 'inventory', key: 'brand background', text: b.id, say: `Added a background to your brand: ${b.title}` }); });
+          return json(res, 200, { ok: true });
+        } catch (e) { return json(res, 400, { error: e.message.split('\n')[0] }); }
+      }
+      if (u.pathname === '/api/focus' && req.method === 'POST') {
+        // back to the agent: the app its CLI runs in, as recorded in piece.json by that CLI
+        const app = readPiece(pieceDir(u.searchParams.get('p') ?? '', cwd))?.agent?.path;
+        if (process.platform !== 'darwin' || !app || !app.endsWith('.app') || !fs.existsSync(app)) return json(res, 400, { error: 'no app to open' });
+        const { spawn } = await import('node:child_process');
+        spawn('open', ['-a', app], { detached: true, stdio: 'ignore' }).on('error', () => {}).unref();
+        return json(res, 200, { ok: true });
+      }
       if (u.pathname.startsWith('/files/')) {
         const f = path.resolve(cwd, decodeURIComponent(u.pathname.slice(7)));
         if (!f.startsWith(path.resolve(cwd) + path.sep) || !fs.existsSync(f) || fs.statSync(f).isDirectory()) { res.writeHead(404); return res.end(); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",

package/runtime/index.js

@@ -144,6 +144,13 @@ const imageCache = new Map();
 // A transparent pixel stands in for an image shader with no image (PaperTexture and Water also work standalone).
 const BLANK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
 
+// A scene shown inside another page (?embed: the studio's live previews) draws its shaders at the size it is shown,
+// not at the frame's full size times the screen's density (8 million pixels a frame on a Retina screen for a box
+// 700 px wide). Renders never pass ?embed, so they keep every pixel.
+const EMBED_PIXELS = typeof location !== 'undefined' && /[?&]embed(?:[=&]|$)/.test(location.search)
+  ? Math.max(480 * 270, Math.round(innerWidth * innerHeight * Math.max(1, globalThis.devicePixelRatio ?? 1) ** 2))
+  : null;
+
 class ShaderLayer {
   /**
    * @param el       element the canvas fills (give it a size: e.g. position:absolute; inset:0)
@@ -177,7 +184,7 @@ class ShaderLayer {
       { preserveDrawingBuffer: true, ...(props.webGlContextAttributes ?? {}) },
       0, this.frame0,
       this.options.minPixelRatio ?? 2,
-      this.options.maxPixelCount ?? 3840 * 2160 * 2,
+      this.options.maxPixelCount ?? EMBED_PIXELS ?? 3840 * 2160 * 2,
       props.mipmaps,
     );
     if (this.options.loop) {
@@ -220,6 +227,8 @@ class ShaderLayer {
 
   seek(t) {
     if (!this.a) return;
+    // embedded, a layer no one can see (a later shot waiting at opacity 0, display none) is not drawn this frame
+    if (EMBED_PIXELS && this.el.checkVisibility && !this.el.checkVisibility({ opacityProperty: true, visibilityProperty: true })) return;
     const time = this.time ?? (t + (this.options.timeOffset ?? 0));
     const ms = (s) => this.frame0 + s * 1000 * this.speed;
     const L = this.options.loop;

package/runtime/player.js

@@ -1,10 +1,15 @@
 // Preview player: real-time playback, scrubbing and frame stepping.
-// Only mounted in preview (never in renders).
+// Only mounted in preview (never in renders). With ?embed in the address it plays and loops with no controls,
+// for a scene shown inside another page (the studio's live previews).
 //   space play/pause · ←/→ one frame · shift+←/→ one second · home start · L loop · H hide UI
 
 export function mountPlayer(scene, startT = 0) {
   const { stage, duration, fps } = scene;
-  let t = startT, playing = true, loop = true, last = performance.now(), busy = false;
+  const q = new URLSearchParams(location.search), embed = q.has('embed');
+  // a part longer or shorter than its scene plays the whole scene slower or faster (the studio passes its rate)
+  const rate = Math.min(4, Math.max(0.25, Number(q.get('rate')) || 1));
+  // embedded, a scene plays once and holds its last frame (a click plays it again); on its own page it loops
+  let t = startT, playing = true, loop = !embed, last = performance.now(), busy = false;
 
   const bar = document.createElement('div');
   bar.innerHTML = `
@@ -25,10 +30,11 @@ export function mountPlayer(scene, startT = 0) {
   const range = bar.querySelector('input');
   const label = bar.querySelector('.pm-time');
   loopBtn.classList.toggle('on', loop);
+  if (embed) bar.style.display = 'none';
 
   function fit() {
     const avail = { w: innerWidth, h: innerHeight - (bar.style.display === 'none' ? 0 : 44) };
-    const s = Math.min(avail.w / scene.width, avail.h / scene.height, 1);
+    const s = Math.min(avail.w / scene.width, avail.h / scene.height, embed ? Infinity : 1);
     stage.style.transform = `translate(${(avail.w - scene.width * s) / 2}px, ${(avail.h - scene.height * s) / 2}px) scale(${s})`;
   }
   addEventListener('resize', fit); fit();
@@ -37,15 +43,20 @@ export function mountPlayer(scene, startT = 0) {
     t = Math.max(0, Math.min(duration, nt));
     range.value = t;
     label.textContent = `${t.toFixed(2)}s · f${String(Math.round(t * fps)).padStart(4, '0')} / ${Math.round(duration * fps)}`;
-    try { sessionStorage.setItem(`pm:t:${location.pathname}`, String(t)); } catch { /* storage blocked */ }
+    if (!embed) { try { sessionStorage.setItem(`pm:t:${location.pathname}`, String(t)); } catch { /* storage blocked */ } }
     busy = true; await scene.seek(t); busy = false;
   }
   function setPlaying(p) { playing = p; playBtn.textContent = p ? '❚❚' : '▶'; last = performance.now(); }
 
+  // embedded, it draws at most 30 frames a second: a preview beside an editor, not the render
+  const step = embed ? 1000 / 30 - 2 : 0;
+  let drawn = 0;
   function tick(now) {
+    if (embed && now - drawn < step) { requestAnimationFrame(tick); return; }
+    drawn = now;
     if (playing && !busy) {
-      let nt = t + (now - last) / 1000;
-      if (nt >= duration) { if (loop) nt %= duration; else { nt = duration; setPlaying(false); } }
+      let nt = t + ((now - last) / 1000) * rate;
+      if (nt >= duration) { if (loop) nt %= duration; else { nt = duration - 1 / fps; setPlaying(false); if (embed) { try { parent.postMessage({ pm: 'ended' }, '*'); } catch { /* no parent */ } } } }
       show(nt);
     }
     last = now;
@@ -54,6 +65,7 @@ export function mountPlayer(scene, startT = 0) {
   requestAnimationFrame(tick);
 
   playBtn.onclick = () => setPlaying(!playing);
+  if (embed) addEventListener('click', () => { if (!playing) show(0); setPlaying(true); });
   loopBtn.onclick = () => { loop = !loop; loopBtn.classList.toggle('on', loop); };
   range.oninput = () => { setPlaying(false); show(Number(range.value)); };
   addEventListener('keydown', (e) => {