paper-motion 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.5.0 · 2026-11-13
+
+**Studio v2: one page, four steps, an honest agent.** The user makes a piece in the studio alone (What you want to
+say, How it looks, Your video, Export); the agent listens in the background, and its visual choices come into the
+studio instead of links. Five phases, one end-to-end check (`scripts/check-studio.mjs`, 53 checks).
+
+Studio v2, phase 1 ([spec](../../docs/spec-studio-v2.md), [plan](../../docs/plan-studio-v2.md)): an honest connection with the agent.
+
+- **`piece listen <piece>`**: the agent keeps it running in the background between turns. It returns as soon as the
+  user does something that needs the agent (a message, an answer, an approval, a choice), printing it as lines and
+  marking them read, or exits 3 after 9 minutes with nothing. The user no longer has to go to the chat to say
+  "continue".
+- **The studio only says what it can check about the agent:** listening (a command of the agent is waiting on the
+  piece, and its process is alive), working on something (said with `piece working … --on "…"`, for up to 20
+  minutes), asking you, or not connected. "Your agent waits" and "tell your agent continue" are gone. A command
+  that was killed stops showing as listening at once.
+- **Questions are answered in the studio.** `piece ask` shows the question with an answer box; the answer reaches
+  `piece listen` as an `answered "…": "…"` line. **Answered in the chat** closes it.
+- **Ask your agent is a thread:** each message shows Sent, then Read with the time; `piece say <piece> "…"` puts the
+  agent's reply there. A message no longer moves the stage to "changes".
+- `scripts/check-studio.mjs` drives a fresh project end to end (headless Chrome for the user, real `pamo` commands
+  for the agent).
+
+Studio v2, phase 2: one page, four steps, and How it looks.
+
+- **A new stage, `look`**, between `inventory` and `video` (`STAGES`: brief, inventory, look, video, final). A
+  project whose brand already settles colours, type and a background starts with it done; older pieces get it as
+  approved.
+- **The stepper:** What you want to say · How it looks · Your video · Export. Steps ahead stay locked until reached;
+  earlier ones reopen. Style moved into How it looks.
+- **How it looks:** colours, type, background and movement (pace, and how words arrive), each a still card. Pointing
+  at one plays it in a single live preview of the user's own first sentence (`line-in`, with the look laid over the
+  brand only for that preview: `?embed&look=…`, read by `runtime/brand.js`). Choosing writes `brand/`: the palette
+  (the brand's library backgrounds take its colours again), the font pair, a colour by hand, the brand's main
+  background (added from the library in its colours when needed), pace and the default entrance
+  (`brand/motion.json` `entrance`, which `line-in` uses when a part sets none). **Make my video** builds the first
+  version, which used to happen on approving the content.
+- **A still of every background** (`apps/web/public/previews/<id>.jpg`, from `scripts/render-backgrounds.mjs`), so
+  cards never run a shader.
+
+Studio v2, phase 3: the agent's choices come into the studio ([ADR 0005](../../docs/adr/0005-the-studio-replaces-board-links-during-a-piece.md)).
+
+- With a piece open and its studio running, **`pamo board --url …` puts the options into the studio** instead of a
+  link, on the step they decide: palettes, font pairs, backgrounds and moves in How it looks (kits as a whole look
+  at its top), transitions, structures and blocks in Your video. The step shows a dot; the options come first in
+  their section, marked **Suggested by your agent**, with the agent's question and notes, and play in the preview
+  when pointed at. The command waits (the studio shows the agent listening) and prints the same reply line, built
+  with `replyLine`. **None of these** sends what the user would rather see. `--link` makes a link anyway.
+- A palette, font pair or background picked there is applied to `brand/` at once, like any card; moves,
+  transitions and structures go to the agent as the line.
+- `board --await c1` waits again for a studio choice, `board --forget c1` takes it out.
+
+Studio v2, phase 4: Your video as scenes.
+
+- **A list of scenes instead of the strip:** each with its number, a still of itself, what it says and how long it
+  plays; drag to reorder; **Add a scene** at the end asks what it is for.
+- **Stills of the real scenes** (the user's words, brand and settings), rendered by the studio one at a time after a
+  scene changes (`pieces/<piece>/.stills/`), never while a final renders; until then the library's still shows.
+- **Five tabs:** Text, Animation (with the block's own settings), Background, Speed (length is speed) and Next scene
+  (the transition, chosen by watching, or the same between every scene).
+- **Nothing rebuilds by itself.** Something new kept in What you want to say offers **Add it to the video**; approving
+  the content again never takes a built piece back to How it looks.
+- **The playing scene no longer restarts when the page redraws** (a still arriving, the agent's state changing): it is
+  moved without reloading (`moveBefore`, where the browser has it), and a still only updates its thumbnail.
+
+Studio v2, phase 5: light on the machine.
+
+- An embedded preview that ended stops its frame loop (a click starts it again): an idle studio draws nothing. The
+  check measures it: 0 shader draws and 0 animation frames for 5 s after a scene ends, and at most one live preview
+  on the page.
+- **Fixed for npm installs:** the site's `registry.json` lists params by name only, so an installed studio had no
+  block settings or entrances to offer (since 0.4) and, now, no palettes' colours, font pairs or backgrounds. It
+  fetches the full resource of those (`/r/<id>.json`) when it starts. `scripts/check-studio.mjs` runs against an
+  installed package with `PAMO_BIN=…`.
+- The site's making-of, hero and docs page tell the four steps, the five stages behind them, `piece listen` and the
+  choices in the studio.
+
+
+## 0.4.1 · 2026-11-12
+
+- **The studio's live previews are much lighter.** A scene opened with `?embed` draws its shaders at the size it is
+  shown, not the full frame times the screen's density (a Retina screen drew 8 million pixels a frame for a box
+  700 px wide), skips layers no one can see, and plays at 30 frames a second. In a test of a part with six shots,
+  shader draws went from 180 to about 10 a second. Renders are unchanged.
+- **A part always plays its whole scene: its length is its speed.** Shorter plays it faster, longer slower, never
+  cut short and never looped; sounds move with the picture and keep their pitch. Each part may run from 1.6× faster
+  to 0.6× slower than its scene (`SPEED`, `lengthRange` in inventory.mjs); a length outside that range is held at
+  the limit with a warning. The studio's Length slider runs over that range, says how much faster or slower the
+  part plays, and its live preview plays at that speed. The planner proposes lengths inside the range.
+- **Previews in the studio play once and hold their last frame** (a click plays one again); "Play the whole video"
+  moves on when each part ends, instead of after a timer that let a part loop.
+- **Beat cuts puts one word on each beat, never repeating, and ends on its last word**: its length is the words
+  at the tempo. The chain records each scene's real length, so the studio knows it.
+
 ## 0.4.0 · 2026-11-12
 
 A piece is built from what the user has to show, not from a mood.

package/bin/pamo.mjs

@@ -364,7 +364,7 @@ async function main() {
         const { parseSet, setArgs } = await import('../lib/customize.mjs');
         const reg = resolveRegistry(args.registry), { items } = await getIndex(reg), index = Object.fromEntries(items.map((i) => [i.id, i]));
         const opts = process.argv.flatMap((a, i, all) => (a === '--option' ? [all[i + 1]] : a.startsWith('--option=') ? [a.slice(9)] : [])).filter(Boolean);
-        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette[:key=value,…],font | --look brand] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url]\n       board --await <id|link> [--wait minutes]   (wait again for a board already shared)\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 [word-swap] one line; Proof 2-12 [browser-frame] three shots; Close 12-18 [svg-logo] the action" (a [block-id] makes the board play that clip for the beat).\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, in minutes; --no-wait returns at once) and prints the reply line, the same one they could paste. If your shell caps how long a command runs, share with --no-wait and then wait in short steps: board --await <id> --wait 2, again until it prints the line (exit code 3 means not yet). Values take lists and several keys: --option graphite:accent=#B8F03C,ramp=["#0A0A0B","#B8F03C"] (quote it for the shell); --look brand uses the palette, colors and font pair this project installed. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
+        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette[:key=value,…],font | --look brand] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url] [--link]  (with a piece open and its studio running the options go into the studio, not a link; --link makes a link anyway)\n       board --await <id|link> [--wait minutes]   (wait again for a board already shared)\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 [word-swap] one line; Proof 2-12 [browser-frame] three shots; Close 12-18 [svg-logo] the action" (a [block-id] makes the board play that clip for the beat).\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, in minutes; --no-wait returns at once) and prints the reply line, the same one they could paste. If your shell caps how long a command runs, share with --no-wait and then wait in short steps: board --await <id> --wait 2, again until it prints the line (exit code 3 means not yet). Values take lists and several keys: --option graphite:accent=#B8F03C,ramp=["#0A0A0B","#B8F03C"] (quote it for the shell); --look brand uses the palette, colors and font pair this project installed. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
         const LABELS = ['A', 'B', 'C', 'D'];
         // commas only separate at the top level (not inside [..], {..} or quotes), and only before a new "key=":
         // so ramp=["#000","#111"] and multi-value colors survive
