paper-motion 0.0.0-stage → 0.2.0

package/lib/board.mjs

@@ -0,0 +1,95 @@
+// Option boards: N rendered options (stills or short clips) composed into one labelled grid,
+// so an interview can show choices side by side and the user answers with a letter.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { launch } from './browser.mjs';
+
+const BOARD_W = 1920, GAP = 16, PAD = 40, LABEL_H = 64;
+
+/** Grid for n options: 2–3 in a row, 4 as 2×2, 5–6 as 3×2 (never an empty cell for 3); `cols` overrides. */
+export function layout(n, aspect, colsOverride) {
+  const cols = colsOverride ? Math.max(1, Math.min(n, colsOverride)) : n <= 3 ? n : n === 4 ? 2 : 3;
+  const rows = Math.ceil(n / cols);
+  const cw = Math.floor((BOARD_W - PAD * 2 - GAP * (cols - 1)) / cols / 2) * 2;
+  const ch = Math.floor(cw / aspect / 2) * 2;
+  const cells = Array.from({ length: n }, (_, i) => ({
+    x: PAD + (i % cols) * (cw + GAP),
+    y: PAD + Math.floor(i / cols) * (ch + LABEL_H + GAP) + LABEL_H,
+  }));
+  const H = Math.ceil((PAD * 2 + rows * (ch + LABEL_H) + (rows - 1) * GAP) / 2) * 2;
+  return { cols, rows, cw, ch, W: BOARD_W, H, cells };
+}
+
+/** Transparent PNG with each option's letter and caption above its cell. */
+async function labelsPng(L, labels, file, { backing = false } = {}) {
+  const browser = await launch();
+  try {
+    const page = await browser.newPage({ viewport: { width: L.W, height: L.H } });
+    const items = L.cells.map((c, i) => {
+      const [letter, ...rest] = labels[i].split(' · ');
+      return `<div style="position:absolute;left:${c.x}px;top:${c.y - LABEL_H}px;height:${LABEL_H}px;width:${L.cw}px;overflow:hidden;display:flex;align-items:center;gap:14px;${backing ? 'width:auto;max-width:' + L.cw + 'px;padding:0 18px 0 12px;border-radius:10px;background:rgba(0,0,0,.62);' : ''}font:500 26px ui-monospace,Menlo,monospace;color:#fff">
+        <span style="flex-shrink:0;display:inline-flex;align-items:center;justify-content:center;width:40px;height:40px;border:1.5px solid #fff;border-radius:6px">${letter}</span>
+        <span style="color:#9a9a9a;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-width:0">${rest.join(' · ')}</span></div>`;
+    }).join('');
+    await page.setContent(`<html><body style="margin:0;background:transparent">${items}</body></html>`);
+    await page.screenshot({ path: file, omitBackground: true });
+  } finally { await browser.close(); }
+}
+
+function ffmpeg(args) {
+  return new Promise((res, rej) => {
+    const p = spawn('ffmpeg', ['-y', '-loglevel', 'error', ...args], { stdio: ['ignore', 'inherit', 'inherit'] });
+    p.on('close', (code) => (code === 0 ? res() : rej(new Error(`ffmpeg exited ${code}`))));
+  });
+}
+
+/**
+ * Compose rendered option files (all PNG or all MP4) into one board.
+ * @param {string[]} inputs  rendered options, in label order
+ * @param {string[]} labels  "A · caption" per option
+ * @param {number} aspect    cell aspect ratio (width / height)
+ * @param {string} out       .png for stills, .mp4 for clips
+ * @param {number} duration  clip length in seconds (bounds the looped label layer)
+ */
+export async function composeBoard({ inputs, labels, aspect, out, tmp, duration, cols }) {
+  const L = layout(inputs.length, aspect, cols);
+  const lab = path.join(tmp, 'labels.png');
+  await labelsPng(L, labels, lab);
+  const clip = out.endsWith('.mp4');
+  const ins = inputs.flatMap((f) => ['-i', f]);
+  const scaled = inputs.map((_, i) => `[${i}:v]scale=${L.cw}:${L.ch}:force_original_aspect_ratio=decrease,pad=${L.cw}:${L.ch}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1[v${i}]`);
+  let chain = `color=c=0x0a0a0a:s=${L.W}x${L.H}${clip ? ':r=30' : ''}[bg0]`;
+  inputs.forEach((_, i) => { chain += `;[bg${i}][v${i}]overlay=${L.cells[i].x}:${L.cells[i].y}${clip ? ':shortest=1' : ''}[bg${i + 1}]`; });
+  chain += `;[bg${inputs.length}][${inputs.length}:v]overlay=0:0${clip ? ':format=auto' : ''}[out]`;
+  const filter = [...scaled, chain].join(';');
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  if (clip) await ffmpeg([...ins, '-loop', '1', '-i', lab, '-filter_complex', filter, '-map', '[out]', ...(duration ? ['-t', String(duration)] : []), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20', '-an', out]);
+  else await ffmpeg([...ins, '-i', lab, '-filter_complex', filter, '-map', '[out]', '-frames:v', '1', out]);
+  return { out, ...L };
+}
+
+/**
+ * Clips one after another, each with its letter and caption burned in and its own sound,
+ * so sound choices are heard in turn: A, then B, then C.
+ */
+export async function composeSequence({ inputs, labels, out, tmp, duration }) {
+  const segs = [];
+  for (const [i, f] of inputs.entries()) {
+    const probe = await new Promise((res) => { const p = spawn('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'csv=p=0', f]); let o = ''; p.stdout.on('data', (d) => (o += d)); p.on('close', () => res(o.trim())); });
+    const [w, h] = probe.split(',').map(Number);
+    const L = { W: w, H: h, cw: w - 80, cells: [{ x: 40, y: 40 + LABEL_H }] };
+    const lab = path.join(tmp, `seq-label-${i}.png`);
+    await labelsPng(L, [labels[i]], lab, { backing: true });
+    const seg = path.join(tmp, `seq-${i}.mp4`);
+    const hasAudio = await new Promise((res) => { const p = spawn('ffprobe', ['-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', f]); let o = ''; p.stdout.on('data', (d) => (o += d)); p.on('close', () => res(!!o.trim())); });
+    // every segment carries a stereo track (silence when the option has no sound) so they concatenate cleanly
+    await ffmpeg(['-i', f, '-loop', '1', '-i', lab, '-f', 'lavfi', '-i', 'anullsrc=r=48000:cl=stereo', '-filter_complex', '[0:v][1:v]overlay=0:0:format=auto[v]', '-map', '[v]', '-map', hasAudio ? '0:a' : '2:a', ...(hasAudio ? ['-af', 'loudnorm=I=-20:TP=-2:LRA=11'] : []), '-t', String(duration), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20', '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', seg]);
+    segs.push(seg);
+  }
+  const list = path.join(tmp, 'seq.txt');
+  fs.writeFileSync(list, segs.map((s) => `file '${s}'`).join('\n'));
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  await ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-c', 'copy', out]);
+  return { out, W: 0, H: 0 };
+}

package/lib/browser.mjs

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { chromium } from 'playwright-core';
+
+const CANDIDATES = {
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  ],
+  linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
+  win32: [
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  ],
+};
+
+export function findBrowser() {
+  const env = process.env.PAPER_MOTION_BROWSER;
+  if (env && fs.existsSync(env)) return env;
+  try { const p = chromium.executablePath(); if (p && fs.existsSync(p)) return p; } catch { /* not installed */ }
+  for (const p of CANDIDATES[os.platform()] ?? []) if (fs.existsSync(p)) return p;
+  return null;
+}
+
+export async function launch() {
+  const executablePath = findBrowser();
+  if (!executablePath) {
+    throw new Error('No Chromium-based browser found. Install Google Chrome, or run:\n  npx playwright-core install chromium\nor set PAPER_MOTION_BROWSER=/path/to/chrome');
+  }
+  return chromium.launch({
+    executablePath,
+    headless: true,
+    args: [
+      '--ignore-gpu-blocklist',
+      '--enable-gpu-rasterization',
+      '--enable-unsafe-swiftshader', // WebGL fallback on machines without a GPU (CI, servers)
+      '--hide-scrollbars',
+      '--mute-audio',
+      '--force-color-profile=srgb',
+      '--disable-background-timer-throttling',
+      '--disable-renderer-backgrounding',
+      '--disable-backgrounding-occluded-windows',
+    ],
+  });
+}
+
+/** Open a scene in render mode and wait until it is ready. */
+export async function openScene(browser, url, { dpr = 1 } = {}) {
+  // Probe size with a throwaway page first, so the real viewport matches the scene.
+  const probe = await browser.newPage();
+  const errors = [];
+  probe.on('pageerror', (e) => errors.push(e));
+  probe.on('console', (m) => { if (m.type() === 'error' && !m.text().startsWith('Failed to load resource')) errors.push(new Error(m.text())); });
+  // A missing script, style, font or image breaks a scene; a fetch() may probe optional files (brand data) and handles its own 404.
+  probe.on('response', (r) => { const k = r.request().resourceType(); if (r.status() >= 400 && k !== 'fetch' && k !== 'xhr') errors.push(new Error(`${r.status()} ${r.url()}`)); });
+  await probe.goto(url);
+  const config = await waitReady(probe, errors);
+  await probe.close();
+
+  const context = await browser.newContext({ viewport: { width: config.width, height: config.height }, deviceScaleFactor: dpr });
+  const page = await context.newPage();
+  const errs = [];
+  page.on('pageerror', (e) => errs.push(e));
+  page.on('console', (m) => { if ((m.type() === 'error' || m.type() === 'warning') && !m.text().startsWith('Failed to load resource')) process.stderr.write(`[scene ${m.type()}] ${m.text()}\n`); });
+  await page.goto(url);
+  await waitReady(page, errs);
+  const cdp = await context.newCDPSession(page);
+  const capture = async () => {
+    const { data } = await cdp.send('Page.captureScreenshot', { format: 'png', optimizeForSpeed: true, captureBeyondViewport: false, fromSurface: true });
+    return Buffer.from(data, 'base64');
+  };
+  const seek = (t) => page.evaluate((tt) => window.__pm.seek(tt), t);
+  return { page, context, config, capture, seek, close: () => context.close() };
+}
+
+async function waitReady(page, errors, timeout = 60000) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (errors.length) throw new Error(`Scene error: ${errors[0].message}`);
+    const cfg = await page.evaluate(() => (window.__pm ? window.__pm.config : null)).catch(() => null);
+    if (cfg) return cfg;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error('Scene never became ready. Did you call `await s.start()`? Check the browser console in preview.');
+}

package/lib/catalog.mjs

@@ -0,0 +1,77 @@
+// Builds a catalog of every Paper shader: description, params with defaults, presets.
+import { register } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { moduleDir } from './modules.mjs';
+
+register('./react-hooks.mjs', import.meta.url);
+const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SIZING = ['fit', 'scale', 'rotation', 'originX', 'originY', 'offsetX', 'offsetY', 'worldWidth', 'worldHeight'];
+
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+
+function describe(name) {
+  const f = path.join(moduleDir('@paper-design/shaders') ?? path.join(ENGINE, 'node_modules/@paper-design/shaders'), 'dist/shaders', `${kebab(name)}.d.ts`);
+  if (!fs.existsSync(f)) return '';
+  const src = fs.readFileSync(f, 'utf8');
+  const m = src.match(/\/\*\*([\s\S]*?)\*\//);
+  if (!m) return '';
+  const lines = m[1].split('\n').map((l) => l.replace(/^\s*\*\s?/, '').trim());
+  const out = [];
+  for (const l of lines) { if (/uniforms:|^Fragment shader|^Vertex shader/i.test(l)) break; if (l) out.push(l); }
+  return out.join(' ');
+}
+
+function enums(name, mod) {
+  // Expose string options for enum-like params (shape, type, ...)
+  const out = {};
+  for (const [k, v] of Object.entries(mod)) {
+    if (k.startsWith(name.replace(/^Static/, '')) && /(Shapes|Types|Patterns|Grids|AspectRatios)$/.test(k) && v && typeof v === 'object') out[k] = Object.keys(v);
+  }
+  return out;
+}
+
+export async function buildCatalog() {
+  const R = await import('@paper-design/shaders-react');
+  const V = await import('@paper-design/shaders');
+  const names = Object.keys(R).filter((k) => /^[A-Z]/.test(k) && k !== 'ShaderMount' && typeof R[k] === 'function');
+  return names.map((name) => {
+    const presets = R[`${name[0].toLowerCase()}${name.slice(1)}Presets`] ?? [];
+    const def = presets[0]?.params ?? {};
+    const own = Object.fromEntries(Object.entries(def).filter(([k]) => !SIZING.includes(k)));
+    const GENERIC = { fit: ['none', 'contain'], scale: [1], rotation: [0], offsetX: [0], offsetY: [0], originX: [0.5], originY: [0.5], worldWidth: [0], worldHeight: [0] };
+    const sizing = Object.fromEntries(Object.entries(def).filter(([k, v]) => SIZING.includes(k) && !GENERIC[k].includes(v)));
+    const isImage = 'image' in own || /\bimage\s*=/.test(R[name].toString());
+    return {
+      name,
+      description: describe(name),
+      animated: (def.speed ?? 0) !== 0,
+      usesImage: isImage,
+      params: own,
+      sizing, // non-obvious sizing defaults, e.g. GodRays sits high (offsetY -0.55)
+      options: enums(name, V),
+      presets: presets.map((p) => ({ name: p.name, params: Object.fromEntries(Object.entries(p.params).filter(([k]) => !SIZING.includes(k) || p.params[k] !== def[k])) })),
+    };
+  });
+}
+
+export function catalogMarkdown(cat, version) {
+  const lines = [`# Paper Shaders catalog`, '', `Generated from @paper-design/shaders-react ${version}. Regenerate with \`paper-motion shaders --md\`.`, '',
+    'Every shader also accepts the sizing params: `fit` (none|contain|cover), `scale`, `rotation` (deg), `originX`, `originY`, `offsetX`, `offsetY`, `worldWidth`, `worldHeight`.',
+    'Motion params: `speed` (multiplier on scene time; 0 = still) and `frame` (start offset, ms).', '',
+    '| Shader | Animated | Image input | What it is |', '|---|---|---|---|',
+    ...cat.map((s) => `| [${s.name}](#${s.name.toLowerCase()}) | ${s.animated ? 'yes' : '—'} | ${s.usesImage ? 'yes' : '—'} | ${s.description.split('. ')[0].replace(/\|/g, '/')} |`), ''];
+  for (const s of cat) {
+    lines.push(`## ${s.name}`, '', s.description, '');
+    lines.push('Defaults:', '```js', JSON.stringify(s.params, null, 0).replace(/,"/g, ', "'), '```');
+    if (Object.keys(s.sizing).length) lines.push(`Sizing defaults that differ from neutral: \`${JSON.stringify(s.sizing)}\` — pass them explicitly (e.g. \`offsetY: 0\`) to re-center.`);
+    for (const [k, v] of Object.entries(s.options)) lines.push(`- \`${k}\`: ${v.map((x) => `\`${x}\``).join(', ')}`);
+    if (s.presets.length > 1) {
+      lines.push('', 'Presets:');
+      for (const p of s.presets.slice(1)) lines.push(`- **${p.name}**: \`${JSON.stringify(p.params).replace(/,"/g, ', "')}\``);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/lib/customize.mjs

@@ -0,0 +1,162 @@
+// Customizing a resource: the code for a set of param values. One module for both sides, so what the site shows
+// (its code tabs, "Copy for your agent") and what `pamo add <id> --set k=v` installs are always the same.
+// Plain ESM with no Node imports: the site copies this file and runs it in the browser.
+
+export const MOVE_TYPES = ['component', 'transition', 'text', 'camera'];
+
+/** Param defaults by name. */
+export const defaults = (item) => Object.fromEntries((item.params ?? []).map((p) => [p.name, p.default]));
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** Params whose value differs from the default. */
+export const changed = (item, values) => (item.params ?? []).filter((p) => p.name in values && !same(values[p.name], p.default));
+
+/** A JS literal: strings in single quotes, `ease.*` left as code, arrays and objects inline. */
+export function literal(v) {
+  if (typeof v === 'string') return /^ease\.\w+$/.test(v) ? v : `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  if (Array.isArray(v)) return `[${v.map(literal).join(', ')}]`;
+  if (v && typeof v === 'object') return `{ ${Object.entries(v).map(([k, x]) => `${k}: ${literal(x)}`).join(', ')} }`;
+  return String(v);
+}
+
+/** `--set key=value` arguments, shell-safe. */
+export function setArgs(item, values) {
+  return changed(item, values).map((p) => {
+    const v = values[p.name], raw = typeof v === 'string' ? v : JSON.stringify(v);
+    const arg = `${p.name}=${raw}`;
+    return /^[\w.=#,:/@+-]+$/.test(arg) ? `--set ${arg}` : `--set '${arg.replace(/'/g, "'\\''")}'`;
+  });
+}
+
+/** Parses `key=value` pairs (from the CLI) into values, JSON where it parses, strings otherwise. */
+export function parseSet(item, pairs) {
+  const out = defaults(item);
+  for (const pair of pairs) {
+    const i = pair.indexOf('=');
+    if (i < 0) throw new Error(`--set needs key=value, got "${pair}"`);
+    const k = pair.slice(0, i), raw = pair.slice(i + 1);
+    if (!(item.params ?? []).some((p) => p.name === k)) throw new Error(`"${item.id}" has no param "${k}" (params: ${(item.params ?? []).map((p) => p.name).join(', ')})`);
+    try { out[k] = JSON.parse(raw); } catch { out[k] = raw; }
+  }
+  return out;
+}
+
+// ── per type ────────────────────────────────────────────────────
+
+const gf = (family, weights) => `https://fonts.googleapis.com/css2?family=${family.replace(/ /g, '+')}${weights?.length ? `:wght@${[...new Set(weights)].sort((a, b) => a - b).join(';')}` : ''}&display=swap`;
+
+/** A move file with the values written in as its defaults (only inside the exported function's options). */
+function moveFile(item, content, values) {
+  const name = item.export, start = content.indexOf(`export function ${name}(`);
+  if (start < 0) return content;
+  const end = content.indexOf(') {', start);
+  let sig = content.slice(start, end);
+  for (const p of changed(item, values)) sig = sig.replace(new RegExp(`(\\b${p.name}\\s*=\\s*)(\\[[^\\]]*\\]|'[^']*'|"[^"]*"|[^,}]+?)(\\s*)(?=[,}])`), `$1${literal(values[p.name])}$3`);
+  return content.slice(0, start) + sig + content.slice(end);
+}
+
+function backgroundEntry(item, values) {
+  const e = item.install.entry ?? {};
+  return { ...e, props: { ...e.props, ...Object.fromEntries((item.params ?? []).map((p) => [p.name, values[p.name] ?? p.default])) } };
+}
+
+function paletteTokens(item, values) {
+  const e = item.install.entry ?? {};
+  const colors = Object.fromEntries(Object.entries(e.colors ?? {}).map(([role, c]) => [role, { ...c, hex: values[role] ?? c.hex }]));
+  return { ...e, colors, ramp: values.ramp ?? e.ramp };
+}
+
+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) }; };
+  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 };
+}
+
+/** A recipe's CONFIG object from flat values (proof1Title… → proof[0].title, "1920x1080" → [1920, 1080]). */
+function recipeConfig(values) {
+  const cfg = {}, groups = {};
+  for (const [k, v] of Object.entries(values)) {
+    const m = k.match(/^(proof|step)(\d)(Label|Title|Body)$/);
+    if (m) { const g = m[1] === 'proof' ? 'proof' : 'steps'; (groups[g] ??= [])[m[2] - 1] ??= {}; groups[g][m[2] - 1][m[3].toLowerCase()] = v; continue; }
+    if (k === 'format') cfg.format = String(v).split('x').map(Number);
+    else cfg[k] = v === '' ? null : v;
+  }
+  return { ...cfg, ...groups };
+}
+
+function recipeScene(content, values) {
+  const cfg = recipeConfig(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'
+    ? `  ${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)}`;
+}
+
+// ── the public API ──────────────────────────────────────────────
+
+/**
+ * Applies values to a resolved resource (files with content): returns the files and install entry that
+ * `pamo add --set` writes, the same ones the site's File / entry tabs show.
+ */
+export function apply(item, values) {
+  const v = { ...defaults(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) };
+    return f;
+  });
+  let entry = item.install?.entry;
+  if (item.type === 'background') entry = backgroundEntry(item, v);
+  if (item.type === 'palette') entry = paletteTokens(item, v);
+  if (item.type === 'font-pair') entry = fontTokens(item, v);
+  return { files, install: { ...item.install, ...(entry ? { entry } : {}) } };
+}
+
+/** The code tabs, the change count and the agent prompt for a resource at these values. */
+export function code(item, values, { showAll = false, site = 'https://paper-motion.app' } = {}) {
+  const v = { ...defaults(item), ...values }, diff = changed(item, v), out = apply(item, v);
+  const args = setArgs(item, v);
+  const agent = `Use the paper-motion resource "${item.id}" (${site}/r/${item.id}.json) in my video. Install it with: npx paper-motion add ${item.id}${args.length ? ` ${args.join(' ')}` : ''}`;
+  let tabs = [];
+  if (MOVE_TYPES.includes(item.type)) {
+    const listed = showAll ? (item.params ?? []).filter((p) => !p.hidden) : diff;
+    const head = ((item.signature ?? '').match(/\(([^{)]*)/)?.[1] ?? 'a, b, p').replace(/,\s*$/, '').trim();
+    const file = out.files.find((f) => f.content !== undefined);
+    const opts = listed.length ? `, { ${listed.map((p) => `${p.name}: ${literal(v[p.name])}`).join(', ')} }` : '';
+    tabs = [
+      { key: 'usage', label: 'Usage', lang: 'js', code: `import { ${item.export} } from './${file?.path ?? `moves/${item.id}.js`}';\n\n// in s.update(t)\n${item.export}(${head}${opts});` },
+      { key: 'file', label: 'File', lang: 'js', code: file?.content ?? '' },
+    ];
+  } else if (item.type === 'background') {
+    const e = out.install.entry, shader = e.shader;
+    tabs = [
+      { key: 'entry', label: 'set.json entry', lang: 'json', code: JSON.stringify({ id: item.id, ...e }, null, 2) },
+      { key: 'usage', label: 'Usage', lang: 'js', code: `import { loadBrand } from 'paper-motion/brand';\n\nconst B = await loadBrand();\nB.shader(s, '#bg', '${item.id}');` },
+      { key: 'react', label: 'Paper React', lang: 'jsx', code: `import { ${shader} } from '@paper-design/shaders-react';\n\n<${shader}\n${Object.entries(e.props).map(([k, x]) => `  ${k}={${typeof x === 'string' ? JSON.stringify(x) : JSON.stringify(x)}}`).join('\n')}\n  style={{ width: '100%', height: '100%' }}\n/>` },
+    ];
+  } else if (item.type === 'palette') {
+    const e = out.install.entry;
+    tabs = [
+      { key: 'tokens', label: 'tokens.json', lang: 'json', code: JSON.stringify({ colors: e.colors, ramp: e.ramp, mode: e.mode }, null, 2) },
+      { key: 'css', label: 'CSS variables', lang: 'css', code: `:root {\n${Object.entries(e.colors).map(([r, c]) => `  --${r}: ${c.hex};`).join('\n')}\n${(e.ramp ?? []).map((h, i) => `  --ramp-${i + 1}: ${h};`).join('\n')}\n}` },
+    ];
+  } else if (item.type === 'font-pair') {
+    const e = out.install.entry, f = e.fonts;
+    const cat = (fam) => (/mono|code/i.test(fam) ? 'monospace' : /serif|playfair|fraunces|garamond|newsreader|instrument/i.test(fam) && !/sans/i.test(fam) ? 'serif' : 'sans-serif');
+    tabs = [
+      { 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') {
+    const scene = out.files.find((f) => /scene\.html$/.test(f.path));
+    tabs = [{ key: 'scene', label: 'scene.html', lang: 'html', code: scene?.content ?? '' }];
+  }
+  return { tabs, changed: diff.length, agent, setArgs: args };
+}

package/lib/keys.mjs

@@ -0,0 +1,93 @@
+// Keystroke banks: split a recording of real typing into single hits, so the `key` sound effect can play
+// real keystrokes instead of synthesized ones. Any audio ffmpeg reads (mp3, m4a, wav, mp4...).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const SR = 48000;
+
+/** Decode any audio file to mono Float32 at 48 kHz. */
+export function decode(file) {
+  const r = spawnSync('ffmpeg', ['-v', 'error', '-i', file, '-ac', '1', '-ar', String(SR), '-f', 'f32le', '-'], { maxBuffer: 1 << 30 });
+  if (r.status !== 0) throw new Error(`could not decode ${file}: ${r.stderr}`);
+  return new Float32Array(r.stdout.buffer, r.stdout.byteOffset, r.stdout.byteLength / 4).slice();
+}
+
+/** 16-bit mono WAV. */
+export function writeMonoWav(file, data) {
+  const buf = Buffer.alloc(44 + data.length * 2);
+  buf.write('RIFF', 0); buf.writeUInt32LE(36 + data.length * 2, 4); buf.write('WAVE', 8); buf.write('fmt ', 12);
+  buf.writeUInt32LE(16, 16); buf.writeUInt16LE(1, 20); buf.writeUInt16LE(1, 22); buf.writeUInt32LE(SR, 24);
+  buf.writeUInt32LE(SR * 2, 28); buf.writeUInt16LE(2, 32); buf.writeUInt16LE(16, 34); buf.write('data', 36); buf.writeUInt32LE(data.length * 2, 40);
+  for (let i = 0; i < data.length; i++) buf.writeInt16LE(Math.round(Math.max(-1, Math.min(1, data[i])) * 32767), 44 + i * 2);
+  fs.writeFileSync(file, buf);
+}
+
+/**
+ * Find keystroke onsets with a fast/slow energy ratio, then cut each hit until just before the next.
+ * @returns {{ hits: {file, t, dur, peak, low}[] }}
+ */
+export function extractKeys(input, outDir, { minGap = 0.055, maxLen = 0.28, sensitivity = 1 } = {}) {
+  const x = decode(input);
+  // envelope: fast (1.5 ms) vs slow (40 ms) RMS; an onset is where the fast one jumps above the slow one
+  const fast = new Float32Array(x.length), slow = new Float32Array(x.length);
+  const af = Math.exp(-1 / (0.0015 * SR)), as = Math.exp(-1 / (0.04 * SR));
+  let f = 0, s = 0, peakAll = 1e-9;
+  for (let i = 0; i < x.length; i++) {
+    const e = x[i] * x[i];
+    f = af * f + (1 - af) * e; s = as * s + (1 - as) * e;
+    fast[i] = Math.sqrt(f); slow[i] = Math.sqrt(s);
+    peakAll = Math.max(peakAll, fast[i]);
+  }
+  const floor = peakAll * 0.04 / sensitivity, gap = Math.round(minGap * SR);
+  const onsets = [];
+  for (let i = 1; i < x.length; i++) {
+    if (fast[i] > floor && fast[i] > slow[i] * (2.2 / sensitivity) && (!onsets.length || i - onsets[onsets.length - 1] > gap)) onsets.push(i);
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+  const hits = [];
+  onsets.forEach((o, k) => {
+    const a = Math.max(0, o - Math.round(0.004 * SR));
+    const end = Math.min(x.length, k + 1 < onsets.length ? onsets[k + 1] - Math.round(0.006 * SR) : x.length, a + Math.round(maxLen * SR));
+    if (end - a < 0.03 * SR) return;
+    const seg = x.slice(a, end);
+    // fade in 2 ms, fade out the last 25 %, normalize to 0.9
+    let pk = 1e-9; for (const v of seg) pk = Math.max(pk, Math.abs(v));
+    const fi = Math.round(0.002 * SR), fo = Math.round(seg.length * 0.25);
+    for (let i = 0; i < seg.length; i++) {
+      const g = Math.min(1, i / fi) * Math.min(1, (seg.length - i) / fo);
+      seg[i] = (seg[i] / pk) * 0.9 * g;
+    }
+    // a rough "weight": share of energy under 400 Hz (spacebars and enters are heavier)
+    let lo = 0, all = 0, y = 0; const c = Math.exp(-2 * Math.PI * 400 / SR);
+    for (const v of seg) { y = (1 - c) * v + c * y; lo += y * y; all += v * v; }
+    const name = `key-${String(hits.length + 1).padStart(3, '0')}.wav`;
+    writeMonoWav(path.join(outDir, name), seg);
+    hits.push({ file: name, t: +(a / SR).toFixed(3), dur: +(seg.length / SR).toFixed(3), peak: +pk.toFixed(3), low: +(lo / Math.max(all, 1e-12)).toFixed(3) });
+  });
+  // the heaviest fifth become the space/enter pool
+  const byLow = [...hits].sort((p, q) => q.low - p.low);
+  const heavy = new Set(byLow.slice(0, Math.max(1, Math.round(hits.length / 5))).map((h) => h.file));
+  for (const h of hits) h.kind = heavy.has(h.file) ? 'heavy' : 'letter';
+  fs.writeFileSync(path.join(outDir, 'keys.json'), JSON.stringify({ source: path.basename(input), sampleRate: SR, hits }, null, 1) + '\n');
+  return { hits };
+}
+
+const banks = new Map();
+/** Load a bank folder written by extractKeys: { letter: Float32Array[], heavy: Float32Array[] }. */
+export function loadBank(dir) {
+  const abs = path.resolve(dir);
+  if (banks.has(abs)) return banks.get(abs);
+  const meta = JSON.parse(fs.readFileSync(path.join(abs, 'keys.json'), 'utf8'));
+  const bank = { letter: [], heavy: [] };
+  for (const h of meta.hits) {
+    const b = fs.readFileSync(path.join(abs, h.file));
+    const n = (b.length - 44) / 2, d = new Float32Array(n);
+    for (let i = 0; i < n; i++) d[i] = b.readInt16LE(44 + i * 2) / 32768;
+    (h.kind === 'heavy' ? bank.heavy : bank.letter).push(d);
+  }
+  if (!bank.letter.length) bank.letter = bank.heavy;
+  if (!bank.heavy.length) bank.heavy = bank.letter;
+  banks.set(abs, bank);
+  return bank;
+}

package/lib/live-board.js

@@ -0,0 +1,128 @@
+// A board: 2–4 labelled options the agent proposes, carried in a paper-motion.app link so the user can see them
+// live in their own look, tune one and choose. Nothing reaches a server: the payload travels in the URL fragment.
+//   https://paper-motion.app/b#<base64url(deflate-raw(JSON))>
+// This module runs in Node (`pamo board --url`) and in the browser (the /b page), so it has no Node imports: it
+// picks zlib or CompressionStream at call time. Plain ESM; the site copies it next to customize.mjs.
+
+// (lib/board.mjs is the other kind of board: the rendered one, stills and clips composed by ffmpeg.)
+
+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'];
+
+/**
+ * @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
+ */
+
+/** Checks a board's shape; returns a list of problems (empty when valid). `index` (registry items by id) adds id checks. */
+export function validateBoard(b, index) {
+  const errs = [];
+  if (!b || typeof b !== 'object') return ['not an object'];
+  if (b.v !== BOARD_VERSION) errs.push(`v must be ${BOARD_VERSION}`);
+  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');
+  const seen = new Set();
+  for (const [i, o] of (b.options ?? []).entries()) {
+    const at = `options[${i}]`;
+    if (!LABELS.includes(o.label)) errs.push(`${at}.label must be A–D`);
+    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`);
+      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`);
+      for (const it of o.items ?? []) if (index && !index[it.id]) errs.push(`${at}: "${it.id}" is not in the registry`);
+    }
+    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));
+    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;
+}
+
+// ── compression, both runtimes ──────────────────────────────────
+
+const b64url = {
+  enc: (bytes) => (typeof Buffer !== 'undefined' ? Buffer.from(bytes).toString('base64url') : btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')),
+  dec: (s) => { const b = s.replace(/-/g, '+').replace(/_/g, '/'); if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(b, 'base64')); const bin = atob(b); return Uint8Array.from(bin, (c) => c.charCodeAt(0)); },
+};
+
+async function deflate(bytes) {
+  if (typeof CompressionStream === 'function') {
+    const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream('deflate-raw'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+  }
+  const { deflateRawSync } = await import('node:zlib');
+  return new Uint8Array(deflateRawSync(bytes));
+}
+async function inflate(bytes) {
+  if (typeof DecompressionStream === 'function') {
+    const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('deflate-raw'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+  }
+  const { inflateRawSync } = await import('node:zlib');
+  return new Uint8Array(inflateRawSync(bytes));
+}
+
+/** Board → the fragment string (no leading #). Throws when invalid or over the size budget. */
+export async function encodeBoard(board, index) {
+  const errs = validateBoard(board, index);
+  if (errs.length) throw new Error(`board: ${errs.join('; ')}`);
+  const json = JSON.stringify(board);
+  if (json.length > MAX_PAYLOAD) throw new Error(`board: ${json.length} bytes of JSON, the limit is ${MAX_PAYLOAD}`);
+  return b64url.enc(await deflate(new TextEncoder().encode(json)));
+}
+
+/** Fragment string → board. Throws on a bad or oversized payload. */
+export async function decodeBoard(fragment) {
+  const s = fragment.replace(/^#/, '');
+  if (!s) throw new Error('empty board');
+  if (s.length > MAX_PAYLOAD * 2) throw new Error('board link too long');
+  const json = new TextDecoder().decode(await inflate(b64url.dec(s)));
+  const board = JSON.parse(json);
+  const errs = validateBoard(board);
+  if (errs.length) throw new Error(`board: ${errs.join('; ')}`);
+  return board;
+}
+
+export const boardUrl = (site, fragment) => `${site.replace(/\/$/, '')}/b#${fragment}`;
+
+// ── the reply line ──────────────────────────────────────────────
+// What the user pastes back in the chat. One line, starts with "paper-motion:", so an agent can spot and parse it.
+//   paper-motion: A · mesh-sage                                   chose A as proposed
+//   paper-motion: B · mesh-sage --set speed=0.8 --set colors=[…]  chose B, tuned
+//   paper-motion: none of bg-1, show me calmer ones               none; free text after the comma
+//   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.
+
+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}`;
+}
+
+/** Parses a reply line the user pasted. Returns null when the text is not one. */
+export function parseReply(text) {
+  const m = String(text).match(/paper-motion:\s*(.+)$/m);
+  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 };
+}