paper-motion 0.3.0 → 0.4.1

package/lib/piece.mjs

@@ -1,17 +1,22 @@
 // A piece's progress: pieces/<piece>/piece.json, shared by the agent (CLI) and the user (pamo studio).
 //
-//   stage      the stage the piece is at: brief → look → structure → parts → assembly → final
+//   stage      the stage the piece is at: brief → inventory → video → final. The user sees three steps (What it says,
+//              Your video, Export); the brief is settled in the chat.
 //   stages     each stage's status: pending · working (the agent's turn) · review (the user's turn) · changes · approved
 //   brief      what, who, format, tone, action: written by the agent, editable by the user
 //   parts      per part (by its folder in chain.json): status (queued · rendering · review · changes · approved), note
 //   events     what the user did in the studio, in order; `seen` is the last one the agent has read
+//   ask        a question the agent asked in the chat and is waiting on (the studio sends the user there)
+//   agent      the app or page the agent runs in, so the studio can take the user back to it
 //
 // chain.json stays the source of what plays (order, seconds, joins); piece.json only tracks decisions.
 import fs from 'node:fs';
 import path from 'node:path';
 import { pieceDir } from './chain.mjs';
 
-export const STAGES = ['brief', 'look', 'structure', 'parts', 'assembly', 'final'];
+export const STAGES = ['brief', 'inventory', 'video', 'final'];
+// the stages a piece had before Your video took them over: a piece at one of them is at `video` now
+const OLD_VIDEO = ['look', 'structure', 'parts', 'assembly'];
 export const STAGE_STATUS = ['pending', 'working', 'review', 'changes', 'approved'];
 export const BRIEF_KEYS = ['what', 'who', 'format', 'tone', 'action'];
 
@@ -19,7 +24,19 @@ const now = () => new Date().toISOString();
 const file = (dir) => path.join(dir, 'piece.json');
 
 export function readPiece(dir) {
-  try { return JSON.parse(fs.readFileSync(file(dir), 'utf8')); } catch { return null; }
+  try { return upgrade(JSON.parse(fs.readFileSync(file(dir), 'utf8'))); } catch { return null; }
+}
+// a piece started before a stage existed: that stage counts as done when the piece is already past it
+function upgrade(p) {
+  if (!p.stages.video) {
+    const at = OLD_VIDEO.indexOf(p.stage), last = OLD_VIDEO.findLast((s) => p.stages[s]);
+    p.stages.video = at >= 0 ? { ...p.stages[p.stage] } : last && p.stages[last].status === 'approved' && STAGES.indexOf(p.stage) > 0 ? { status: 'approved' } : undefined;
+    if (at >= 0) p.stage = 'video';
+    for (const s of OLD_VIDEO) delete p.stages[s];
+    if (!p.stages.video) delete p.stages.video;
+  }
+  for (const s of STAGES) p.stages[s] ??= STAGES.indexOf(p.stage) > STAGES.indexOf(s) ? { status: 'approved', skipped: true } : { status: 'pending' };
+  return p;
 }
 
 /** Writes atomically (the studio and the CLI both write it). */
@@ -63,8 +80,10 @@ export function eventLine(p, e) {
     : e.kind === 'changes' ? `changes: "${e.text}"`
     : e.kind === 'order' ? `order ${e.text}`
     : e.kind === 'reopen' ? 'reopened'
-    : `${e.key}="${e.text}"${e.rerendered ? ' (re-rendered)' : ''}`;
-  const tail = e.rejoin ? ' · join again: pamo chain --draft' : '';
+    : e.kind === 'failed' ? `could not join the parts: "${e.text}"`
+    : e.say ? e.say : `${e.key}="${e.text}"${e.rerendered ? ' (re-rendered)' : ''}`;
+  // the studio joins the draft again by itself after an edit by hand; the full-quality render stays the agent's
+  const tail = `${e.rejoined ? ' (the studio is joining the draft again)' : ''}${e.rejoin ? ' · join again: pamo chain --draft' : ''}${e.refinal ? ` · the final is out of date: render it again (pamo chain ${p.piece} --motion-blur 5), then review final` : ''}`;
   return `paper-motion: piece ${p.piece} · ${e.kind === 'order' ? '' : `${who} `}${what}${tail}`.replace(/ {2,}/g, ' ');
 }
 