@@ -420,6 +420,31 @@ async function main() {
         } else if (typeof args.look === 'string') for (const spec of splitLook(args.look)) { const o = await parseOne(spec); const t = index[o.id]?.type; if (t === 'palette') look.palette = o; else if (t === 'font-pair') look.font = o; else throw new Error(`--look takes a palette and a font pair (or "brand"), not "${o.id}"`); }
         const choose = args.choose === undefined ? undefined : /^\d+-\d+$/.test(String(args.choose)) ? String(args.choose).split('-').map(Number) : Number(args.choose);
         const board = { v: 1, kind: args.kit ? 'kit' : 'resource', title: String(args.title), ...(args.ask ? { ask: String(args.ask) } : {}), ...(args.reply ? { reply: String(args.reply) } : {}), ...(Object.keys(look).length ? { look } : {}), ...(choose !== undefined ? { choose } : {}), options };
+        // a piece open with its studio running: the options go into the studio, on the step they decide, not into a
+        // link; the command waits there and prints the same reply line (ADR 0005). --link makes a site link anyway.
+        if (!args.link) {
+          const PCs = await import('../lib/piece.mjs');
+          const pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+          const st = pdirS ? await (await import('../lib/studio.mjs')).findStudio(process.cwd()) : null;
+          if (st) {
+            const { validateBoard } = await import('../lib/live-board.js');
+            const errs = validateBoard(board, index); if (errs.length) { console.error(`✗ ${errs.join('; ')}`); process.exit(1); }
+            const type = board.kind === 'kit' ? 'kit' : board.options[0].structure ? 'structure' : index[board.options[0].id]?.type;
+            const PLACE = { palette: ['look', 'colours', 'How it looks · Colours'], 'font-pair': ['look', 'type', 'How it looks · Type'], background: ['look', 'background', 'How it looks · Background'],
+              text: ['look', 'movement', 'How it looks · Movement'], component: ['look', 'movement', 'How it looks · Movement'], camera: ['look', 'movement', 'How it looks · Movement'], kit: ['look', 'kit', 'How it looks'],
+              transition: ['video', 'joins', 'Your video'], structure: ['video', 'structure', 'Your video'], recipe: ['video', 'structure', 'Your video'], block: ['video', 'scenes', 'Your video'], shot: ['video', 'scenes', 'Your video'] };
+            const [step, section, label] = PLACE[type] ?? ['video', 'other', 'Your video'];
+            const cid = PCs.addChoice(pdirS, { board, where: { step, section, type } });
+            console.log(`in the studio, on ${label}: ${st.url}?p=${encodeURIComponent(path.basename(pdirS))}  (choice ${cid}; no link to share)`);
+            if (args['no-wait']) { console.error(`the user chooses in the studio; wait for it with: board --await ${cid}`); break; }
+            const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 10;
+            console.error(`waiting up to ${minutes} min for their choice in the studio…`);
+            const line = await PCs.awaitChoiceIn(pdirS, cid, { timeout: minutes * 60 * 1000 });
+            if (!line) { console.error(`no choice yet: wait again with board --await ${cid}`); process.exit(3); }
+            console.log(line);
+            break;
+          }
+        }
         const site = typeof args.site === 'string' ? args.site : SITE;
         let frag, short = null;
         try { frag = await encodeBoard(board, index); } catch (e) { console.error(e.message); process.exit(1); }
