paper-motion 0.4.0 → 0.5.0

package/lib/piece.mjs

@@ -1,12 +1,17 @@
 // 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 → inventory → video → final. The user sees three steps (What it says,
-//              Your video, Export); the brief is settled in the chat.
+//   stage      the stage the piece is at: brief → inventory → look → video → final. The user sees four steps (What
+//              you want to say: the brief and the inventory; How it looks; Your video; Export).
 //   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)
+//   events     what the user did in the studio, in order; `seen` is the last one the agent has read, and each
+//              event the agent read carries `readAt`
+//   ask        a question the agent asked and is waiting on; the user answers it in the studio (an `answer` event)
+//   working    what the agent said it is doing (`piece working --on`) and since when; it lapses after 20 minutes
+//   notes      the agent's short replies to the user, shown in the studio's thread (`piece say`)
+//   choices    options the agent put into the studio (`pamo board` while a piece is open), where they show, and
+//              the reply line once the user chose (ADR 0005)
 //   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.
@@ -14,7 +19,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pieceDir } from './chain.mjs';
 
-export const STAGES = ['brief', 'inventory', 'video', 'final'];
+export const STAGES = ['brief', 'inventory', 'look', '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'];
@@ -39,6 +44,13 @@ function upgrade(p) {
   return p;
 }
 