@@ -77,15 +96,23 @@ export function addEvent(p, e) {
 }
 
 /** The agent hands a stage to the user: it becomes the current stage, in review. */
-export function toReview(dir, stage) {
+export function toReview(dir, stage, { skip = false } = {}) {
   if (!STAGES.includes(stage)) throw new Error(`stage "${stage}": use ${STAGES.join(', ')}`);
   return updatePiece(dir, (p) => {
+    // nothing moves on until the user approves: an earlier stage they have not approved stops the hand-over,
+    // unless the agent says outright that it is skipping it (`skip`), which marks it approved
+    const open = earlierOpen(p, stage);
+    if (open.length && !skip) throw new Error(`${open.join(', ')} not approved yet: review ${open.length > 1 ? 'them' : 'it'} first (piece review ${p.piece} ${open[0]}), or pass --skip when the user agreed to move on without ${open.length > 1 ? 'them' : 'it'}`);
+    for (const s of open) p.stages[s] = { ...p.stages[s], status: 'approved' };
+    delete p.ask;   // handing a stage over means the question in the chat is settled
     p.stage = stage;
     p.stages[stage] = { status: 'review', since: now() };
-    for (const s of STAGES.slice(0, STAGES.indexOf(stage))) if (p.stages[s].status !== 'approved') p.stages[s] = { ...p.stages[s], status: 'approved' };
   });
 }
 
+/** The stages before `stage` that the user has not approved. */
+export const earlierOpen = (p, stage) => STAGES.slice(0, STAGES.indexOf(stage)).filter((s) => p.stages[s].status !== 'approved');
+
 /** Events the agent hasn't read; marks them read when `mark`. */
 export function unseen(dir, { mark = true } = {}) {
   let out = [];
@@ -94,7 +121,7 @@ export function unseen(dir, { mark = true } = {}) {
 }
 
 // an event that ends the agent's wait: a decision on the stage under review, or a change asked anywhere
-const decisive = (e, stage) => (e.kind === 'approve' && e.stage === stage && !e.part) || e.kind === 'changes' || e.kind === 'reopen' || e.rejoin;
+const decisive = (e, stage) => (e.kind === 'approve' && e.stage === stage && !e.part) || e.kind === 'changes' || e.kind === 'reopen' || e.rejoin || e.refinal;
 
 /**
  * Waits until the user decides on `stage` in the studio (approves it, or asks for changes), then returns every
@@ -102,16 +129,39 @@ const decisive = (e, stage) => (e.kind === 'approve' && e.stage === stage && !e.
  */
 export async function awaitDecision(dir, stage, { timeout = 30 * 60 * 1000, every = 1000, signal } = {}) {
   const t0 = Date.now();
-  for (;;) {
-    const p = readPiece(dir);
-    const fresh = p.events.filter((e) => e.n > (p.seen ?? 0));
-    if (fresh.some((e) => decisive(e, stage))) {
-      const r = unseen(dir);
-      return { done: true, piece: r.piece, events: r.events, lines: r.events.map((e) => eventLine(r.piece, e)) };
+  let last = 0;
+  try {
+    for (;;) {
+      if (Date.now() - last > 3000) { beat(dir, { waiting: stage }); last = Date.now(); }   // the studio shows "your agent is listening"
+      const p = readPiece(dir);
+      const fresh = p.events.filter((e) => e.n > (p.seen ?? 0));
+      if (fresh.some((e) => decisive(e, stage))) {
+        const r = unseen(dir);
+        return { done: true, piece: r.piece, events: r.events, lines: r.events.map((e) => eventLine(r.piece, e)) };
+      }
+      if (Date.now() - t0 > timeout || signal?.aborted) return { done: false, piece: p, events: fresh, lines: fresh.map((e) => eventLine(p, e)) };
+      await new Promise((res) => setTimeout(res, every));
     }
-    if (Date.now() - t0 > timeout || signal?.aborted) return { done: false, piece: p, events: fresh, lines: fresh.map((e) => eventLine(p, e)) };
-    await new Promise((res) => setTimeout(res, every));
-  }
+  } finally { unbeat(dir); }
+}
+
+// ── the agent's side of the conversation: is it listening, what did it ask, where does it live ────────────────
+// While a command waits for the user (piece review, board), it says so every few seconds in a small file beside
+// piece.json (piece.json itself stays quiet). No fresh beat means nobody reads what the user does in the studio.
+const beatFile = (dir) => path.join(dir, '.agent.json');
+export function beat(dir, info = {}) { try { fs.writeFileSync(beatFile(dir), JSON.stringify({ at: Date.now(), pid: process.pid, ...info })); } catch { /* a read-only project: the studio just won't know */ } }
+export function unbeat(dir) { try { if (JSON.parse(fs.readFileSync(beatFile(dir), 'utf8')).pid === process.pid) fs.rmSync(beatFile(dir)); } catch { /* already gone */ } }
+/** The command waiting on this piece right now, if any. */
+export function listening(dir, within = 9000) { try { const a = JSON.parse(fs.readFileSync(beatFile(dir), 'utf8')); return Date.now() - a.at < within ? a : null; } catch { return null; } }
+
+/** The agent asked the user something in the chat: the studio says so until the agent moves on. */
+export function setAsk(dir, text) { return updatePiece(dir, (p) => { p.ask = { text: String(text ?? '').trim(), at: now() }; }); }
+export function clearAsk(dir) { const p = readPiece(dir); return p?.ask ? updatePiece(dir, (q) => { delete q.ask; }) : p; }
+/** Where the agent runs (see host.mjs), kept so the studio can take the user back there. */
+export function setHost(dir, host) {
+  const p = readPiece(dir);
+  if (!p || !host || JSON.stringify(p.agent ?? null) === JSON.stringify(host)) return p;
+  return updatePiece(dir, (q) => { q.agent = host; });
 }
 
 // ── the words on screen: a scene's top-level string CONFIG entries ──────────────────────────
@@ -145,3 +195,29 @@ export function setSceneText(html, key, value) {
   if (!hit) throw new Error(`CONFIG has no text "${key}"`);
   return head + next + tail;
 }
+
+// ── boards: the decisions taken on paper-motion.app, listed in the studio so the user finds them there too ──────
+const BOARD_STAGE = () => 'video';
+
+/** The piece a board belongs to: the one named, else the only one in progress before Parts. */
+export function activePiece(cwd, name) {
+  if (name) { const dir = pieceDir(name, cwd); return readPiece(dir) ? dir : null; }
+  const root = path.join(cwd, 'pieces');
+  if (!fs.existsSync(root)) return null;
+  const live = fs.readdirSync(root).map((d) => path.join(root, d)).filter((d) => { const p = readPiece(d); return p && ['brief', 'inventory', 'video'].includes(p.stage); });
+  return live.length === 1 ? live[0] : null;
+}
+
+/** Records a board shared for this piece (shown in the studio's Look or Structure stage until chosen). */
+export function attachBoard(dir, { url, id, title, kind }) {
+  return updatePiece(dir, (p) => {
+    p.boards ??= [];
+    if (id && p.boards.some((b) => b.id === id)) return;
+    p.boards.push({ url, id: id ?? null, title, kind, stage: BOARD_STAGE(p.stage), at: now(), status: 'waiting' });
+  });
+}
+
+/** Marks a board chosen with the reply line. */
+export function markBoard(dir, id, line) {
+  return updatePiece(dir, (p) => { const b = (p.boards ?? []).find((x) => x.id === id); if (b) { b.status = 'chosen'; b.line = line; } });
+}

package/lib/registry.mjs

@@ -110,12 +110,12 @@ export function llmsTxt(items, site, { full = false } = {}) {
 ## The flow (for agents)
 
 1. **Set up.** \`npx skills add solanodz/paper-motion\` (the skills) and \`npx paper-motion setup\` (the engine: Node 18+,
-   ffmpeg, Chrome). The CLI is \`npx paper-motion\` (short: \`pamo\`). Every command answers \`--help\`. Agents load
+   ffmpeg, Chrome). The CLI is \`npx paper-motion\`; where these docs write \`pamo\`, type \`npx paper-motion\` (the npm package named \`pamo\` is unrelated). \`npx paper-motion --version\` prints the version. Every command answers \`--help\`. Agents load
    skills and MCP servers when a session starts, so after installing the skills **read
    \`.claude/skills/make-video/SKILL.md\` now** (or \`.agents/skills/make-video/SKILL.md\`) and follow it in this
    session; tell the user that the MCP at ${site}/mcp, if they want it, is added before opening a session.
 2. **Open the studio: it is where the user decides.** A video is made in stages the user watches and approves in
-   a local page: brief, look, structure, parts, assembly, final. Start the piece right after setup:
+   a local page in three steps (What it says: brief and inventory; Your video; Export). Start the piece right after setup:
    \`npx paper-motion piece init <piece> --title "…"\` (it starts the project's studio in the background). Then,
    at the end of each stage, \`npx paper-motion piece review <piece> <stage>\`: the first time it opens the studio in
    the user's browser; it waits for their decision and prints what they did, one \`paper-motion: piece …\` line each
@@ -151,7 +151,8 @@ export function llmsTxt(items, site, { full = false } = {}) {
    the user re-chooses or re-tunes something you installed before, pass \`--force\`. A recipe also reads
    \`brand/motion.json\` (pace) and \`brand/sound.json\` (cues; without it the piece is silent) and the brand's name
    from \`tokens.json\` \`brand\`: write those from the interview before rendering.
-6. **Make the video.** Every move the user chose appears in the piece, and the brief says where each one plays;
+6. **Make the video.** Every move the user chose appears in the piece, and the brief says where each one plays
+   (a chosen transition may be the join between two parts of a chain: \`"join": "wipe"\` in chain.json takes its id);
    a recipe's own moves are placeholders to swap for theirs. Build \`scene.html\` (a pure function of time), check stills with \`pamo still\`, render with
    \`pamo render scene.html --motion-blur 5\`. The test shot and the final piece are real renders, not boards.
    When the user chose a structure whose beats name blocks or shots (or several blocks in order), chain them instead:
@@ -159,8 +160,13 @@ export function llmsTxt(items, site, { full = false } = {}) {
    \`pieces/<piece>/<nn>-<id>/\` and writes \`chain.json\` (seconds per part; \`join\`: whip, cut, dissolve or dip);
    write each part's \`CONFIG\` from its beat, then \`npx paper-motion chain <piece> --motion-blur 5\` renders every
    part in the brand's look and joins them into one video. It warns when a part is cut before its land.
-   In the studio: review \`look\` after installing the choices, \`structure\` after \`chain init\`, \`parts\` after
-   \`chain --drafts\`, \`assembly\` after \`chain --draft\`, \`final\` after the full render.
+   In the studio the stages are brief, inventory, video and final. When the user approves the inventory the studio
+   builds the video itself from what they kept, and then they edit it there, live (words, how each part arrives,
+   backgrounds, settings, lengths, transitions, order, adding and swapping parts, colours, type, pace); every edit
+   reaches you as a line. Review \`video\` to wait for their approval; they can render the final from the studio. \`chain --check\` warns when the total drifts from the brief's
+   length. Boards you share while a piece is open also appear in its studio (Look or Structure), so the user finds them
+   there; if your shell caps how long a command may run, share with \`--no-wait\` and then
+   \`npx paper-motion board --await <id> --wait 2\` until it prints the line (exit code 3 = not yet).
 
 ## Choosing well: the metadata
 
@@ -169,6 +175,16 @@ ${site}/registry.json is the index; every item carries, beside id, type, title,
 - \`when\`: 2–3 "use it when…" phrases.
 - \`mood\`: calm, bold, playful, technical, editorial, warm, minimal, luxury, raw.
 - Moves: \`energy\` 1 (still) to 5 (violent) and \`role\` (enter, exit, swap, emphasis, camera, text).
+- Blocks and shots: \`needs\`, the content each one shows by kind (a \`figure\`, a \`change\`, a \`screen\`, a \`command\`, a
+  \`line\`…). Choose them by what the user has to show, not by mood. Gather \`pieces/<piece>/inventory.json\` with
+  \`npx paper-motion inventory <piece> --from <their site> --from README.md --from brand\` (it reads the page and
+  screenshots it, a markdown file, a folder, or the brand's Facts and assets, and writes proposals, each with its
+  source; \`npx paper-motion inventory kinds\` lists the kinds and their fields). Complete what a proposal still
+  needs (a command's real output), add what gathering cannot see, and hand it over:
+  \`npx paper-motion piece review <piece> inventory\`. The user keeps or removes each proposal in the studio; only
+  what they kept is used. Then let \`npx paper-motion plan <piece> --seconds <n>\` propose
+  the structures: it prints the structure board to share, and \`chain init <piece> --plan <letter>\` installs the
+  chosen one with the content already in every part's CONFIG.
 - Backgrounds and palettes: \`colors\` (dominant hex) and \`mode\` (light, dark); backgrounds also \`motion\` (still, gentle, lively).
   **Every background is a color family**: a board with a \`look.palette\` shows each background recolored into that
   palette (each of its colors keeps its tone and takes the nearest palette hue, so a dark one stays dark), and the
@@ -279,7 +295,7 @@ export function build({ dir = resolveRegistry().dir, out, site = SITE } = {}) {
   for (const it of items) if (it.preview) { const have = Object.fromEntries(Object.entries(it.preview).filter(([, p]) => typeof p !== 'string' || fs.existsSync(path.join(out, p)))); it.preview = Object.values(have).some((p) => typeof p === 'string') ? have : undefined; }
   const index = {
     name: 'paper-motion', site, schema: `${site}/schema.json`, count: items.length, types: TYPES.filter((t) => items.some((i) => i.type === t)),
-    items: items.map(({ id, type, title, summary, tags, version, preview, related, when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, params }) => ({ id, type, title, summary, tags, version, url: `${site}/r/${id}.json`, ...Object.fromEntries(Object.entries({ when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, preview, related, params: params?.filter((p) => !p.hidden).map((p) => p.name) }).filter(([, v]) => v !== undefined)) })),
+    items: items.map(({ id, type, title, summary, tags, version, preview, related, when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, needs, repeat, params }) => ({ id, type, title, summary, tags, version, url: `${site}/r/${id}.json`, ...Object.fromEntries(Object.entries({ when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, needs, repeat, preview, related, params: params?.filter((p) => !p.hidden).map((p) => p.name) }).filter(([, v]) => v !== undefined)) })),
   };
   fs.writeFileSync(path.join(out, 'registry.json'), JSON.stringify(index, null, 2));
   fs.mkdirSync(path.join(out, 'files'), { recursive: true });

package/lib/render.mjs

@@ -94,12 +94,13 @@ export async function renderSfx({ url, out, from = 0, to }) {
   } finally { await browser.close(); }
 }
 
-async function sfxFromPage(s, { from = 0, to, out, normalize = true }) {
+async function sfxFromPage(s, { from = 0, to, rate = 1, length, out, normalize = true }) {
   const { cues, audio } = await s.page.evaluate(() => ({ cues: window.__pm.cues ?? [], audio: window.__pm.audio ?? {} }));
   if (!cues.length) return null;
   const end = to ?? s.config.duration;
-  const shifted = cues.filter((c) => c.t < end).map((c) => ({ ...c, t: c.t - from }));
-  writeWav(out, synthesize(shifted, { duration: end - from, ...audio, normalize }));
+  // a faster or slower part moves its hits with the picture; each sound keeps its own pitch and length
+  const shifted = cues.filter((c) => c.t < end).map((c) => ({ ...c, t: (c.t - from) / rate }));
+  writeWav(out, synthesize(shifted, { duration: length ?? (end - from) / rate, ...audio, normalize }));
   return { out, cues: cues.length };
 }
 
@@ -110,7 +111,7 @@ function subframes(f, fps, k, shutter, duration) {
   return Array.from({ length: k }, (_, j) => Math.min(duration - 1e-4, Math.max(0, (f + ((j + 0.5) / k - 0.5) * open) / fps)));
 }
 
-export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1, from, to, fps: fpsOverride, crf, audio, sfx = true, motionBlur = 1, shutter = 180, gifWidth = 720, gifFps = 24, onProgress }) {
+export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1, from, to, rate = 1, seconds, fps: fpsOverride, crf, audio, sfx = true, motionBlur = 1, shutter = 180, gifWidth = 720, gifFps = 24, onProgress }) {
   const fmt = FORMATS[format];
   if (!fmt) throw new Error(`Unknown format "${format}". Use one of: ${Object.keys(FORMATS).join(', ')}`);
   const browser = await launch();
@@ -120,9 +121,12 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
     const first = await openScene(browser, url, { dpr });
     const cfg = first.config;
     const fps = fpsOverride ?? cfg.fps;
+    // the scene's window [from, to], played at `rate` (scene seconds per second of video): 2 plays it twice as fast.
+    // `seconds` sets the video's length; past the window's end the last frame holds (under an overlapping join)
     const f0 = Math.round((from ?? 0) * fps);
     const f1 = Math.round((to ?? cfg.duration) * fps);
-    const total = f1 - f0;
+    const total = seconds !== undefined ? Math.round(seconds * fps) : Math.round((f1 - f0) / rate);
+    const sceneT = (st) => Math.min(f1 / fps - 1e-4, f0 / fps + st * rate);   // a time in the video → in the scene
     if (total <= 0) throw new Error('Nothing to render (check --from/--to).');
     const n = Math.max(1, Math.min(workers ?? Math.min(4, Math.max(1, Math.floor(os.cpus().length / 2))), Math.ceil(total / 15)));
     const chunk = Math.ceil(total / n);
@@ -131,7 +135,7 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
 
     let sfxWav = null;
     if (sfx && !fmt.gif && !fmt.seq) {
-      const r = await sfxFromPage(first, { from: f0 / fps, to: f1 / fps, out: path.join(tmp, 'sfx.wav'), normalize: !audio }); // with an external track, effects keep their own gains
+      const r = await sfxFromPage(first, { from: f0 / fps, to: f1 / fps, rate, length: total / fps, out: path.join(tmp, 'sfx.wav'), normalize: !audio }); // with an external track, effects keep their own gains
       sfxWav = r?.out ?? null;
     }
 
@@ -139,7 +143,7 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
     for (let i = 1; i < n; i++) sessions.push(await openScene(browser, url, { dpr }));
 
     const segments = await Promise.all(sessions.map(async (s, i) => {
-      const a = f0 + i * chunk, b = Math.min(f1, a + chunk);
+      const a = i * chunk, b = Math.min(total, a + chunk);
       if (a >= b) return null;
       const seg = path.join(tmp, `seg${String(i).padStart(3, '0')}.mkv`);
       // Lossless RGB intermediate; the final encode happens once, after concat.
@@ -148,8 +152,8 @@ export async function renderVideo({ url, out, format = 'mp4', workers, dpr = 1,
       const blur = k > 1 ? ['-vf', `tmix=frames=${k},select='eq(mod(n\\,${k})\\,${k - 1})',setpts=N/(${fps}*TB)`, '-r', String(fps)] : [];
       const p = ffmpeg(['-f', 'image2pipe', '-framerate', String(fps * k), '-c:v', 'png', '-i', '-', ...blur, '-c:v', 'libx264rgb', '-preset', 'ultrafast', '-crf', '0', seg], { stdin: true });
       for (let f = a; f < b; f++) {
-        for (const tt of subframes(f, fps, k, shutter, cfg.duration)) {
-          await s.seek(tt);
+        for (const st of subframes(f, fps, k, shutter, Infinity)) {
+          await s.seek(sceneT(st));
           await write(p, await s.capture());
         }
         done++; tick();