@@ -443,6 +468,22 @@ async function main() {
         } else if (!short && wait) console.error('(no short link, so no waiting: the user will paste the line from the board)');
         break;
       }
+      if (args.await && /^c\d+$/.test(String(args.await))) {   // a choice in the studio
+        const PCs = await import('../lib/piece.mjs'), pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+        if (!pdirS) { console.error('no open piece here (pass --piece)'); process.exit(1); }
+        const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 10;
+        console.error(`waiting up to ${minutes} min for their choice in the studio…`);
+        const line = await PCs.awaitChoiceIn(pdirS, String(args.await), { timeout: minutes * 60 * 1000 });
+        if (!line) { console.error('no choice yet: run it again'); process.exit(3); }
+        console.log(line);
+        break;
+      }
+      if (args.forget && /^c\d+$/.test(String(args.forget))) {
+        const PCs = await import('../lib/piece.mjs'), pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+        if (!pdirS) { console.error('no open piece here (pass --piece)'); process.exit(1); }
+        PCs.forgetChoice(pdirS, String(args.forget)); console.log(`took choice ${args.forget} out of the studio`);
+        break;
+      }
       if (args.await) {
         // wait (again) for the choice on a board already shared: for shells that cap how long one command may run
         const { awaitChoice } = await import('../lib/live-board.js');
@@ -550,7 +591,7 @@ async function main() {
       await ensureDeps();
       if (args.check) {
         const r = await chainLib.checkChain({ piece });
-        for (const p of r.parts) console.log(`  ${p.dir} · ${p.join} · ${p.from}–${+(p.from + p.seconds).toFixed(2)} s of ${p.D}`);
+        for (const p of r.parts) console.log(`  ${p.dir} · ${p.join} · ${p.seconds} s (its ${p.natural} s scene${Math.abs(p.rate - 1) > 0.005 ? `, ×${p.rate.toFixed(2)}` : ''})`);
         for (const w of r.warnings) console.log(`  ! ${w}`);
         console.log(`${r.total.toFixed(1)} s in all`);
         break;
@@ -657,7 +698,7 @@ async function main() {
 
     case 'piece': {
       const sub = args._[1], piece = args._[2];
-      if (!['init', 'review', 'working', 'status', 'ask'].includes(sub) || !piece || args.help) { console.error('Usage: piece init <piece> [--title "…"] [--what …] [--who …] [--format …] [--tone …] [--action …] [--no-studio] [--force]\n       piece review <piece> <stage> [--wait 30 (minutes)] [--no-wait] [--no-open] [--no-studio] [--skip]\n       piece working <piece> <stage>\n       piece ask <piece> "the question you are asking in the chat" | --done\n       piece status <piece>\n  ask: run it right before you ask the user anything in the chat, so the studio sends them there (the next review or working clears it, or --done). --return <url> on any of these gives the studio a link back to you when you run in a browser.\n  Stages: brief, inventory (what the video can show), video (they edit it in the studio), final. review hands a stage to the user in the studio and prints what they did, one line each; it refuses while an earlier stage is not approved (--skip moves on without it, only when the user agreed). --no-wait returns at once with what is unread; --no-open does not open their browser; --no-studio runs without the studio.'); process.exit(args.help ? 0 : 1); }
+      if (!['init', 'review', 'working', 'status', 'ask', 'listen', 'say'].includes(sub) || !piece || args.help) { console.error('Usage: piece init <piece> [--title "…"] [--what …] [--who …] [--format …] [--tone …] [--action …] [--no-studio] [--force]\n       piece review <piece> <stage> [--wait 30 (minutes)] [--no-wait] [--no-open] [--no-studio] [--skip]\n       piece listen <piece> [--wait 9 (minutes)]\n       piece working <piece> <stage> [--on "what you are doing, in plain words"]\n       piece say <piece> "a short reply the user reads in the studio"\n       piece ask <piece> "the question" | --done\n       piece status <piece>\n  listen: run it in the background between your turns; it returns as soon as the user does something that needs you (a message, an answer, an approval, a choice), printing it as lines, or after --wait minutes with nothing (exit 3: start it again). While it runs the studio says you are listening.\n  ask: run it right before you ask the user anything in the chat, so the studio sends them there (the next review or working clears it, or --done). --return <url> on any of these gives the studio a link back to you when you run in a browser.\n  Stages: brief, inventory (what the video can show), video (they edit it in the studio), final. review hands a stage to the user in the studio and prints what they did, one line each; it refuses while an earlier stage is not approved (--skip moves on without it, only when the user agreed). --no-wait returns at once with what is unread; --no-open does not open their browser; --no-studio runs without the studio.'); process.exit(args.help ? 0 : 1); }
       const P = await import('../lib/piece.mjs');
       const { pieceDir } = await import('../lib/chain.mjs');
       const dir = pieceDir(piece), studioLib = await import('../lib/studio.mjs'), q = `?p=${encodeURIComponent(path.basename(dir))}`;
@@ -689,15 +730,31 @@ async function main() {
         await host();
         if (args.done) { P.clearAsk(dir); console.log('✓ cleared: the studio no longer sends the user to the chat'); break; }
         const question = typeof args._[3] === 'string' ? args._[3].trim() : '';
-        if (!question) { console.error('piece ask: give the question in one line (the one you are asking in the chat), or --done'); process.exit(1); }
+        if (!question) { console.error('piece ask: give the question in one line, or --done'); process.exit(1); }
         P.setAsk(dir, question);
-        console.log(`✓ the studio now tells the user you asked this in the chat${P.readPiece(dir).agent ? ', with a way back to you' : ''}. Ask it now; the next piece review or piece working clears it (or piece ask ${piece} --done).`);
+        console.log(`✓ the studio shows your question with a box to answer it; their answer reaches piece listen ${piece} as an "answered" line. Ask it in the chat too. It closes when they answer, or with the next piece review or piece working (or piece ask ${piece} --done).`);
+        break;
+      }
+      if (sub === 'listen') {
+        if (!P.readPiece(dir)) { console.error(`no piece.json in ${path.relative(process.cwd(), dir)}`); process.exit(1); }
+        await host();
+        const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 9;
+        const r = await P.listenFor(dir, { timeout: minutes * 60 * 1000 });
+        for (const l of r.lines) console.log(l);
+        if (!r.done) { console.log(`(nothing from the user in ${minutes} min: run piece listen ${piece} again)`); process.exit(3); }
+        break;
+      }
+      if (sub === 'say') {
+        if (!P.readPiece(dir)) { console.error(`no piece.json in ${path.relative(process.cwd(), dir)}`); process.exit(1); }
+        const text = typeof args._[3] === 'string' ? args._[3].trim() : '';
+        if (!text) { console.error('piece say: give the reply in one or two plain sentences'); process.exit(1); }
+        P.addNote(dir, text); console.log('✓ the user sees it in the studio, under Ask your agent');
         break;
       }
       const stage = args._[3];
       await host();
       if (!P.STAGES.includes(stage)) { console.error(`piece ${sub}: give a stage (${P.STAGES.join(', ')})`); process.exit(1); }
-      if (sub === 'working') { P.updatePiece(dir, (p) => { delete p.ask; p.stage = stage; p.stages[stage] = { ...p.stages[stage], status: 'working', since: new Date().toISOString() }; }); console.log(`✓ ${stage}: working`); break; }
+      if (sub === 'working') { P.updatePiece(dir, (p) => { p.stage = stage; p.stages[stage] = { ...p.stages[stage], status: 'working', since: new Date().toISOString() }; }); P.setWorking(dir, typeof args.on === 'string' ? args.on : null); console.log(`✓ ${stage}: working${typeof args.on === 'string' ? ` on ${args.on}` : ''} (the studio shows it until you listen or review, or for 20 minutes)`); break; }
       // review: hand the stage over and wait for the user's decision in the studio
       if (stage === 'inventory') {
         // the user is asked whether each thing is true and worth showing: they cannot judge half an item

package/lib/chain.mjs

@@ -22,6 +22,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { lengthRange } from './inventory.mjs';
 
 export const JOINS = { cut: 0, whip: 0.35, dissolve: 0.5, dip: 0.5 };
 // the registry's transitions the user may have chosen, as joins between parts: [ffmpeg xfade transition, seconds].
@@ -35,7 +36,6 @@ export const MOVE_JOINS = {
 for (const [k, [, d]] of Object.entries(MOVE_JOINS)) JOINS[k] = d;
 JOINS.whip = 0.35;   // the engine's own whip (slide + smear) wins over the registry's whip move of the same name
 const OVERLAP = new Set(['whip', 'dissolve', ...Object.keys(MOVE_JOINS)]);   // joins that need the outgoing part to run on under the next
-const LAND_HOLD = 0.6;                           // seconds after a land for the hit to read
 
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 const pad = (i) => String(i + 1).padStart(2, '0');
@@ -156,17 +156,20 @@ export function plan(chain, infos) {
     const info = infos[i], D = info.config.duration, from = p.from ?? 0;
     const join = i === 0 ? 'cut' : (p.join ?? chain.join ?? 'whip');
     if (!JOINS.hasOwnProperty(join)) throw new Error(`part ${i + 1}: join "${join}" (use ${Object.keys(JOINS).join(', ')})`);
-    let seconds = p.seconds ?? D - from;
-    if (from + seconds > D + 1e-6) { warnings.push(`${p.dir}: ${seconds} s from ${from} runs past its end (${D} s); it plays ${+(D - from).toFixed(2)} s`); seconds = D - from; }
-    const lands = info.marks.filter((m) => m.gesture === 'land').map((m) => m.t).filter((t) => t >= from);
-    const land = lands.length ? Math.max(...lands) : null;
-    if (land !== null && from + seconds < land + LAND_HOLD) warnings.push(`${p.dir}: cut at ${seconds} s loses its land at ${+(land - from).toFixed(2)} s; give it at least ${+(land - from + LAND_HOLD).toFixed(1)} s`);
-    return { ...p, from, seconds, join, D };
+    // a part plays its whole scene: another length plays it faster or slower (never cut, never looped), within limits
+    const natural = +(D - from).toFixed(3), range = lengthRange(natural);
+    let seconds = p.seconds ?? natural;
+    if (seconds < range.min - 1e-6 || seconds > range.max + 1e-6) {
+      const held = Math.min(range.max, Math.max(range.min, seconds));
+      warnings.push(`${p.dir}: ${seconds} s would play its ${natural} s scene too ${seconds < range.min ? 'fast' : 'slow'} (it takes ${range.min}–${range.max} s); it plays ${held} s`);
+      seconds = held;
+    }
+    return { ...p, from, seconds, join, D, natural, rate: natural / seconds };
   });
-  // the outgoing part runs on under an overlapping join, as far as it can
+  // under an overlapping join the outgoing part holds its last frame while the next one comes in
   for (const [i, p] of parts.entries()) {
     const next = parts[i + 1], d = next && OVERLAP.has(next.join) ? JOINS[next.join] : 0;
-    p.to = Math.min(p.D, p.from + p.seconds + d);
+    p.out = +(p.seconds + d).toFixed(3);
   }
   return { parts, warnings, total: parts.reduce((a, p) => a + p.seconds, 0) };
 }
@@ -232,7 +235,7 @@ export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur
         onStep({ part: i + 1, of: parts.length, dir: p.dir });
         if (kind) writeJob(home, { kind, part: i + 1, of: parts.length });
         const f = path.join(tmp, `${pad(i)}.mov`);
-        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.to, sfx, motionBlur, dpr });
+        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.D, rate: p.rate, seconds: p.out, sfx, motionBlur, dpr });
         files.push(f);
       }
       const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {}), sound = readJson(path.join(cwd, 'brand/sound.json'), {});