+/** A project whose brand already settles colours, type and a background: How it looks starts done. */
+export function brandSettled(cwd) {
+  const read = (f) => { try { return JSON.parse(fs.readFileSync(path.join(cwd, f), 'utf8')); } catch { return {}; } };
+  const t = read('brand/tokens.json'), set = read('brand/shader-set/set.json');
+  return !!(t.colors?.ground && t.colors?.figure && t.fonts?.display && (Array.isArray(set) ? set : set.entries ?? []).some((e) => e.shader && !e.image));
+}
+
 /** Writes atomically (the studio and the CLI both write it). */
 export function writePiece(dir, p) {
   fs.mkdirSync(dir, { recursive: true });
@@ -67,7 +79,7 @@ export function initPiece({ cwd = process.cwd(), piece, title, brief = {}, force
   return writePiece(dir, {
     v: 1, piece: path.basename(dir), title: title ?? path.basename(dir), brand: tokens.brand ?? null,
     stage: 'brief',
-    stages: Object.fromEntries(STAGES.map((s, i) => [s, { status: i ? 'pending' : 'working' }])),
+    stages: Object.fromEntries(STAGES.map((s, i) => [s, s === 'look' && brandSettled(cwd) ? { status: 'approved', brand: true } : { status: i ? 'pending' : 'working' }])),
     brief: Object.fromEntries(BRIEF_KEYS.map((k) => [k, brief[k] ?? ''])),
     parts: {}, events: [], seen: 0, created: now(), updated: now(),
   });
@@ -75,12 +87,14 @@ export function initPiece({ cwd = process.cwd(), piece, title, brief = {}, force
 
 /** The line the agent reads for an event (same family as the board reply). */
 export function eventLine(p, e) {
-  const who = e.part ? `part ${e.part}` : e.stage;
+  const who = e.part ? `part ${e.part}` : e.stage ?? '';
   const what = e.kind === 'approve' ? 'approved'
     : e.kind === 'changes' ? `changes: "${e.text}"`
     : e.kind === 'order' ? `order ${e.text}`
     : e.kind === 'reopen' ? 'reopened'
     : e.kind === 'failed' ? `could not join the parts: "${e.text}"`
+    : e.kind === 'answer' ? `answered${e.q ? ` "${e.q}"` : ''}: "${e.text}"`
+    : e.kind === 'choice' ? `chose${e.title ? ` on "${e.title}"` : ''}: ${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` : ''}`;
@@ -105,6 +119,7 @@ export function toReview(dir, stage, { skip = false } = {}) {
     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
+    delete p.working;
     p.stage = stage;
     p.stages[stage] = { status: 'review', since: now() };
   });
@@ -116,10 +131,55 @@ export const earlierOpen = (p, stage) => STAGES.slice(0, STAGES.indexOf(stage)).
 /** Events the agent hasn't read; marks them read when `mark`. */
 export function unseen(dir, { mark = true } = {}) {
   let out = [];
-  const p = updatePiece(dir, (q) => { out = q.events.filter((e) => e.n > (q.seen ?? 0)); if (mark && out.length) q.seen = out.at(-1).n; });
+  const p = updatePiece(dir, (q) => {
+    out = q.events.filter((e) => e.n > (q.seen ?? 0));
+    if (mark && out.length) { const at = now(); for (const e of out) e.readAt = at; q.seen = out.at(-1).n; }
+  });
   return { piece: p, events: out };
 }
 
+// what the user does that needs the agent: something asked, answered, approved, reopened, chosen, or a join that failed
+const needsAgent = (e) => ['changes', 'answer', 'reopen', 'choice', 'failed'].includes(e.kind) || (e.kind === 'approve' && !e.part) || e.rejoin || e.refinal;
+
+/**
+ * Listens on the piece between the agent's turns (`pamo piece listen`): returns as soon as the user does something
+ * that needs the agent, with every unread event as lines (and marks them read), or after `timeout` with nothing.
+ * While it listens the studio says so; it is the agent's way to hear the studio without the user going to the chat.
+ */
+export async function listenFor(dir, { timeout = 9 * 60 * 1000, every = 1000, signal } = {}) {
+  const t0 = Date.now();
+  let last = 0;
+  updatePiece(dir, (p) => { delete p.working; });   // listening means it is not doing anything else
+  // interrupted (the agent cancels it, Ctrl+C): stop saying it listens right away
+  const stop = () => { unbeat(dir); process.exit(130); };
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    for (;;) {
+      if (Date.now() - last > 3000) { beat(dir, { waiting: 'listen' }); last = Date.now(); }
+      const p = readPiece(dir);
+      const fresh = p.events.filter((e) => e.n > (p.seen ?? 0));
+      if (fresh.some(needsAgent)) { 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: [], lines: [] };
+      await new Promise((res) => setTimeout(res, every));
+    }
+  } finally { unbeat(dir); process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+
+const WORKING_FOR = 20 * 60 * 1000;
+/** The agent says what it is doing; the studio shows it, with how long, until it listens, reviews or 20 minutes pass. */
+export function setWorking(dir, on) { return updatePiece(dir, (p) => { delete p.ask; p.working = { on: String(on ?? '').trim() || null, at: now() }; }); }
+/** A short reply from the agent to the user, shown in the studio's thread. */
+export function addNote(dir, text) { return updatePiece(dir, (p) => { (p.notes ??= []).push({ at: now(), text: String(text).trim() }); }); }
+
+/**
+ * What the studio may say about the agent, only from facts: `ask` (a question is open), `listen` (a command of the
+ * agent is waiting on this piece right now), `work` (it said what it is doing, less than 20 minutes ago) or `off`.
+ */
+export function agentState(dir, p = readPiece(dir)) {
+  const l = listening(dir), w = p?.working && Date.now() - Date.parse(p.working.at) < WORKING_FOR ? p.working : null;
+  return { state: p?.ask ? 'ask' : l ? 'listen' : w ? 'work' : 'off', listening: !!l, working: w };
+}
+
 // 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 || e.refinal;
 
@@ -152,7 +212,15 @@ 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; } }
+export function listening(dir, within = 9000) {
+  try {
+    const a = JSON.parse(fs.readFileSync(beatFile(dir), 'utf8'));
+    if (Date.now() - a.at >= within) return null;
+    // a command that was killed leaves its last beat behind: it only counts while its process is alive
+    if (a.pid) { try { process.kill(a.pid, 0); } catch (e) { if (e.code === 'ESRCH') return null; } }
+    return a;
+  } 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() }; }); }
@@ -196,6 +264,49 @@ export function setSceneText(html, key, value) {
   return head + next + tail;
 }
 
+// ── choices: a board shown inside the studio instead of a link (ADR 0005) ─────────────────────────────────────
+/** Puts a board into the piece, on the step and section it decides. Returns its id (`c1`, `c2`…). */
+export function addChoice(dir, { board, where }) {
+  let id;
+  updatePiece(dir, (p) => {
+    p.choices ??= [];
+    id = `c${p.choices.length + 1}`;
+    p.choices.push({ id, board, where, status: 'waiting', at: now() });
+  });
+  return id;
+}
+/** The user's pick on a choice: records the reply line and an event the agent reads. */
+export function settleChoice(p, id, line) {
+  const c = (p.choices ?? []).find((x) => x.id === id);
+  if (!c) throw new Error('no such choice');
+  if (c.status !== 'waiting') throw new Error('already chosen');
+  c.status = 'chosen'; c.line = line; c.chosenAt = now();
+  addEvent(p, { kind: 'choice', stage: c.where?.step ?? p.stage, text: line, title: c.board.title, choice: id });
+  return c;
+}
+/** Waits for the user's pick on a studio choice, beating as listening; returns the reply line, or null on timeout. */
+export async function awaitChoiceIn(dir, id, { timeout = 10 * 60 * 1000, every = 1000 } = {}) {
+  const t0 = Date.now(); let last = 0;
+  const stop = () => { unbeat(dir); process.exit(130); };
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    for (;;) {
+      if (Date.now() - last > 3000) { beat(dir, { waiting: 'board' }); last = Date.now(); }
+      const c = (readPiece(dir)?.choices ?? []).find((x) => x.id === id);
+      if (!c) return null;
+      if (c.status === 'chosen') {
+        // the agent has the pick from here: the event that carries it counts as read
+        updatePiece(dir, (p) => { const at = now(); for (const e of p.events) if (e.kind === 'choice' && e.choice === id && !e.readAt) { e.readAt = at; if (e.n === (p.seen ?? 0) + 1) p.seen = e.n; } });
+        return c.line;
+      }
+      if (Date.now() - t0 > timeout) return null;
+      await new Promise((res) => setTimeout(res, every));
+    }
+  } finally { unbeat(dir); process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+/** Takes a choice back out of the studio. */
+export function forgetChoice(dir, id) { return updatePiece(dir, (p) => { p.choices = (p.choices ?? []).filter((x) => x.id !== id); }); }
+
 // ── boards: the decisions taken on paper-motion.app, listed in the studio so the user finds them there too ──────
 const BOARD_STAGE = () => 'video';
 
@@ -204,7 +315,7 @@ 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); });
+  const live = fs.readdirSync(root).map((d) => path.join(root, d)).filter((d) => { const p = readPiece(d); return p && ['brief', 'inventory', 'look', 'video'].includes(p.stage); });
   return live.length === 1 ? live[0] : null;
 }
 

package/lib/registry.mjs

@@ -122,7 +122,11 @@ export function llmsTxt(items, site, { full = false } = {}) {
    (an approval, a change to make, or an edit they already made by hand: the brief, words on screen, lengths, joins,
    order; build on those, never undo them). Quick renders for review: \`chain <piece> --drafts\` (each part on its
    own) and \`chain <piece> --draft\` (joined). Only when the user can't open a browser, run the same stages in the
-   chat.
+   chat. Between your turns keep \`npx paper-motion piece listen <piece>\` running in the background: it returns as
+   soon as the user needs you (a message, an answer, an approval), with lines like review's, so they never have to
+   come back to the chat (start it again after; exit 3 means nothing in 9 minutes). Say what you are doing with
+   \`piece working <piece> <stage> --on "…"\`, ask with \`piece ask <piece> "…"\` (they answer in the studio), and
+   reply there with \`piece say <piece> "…"\`. The studio only shows what it can check about you.
 3. **Interview.** Follow the \`make-video\` skill. Without the skills, ask at least: what the brand is in one plain
    line; what this video is for and where it plays (format: 16:9, 9:16, 1:1); its ground, text and accent colors or
    "no brand yet"; three words for the feel and one thing it must never look like; the one action at the end.
@@ -164,9 +168,11 @@ export function llmsTxt(items, site, { full = false } = {}) {
    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).
+   length. While a piece is open and its studio runs, \`board --url\` puts the options into the studio, on the step
+   they decide (How it looks for palettes, type, backgrounds and moves; Your video for transitions and structures),
+   instead of making a link; it waits there and prints the same reply line, and a palette, font pair or background
+   the user picks is applied already. \`--link\` makes a link anyway. If your shell caps how long a command may run,
+   use \`--no-wait\` and then \`npx paper-motion board --await <c1…> --wait 2\` (exit code 3 = not yet).
 
 ## Choosing well: the metadata
 

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();

package/lib/studio.mjs

@@ -18,10 +18,13 @@
 // 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 os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { pieceDir, JOINS, chainSig, readSigs, readJob } from './chain.mjs';
-import { STAGES, BRIEF_KEYS, readPiece, updatePiece, addEvent, eventLine, sceneTexts, setSceneText, listening } from './piece.mjs';
+import { STAGES, BRIEF_KEYS, readPiece, updatePiece, addEvent, eventLine, sceneTexts, setSceneText, listening, agentState, settleChoice } from './piece.mjs';
+import { replyLine } from './live-board.js';
+import { setArgs } from './customize.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';
 
@@ -63,6 +66,9 @@ const joinErrors = new Map();   // piece folder → why the studio's last join f
 // 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;
+// How it looks: the library's palettes (every colour by role), font pairs (families and their stylesheets) and
+// background resources (to recolour them into a palette), read with the index
+let LOOK = { palettes: [], fonts: [], bgItems: new Map(), entrances: [], items: new Map() };
 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
@@ -151,6 +157,129 @@ function libraryView() {
   };
 }
 
+// ── scene stills: one small frame of each scene as it really is (the user's words, brand and settings), for the
+// list in Your video. Rendered one at a time, only when a scene changed, never while a final renders. Until a
+// scene has one, the list shows the library's still of its block.
+const stillJobs = [];
+let stillBusy = false;
+function sceneStill(cwd, dir, x, stamp) {
+  const d = path.join(dir, '.stills'), img = path.join(d, `${x.dir}.png`), meta = path.join(d, `${x.dir}.json`), key = `${x.mtime}-${stamp}`;
+  const have = fs.existsSync(img), was = readJson(meta, {}).key;
+  if (was !== key && LIVE && !stillJobs.some((j) => j.img === img)) {
+    stillJobs.push({ dir, img, meta, key, url: `${LIVE}/${path.relative(cwd, path.join(dir, x.dir, 'scene.html')).split(path.sep).map(encodeURIComponent).join('/')}?render`, t: (Number(x.duration) || 4) * 0.62 });
+    setTimeout(runStills, 400);
+  }
+  return have ? fileUrl(cwd, img) : null;
+}
+async function runStills() {
+  if (stillBusy) return;
+  stillBusy = true;
+  try {
+    const { renderStills } = await import('./render.mjs');
+    while (stillJobs.length) {
+      const j = stillJobs[0];
+      if (rendering.has(j.dir) || building.has(j.dir)) { await new Promise((r) => setTimeout(r, 3000)); continue; }
+      stillJobs.shift();
+      const out = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-still-'));
+      try {
+        const r = await renderStills({ url: j.url, times: [j.t], outDir: out, dpr: 0.35, sheet: false });
+        fs.mkdirSync(path.dirname(j.img), { recursive: true });
+        fs.copyFileSync(r.files[0], j.img);
+        fs.writeFileSync(j.meta, JSON.stringify({ key: j.key }));
+      } catch { /* the list keeps the library's still */ } finally { fs.rmSync(out, { recursive: true, force: true }); }
+    }
+  } finally { stillBusy = false; }
+}
+
+// ── How it looks ────────────────────────────────────────────────────────────────────────────────────────────
+const b64url = (o) => Buffer.from(JSON.stringify(o), 'utf8').toString('base64url');
+const hexOf = (v) => (typeof v === 'string' ? v : v?.hex ?? null);
+/** The sentence the look is judged with: the first one the user must show, else the first they kept, else the brief. */
+function headline(cwd, dir) {
+  try { const items = normalize(loadRaw(dir), { cwd }).items.filter((i) => i.kind === 'line'); return (items.find((i) => i.must) ?? items[0])?.text ?? readPiece(dir)?.brief?.what ?? ''; } catch { return readPiece(dir)?.brief?.what ?? ''; }
+}
+/** The brand's look as it is, and every option How it looks offers, as the page shows them (stills, no shaders). */
+function lookView(cwd, dir) {
+  const t = readJson(path.join(cwd, 'brand/tokens.json'), {}), m = readJson(path.join(cwd, 'brand/motion.json'), {});
+  const set = readJson(path.join(cwd, 'brand/shader-set/set.json'), {}), entries = (set.entries ?? []).filter((e) => e.shader && !e.image);
+  const colors = { ground: hexOf(t.colors?.ground), figure: hexOf(t.colors?.figure), accent: hexOf(t.colors?.accent) };
+  const same = (a, b) => String(a ?? '').toLowerCase() === String(b ?? '').toLowerCase();
+  const palette = LOOK.palettes.find((x) => ['ground', 'figure', 'accent'].every((k) => same(x.colors[k], colors[k])))?.id ?? (colors.ground ? 'custom' : null);
+  const font = LOOK.fonts.find((f) => same(f.fonts.display.family, t.fonts?.display?.family) && same(f.fonts.text?.family, t.fonts?.text?.family))?.id ?? null;
+  const mine = new Set(entries.map((e) => e.id));
+  return {
+    current: { colors, palette, font, display: t.fonts?.display?.family ?? null, text: t.fonts?.text?.family ?? null, background: entries[0]?.id ?? null, pace: m.pace ?? 'medium', entrance: m.entrance ?? null },
+    headline: headline(cwd, dir), live: !!LIVE,
+    palettes: LOOK.palettes.map((x) => ({ id: x.id, title: x.title, colors: x.colors })),
+    fonts: LOOK.fonts.map((f) => ({ id: f.id, title: f.title, display: f.fonts.display.family, text: f.fonts.text?.family ?? null, css: [f.fonts.display.css, f.fonts.text?.css].filter(Boolean) })),
+    backgrounds: [
+      ...entries.map((e) => ({ id: e.id, title: TITLES.get(e.id) ?? e.id, mine: true, poster: fs.existsSync(path.join(LOCAL_PREVIEWS, `${e.id}.jpg`)) || TITLES.has(e.id) ? preview(e.id, 'jpg') : null, colors: (e.props?.colors ?? [e.props?.colorBack, e.props?.colorFront]).filter(Boolean).slice(0, 4) })),
+      ...BACKGROUNDS.filter((b) => !mine.has(b.id)).map((b) => ({ id: b.id, title: b.title, mine: false, poster: preview(b.id, 'jpg'), colors: b.colors ?? [] })),
+    ],
+    entrances: LOOK.entrances, paces: ['calm', 'medium', 'fast'],
+  };
+}
+/**
+ * The look preview: the user's sentence in `line-in`, playing live from .try/look/, with a look laid over the brand
+ * for this preview only (`?embed&look=…`, read by runtime/brand.js). `o` changes any of palette, colors, font,
+ * background, pace, entrance; what it leaves out is the brand's own. One preview plays at a time.
+ */
+async function lookPreview(cwd, piece, o = {}) {
+  if (!LIVE) throw new Error('the live preview is not ready yet');
+  const dir = pieceDir(piece, cwd), sub = path.join('.try', 'look'), file = path.join(dir, sub, 'scene.html');
+  if (!fs.existsSync(file)) { const { add } = await import('./registry.mjs'); await add(['line-in'], { cwd, force: true, name: path.join(path.relative(path.join(cwd, 'pieces'), dir), sub) }); }
+  const text = headline(cwd, dir), html = fs.readFileSync(file, 'utf8'), want = fillConfig(html, { text, mark: '', entrance: null, background: null });
+  if (want !== html) fs.writeFileSync(file, want);
+  const t = readJson(path.join(cwd, 'brand/tokens.json'), {}), set = readJson(path.join(cwd, 'brand/shader-set/set.json'), {});
+  const pal = o.palette ? LOOK.palettes.find((x) => x.id === o.palette)?.colors : null;
+  const colors = { ...Object.fromEntries(Object.entries(t.colors ?? {}).map(([k, v]) => [k, hexOf(v)])), ...(pal ?? {}), ...(o.colors ?? {}) };
+  const look = {};
+  if (pal || o.colors) look.colors = colors;
+  if (o.font) { const f = LOOK.fonts.find((x) => x.id === o.font); if (f) look.fonts = f.fonts; }
+  // the background: the one asked for, else the brand's first; recoloured whenever the colours are not the brand's own
+  const entries = (set.entries ?? []).filter((e) => e.shader && !e.image), bgId = o.background ?? entries[0]?.id;
+  const item = LOOK.bgItems.get(bgId), own = entries.find((e) => e.id === bgId);
+  if (item && (o.background || look.colors)) {
+    const { recolor } = await import('./customize.mjs');
+    const e = item.install?.entry ?? {};
+    look.background = { ...e, id: bgId, props: { ...(e.props ?? {}), ...recolor(item, colors) } };
+  } else if (own && o.background) look.background = own;
+  if (o.pace) look.pace = o.pace;
+  if (o.entrance) look.entrance = o.entrance;
+  return { url: `${LIVE}/${path.relative(cwd, file).split(path.sep).map(encodeURIComponent).join('/')}?embed&look=${b64url(look)}&v=${Date.now()}` };
+}
+
+// ── choices from the agent (ADR 0005): what each option's card needs, and what the studio applies on a pick ──────
+const COLOR_ROLES = ['ground', 'figure', 'muted', 'surface', 'accent'];
+function itemFace(o) {
+  const it = LOOK.items.get(o.id), type = it?.type ?? null, face = { id: o.id, type, title: `${it?.title ?? o.id}${Object.keys(o.values ?? {}).length ? ', tuned' : ''}` };
+  if (type === 'palette') face.colors = { ...(LOOK.palettes.find((x) => x.id === o.id)?.colors ?? {}), ...Object.fromEntries(Object.entries(o.values ?? {}).filter(([k]) => COLOR_ROLES.includes(k))) };
+  else if (type === 'font-pair') { const f = LOOK.fonts.find((x) => x.id === o.id); if (f) Object.assign(face, { display: f.fonts.display.family, text: f.fonts.text?.family ?? null, css: [f.fonts.display.css, f.fonts.text?.css].filter(Boolean) }); }
+  else Object.assign(face, { poster: preview(o.id, 'jpg'), clip: type === 'background' ? null : preview(o.id, 'webm') });
+  return face;
+}
+function choiceView(c) {
+  const opt = (o) => {
+    const base = { label: o.label, note: o.note ?? null };
+    if (o.structure) return { ...base, title: o.structure.title, seconds: o.structure.duration, beats: o.structure.beats.map((b) => ({ name: b.name, what: b.what, id: b.id ?? null, from: b.from, to: b.to })) };
+    if (c.board.kind === 'kit') return { ...base, title: `Look ${o.label}`, items: o.items.map(itemFace) };
+    return { ...base, ...itemFace(o) };
+  };
+  return { id: c.id, title: c.board.title, ask: c.board.ask ?? null, where: c.where, status: c.status, line: c.line ?? null, options: c.board.options.map(opt) };
+}
+/** After a pick: what the studio itself applies to brand/ (palette, font pair, background); the rest is the agent's. */
+async function applyChoice(cwd, dir, c, label) {
+  const o = c.board.options.find((x) => x.label === label); if (!o) return;
+  for (const x of c.board.kind === 'kit' ? o.items : [o]) {
+    const type = LOOK.items.get(x.id)?.type;
+    if (type === 'palette') {
+      await editStyle(cwd, dir, { type: 'palette', value: x.id });
+      for (const k of ['ground', 'figure', 'accent']) if (x.values?.[k]) await editStyle(cwd, dir, { type: 'color', key: k, value: x.values[k] });
+    } else if (type === 'font-pair') await editStyle(cwd, dir, { type: 'font', value: x.id });
+    else if (type === 'background') await editStyle(cwd, dir, { type: 'background', value: x.id });
+  }
+}
+
 /** What the page shows for one piece. */
 export function view(cwd, piece) {
   const dir = pieceDir(piece, cwd), p = readPiece(dir);
@@ -177,13 +306,16 @@ export function view(cwd, piece) {
     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&v=${x.mtime}-${styleView(cwd).stamp}` : null; x.poster = preview(x.id, 'jpg'); x.clip = preview(x.id, 'webm');
+      const stamp = styleView(cwd).stamp;
+      for (const x of v.parts) { x.still = sceneStill(cwd, dir, x, stamp); 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 },
+    lookOptions: lookView(cwd, dir),   // How it looks: the brand's look now and every option, as stills
+    choices: (p.choices ?? []).map(choiceView),   // what the agent put into the studio for the user to decide
     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, v?.css ?? null]),
@@ -195,7 +327,13 @@ export function view(cwd, piece) {
     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 },
+    // only what can be checked: a question open, a command waiting on the piece now, or what it said it is doing (20 min)
+    agent: { ...agentState(dir, p), app: p.agent?.app ?? null, focus: process.platform === 'darwin' && !!p.agent?.path, url: p.agent?.url ?? null },
+    // the conversation in the studio: what the user sent (and when the agent read it) and the agent's replies
+    thread: [
+      ...p.events.filter((e) => (e.kind === 'changes' && !e.part) || e.kind === 'answer').map((e) => ({ who: 'you', text: e.kind === 'answer' ? `${e.q ? `“${e.q}” ` : ''}${e.text}` : e.text, at: e.at, read: e.readAt ?? (e.n <= (p.seen ?? 0) ? e.at : null) })),
+      ...(p.notes ?? []).map((x) => ({ who: 'agent', text: x.text, at: x.at })),
+    ].sort((x, y) => x.at.localeCompare(y.at)),
     unread: p.events.filter((e) => e.n > (p.seen ?? 0)).length,
   };
 }
@@ -243,7 +381,9 @@ function act(cwd, piece, a, queue) {
         }
         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', since: new Date().toISOString() }; }
+        // How it looks is the user's step: it opens ready to choose (or done, when the brand already settles it)
+        if (next === 'look') { if (STAGES.indexOf(p.stage) < STAGES.indexOf('look')) p.stage = next; if (p.stages.look.status !== 'approved') p.stages.look = { status: 'review', since: new Date().toISOString() }; }
+        else if (next && !(a.stage === 'look' && STAGES.indexOf(p.stage) > STAGES.indexOf('look'))) { 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;
       }
@@ -254,6 +394,30 @@ function act(cwd, piece, a, queue) {
         break;
       }
       case 'reopen': { p.stages[a.stage] = { status: 'review' }; addEvent(p, { kind: 'reopen', stage: a.stage }); break; }
+      case 'message': {   // Ask your agent: a request, read as a changes line, that leaves the stage where it is
+        const t = text(a.text); if (!t) throw new Error('say what you need');
+        addEvent(p, { kind: 'changes', stage: p.stage, text: t, msg: true });
+        break;
+      }
+      case 'answer': {   // the agent's open question, answered here
+        const t = text(a.text); if (!t) throw new Error('write your answer');
+        addEvent(p, { kind: 'answer', text: t, q: p.ask?.text ?? null });
+        delete p.ask;
+        break;
+      }
+      case 'ask-close': { delete p.ask; break; }   // answered in the chat instead
+      case 'choose': {   // a pick on a choice the agent put here, or none of them with what they'd rather see
+        const c = (p.choices ?? []).find((x) => x.id === a.choice); if (!c) throw new Error('no such choice');
+        let line;
+        if (a.none) line = replyLine(c.board, { none: true, text: text(a.text) });
+        else {
+          const o = c.board.options.find((x) => x.label === a.label); if (!o) throw new Error('no such option');
+          const it = o.id ? LOOK.items.get(o.id) : null;
+          line = replyLine(c.board, { label: o.label, setArgs: it && o.values && Object.keys(o.values).length ? setArgs(it, o.values) : [] });
+        }
+        settleChoice(p, c.id, line);
+        break;
+      }
       case 'approve-part': { p.parts[a.part] = { ...(p.parts[a.part] ?? {}), status: 'approved', note: undefined }; addEvent(p, { kind: 'approve', stage: 'parts', part: a.part }); break; }
       case 'brief': {
         if (!BRIEF_KEYS.includes(a.key)) throw new Error('bad brief key');
@@ -444,10 +608,28 @@ 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
+  import('./registry.mjs').then(async (r) => {
+    const i = await r.getIndex();
+    // the site's index is light (params by name only, no install data): the studio needs the full resource of every
+    // palette, font pair and background (How it looks) and of every block and shot (their settings and entrances),
+    // fetched a few at a time when the index lacks it (a local registry already has it)
+    const light = (i.items ?? []).filter((x) => ['palette', 'font-pair', 'background', 'block', 'shot'].includes(x.type) && (!x.install || (x.params ?? []).some((q) => typeof q === 'string')));
+    for (let k = 0; k < light.length; k += 8) {
+      const full = await Promise.all(light.slice(k, k + 8).map((x) => r.getItem(x.id).catch(() => null)));
+      for (const f of full) if (f) { const at = i.items.findIndex((x) => x.id === f.id); if (at >= 0) i.items[at] = { ...i.items[at], ...f }; }
+    }
+    return i;
+  }).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 }));
+    const def = (x, k) => x.params?.find((q) => q.name === k)?.default;
+    LOOK.palettes = (i.items ?? []).filter((x) => x.type === 'palette').map((x) => ({ id: x.id, title: x.title, colors: Object.fromEntries(['ground', 'figure', 'muted', 'surface', 'accent'].map((k) => [k, def(x, k)]).filter(([, v]) => v)) }));
+    LOOK.fonts = (i.items ?? []).filter((x) => x.type === 'font-pair' && x.install?.entry?.fonts?.display).map((x) => ({ id: x.id, title: x.title, fonts: x.install.entry.fonts, type: x.install.entry.type ?? null }));
+    LOOK.bgItems = new Map((i.items ?? []).filter((x) => x.type === 'background').map((x) => [x.id, x]));
+    LOOK.items = new Map((i.items ?? []).map((x) => [x.id, x]));
+    const li = (i.items ?? []).find((x) => x.id === 'line-in');
+    LOOK.entrances = (li?.params?.find((q) => q.name === 'entrance')?.options ?? []).map((o) => { const r = li.repeat?.previews?.[o]; return { value: o, title: TITLES.get(r) ?? o, poster: r ? preview(r, 'jpg') : null, clip: r ? preview(r, 'webm') : null }; });
     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
