paper-motion 0.2.6 → 0.3.0

package/lib/piece.mjs

@@ -0,0 +1,147 @@
+// 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
+//   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
+//
+// 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 STAGE_STATUS = ['pending', 'working', 'review', 'changes', 'approved'];
+export const BRIEF_KEYS = ['what', 'who', 'format', 'tone', 'action'];
+
+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; }
+}
+
+/** Writes atomically (the studio and the CLI both write it). */
+export function writePiece(dir, p) {
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file(dir)}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(p, null, 2) + '\n');
+  fs.renameSync(tmp, file(dir));
+  return p;
+}
+
+/** Read, change, write: `fn` mutates the piece (re-read right before writing, so concurrent writers rarely clash). */
+export function updatePiece(dir, fn) {
+  const p = readPiece(dir);
+  if (!p) throw new Error(`no piece.json in ${dir} (pamo piece init first)`);
+  fn(p);
+  p.updated = now();
+  return writePiece(dir, p);
+}
+
+export function initPiece({ cwd = process.cwd(), piece, title, brief = {}, force = false }) {
+  const dir = pieceDir(piece, cwd), old = readPiece(dir);
+  if (old && !force) {
+    // an existing piece: fill in what was given, keep the rest
+    return updatePiece(dir, (p) => { if (title) p.title = title; for (const k of BRIEF_KEYS) if (brief[k]) p.brief[k] = brief[k]; });
+  }
+  const tokens = (() => { try { return JSON.parse(fs.readFileSync(path.join(cwd, 'brand/tokens.json'), 'utf8')); } catch { return {}; } })();
+  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' }])),
+    brief: Object.fromEntries(BRIEF_KEYS.map((k) => [k, brief[k] ?? ''])),
+    parts: {}, events: [], seen: 0, created: now(), updated: now(),
+  });
+}
+
+/** 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 what = e.kind === 'approve' ? 'approved'
+    : 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' : '';
+  return `paper-motion: piece ${p.piece} · ${e.kind === 'order' ? '' : `${who} `}${what}${tail}`.replace(/ {2,}/g, ' ');
+}
+
+/** Appends a user event (from the studio). */
+export function addEvent(p, e) {
+  const n = (p.events.at(-1)?.n ?? 0) + 1;
+  const ev = { n, at: now(), ...e };
+  p.events.push(ev);
+  return ev;
+}
+
+/** The agent hands a stage to the user: it becomes the current stage, in review. */
+export function toReview(dir, stage) {
+  if (!STAGES.includes(stage)) throw new Error(`stage "${stage}": use ${STAGES.join(', ')}`);
+  return updatePiece(dir, (p) => {
+    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' };
+  });
+}
+
+/** 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; });
+  return { piece: p, events: out };
+}
+
+// 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;
+
+/**
+ * Waits until the user decides on `stage` in the studio (approves it, or asks for changes), then returns every
+ * event since the agent last looked, as lines. Edits the studio already applied (texts, seconds, order) come along.
+ */
+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)) };
+    }
+    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));
+  }
+}
+
+// ── the words on screen: a scene's top-level string CONFIG entries ──────────────────────────
+const CONFIG_STRING = /^ {2}(\w+): '((?:[^'\\]|\\.)*)',?\s*(\/\/.*)?$/;
+const SKIP = new Set(['background', 'image', 'svg', 'font', 'fontFamily']);
+
+/** The editable texts of a scene: top-level CONFIG strings (not ids or file paths). */
+export function sceneTexts(html) {
+  const start = html.indexOf('const CONFIG = {'), end = html.indexOf('\n};', start);
+  if (start < 0 || end < 0) return {};
+  const out = {};
+  for (const line of html.slice(start, end).split('\n')) {
+    const m = line.match(CONFIG_STRING);
+    if (m && !SKIP.has(m[1]) && !/\.(png|jpe?g|webp|svg|mp4|webm)$/.test(m[2])) out[m[1]] = m[2].replace(/\\(.)/g, '$1');
+  }
+  return out;
+}
+
+/** Rewrites one top-level CONFIG string in a scene. */
+export function setSceneText(html, key, value) {
+  const start = html.indexOf('const CONFIG = {'), end = html.indexOf('\n};', start);
+  const head = html.slice(0, start), body = html.slice(start, end), tail = html.slice(end);
+  const lit = `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  let hit = false;
+  const next = body.split('\n').map((line) => {
+    const m = line.match(CONFIG_STRING);
+    if (!m || m[1] !== key) return line;
+    hit = true;
+    return `  ${key}: ${lit},${m[3] ? ` ${m[3]}` : ''}`;
+  }).join('\n');
+  if (!hit) throw new Error(`CONFIG has no text "${key}"`);
+  return head + next + tail;
+}

package/lib/registry.mjs

@@ -12,8 +12,8 @@ const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = path.resolve(ENGINE, '..', '..');
 // until the paper-motion.app domain is connected, the live site is the vercel URL
 export const SITE = (process.env.PAPER_MOTION_SITE ?? 'https://paper-motion.vercel.app').replace(/\/$/, '');
-const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot'];
-const TYPE_TITLES = { component: 'Component transitions', transition: 'Transitions', text: 'Text effects', camera: 'Camera and energy', background: 'Backgrounds', palette: 'Palettes', 'font-pair': 'Font pairs', recipe: 'Recipes', shot: 'Shots' };
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot', 'block'];
+const TYPE_TITLES = { component: 'Component transitions', transition: 'Transitions', text: 'Text effects', camera: 'Camera and energy', background: 'Backgrounds', palette: 'Palettes', 'font-pair': 'Font pairs', recipe: 'Recipes', shot: 'Shots', block: 'Blocks' };
 
 /** The registry to use: an explicit folder or URL, $PAPER_MOTION_REGISTRY, this repo's registry/ when present, else the site. */
 export function resolveRegistry(given) {
@@ -114,16 +114,27 @@ export function llmsTxt(items, site, { full = false } = {}) {
    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. **Interview.** Follow the \`make-video\` skill. Without the skills, ask at least: what the brand is in one plain
+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:
+   \`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
+   (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.
+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.
-   Mirror it back before proposing anything. **You never choose a look for the user.** These decisions always go
+   Mirror it back, write it into the brief (\`piece init --what … --who … --format … --tone … --action …\`) and
+   \`piece review <piece> brief\`. **You never choose a look for the user.** These decisions always go
    through a board, in this order, one board each: palette · font pair · background(s) · moves by role (how things
    enter, how one thing becomes the next, how text arrives; let them pick several with \`choose\`) · recipe or shots
    (shots are 3–6 s camera gestures: a close-up, a pass over a component, a cursor that clicks; they chain before a
-   recipe or stand alone). Skip a
+   recipe or stand alone) · blocks for the moments inside it (ready-made 4–8 s pieces: annotations on a screen, a
+   form, a terminal, code typing, a chart, captions, a logo sting; each recomposes for 16:9, 9:16 and 1:1). Skip a
    board only when the brand folder already settles that decision, and say so.
-3. **Propose with boards.** For each visual decision (palette, type, background, moves, recipe) pick 2–4 options from
+4. **Propose with boards.** For each visual decision (palette, type, background, moves, recipe) pick 2–4 options from
    this registry and share a board link: \`pamo board --url --title … --option id … --look palette,font\` prints it
    (format below): a short link (\`${site}/b/<id>\`, stored for 90 days) when the site answers, the long form
    with the board in the URL fragment otherwise. The user opens it, sees the options live in their look, may tune one,
@@ -133,16 +144,23 @@ export function llmsTxt(items, site, { full = false } = {}) {
    (\`--choose 1-3\`: use it for text effects and transitions), or \`paper-motion: none of bg-1, calmer ones\`. The
    reply carries every value that differs from the defaults, your pre-tuning included, so installing it reproduces what
    they saw. Never ask the user to paste anything while a command or the MCP is waiting: the choice arrives on its own.
-4. **Install the choices.** \`npx paper-motion add <id> [--set key=value …]\` in the project root, with exactly the
+5. **Install the choices.** \`npx paper-motion add <id> [--set key=value …]\` in the project root, with exactly the
    \`--set\` arguments from the reply. Moves go to \`moves/\`, backgrounds to \`brand/shader-set/set.json\`, palettes and
    fonts to \`brand/tokens.json\`, recipes to \`pieces/<id>/\`. Their choices also accumulate in a kit at ${site}/kit,
    whose prompt carries the whole \`pamo add\` command. \`add\` never overwrites a value already in the project: when
    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.
-5. **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 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:
+   \`npx paper-motion chain init <piece> --board <id> --option D\` installs each beat's block under
+   \`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.
 
 ## Choosing well: the metadata
 
@@ -157,10 +175,11 @@ ${site}/registry.json is the index; every item carries, beside id, type, title,
   reply line carries the resulting values. Without a board, \`pamo add <background> --palette <palette-id|brand>\`
   installs it that way (\`brand\` reads \`brand/tokens.json\`). So choose backgrounds by \`motion\`, \`mood\` and
   texture first; the color comes from the palette.
-- Font pairs: \`voice\` (serif, sans, display, mono). Recipes and shots: \`duration\`, \`formats\` and \`beats\` (the structure as a
+- Font pairs: \`voice\` (serif, sans, display, mono). Recipes, shots and blocks: \`duration\`, \`formats\` and \`beats\` (the structure as a
   timeline: name, from, to, what). A recipe board plays each structure as a sketch, so the user chooses a rhythm, not a
   name; you may add one option that is a **structure of your own** for this brief (\`structure\` instead of \`id\`,
-  format below), which you then build from scratch. Give the recipe board \`choose: [1, 3]\`: picking several recipes in
+  format below), which you then build from scratch. Give each of its beats the \`id\` of the block or shot that shows
+  it: the board then plays those clips in order, so the user watches the structure instead of reading it. Give the recipe board \`choose: [1, 3]\`: picking several recipes in
   order means **one piece made of those blocks in that order**, each block's closing beat dropped except the last; the
   reply reads \`A+C · manifesto · three-things\`, and you build that sequence from scratch, using each recipe's scene as
   the reference for its block.
@@ -202,9 +221,9 @@ A recipe board may hold one option that is a structure of your own for this brie
 
 \`\`\`json
 { "label": "D", "structure": { "title": "Three cuts", "duration": 18, "beats": [
-    { "name": "Hook", "from": 0, "to": 2, "what": "one line over the field" },
-    { "name": "Proof", "from": 2, "to": 12, "what": "three shots of the product" },
-    { "name": "Close", "from": 12, "to": 18, "what": "the wordmark and the action" } ] } }
+    { "name": "Hook", "from": 0, "to": 2, "what": "one line over the field", "id": "word-swap" },
+    { "name": "Proof", "from": 2, "to": 12, "what": "three shots of the product", "id": "browser-frame" },
+    { "name": "Close", "from": 12, "to": 18, "what": "the wordmark and the action", "id": "svg-logo" } ] } }
 \`\`\`
 
 Short links: \`POST ${site}/api/boards\` with \`{ "board": … }\` returns \`{ id, url }\`; \`GET /api/boards/<id>/choice\`

package/lib/studio.mjs

@@ -0,0 +1,258 @@
+// pamo studio: a local page where the user follows a piece through its stages, watches each stage's renders,
+// approves or asks for changes, and edits the brief, the words on screen, lengths, joins and order by hand.
+//
+//   GET  /                         the studio page (studio/index.html)
+//   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())
+//   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.
+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';
+
+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 readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+
+/** Pieces in the project that the studio can show. */
+export function listPieces(cwd) {
+  const root = path.join(cwd, 'pieces');
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root).filter((d) => fs.existsSync(path.join(root, d, 'piece.json'))).map((d) => {
+    const p = readJson(path.join(root, d, 'piece.json'), {});
+    return { piece: d, title: p.title, stage: p.stage, status: p.stages?.[p.stage]?.status, updated: p.updated };
+  }).sort((a, b) => String(b.updated).localeCompare(String(a.updated)));
+}
+
+const fileUrl = (cwd, f) => {
+  if (!fs.existsSync(f)) return null;
+  return `/files/${path.relative(cwd, f).split(path.sep).map(encodeURIComponent).join('/')}?v=${Math.round(fs.statSync(f).mtimeMs)}`;
+};
+
+/** What the page shows for one piece. */
+export function view(cwd, piece) {
+  const dir = pieceDir(piece, cwd), p = readPiece(dir);
+  if (!p) return null;
+  const chain = readJson(path.join(dir, 'chain.json'), { parts: [] });
+  const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {}), set = readJson(path.join(cwd, 'brand/shader-set/set.json'), {});
+  const movesDir = path.join(cwd, 'moves');
+  const parts = (chain.parts ?? []).map((c) => {
+    const html = c.dir ? (() => { try { return fs.readFileSync(path.join(dir, c.dir, 'scene.html'), 'utf8'); } catch { return ''; } })() : '';
+    return {
+      dir: c.dir, id: c.id, name: c.name ?? c.id, what: c.what ?? '', seconds: c.seconds ?? null, join: c.join ?? chain.join ?? 'whip',
+      texts: sceneTexts(html), clip: c.id ? `${SITE}/previews/${c.id}.webm` : null,
+      draft: c.dir ? fileUrl(cwd, path.join(dir, 'drafts', `${c.dir}.mp4`)) : null,
+      ...(p.parts?.[c.dir] ?? { status: 'queued' }),
+    };
+  });
+  const renders = path.join(dir, 'renders'), name = path.basename(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),
+    parts,
+    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]),
+      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 },
+  };
+}
+
+// ── 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;
+  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');
+        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' }; }
+        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 }); }
+        break;
+      }
+      case 'reopen': { p.stages[a.stage] = { status: 'review' }; addEvent(p, { kind: 'reopen', stage: a.stage }); 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');
+        const t = text(a.value); if (t === p.brief[a.key]) break;
+        p.brief[a.key] = t;
+        // an approved brief that changes comes back for the user to confirm
+        if (p.stages.brief.status === 'approved') p.stages.brief = { status: 'review', note: 'edited by hand' };
+        addEvent(p, { kind: 'edit', stage: 'brief', key: a.key, text: t });
+        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);
+        addEvent(p, { kind: 'edit', stage: 'parts', part: a.part, key: 'what', text: part.what });
+        break;
+      }
+      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' };
+        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' }; }
+        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' });
+        break;
+      }
+      case 'order': {
+        const c = chain(), by = new Map(c.parts.map((x) => [x.dir, x]));
+        if (a.order.length !== c.parts.length || a.order.some((d) => !by.has(d))) throw new Error('bad order');
+        c.parts = a.order.map((d) => by.get(d)); saveChain(c);
+        addEvent(p, { kind: 'order', stage: 'parts', text: a.order.join(',') });
+        break;
+      }
+      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);
+  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). */
+function renderQueue(cwd, log) {
+  const q = [];
+  let busy = false;
+  const next = async () => {
+    if (busy || !q.length) 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}`); }
+    busy = false; next();
+  };
+  return (piece, part) => { if (!q.some(([a, b]) => a === piece && b === part)) q.push([piece, part]); next(); };
+}
+
+function sendFile(req, res, f) {
+  const st = fs.statSync(f), type = TYPES[path.extname(f).toLowerCase()] ?? 'application/octet-stream';
+  const range = req.headers.range?.match(/bytes=(\d*)-(\d*)/);
+  if (range) {
+    const start = range[1] ? Number(range[1]) : 0, end = range[2] ? Number(range[2]) : st.size - 1;
+    res.writeHead(206, { 'Content-Type': type, 'Content-Range': `bytes ${start}-${end}/${st.size}`, 'Accept-Ranges': 'bytes', 'Content-Length': end - start + 1, 'Cache-Control': 'no-cache' });
+    fs.createReadStream(f, { start, end }).pipe(res);
+  } else {
+    res.writeHead(200, { 'Content-Type': type, 'Content-Length': st.size, 'Accept-Ranges': 'bytes', 'Cache-Control': 'no-cache' });
+    fs.createReadStream(f).pipe(res);
+  }
+}
+
+export function startStudio({ cwd = process.cwd(), port = 4317, log = console.log } = {}) {
+  const queue = renderQueue(cwd, log);
+  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 === '/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 }); }
+        }
+        const v = view(cwd, piece);
+        return v ? json(res, 200, v) : json(res, 404, { error: `no piece "${piece}"` });
+      }
+      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(); }
+        return sendFile(req, res, f);
+      }
+      res.writeHead(404); res.end();
+    } catch (e) { json(res, 500, { error: e.message }); }
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve({ server, port: server.address().port, close: () => new Promise((r) => server.close(r)) }));
+  });
+}
+
+// ── one studio per project, in the background ─────────────────────────────────────────────────
+const FIRST_PORT = 4317, LAST_PORT = 4336;
+async function probe(port) {
+  try {
+    const r = await fetch(`http://127.0.0.1:${port}/api/info`, { signal: AbortSignal.timeout(800) });
+    return r.ok ? await r.json() : { busy: true };
+  } catch (e) { return e?.cause?.code === 'ECONNREFUSED' ? null : { busy: true }; }
+}
+
+/** The studio serving this project, if one is running: { port, url }. */
+export async function findStudio(cwd = process.cwd()) {
+  for (let port = FIRST_PORT; port <= LAST_PORT; port++) {
+    const info = await probe(port);
+    if (info?.app === 'paper-motion-studio' && info.cwd === path.resolve(cwd)) return { port, url: `http://127.0.0.1:${port}/`, pid: info.pid };
+  }
+  return null;
+}
+
+/**
+ * Makes sure this project has a studio running: reuses it, or starts one detached (it outlives the command, so the
+ * user's page keeps working between the agent's steps) on the first free port. `pamo studio --stop` ends it.
+ */
+export async function ensureStudio(cwd = process.cwd(), { bin } = {}) {
+  const found = await findStudio(cwd);
+  if (found) return { ...found, started: false };
+  let port = FIRST_PORT;
+  while (port <= LAST_PORT && (await probe(port))) port++;
+  if (port > LAST_PORT) throw new Error(`no free port between ${FIRST_PORT} and ${LAST_PORT} for the studio`);
+  const { spawn } = await import('node:child_process');
+  const child = spawn(process.execPath, [bin, 'studio', '--port', String(port)], { cwd, detached: true, stdio: 'ignore' });
+  child.unref();
+  for (let i = 0; i < 40; i++) {
+    await new Promise((res) => setTimeout(res, 150));
+    const info = await probe(port);
+    if (info?.app === 'paper-motion-studio') return { port, url: `http://127.0.0.1:${port}/`, pid: info.pid, started: true };
+  }
+  throw new Error(`the studio didn't start on port ${port} (run: npx paper-motion studio --port ${port})`);
+}
+
+/** Opens a URL in the user's browser (macOS, Windows, Linux); quietly does nothing where it can't. */
+export async function openInBrowser(url) {
+  if (process.env.CI || process.env.PAPER_MOTION_NO_OPEN) return false;
+  const { spawn } = await import('node:child_process');
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+  try { spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => {}).unref(); return true; } catch { return false; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",
@@ -32,6 +32,7 @@
     "bin/",
     "lib/",
     "runtime/",
+    "studio/",
     "templates/",
     "examples/",
     "!examples/**/renders/",

package/runtime/brand.js

@@ -71,7 +71,7 @@ export async function loadBrand(root = '/brand') {
       return layer;
     },
     /** Schedule the brand's sound for a gesture (transition, land, text) at time t. */
-    cue: (s, gesture, t, extra = {}) => { const c = pal[gesture]; if (c) s.sfx(t, c.type, { ...c, ...extra }); },
+    cue: (s, gesture, t, extra = {}) => { (s.marks ??= []).push({ gesture, t }); const c = pal[gesture]; if (c) s.sfx(t, c.type, { ...c, ...extra }); },
     /** The brand's keystroke options for keySounds(): { bank, style, gain }. */
     keys: { ...(sound?.keys?.bank ? { bank: sound.keys.bank } : {}), ...(sound?.keys?.style ? { style: sound.keys.style } : {}), gain: sound?.keys?.gain ?? 0.16 },
     /** Apply the brand's master sound settings (and its bed, if any) to a scene. */

package/runtime/index.js

@@ -124,6 +124,7 @@ class Scene {
       seek: async (t) => { await this.seek(t); await nextFrame(); await nextFrame(); return true; },
       cues: this.cues,
       audio: this.audio,
+      marks: this.marks ?? [],   // gestures a scene declared (B.cue): where its hits land, for cutting it short
     };
     document.documentElement.dataset.pmReady = '1';
     if (!RENDER) mountPlayer(this, startT);