@@ -268,7 +271,7 @@ export async function renderDrafts({ cwd = process.cwd(), piece, only, onStep =
       mark(p.dir, { status: 'rendering' });
       const out = path.join(dir, 'drafts', `${p.dir}.mp4`);
       try {
-        await renderVideo({ url: url(p), out, from: p.from, to: p.from + p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
+        await renderVideo({ url: url(p), out, from: p.from, to: p.D, rate: p.rate, seconds: p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
       } catch (e) { mark(p.dir, { status: 'review', error: String(e.message ?? e).slice(0, 300) }); throw e; }
       const v = (readPiece(dir)?.parts?.[p.dir]?.v ?? 0) + 1;
       mark(p.dir, { status: 'review', v, error: undefined, note: undefined });
@@ -296,6 +299,12 @@ async function withChain({ cwd, piece }, fn) {
   try {
     const browser = await launch(), infos = [];
     try { for (const p of chain.parts) infos.push(await sceneInfo(browser, url(p))); } finally { await browser.close(); }
+    // what each scene really lasts (some depend on their content: one beat per word), for the studio's length slider
+    try {
+      fs.writeFileSync(path.join(dir, '.lengths.json'), JSON.stringify(Object.fromEntries(chain.parts.map((p, i) => [p.dir, {
+        duration: infos[i].config.duration, mtime: Math.round(fs.statSync(path.join(dir, p.dir, 'scene.html')).mtimeMs),
+      }])), null, 2) + '\n');
+    } catch { /* the slider falls back to the block's usual length */ }
     const sizes = new Set(infos.map((x) => `${x.config.width}x${x.config.height}`));
     if (sizes.size > 1) throw new Error(`parts come in different sizes (${[...sizes].join(', ')}): set the same format in each CONFIG`);
     const planned = plan(chain, infos);

package/lib/edit.mjs

@@ -9,7 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
-import { fillConfig, evalFill, normalize, loadRaw, propose, writePlan, describe } from './inventory.mjs';
+import { fillConfig, evalFill, normalize, loadRaw, propose, writePlan, describe, lengthRange } from './inventory.mjs';
 
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 const writeJson = (f, v) => fs.writeFileSync(f, JSON.stringify(v, null, 2) + '\n');
@@ -106,16 +106,29 @@ export const canUndo = (dir) => readJson(histFile(dir), []).at(-1)?.label ?? nul
 
 // ── reading the video ──────────────────────────────────────────────────────────────────────────────────────────
 
+/**
+ * A part's length within what its scene allows: it always plays the whole scene, so a length is a speed. Returns the
+ * length (held inside the range), the scene's own length, the range and the speed (above 1 is faster).
+ */
+export function timing(seconds, natural) {
+  const range = lengthRange(natural), s = Math.min(range.max, Math.max(range.min, seconds ?? natural));
+  return { seconds: s, duration: natural, range: { min: range.min, max: range.max }, rate: +(natural / s).toFixed(3) };
+}
+
 /** The parts as the editor shows them: each with its block, its words, motion, background, settings and join. */
 export function videoView(cwd, dir, scenes) {
   const chain = readJson(path.join(dir, 'chain.json'), null);
   if (!chain) return null;
   const byId = new Map(scenes.map((b) => [b.id, b]));
+  // what each scene really lasts, read by the last join (a scene's length can depend on its content); stale once edited
+  const lengths = readJson(path.join(dir, '.lengths.json'), {});
+  const real = (p) => { const l = lengths[p.dir]; try { return l && l.mtime === Math.round(fs.statSync(partFile(dir, p)).mtimeMs) ? l.duration : null; } catch { return null; } };
   const parts = (chain.parts ?? []).filter((p) => p.dir && fs.existsSync(partFile(dir, p))).map((p, i, all) => {
     const html = fs.readFileSync(partFile(dir, p), 'utf8'), cfg = readConfig(html), b = byId.get(p.id) ?? { id: p.id, params: [], needs: [] };
+    const D = real(p);
     const motion = b.repeat ? { param: b.repeat.param, value: cfg[b.repeat.param] ?? null, options: (b.params ?? []).find((x) => x.name === b.repeat.param)?.options ?? [], previews: b.repeat.previews ?? {} } : null;
     return {
-      dir: p.dir, id: p.id, title: b.title ?? p.id, kind: b.needs?.[0]?.kind ?? null, summary: b.summary ?? '', seconds: p.seconds ?? b.duration ?? 4, duration: b.duration ?? null,
+      dir: p.dir, id: p.id, title: b.title ?? p.id, kind: b.needs?.[0]?.kind ?? null, summary: b.summary ?? '', ...timing(p.seconds, D ?? b.duration ?? 4), exact: D !== null,
       join: i < all.length - 1 ? p.join ?? chain.join ?? 'whip' : null, shows: p.shows ?? [], what: p.what ?? '',
       words: wordFields(b, cfg), motion, background: cfg.background ?? null, takesBackground: (b.params ?? []).some((x) => x.name === 'background'), tune: tunables(b, cfg),
       mtime: Math.round(fs.statSync(partFile(dir, p)).mtimeMs),
@@ -193,8 +206,11 @@ export async function editVideo(cwd, dir, a, scenes, brief = {}) {
     }
     case 'seconds': {
       const p = find(), n = Number(a.value); if (!Number.isFinite(n)) throw new Error('give a length in seconds');
-      keep([chainFile], `the length of ${title(p)}`); p.seconds = Math.max(1, Math.min(30, +n.toFixed(1))); writeJson(chainFile, chain);
-      return { say: `${title(p)}: ${p.seconds} s`, part: p.dir };
+      const b = byId.get(p.id) ?? {}, natural = readJson(path.join(dir, '.lengths.json'), {})[p.dir]?.duration ?? b.duration ?? 4;
+      const t = timing(+n.toFixed(1), natural);
+      keep([chainFile], `the length of ${title(p)}`); p.seconds = t.seconds; writeJson(chainFile, chain);
+      const pace = t.rate > 1.005 ? `, ${Math.round((t.rate - 1) * 100)}% faster` : t.rate < 0.995 ? `, ${Math.round((1 - t.rate) * 100)}% slower` : '';
+      return { say: `${title(p)}: ${p.seconds} s${pace}`, part: p.dir };
     }
     case 'join': {
       const { JOINS } = await import('./chain.mjs'); if (!(a.value in JOINS)) throw new Error('bad transition');
@@ -304,19 +320,47 @@ export async function ensureLook(cwd, name) {
   return installed;
 }
 
+// the brand's backgrounds that come from the library take its colours again (after the palette or a colour changed)
+async function recolorBackgrounds(cwd) {
+  const setFile = path.join(cwd, 'brand/shader-set/set.json'), set = readJson(setFile, {});
+  const { add, getIndex } = await import('./registry.mjs');
+  const index = new Set(((await getIndex().catch(() => ({ items: [] }))).items ?? []).filter((x) => x.type === 'background').map((x) => x.id));
+  const ids = (set.entries ?? []).filter((e) => e.shader && !e.image && index.has(e.id)).map((e) => e.id);
+  if (!ids.length) return;
+  const order = (set.entries ?? []).map((e) => e.id);
+  await add(ids, { cwd, palette: 'brand', force: true });
+  const after = readJson(setFile, {});   // keep the order the user had: the first is the brand's background
+  after.entries = [...(after.entries ?? [])].sort((x, y) => (order.indexOf(x.id) + 1 || 1e9) - (order.indexOf(y.id) + 1 || 1e9));
+  writeJson(setFile, after);
+}
+
 export async function editStyle(cwd, dir, a) {
-  const tokens = path.join(cwd, 'brand/tokens.json'), motion = path.join(cwd, 'brand/motion.json');
-  snapshot(cwd, dir, [tokens, motion, path.join(cwd, 'brand/fonts.css')], 'the style');
+  const tokens = path.join(cwd, 'brand/tokens.json'), motion = path.join(cwd, 'brand/motion.json'), setFile = path.join(cwd, 'brand/shader-set/set.json');
+  snapshot(cwd, dir, [tokens, motion, path.join(cwd, 'brand/fonts.css'), setFile], 'the style');
   if (a.type === 'palette' || a.type === 'font') {
     const { add } = await import('./registry.mjs');
     await add([a.value], { cwd, force: true });
+    if (a.type === 'palette') await recolorBackgrounds(cwd);
     return { say: `${a.type === 'palette' ? 'Colours' : 'Type'}: ${a.value}` };
   }
   if (a.type === 'color') {
     if (!/^#[0-9a-f]{6}$/i.test(a.value) || !['ground', 'figure', 'accent'].includes(a.key)) throw new Error('bad colour');
-    const t = readJson(tokens, {}); t.colors ??= {}; t.colors[a.key] = { ...(t.colors[a.key] ?? {}), hex: a.value.toUpperCase() }; writeJson(tokens, t);
+    const t = readJson(tokens, {}); t.colors ??= {}; t.colors[a.key] = { ...(t.colors[a.key] ?? {}), hex: a.value.toUpperCase() }; delete t.ramp; writeJson(tokens, t);
+    await recolorBackgrounds(cwd);
     return { say: `${{ ground: 'Background', figure: 'Text', accent: 'Accent' }[a.key]} colour ${a.value}` };
   }
+  if (a.type === 'background') {   // the brand's background: the first entry of its set, added from the library in its colours
+    let set = readJson(setFile, { entries: [] });
+    if (!(set.entries ?? []).some((e) => e.id === a.value)) { const { add } = await import('./registry.mjs'); await add([a.value], { cwd, palette: 'brand' }); set = readJson(setFile, { entries: [] }); }
+    const i = set.entries.findIndex((e) => e.id === a.value); if (i < 0) throw new Error('no such background');
+    set.entries.unshift(...set.entries.splice(i, 1)); writeJson(setFile, set);
+    return { say: `Background: ${a.value}` };
+  }
+  if (a.type === 'entrance') {   // how words arrive, unless a part says otherwise
+    if (!/^[a-z-]+$/.test(a.value)) throw new Error('bad entrance');
+    const m = readJson(motion, {}); m.entrance = a.value; writeJson(motion, m);
+    return { say: `Words arrive: ${a.value}` };
+  }
   if (a.type === 'pace') {
     if (!['calm', 'medium', 'fast'].includes(a.value)) throw new Error('bad pace');
     const m = readJson(motion, {}); m.pace = a.value; writeJson(motion, m);

package/lib/inventory.mjs

@@ -281,7 +281,14 @@ const lead = (b) => b.needs[0];
 // the shortest a scene can run in a chain: its land (where its last beat, the hold, begins) plus the time for the
 // hit to read; a scene that ends on something else keeps most of its length
 const LAND_HOLD = 0.6;
-const floorOf = (b) => { const d = b.duration ?? 5, last = b.beats?.at(-1); return +(last && /^hold$/i.test(last.name) ? Math.min(d, last.from + LAND_HOLD + 0.1) : d * 0.8).toFixed(1); };
+/**
+ * A part always plays its whole scene: a different length plays it faster or slower, never cut short and never
+ * looped. These are how far it may go, so motion still reads (too fast) and still moves (too slow).
+ */
+export const SPEED = { fast: 1.6, slow: 0.6 };
+/** The lengths a part may take, from its scene's own length: { natural, min, max } in seconds. */
+export const lengthRange = (natural) => ({ natural, min: Math.ceil((natural / SPEED.fast) * 10) / 10, max: Math.floor((natural / SPEED.slow) * 10) / 10 });
+const floorOf = (b) => lengthRange(b.duration ?? 5).min;   // as fast as it may play
 const fits = (need, it) => it.kind === need.kind && (need.has ?? []).every((f) => it[f] !== undefined && it[f] !== '') && Object.entries(need.where ?? {}).every(([k, v]) => it[k] === v);
 // an item that says otherwise ("device: phone" for a block that prefers desktop) goes to this block last
 const offKey = (need, it) => Object.entries(need.prefer ?? {}).some(([k, v]) => it[k] !== undefined && it[k] !== v);
@@ -411,9 +418,9 @@ export function propose(items, scenes, { seconds, brief = {} } = {}) {
   return options.map((o, i) => ({ letter: String.fromCharCode(65 + i), ...o }));
 }
 
-// Fits the beats to the length asked for. No beat runs shorter than its floor (its land must read), so a piece that
-// is too long loses its last beat that is not a must instead; what time is left over the floors is shared out. A
-// short piece stays short: a scene cannot run past its own length, and padding it would be a lie about the content.
+// Fits the beats to the length asked for. Every beat plays its whole scene, faster or slower: none faster than its
+// floor (SPEED.fast), so a piece that is too long loses its last beat that is not a must instead. A short piece plays
+// a little slower (up to a quarter), never more: padding it further would be a lie about the content.
 function timed(beats, target) {
   let list = beats.map((b) => ({ ...b })), notes = [];
   const sum = (k) => list.reduce((s, b) => s + b[k], 0);
@@ -425,8 +432,9 @@ function timed(beats, target) {
       notes.push(`dropped "${list[i].what}" to fit ${target} s`); list.splice(i, 1);
     }
     // share out what is left over the floors; a scene never runs past its own length, so a short piece stays short
-    const room = sum('duration') - sum('min'), k = target >= sum('duration') ? 1 : Math.max(0, (target - sum('min')) / (room || 1));
-    list.forEach((b) => { b.duration = +(b.min + (b.duration - b.min) * k).toFixed(1); });
+    const total = sum('duration'), room = total - sum('min');
+    if (target >= total) { const g = Math.min(1.25, target / (total || 1)); list.forEach((b) => { b.duration = +(b.duration * g).toFixed(1); }); }
+    else { const k = Math.max(0, (target - sum('min')) / (room || 1)); list.forEach((b) => { b.duration = +(b.min + (b.duration - b.min) * k).toFixed(1); }); }
     if (sum('duration') > target * 1.05) notes.push(`runs ${sum('duration').toFixed(1)} s, over the ${target} s asked: every beat left is a must and none can run shorter`);
     if (sum('duration') < target * 0.9) notes.push(`runs ${sum('duration').toFixed(1)} s of the ${target} s asked: there is no more material to show`);
   }