@@ -473,8 +655,10 @@ export function startStudio({ cwd = process.cwd(), port = 4317, log = console.lo
             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);
+            // a pick on the agent's palette, font pair or background is applied at once, like any card here
+            if (a.type === 'choose' && !a.none) { const dir = pieceDir(piece, cwd), c = (readPiece(dir).choices ?? []).find((x) => x.id === a.choice); if (c) await applyChoice(cwd, dir, c, a.label); }
+            // choosing how it looks builds the first version of the video, by itself: the user lands on something to edit
+            if (a.type === 'approve' && a.stage === 'look') buildFirst(cwd, piece, log);
             return json(res, 200, r);
           } catch (e) { return json(res, 400, { error: e.message.split('\n')[0] }); }
         }
@@ -487,6 +671,10 @@ export function startStudio({ cwd = process.cwd(), port = 4317, log = console.lo
         if (!fs.existsSync(f)) { res.writeHead(404); return res.end(); }
         return sendFile(req, res, f);
       }
+      if (u.pathname === '/api/look' && req.method === 'POST') {   // How it looks: the user's sentence with a look laid over
+        let body = ''; for await (const c of req) body += c;
+        try { return json(res, 200, await lookPreview(cwd, u.searchParams.get('p'), JSON.parse(body || '{}'))); } catch (e) { return json(res, 400, { error: e.message.split('\n')[0] }); }
+      }
       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] }); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",
@@ -36,6 +36,7 @@
     "templates/",
     "examples/",
     "!examples/**/renders/",
+    "!examples/**/stills/",
     "README.md",
     "CHANGELOG.md"
   ],