paper-motion 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,7 +2,24 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
-## 0.2.3 · unreleased
+## 0.2.6 · 2026-11-10
+
+- `camera()` in `paper-motion/kit`: a 3D world for a piece (`place`, `at`, `travel` with keyframes, `focus` with depth of field and gradual exits). Every recipe is rebuilt on it: a corridor the camera travels (launch, manifesto), a column it descends (three-things), a line it dollies along with a pull-back recap (explainer), a window it tilts into and punches (product-demo), a slab it swings around (before-after), a sleeve it orbits (release).
+- A new resource type, **shots**: 3–6 s camera gestures (`focus-pull`, `pass-over`, `cursor-guide`, `push-in`, `turn-in`), installed like recipes, chained before one or used alone.
+- `scramble` measures letters by layout width, so it works inside a 3D world.
+
+## 0.2.5 · unreleased
+
+- Recipes declare `beats` (the structure as a timeline); boards draw them, and a recipe board may hold a structure of the agent's own (`--option "@Title | 18 | Hook 0-2 …"`), which `parseReply` returns as `structure`.
+- Three recipes: `manifesto` (words only, three statements and a turn), `three-things` (three cards, three mechanics) and `before-after` (two states, one wipe).
+- Font pairs keep their own stylesheet when the family is unchanged, so self-hosted faces work: the new `geist-serif` pair (Geist Serif headlines served by paper-motion.app, Geist text, Geist Mono labels) is the site's own look.
+
+## 0.2.4 · 2026-11-09
+
+- `pamo board --url` waits for the user's choice by default (`--no-wait`, `--wait <minutes>`); `--choose 3` or `--choose 1-3` lets them pick several options, and the reply line lists them (`A+C · type-on · scramble`). `parseReply` returns `picks`.
+- llms.txt: read the installed skill at once, the decisions that always go through a board, every chosen move appears in the piece.
+
+## 0.2.3 · 2026-11-09
 
 - Boards get short links and a return channel: `pamo board --url` stores the board on the site (`/b/<id>`, 90 days) and falls back to the long link; `--wait [minutes]` prints the reply line when the user chooses in the browser; `--long`, `--forget <id>`. `lib/live-board.js` gains `shortenBoard`, `awaitChoice`, `forgetBoard`; the search filters move to `lib/find.mjs` (shared with the site's MCP at `/mcp`).
 

package/bin/pamo.mjs

@@ -327,9 +327,15 @@ 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,font] --option id[:key=value,…] [--note "why"] … [--kit] [--wait [minutes]] [--long] [--site url]\n       board --forget <id>\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  --wait keeps running until the user chooses in the browser (10 min by default) and prints the reply line, the same one they could paste. --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,font] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url]\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 one line; Proof 2-12 three shots; Close 12-18 the action".\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, --no-wait returns at once) and prints the reply line, the same one they could paste. --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'];
         const parseOne = async (spec) => {
+          if (spec.startsWith('@')) {
+            // a structure of the agent's own: "@Title | 18 | Hook 0-2 one line; Proof 2-12 three shots; Close 12-18 the action"
+            const [title, dur, beatsSpec] = spec.slice(1).split('|').map((x) => x.trim());
+            const beats = (beatsSpec ?? '').split(';').map((x) => x.trim()).filter(Boolean).map((x) => { const m = x.match(/^(.+?)\s+(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)\s+(.+)$/); if (!m) throw new Error(`structure beat "${x}" must read "Name from-to what"`); return { name: m[1], from: Number(m[2]), to: Number(m[3]), what: m[4] }; });
+            return { structure: { title, duration: Number(dur), beats } };
+          }
           const [id, kv] = spec.split(':'), it = index[id];
           if (!it) throw new Error(`"${id}" is not in the registry (try pamo search)`);
           if (!kv) return { id, values: {} };
@@ -346,20 +352,22 @@ async function main() {
         }
         const look = {};
         if (typeof args.look === 'string') for (const spec of args.look.split(',')) { const o = await parseOne(spec.trim()); 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, not "${o.id}"`); }
-        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 } : {}), options };
+        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 };
         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); }
         // the short link when the site stores it; the long one (the board in the fragment) when it cannot
         if (!args.long) { try { short = await shortenBoard(site, board); } catch (e) { console.error(`(${e.message}; sharing the long link)`); } }
         console.log(short ? short.url : boardUrl(site, frag));
-        if (short && args.wait) {
-          const minutes = Number.isFinite(Number(args.wait)) && args.wait !== true ? Number(args.wait) : 10;
+        const wait = !args['no-wait'];   // waiting is the default: the choice comes back without the user pasting anything
+        if (short && wait) {
+          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 the choice on ${short.id} (the user can still paste the line)…`);
           const choice = await awaitChoice(site, short.id, { timeout: minutes * 60 * 1000 });
           if (!choice) { console.error('no choice yet; ask the user to paste the line from the board'); process.exit(3); }
           console.log(choice.line);
-        } else if (!short && args.wait) console.error('--wait needs the short link; the user will paste the line instead');
+        } else if (!short && wait) console.error('(no short link, so no waiting: the user will paste the line from the board)');
         break;
       }
       if (args.forget) {
@@ -639,18 +647,22 @@ async function main() {
         const only = typeof args.only === 'string' ? args.only.split(',') : null;
         const out = path.resolve(args.out ?? path.join(reg.dir, '..', 'apps', 'web', 'public', 'previews'));
         fs.mkdirSync(out, { recursive: true });
-        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe'].includes(i.type) && (!only || only.includes(i.id)));
-        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5 };
+        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe', 'shot'].includes(i.type) && (!only || only.includes(i.id)));
+        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5, shot: 1.8 };
         const demo = path.join(reg.dir, '_demo', 'index.html');
         const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-previews-'));
         try {
           for (const [k, it] of items.entries()) {
             process.stdout.write(`\r${k + 1}/${items.length} ${it.id.padEnd(16)}`);
             const mp4 = path.join(tmp, `${it.id}.mp4`);
-            if (it.type === 'recipe') {
+            if (it.type === 'recipe' || it.type === 'shot') {
               // a recipe renders whole, wired to the demo brand in registry/_demo/brand (served as /brand)
               const here = process.cwd(), copy = path.join(reg.dir, '_demo', `.${it.id}.recipe.html`);
-              fs.copyFileSync(path.join(reg.dir, 'recipe', it.id, 'scene.html'), copy);
+              // the demo brand's copy goes in through the same generator `pamo add --set` uses (preview.values)
+              const { apply: applyValues } = await import('../lib/customize.mjs');
+              const sceneFile = { path: 'scene.html', content: fs.readFileSync(path.join(reg.dir, it.type, it.id, 'scene.html'), 'utf8') };
+              const out = applyValues({ ...it, files: [sceneFile] }, it.preview?.values ?? {});
+              fs.writeFileSync(copy, out.files[0].content);
               process.chdir(path.join(reg.dir, '_demo'));
               try { await withServer(copy, (url) => renderVideo({ url: url('?render'), out: mp4, sfx: false, crf: 18, motionBlur: Number(args['motion-blur'] ?? 3) })); }
               finally { process.chdir(here); fs.rmSync(copy, { force: true }); }

package/lib/customize.mjs

@@ -130,7 +130,8 @@ function paletteTokens(item, values) {
 function fontTokens(item, values) {
   const e = item.install.entry ?? {};
   const f = e.fonts ?? {}, w = values.displayWeight ?? e.type?.display?.weight ?? 400, tr = `${values.tracking ?? parseFloat(e.type?.display?.tracking ?? '0')}em`;
-  const pick = (role, weights) => { const family = values[role] ?? f[role]?.family; return { ...f[role], family, weights, css: gf(family, weights) }; };
+  // a pair's own css (self-hosted families such as Geist Serif) stays while its family is unchanged; a new family loads from Google Fonts
+  const pick = (role, weights) => { const family = values[role] ?? f[role]?.family; const own = f[role]?.css && family === f[role]?.family && !/fonts\.googleapis\.com/.test(f[role].css); return { ...f[role], family, weights, css: own ? f[role].css : gf(family, weights) }; };
   const fonts = { display: pick('display', [w]), text: pick('text', f.text?.weights ?? [400, 500]), mono: pick('mono', f.mono?.weights ?? [400]) };
   const type = { ...e.type, display: { ...e.type?.display, weight: w, tracking: tr }, title: { ...e.type?.title, weight: w, tracking: tr } };
   return { fonts, type };
@@ -140,8 +141,12 @@ function fontTokens(item, values) {
 function recipeConfig(values) {
   const cfg = {}, groups = {};
   for (const [k, v] of Object.entries(values)) {
-    const m = k.match(/^(proof|step|shot)(\d)(Label|Title|Body|Image|Caption)$/);
-    if (m) { const g = { proof: 'proof', step: 'steps', shot: 'shots' }[m[1]]; (groups[g] ??= [])[m[2] - 1] ??= {}; groups[g][m[2] - 1][m[3].toLowerCase()] = v; continue; }
+    const m = k.match(/^(proof|step|shot|thing)(\d)(Label|Title|Body|Image|Caption)$/);
+    if (m) { const g = { proof: 'proof', step: 'steps', shot: 'shots', thing: 'things' }[m[1]]; (groups[g] ??= [])[m[2] - 1] ??= {}; groups[g][m[2] - 1][m[3].toLowerCase()] = v; continue; }
+    const ba = k.match(/^(before|after)(Tag|Line|Image)$/);
+    if (ba) { (cfg[ba[1]] ??= {})[ba[2].toLowerCase()] = v; continue; }
+    const st = k.match(/^statement(\d)$/);
+    if (st) { (cfg.statements ??= [])[st[1] - 1] = v; continue; }
     if (k === 'format') cfg.format = String(v).split('x').map(Number);
     else cfg[k] = v === '' ? null : v;
   }
@@ -153,10 +158,17 @@ function recipeScene(content, values) {
   const start = content.indexOf('const CONFIG = {');
   if (start < 0) return content;
   const end = content.indexOf('\n};', start) + 3;
-  const body = Object.entries(cfg).map(([k, v]) => (Array.isArray(v) && v.length && typeof v[0] === 'object'
+  // the original entries, by key (an entry runs until the next top-level key), so settings that are not params
+  // (backgroundOpacity, turnWord, a card's label…) survive a --set
+  const original = content.slice(start + 'const CONFIG = {\n'.length, end - 3).split(/\n(?=  \w+: )/);
+  const kept = new Map(original.map((e) => [e.match(/^  (\w+):/)?.[1], e]).filter(([k]) => k));
+  const render = (k, v) => (Array.isArray(v) && v.length && typeof v[0] === 'object'
     ? `  ${k}: [\n${v.map((o) => `    ${literal(o)},`).join('\n')}\n  ],`
-    : `  ${k}: ${v === null ? 'null' : literal(v)},`)).join('\n');
-  return `${content.slice(0, start)}const CONFIG = {\n${body}\n};${content.slice(end)}`;
+    : `  ${k}: ${v === null ? 'null' : literal(v)},`);
+  const lines = [];
+  for (const [k, e] of kept) lines.push(k in cfg ? render(k, cfg[k]) : e);
+  for (const [k, v] of Object.entries(cfg)) if (!kept.has(k)) lines.push(render(k, v));
+  return `${content.slice(0, start)}const CONFIG = {\n${lines.join('\n')}\n};${content.slice(end)}`;
 }
 
 // ── the public API ──────────────────────────────────────────────
@@ -170,7 +182,7 @@ export function apply(item, values) {
   const files = (item.files ?? []).map((f) => {
     if (f.content === undefined) return f;
     if (MOVE_TYPES.includes(item.type)) return { ...f, content: moveFile(item, f.content, v) };
-    if (item.type === 'recipe' && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
+    if ((item.type === 'recipe' || item.type === 'shot') && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
     return f;
   });
   let entry = item.install?.entry;
@@ -215,7 +227,7 @@ export function code(item, values, { showAll = false, site = 'https://paper-moti
       { key: 'tokens', label: 'tokens.json', lang: 'json', code: JSON.stringify(e, null, 2) },
       { key: 'css', label: 'CSS variables', lang: 'css', code: `${Object.values(f).map((x) => `@import url('${x.css}');`).filter((x, i, a) => a.indexOf(x) === i).join('\n')}\n\n:root {\n${Object.entries(f).map(([r, x]) => `  --font-${r}: '${x.family}', ${cat(x.family)};`).join('\n')}\n  --display-weight: ${e.type.display.weight};\n  --display-tracking: ${e.type.display.tracking};\n}` },
     ];
-  } else if (item.type === 'recipe') {
+  } else if (item.type === 'recipe' || item.type === 'shot') {
     const scene = out.files.find((f) => /scene\.html$/.test(f.path));
     tabs = [{ key: 'scene', label: 'scene.html', lang: 'html', code: scene?.content ?? '' }];
   }

package/lib/live-board.js

@@ -9,12 +9,15 @@
 export const BOARD_VERSION = 1;
 export const MAX_PAYLOAD = 8 * 1024;
 const LABELS = ['A', 'B', 'C', 'D'];
-const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe'];
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot'];
 
 /**
  * @typedef {{ v: 1, kind: 'resource'|'kit', title: string, ask?: string, reply?: string,
  *   look?: { palette?: { id: string, values?: object }, font?: { id: string, values?: object } },
- *   options: Array<{ label: string, id?: string, values?: object, items?: Array<{ id: string, values?: object }>, note?: string }> }} Board
+ *   choose?: number | [number, number],   // how many options the user may pick: 1 (default), 3, or [min, max]
+ *   options: Array<{ label: string, id?: string, values?: object, items?: Array<{ id: string, values?: object }>, note?: string,
+ *     structure?: { title: string, duration: number, beats: Array<{ name: string, from: number, to: number, what: string }> } }> }} Board
+ * An option with `structure` (recipe boards only) is a structure the agent proposes for this brief instead of a recipe.
  */
 
 /** Checks a board's shape; returns a list of problems (empty when valid). `index` (registry items by id) adds id checks. */
@@ -25,6 +28,7 @@ export function validateBoard(b, index) {
   if (!['resource', 'kit'].includes(b.kind)) errs.push('kind must be "resource" or "kit"');
   if (!b.title || typeof b.title !== 'string') errs.push('title is required');
   if (!Array.isArray(b.options) || b.options.length < 2 || b.options.length > 4) errs.push('2 to 4 options');
+  if (b.choose !== undefined) { const [lo, hi] = chooseRange(b); if (!(Number.isInteger(lo) && Number.isInteger(hi) && lo >= 1 && hi >= lo && hi <= 4)) errs.push('choose must be 1–4 or [min, max] within 1–4'); }
   const seen = new Set();
   for (const [i, o] of (b.options ?? []).entries()) {
     const at = `options[${i}]`;
@@ -32,7 +36,14 @@ export function validateBoard(b, index) {
     if (seen.has(o.label)) errs.push(`${at}.label "${o.label}" repeats`);
     seen.add(o.label);
     if (b.kind === 'resource') {
-      if (!o.id) errs.push(`${at}.id is required`);
+      if (o.structure) {
+        const st = o.structure;
+        if (o.id) errs.push(`${at}: either id or structure, not both`);
+        if (!st.title || typeof st.title !== 'string') errs.push(`${at}.structure.title is required`);
+        if (!(Number(st.duration) > 0)) errs.push(`${at}.structure.duration (seconds) is required`);
+        if (!Array.isArray(st.beats) || st.beats.length < 2 || st.beats.length > 8) errs.push(`${at}.structure.beats: 2 to 8 beats`);
+        for (const [j, bt] of (st.beats ?? []).entries()) if (!bt?.name || typeof bt.from !== 'number' || typeof bt.to !== 'number' || bt.to <= bt.from || !bt.what) errs.push(`${at}.structure.beats[${j}] needs name, from < to (seconds) and what`);
+      } else if (!o.id) errs.push(`${at}.id is required`);
       else if (index && !index[o.id]) errs.push(`${at}.id "${o.id}" is not in the registry`);
     } else {
       if (!Array.isArray(o.items) || !o.items.length) errs.push(`${at}.items is required for a kit board`);
@@ -41,13 +52,16 @@ export function validateBoard(b, index) {
     if (o.values && typeof o.values !== 'object') errs.push(`${at}.values must be an object`);
   }
   if (b.kind === 'resource' && index) {
-    const types = new Set(b.options.map((o) => index[o.id]?.type).filter(Boolean));
+    const types = new Set(b.options.map((o) => (o.structure ? 'recipe' : index[o.id]?.type)).filter(Boolean));
     if (types.size > 1) errs.push(`a resource board shows one type at a time (got ${[...types].join(', ')})`);
   }
   for (const k of ['palette', 'font']) { const l = b.look?.[k]; if (l && index && !index[l.id]) errs.push(`look.${k} "${l.id}" is not in the registry`); }
   return errs;
 }
 
+/** How many options a board lets the user pick: [min, max]. Defaults to [1, 1]. */
+export const chooseRange = (b) => (Array.isArray(b?.choose) ? [Number(b.choose[0]), Number(b.choose[1])] : [1, Math.max(1, Number(b?.choose ?? 1))]);
+
 // ── compression, both runtimes ──────────────────────────────────
 
 const b64url = {
@@ -134,14 +148,18 @@ export async function forgetBoard(site, id) {
 //   paper-motion: kit B · cobalt geist mesh-graphite whip-pan      a kit board choice
 // `reply` (the agent's name for the decision) is appended as "(bg-1)" when present.
 
+//   paper-motion: A+C · type-on · scramble --set speed=2           several picks on a board with choose > 1
+//   paper-motion: D · structure "Three cuts"                        a structure the agent proposed, chosen
+// `choice` is { label, setArgs? } for one pick, { picks: [{ label, setArgs? }, …] } for several, or { none, text }.
+
 export function replyLine(board, choice) {
   const tag = board.reply ? ` (${board.reply})` : '';
   if (choice.none) return `paper-motion: none of ${board.reply ?? `"${board.title}"`}${choice.text ? `, ${choice.text}` : ''}`;
-  const o = board.options.find((x) => x.label === choice.label);
-  if (!o) throw new Error(`no option ${choice.label}`);
-  if (board.kind === 'kit') return `paper-motion: kit ${o.label} · ${o.items.map((i) => i.id).join(' ')}${tag}`;
-  const sets = (choice.setArgs ?? []).join(' ');
-  return `paper-motion: ${o.label} · ${o.id}${sets ? ` ${sets}` : ''}${tag}`;
+  const picks = choice.picks ?? [choice];
+  const found = picks.map((c) => { const o = board.options.find((x) => x.label === c.label); if (!o) throw new Error(`no option ${c.label}`); return { o, sets: (c.setArgs ?? []).join(' ') }; });
+  const labels = found.map((f) => f.o.label).join('+');
+  if (board.kind === 'kit') return `paper-motion: kit ${labels} · ${found.map((f) => f.o.items.map((i) => i.id).join(' ')).join(' + ')}${tag}`;
+  return `paper-motion: ${labels} · ${found.map((f) => (f.o.structure ? `structure "${f.o.structure.title.replace(/"/g, "'")}"` : `${f.o.id}${f.sets ? ` ${f.sets}` : ''}`)).join(' · ')}${tag}`;
 }
 
 /** Parses a reply line the user pasted. Returns null when the text is not one. */
@@ -150,10 +168,17 @@ export function parseReply(text) {
   if (!m) return null;
   const body = m[1].trim(), tag = body.match(/\(([^()]+)\)\s*$/)?.[1] ?? null, core = body.replace(/\s*\([^()]+\)\s*$/, '');
   if (core.startsWith('none of ')) { const rest = core.slice(8); const i = rest.indexOf(','); return { none: true, reply: tag ?? rest.slice(0, i < 0 ? undefined : i).trim(), text: i < 0 ? '' : rest.slice(i + 1).trim() }; }
-  const kit = core.match(/^kit ([A-D]) · (.+)$/);
-  if (kit) return { kind: 'kit', label: kit[1], ids: kit[2].split(/\s+/), reply: tag };
-  const one = core.match(/^([A-D]) · (\S+)(.*)$/);
-  if (!one) return null;
-  const sets = [...one[3].matchAll(/--set\s+('([^']*)'|(\S+))/g)].map((x) => x[2] ?? x[3]);
-  return { kind: 'resource', label: one[1], id: one[2], set: sets, reply: tag };
+  const kit = core.match(/^kit ([A-D](?:\+[A-D])*) · (.+)$/);
+  if (kit) { const labels = kit[1].split('+'), kits = kit[2].split(' + ').map((k) => k.split(/\s+/)); return { kind: 'kit', label: labels[0], labels, ids: kits[0], kits, reply: tag }; }
+  const many = core.match(/^([A-D](?:\+[A-D])*) · (.+)$/);
+  if (!many) return null;
+  const labels = many[1].split('+');
+  const picks = many[2].split(' · ').map((part, i) => {
+    const st = part.trim().match(/^structure "(.+)"$/);
+    if (st) return { label: labels[i], structure: st[1], set: [] };
+    const m = part.trim().match(/^(\S+)(.*)$/);
+    return { label: labels[i], id: m[1], set: [...m[2].matchAll(/--set\s+('([^']*)'|(\S+))/g)].map((x) => x[2] ?? x[3]) };
+  });
+  // one pick keeps the original shape (label, id, set); several add `picks`
+  return { kind: 'resource', label: picks[0].label, id: picks[0].id, set: picks[0].set, labels, picks, reply: tag };
 }

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'];
-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' };
+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' };
 
 /** 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) {
@@ -110,19 +110,29 @@ export function llmsTxt(items, site, { full = false } = {}) {
 ## The flow (for agents)
 
 1. **Set up.** \`npx skills add solanodz/paper-motion\` (the skills) and \`npx paper-motion setup\` (the engine: Node 18+,
-   ffmpeg, Chrome). The CLI is \`npx paper-motion\` (short: \`pamo\`). Every command answers \`--help\`.
+   ffmpeg, Chrome). The CLI is \`npx paper-motion\` (short: \`pamo\`). Every command answers \`--help\`. Agents load
+   skills and MCP servers when a session starts, so after installing the skills **read
+   \`.claude/skills/make-video/SKILL.md\` now** (or \`.agents/skills/make-video/SKILL.md\`) and follow it in this
+   session; tell the user that the MCP at ${site}/mcp, if they want it, is added before opening a session.
 2. **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.
+   Mirror it back before proposing anything. **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
+   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
    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,
-   and chooses. The choice comes back as one line: \`paper-motion: B · mesh-sage --set speed=0.8 (bg-1)\`, or
-   \`paper-motion: none of bg-1, calmer ones\`. With \`--wait\` the command keeps running and prints that line the
-   moment they choose (10 min by default); without it, they paste the line in the chat. The reply carries every value
-   that differs from the defaults, your pre-tuning included, so installing it reproduces what they saw.
+   and chooses. The command keeps running and prints the choice the moment they choose (10 min by default;
+   \`--no-wait\` returns at once and they paste the line instead). It is one line: \`paper-motion: B · mesh-sage --set
+   speed=0.8 (bg-1)\`, \`paper-motion: A+C · type-on · scramble (text-1)\` when the board let them pick several
+   (\`--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
    \`--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,
@@ -130,7 +140,8 @@ export function llmsTxt(items, site, { full = false } = {}) {
    the user re-chooses or re-tunes something you installed before, pass \`--force\`. A recipe also reads
    \`brand/motion.json\` (pace) and \`brand/sound.json\` (cues; without it the piece is silent) and the brand's name
    from \`tokens.json\` \`brand\`: write those from the interview before rendering.
-5. **Make the video.** Build \`scene.html\` (a pure function of time), check stills with \`pamo still\`, render with
+5. **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.
 
 ## Choosing well: the metadata
@@ -146,7 +157,13 @@ ${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: \`duration\`, \`formats\`.
+- Font pairs: \`voice\` (serif, sans, display, mono). Recipes and shots: \`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
+  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.
 
 \`pamo search\` filters by them: \`pamo search --type background --mode dark --near "#0a0f1f,#eef1f8,#3d6bff"\`
 sorts backgrounds by color fit (the mean distance from each of theirs to the nearest of yours; lower is closer; pass
@@ -163,7 +180,7 @@ one-line \`--note\` for each; share the link.
 
 The same registry as tools, with no install: add \`${site}/mcp\` (streamable HTTP, no auth) to your agent. Tools:
 \`search\` (the filters above), \`resource\` (one record in full), \`recolor\` (a background's values in a palette),
-\`board\` (creates a short link and, with \`wait\`, returns the user's choice) and \`board_choice\`. Installing is
+\`board\` (creates a short link and waits for the user's choice, which it returns as \`choices\`) and \`board_choice\`. Installing is
 still \`npx paper-motion add\` in the user's project, or your own file tools from the record.
 
 ## The board link format
@@ -172,7 +189,7 @@ still \`npx paper-motion add\` in the user's project, or your own file tools fro
 
 \`\`\`json
 { "v": 1, "kind": "resource", "title": "Backgrounds for Kiln", "ask": "Which one feels like the product?",
-  "reply": "bg-1",
+  "reply": "bg-1", "choose": 1,
   "look": { "palette": { "id": "cobalt", "values": {} }, "font": { "id": "geist", "values": {} } },
   "options": [
     { "label": "A", "id": "mesh-graphite", "values": {}, "note": "quiet, graphite" },
@@ -181,10 +198,19 @@ still \`npx paper-motion add\` in the user's project, or your own file tools fro
     { "label": "D", "id": "grain-slate", "values": {} } ] }
 \`\`\`
 
+A recipe board may hold one option that is a structure of your own for this brief; if chosen, you build it from scratch:
+
+\`\`\`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" } ] } }
+\`\`\`
+
 Short links: \`POST ${site}/api/boards\` with \`{ "board": … }\` returns \`{ id, url }\`; \`GET /api/boards/<id>/choice\`
 answers 204 until the user chooses, then \`{ line, label }\`. Boards expire after 90 days; \`DELETE /api/boards/<id>\` forgets one.
 
-Rules: 2–4 options, labels A–D, one resource type per \`resource\` board; \`kind: "kit"\` makes each option
+Rules: 2–4 options, labels A–D, \`choose\` 1 (default), a count or \`[min, max]\`, one resource type per \`resource\` board; \`kind: "kit"\` makes each option
 \`{ "label", "items": [{ "id", "values" }], "note" }\` (a whole kit); \`values\` hold only what differs from the
 defaults; the JSON stays under 8 KB. \`pamo board --url\` builds and validates it for you.
 
@@ -234,7 +260,7 @@ export function build({ dir = resolveRegistry().dir, out, site = SITE } = {}) {
   for (const it of items) if (it.preview) { const have = Object.fromEntries(Object.entries(it.preview).filter(([, p]) => typeof p !== 'string' || fs.existsSync(path.join(out, p)))); it.preview = Object.values(have).some((p) => typeof p === 'string') ? have : undefined; }
   const index = {
     name: 'paper-motion', site, schema: `${site}/schema.json`, count: items.length, types: TYPES.filter((t) => items.some((i) => i.type === t)),
-    items: items.map(({ id, type, title, summary, tags, version, preview, related, when, mood, energy, role, colors, mode, motion, voice, duration, formats, params }) => ({ id, type, title, summary, tags, version, url: `${site}/r/${id}.json`, ...Object.fromEntries(Object.entries({ when, mood, energy, role, colors, mode, motion, voice, duration, formats, preview, related, params: params?.filter((p) => !p.hidden).map((p) => p.name) }).filter(([, v]) => v !== undefined)) })),
+    items: items.map(({ id, type, title, summary, tags, version, preview, related, when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, params }) => ({ id, type, title, summary, tags, version, url: `${site}/r/${id}.json`, ...Object.fromEntries(Object.entries({ when, mood, energy, role, colors, mode, motion, voice, duration, formats, beats, preview, related, params: params?.filter((p) => !p.hidden).map((p) => p.name) }).filter(([, v]) => v !== undefined)) })),
   };
   fs.writeFileSync(path.join(out, 'registry.json'), JSON.stringify(index, null, 2));
   fs.mkdirSync(path.join(out, 'files'), { recursive: true });

package/package.json

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

package/runtime/brand.js

@@ -5,6 +5,7 @@
 //   const s = scene({ ..., background: B.color('ground') });
 //   B.style(title, 'display'); B.shader(s, '#bg', 'mesh-ground'); B.cue(s, 'transition', 2.4); B.sound(s);
 import { PACE } from './moves.js';
+import { mixColor } from './core.js';
 
 const get = (p, json) => fetch(p).then((r) => (r.ok ? (json ? r.json() : r.text()) : null)).catch(() => null);
 const sections = (md) => Object.fromEntries((md ?? '').split(/^## /m).slice(1).map((b) => { const i = b.indexOf('\n'); return [b.slice(0, i).trim(), b.slice(i + 1).trim()]; }));
@@ -33,6 +34,15 @@ export async function loadBrand(root = '/brand') {
     name: wm.text ?? tokens?.brand ?? 'brand',
     /** A color by role (ground, figure, muted, surface, accent…), with a fallback. */
     color: (role, fallback = '#888888') => C[role]?.hex ?? fallback,
+    /**
+     * The surface for cards and panels, lifted toward the figure when the brand's own surface is too close to the
+     * ground to read (a black brand with a near-black surface would draw black cards on black).
+     */
+    surface: (lift = 0.14) => {
+      const g = C.ground?.hex ?? '#000000', s = C.surface?.hex ?? g, f = C.figure?.hex ?? '#ffffff';
+      const lum = (h) => { const n = parseInt(h.slice(1, 7), 16); return (0.2126 * (n >> 16) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255; };
+      return Math.abs(lum(s) - lum(g)) < 0.06 ? mixColor(g, f, lift) : s;
+    },
     ramp: tokens?.ramp ?? [C.ground?.hex, C.surface?.hex, C.accent?.hex].filter(Boolean),
     /** CSS font-family for a font key (display, text, mono). */
     font: fam,

package/runtime/kit.js

@@ -96,3 +96,76 @@ export function copy(el) {
 }
 
 export const partsOf = (el) => new Map([...el.querySelectorAll('[data-part]')].map((e) => [e.dataset.part, e]));
+
+// ── a 3D camera over a world ────────────────────────────────────
+// A recipe is a world the camera moves through, not a deck of cards. `stage` gets the perspective; `world` holds
+// children placed in space with `place()`; the camera's position is applied to the world as its inverse.
+//   const cam = camera(stage, world, { perspective: 2000 });
+//   cam.place(title, { z: -1200, yaw: 8 });
+//   s.update((t) => { cam.travel(t, [[0, { z: 1400 }], [3, { z: -200, yaw: 6 }, ease.inOutCubic]]); cam.focus(0, 900); });
+// Rules: never set opacity < 1 on `world` (it flattens its children); fade the placed elements instead.
+const CAM = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0, roll: 0, zoom: 1 };
+export function camera(stage, world, { perspective = 2000, origin = '50% 50%' } = {}) {
+  Object.assign(stage.style, { perspective: `${perspective}px`, perspectiveOrigin: origin });
+  Object.assign(world.style, { position: 'absolute', inset: 0, transformStyle: 'preserve-3d', transformOrigin: '50% 50%' });
+  const placed = [];
+  let pos = { ...CAM };
+  const P = perspective;
+  const cam = {
+    /** Where the camera is (the last `at`/`travel`). */
+    get pos() { return pos; },
+    /** Puts an element in the world, centred on its own box: { x, y, z, yaw, pitch, roll, scale }. */
+    place(el, p = {}) {
+      const q = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0, roll: 0, scale: 1, ...p };
+      Object.assign(el.style, { position: 'absolute', left: '50%', top: '50%', transformStyle: 'preserve-3d', backfaceVisibility: 'hidden' });
+      el.style.transform = `translate(-50%, -50%) translate3d(${q.x}px, ${q.y}px, ${q.z}px) rotateY(${q.yaw}deg) rotateX(${q.pitch}deg) rotateZ(${q.roll}deg) scale(${q.scale})`;
+      el._pmPlace = q;
+      if (!placed.includes(el)) placed.push(el);
+      return el;
+    },
+    /** Moves the camera: the world gets the inverse transform. Fields missing keep the current value. */
+    at(p) {
+      pos = { ...pos, ...p };
+      world.style.transform = `scale(${pos.zoom}) rotateZ(${-pos.roll}deg) rotateX(${-pos.pitch}deg) rotateY(${-pos.yaw}deg) translate3d(${-pos.x}px, ${-pos.y}px, ${-pos.z}px)`;
+      return pos;
+    },
+    /** Keyframes for the camera: [[t, { x, y, z, yaw, pitch, roll, zoom }, ease?], …]. Fields carry over between frames. */
+    travel(t, frames) {
+      const full = [];
+      let acc = { ...CAM, ...frames[0][1] };
+      for (const [time, p, e] of frames) { acc = { ...acc, ...p }; full.push([time, acc, e]); }
+      if (t <= full[0][0]) return cam.at(full[0][1]);
+      for (let i = 1; i < full.length; i++) {
+        const [t1, v1, e = ease.inOutCubic] = full[i], [t0, v0] = full[i - 1];
+        if (t <= t1) { const q = e(clamp((t - t0) / (t1 - t0))); return cam.at(Object.fromEntries(Object.keys(CAM).map((k) => [k, lerp(v0[k], v1[k], q)]))); }
+      }
+      return cam.at(full[full.length - 1][1]);
+    },
+    /**
+     * Depth of field and presence. Blur follows DEPTH: distance from the focal plane `z` ahead of the camera (sharp
+     * within a third of `range`, up to `max` px). Presence follows DISTANCE in 3D from the point the camera looks at:
+     * a place is whole within `fade`·0.4 and gone by `fade` (default `range`·0.85), so the next place is never
+     * peeking into frame while the camera rests, and while it travels the two overlap instead of leaving an empty
+     * frame. A place passing the lens softens and fades over the last stretch: it finishes its exit, never cuts.
+     * `fade: Infinity` keeps everything present (a focus pull where only the blur should change).
+     */
+    focus(z = 0, range = 800, max = 12, { fade = range * 0.85 } = {}) {
+      const fx = pos.x, fy = pos.y, fz = pos.z - z;          // the point in focus
+      for (const el of placed) {
+        const q = el._pmPlace;
+        const blur = clamp((Math.abs(q.z - fz) - range * 0.33) / range) * max;
+        const dist = Math.hypot(q.x - fx, q.y - fy, q.z - fz);
+        const present = fade === Infinity ? 1 : 1 - clamp((dist - fade * 0.4) / Math.max(1, fade * 0.6));
+        const toLens = pos.z - q.z;                          // distance left before it passes the camera
+        const near = clamp((toLens - P * 0.03) / (P * 0.1));   // the last stretch before the lens, whatever the focus range
+        const b = Math.max(blur, (1 - near) * max, (1 - present) * max * 0.6);
+        el.style.filter = b > 0.3 ? `blur(${b.toFixed(1)}px)` : 'none';
+        const o = Math.min(near, present);
+        el.style.opacity = String(o);
+        el.style.visibility = o < 0.005 ? 'hidden' : '';
+      }
+    },
+  };
+  cam.at({});
+  return cam;
+}

package/runtime/moves/scramble.js

@@ -6,7 +6,8 @@ export function scramble(el, t, { start = 0, duration = 1.4, fps = 30, rate = 2,
   const cs = chars(el);
   if (!el._labText) {
     el._labText = cs.map((c) => c.textContent);
-    cs.forEach((c) => { c.style.width = `${c.getBoundingClientRect().width}px`; c.style.textAlign = 'center'; });
+    // layout width, not the on-screen rect: inside a 3D world the rect is scaled by perspective
+    cs.forEach((c) => { c.style.width = `${c.offsetWidth}px`; c.style.textAlign = 'center'; });
     const r = rng(seed); el._labJit = cs.map(() => r.next());
   }
   const n = cs.length, tick = Math.floor((t * fps) / rate);

package/runtime/moves/word-rise.js

@@ -5,6 +5,8 @@ import { words } from '../kit.js';
 export function wordRise(el, t, { start = 0, each = 0.08, duration = 0.5, curve = ease.outExpo } = {}) {
   words(el).forEach((w, i) => {
     const q = curve(progress(t, start + i * each, start + i * each + duration));
-    w.style.transform = `translateY(${(1 - q) * 110}%)`;
+    // fully below the mask line, and hidden until it moves: tall glyphs overflow a tight line-height box
+    w.style.transform = `translateY(${(1 - q) * 125}%)`;
+    w.style.opacity = q > 0.001 ? 1 : 0;
   });
 }