paper-motion 0.1.0 → 0.2.0

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/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 };
+}

package/lib/registry.mjs

@@ -0,0 +1,344 @@
+// The paper-motion registry: resources (moves, backgrounds, palettes, font pairs, recipes) that agents pick by
+// name and install into a project as editable code or brand files. Source: registry/<type>/<id>/item.json in the
+// repo. `build` publishes it for the site (registry.json, r/<id>.json, llms.txt); `add` installs from a local
+// registry folder or from the site.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { apply as applyValues, parseSet } from './customize.mjs';
+
+const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REPO = path.resolve(ENGINE, '..', '..');
+export const SITE = (process.env.PAPER_MOTION_SITE ?? 'https://paper-motion.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' };
+
+/** 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) {
+  const r = given ?? process.env.PAPER_MOTION_REGISTRY;
+  if (r) return /^https?:\/\//.test(r) ? { url: r.replace(/\/$/, '') } : { dir: path.resolve(r) };
+  const local = path.join(REPO, 'registry');
+  return fs.existsSync(path.join(local, 'schema.json')) ? { dir: local } : { url: SITE };
+}
+
+// ── reading and validating ──────────────────────────────────────
+
+export function loadItems(dir) {
+  const out = [];
+  for (const type of fs.readdirSync(dir)) {
+    const td = path.join(dir, type);
+    if (!fs.statSync(td).isDirectory() || type.startsWith('_')) continue;
+    for (const id of fs.readdirSync(td)) {
+      const f = path.join(td, id, 'item.json');
+      if (fs.existsSync(f)) out.push({ ...JSON.parse(fs.readFileSync(f, 'utf8')), _dir: path.join(td, id) });
+    }
+  }
+  return out.sort((a, b) => TYPES.indexOf(a.type) - TYPES.indexOf(b.type) || a.id.localeCompare(b.id));
+}
+
+/** A small JSON Schema check (the subset registry/schema.json uses). Returns a list of problems. */
+function check(value, schema, at = '') {
+  const errs = [];
+  const t = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+  if (schema.type && schema.type !== t && !(schema.type === 'integer' && t === 'number' && Number.isInteger(value))) return [`${at || '/'}: expected ${schema.type}, got ${t}`];
+  if (schema.type === 'integer') { if (schema.minimum !== undefined && value < schema.minimum) errs.push(`${at}: below ${schema.minimum}`); if (schema.maximum !== undefined && value > schema.maximum) errs.push(`${at}: above ${schema.maximum}`); }
+  if (schema.enum && !schema.enum.includes(value)) errs.push(`${at}: "${value}" is not one of ${schema.enum.join(', ')}`);
+  if (t === 'string') {
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) errs.push(`${at}: "${value}" does not match ${schema.pattern}`);
+    if (schema.maxLength && value.length > schema.maxLength) errs.push(`${at}: longer than ${schema.maxLength} characters`);
+  }
+  if (t === 'array') {
+    if (schema.minItems && value.length < schema.minItems) errs.push(`${at}: needs at least ${schema.minItems} items`);
+    if (schema.items) value.forEach((v, i) => errs.push(...check(v, schema.items, `${at}/${i}`)));
+  }
+  if (t === 'object') {
+    for (const k of schema.required ?? []) if (!(k in value)) errs.push(`${at}/${k}: required`);
+    for (const [k, v] of Object.entries(value)) {
+      if (schema.properties?.[k]) errs.push(...check(v, schema.properties[k], `${at}/${k}`));
+      else if (schema.additionalProperties === false && !k.startsWith('_')) errs.push(`${at}/${k}: not allowed`);
+    }
+  }
+  return errs;
+}
+
+export function validate(dir) {
+  const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'));
+  const items = loadItems(dir), ids = new Set(), problems = [];
+  for (const it of items) {
+    const where = path.relative(REPO, it._dir);
+    for (const e of check(it, schema)) problems.push(`${where}: ${e}`);
+    if (ids.has(it.id)) problems.push(`${where}: duplicate id "${it.id}"`);
+    ids.add(it.id);
+    if (path.basename(it._dir) !== it.id) problems.push(`${where}: folder name must equal id "${it.id}"`);
+    if (path.basename(path.dirname(it._dir)) !== it.type) problems.push(`${where}: lives under ${path.basename(path.dirname(it._dir))}/ but type is "${it.type}"`);
+    for (const f of it.files ?? []) if (!fs.existsSync(path.join(REPO, f.from))) problems.push(`${where}: missing file ${f.from}`);
+  }
+  for (const it of items) for (const r of [...(it.requires?.items ?? []), ...(it.related ?? [])]) if (!ids.has(r)) problems.push(`${it.id}: refers to unknown resource "${r}"`);
+  return { items, problems };
+}
+
+// ── publishing ──────────────────────────────────────────────────
+
+/** Imports inside the repo point at the runtime; in a user's project they point at the package. */
+export const rewriteImports = (code) => code.replace(/(['"])\.\.\/(index|core)\.js\1/g, "'paper-motion'").replace(/(['"])\.\.\/kit\.js\1/g, "'paper-motion/kit'");
+
+const BINARY = /\.(png|jpe?g|webp|gif|avif|woff2?|ttf|otf|mp4|webm)$/i;
+
+/**
+ * The full resource as served at r/<id>.json: the item plus its files, ready to write. Text files carry their content;
+ * binary files (images, fonts) carry a URL under <site>/files/ instead.
+ */
+export function resolveItem(it, site = SITE) {
+  const { _dir, ...item } = it;
+  return { ...item, files: (it.files ?? []).map((f) => (BINARY.test(f.from)
+    ? { path: f.to, url: `${site}/files/${path.basename(f.from)}`, from: f.from }
+    : { path: f.to, content: rewriteImports(fs.readFileSync(path.join(REPO, f.from), 'utf8')) })) };
+}
+
+const summaryLine = (it, site) => `- [${it.title}](${site}/r/${it.id}.json): ${it.summary}${it.tags?.length ? ` _(${it.tags.filter((t) => t !== it.type).join(', ')})_` : ''}`;
+
+export function llmsTxt(items, site, { full = false } = {}) {
+  const head = `# paper-motion
+
+> Motion resources for AI agents: component transitions, transitions, text effects, camera moves, backgrounds
+> (Paper shaders), palettes, font pairs and video recipes, each with a name. You pick them for the user's brand,
+> propose options as a **board** link they open in a browser, install what they choose as code they own, and render
+> the video with the paper-motion engine. Nothing here renders on a server: every preview plays in the user's browser.
+
+## 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\`.
+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.
+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). The user opens it, sees the options live in their look, may tune one, and pastes back one line:
+   \`paper-motion: B · mesh-sage --set speed=0.8 (bg-1)\`, 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.
+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,
+   whose prompt carries the whole \`pamo add\` command.
+5. **Make the video.** 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
+
+${site}/registry.json is the index; every item carries, beside id, type, title, summary, tags and the names of its
+\`params\` (ranges and defaults are in ${site}/r/<id>.json, fetch it before writing a \`--set\`):
+- \`when\`: 2–3 "use it when…" phrases.
+- \`mood\`: calm, bold, playful, technical, editorial, warm, minimal, luxury, raw.
+- Moves: \`energy\` 1 (still) to 5 (violent) and \`role\` (enter, exit, swap, emphasis, camera, text).
+- Backgrounds and palettes: \`colors\` (dominant hex) and \`mode\` (light, dark); backgrounds also \`motion\` (still, gentle, lively).
+- Font pairs: \`voice\` (serif, sans, display, mono). Recipes: \`duration\`, \`formats\`.
+
+\`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
+ground, figure and accent so resources with white type are not punished); \`pamo search --type component --mood calm
+--energy "<=3" --role swap\`.
+
+Worked example, four backgrounds for a dark cobalt brand: filter \`type=background\`, \`mode=dark\`; rank by nearest
+\`colors\` to the brand's ground, figure and accent; spread the \`motion\` as far as the catalog allows (a quiet one,
+a lively one); prefer
+\`mood\` overlapping the brand's words; tune one toward the accent (\`dither-slate:colorFront=#3d6bff\`); write a
+one-line \`--note\` for each; share the link.
+
+## The board link format
+
+\`${site}/b#<payload>\` where payload = base64url(deflate-raw(JSON)). The JSON:
+
+\`\`\`json
+{ "v": 1, "kind": "resource", "title": "Backgrounds for Kiln", "ask": "Which one feels like the product?",
+  "reply": "bg-1",
+  "look": { "palette": { "id": "cobalt", "values": {} }, "font": { "id": "geist", "values": {} } },
+  "options": [
+    { "label": "A", "id": "mesh-graphite", "values": {}, "note": "quiet, graphite" },
+    { "label": "B", "id": "neuro-slate", "values": {}, "note": "a technical web" },
+    { "label": "C", "id": "dither-slate", "values": { "colorFront": "#3d6bff" }, "note": "pixels in your accent" },
+    { "label": "D", "id": "grain-slate", "values": {} } ] }
+\`\`\`
+
+Rules: 2–4 options, labels A–D, 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.
+
+Resources by type (${items.length} in all):
+`;
+  const sections = TYPES.filter((t) => items.some((i) => i.type === t)).map((t) => {
+    const list = items.filter((i) => i.type === t);
+    if (!full) return `\n## ${TYPE_TITLES[t]}\n\n${list.map((i) => summaryLine(i, site)).join('\n')}\n`;
+    return `\n## ${TYPE_TITLES[t]}\n\n${list.map((i) => [
+      `### ${i.title} · \`${i.id}\``, '', i.summary, '',
+      i.signature ? `Signature: \`${i.signature}\`` : '',
+      i.params?.length ? `Params: ${i.params.map((p) => `\`${p.name}\`${p.default !== undefined ? ` = ${JSON.stringify(p.default)}` : ''}${p.description ? ` (${p.description})` : ''}`).join('; ')}` : '',
+      i.notes?.length ? i.notes.map((n) => `- ${n}`).join('\n') : '',
+      `Install: \`npx paper-motion add ${i.id}\` · ${site}/r/${i.id}.json`, '',
+      '```js', i.usage, '```', '',
+    ].filter((x) => x !== '').join('\n')).join('\n\n')}\n`;
+  });
+  return head + sections.join('');
+}
+
+/**
+ * The site's live player: the moves, kit and core (browser-safe), the demo harness with its imports pointed at them,
+ * its stylesheet scoped to `.pm-play`, and its fonts. The site imports them at runtime from /play/.
+ */
+function publishPlayer(dir, out) {
+  const RT = path.join(ENGINE, 'runtime'), demo = path.join(dir, '_demo');
+  fs.rmSync(out, { recursive: true, force: true });
+  fs.mkdirSync(path.join(out, 'engine', 'moves'), { recursive: true });
+  for (const f of ['core.js', 'kit.js', 'moves.js']) fs.copyFileSync(path.join(RT, f), path.join(out, 'engine', f));
+  for (const f of fs.readdirSync(path.join(RT, 'moves'))) fs.copyFileSync(path.join(RT, 'moves', f), path.join(out, 'engine', 'moves', f));
+  const js = fs.readFileSync(path.join(demo, 'demos.js'), 'utf8')
+    .replace(/import \{ scene, ([^}]*) \} from 'paper-motion';/, "import { $1 } from './engine/core.js';\nconst scene = () => { throw new Error('the site mounts demos with mount()'); };")
+    .replace(/from 'paper-motion\/moves'/g, "from './engine/moves.js'");
+  fs.writeFileSync(path.join(out, 'demos.js'), js);
+  const css = fs.readFileSync(path.join(demo, 'demo.css'), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/^([^@\s{][^{]*)\{/gm, (m, sel) => `${sel.split(',').map((x) => (x.trim().startsWith('#stage') ? x.replace('#stage', '.pm-play') : `.pm-play ${x.trim()}`)).join(', ')} {`);
+  fs.writeFileSync(path.join(out, 'demo.css'), css);
+  fs.mkdirSync(path.join(out, 'fonts'), { recursive: true });
+  for (const f of fs.readdirSync(path.join(demo, 'fonts'))) fs.copyFileSync(path.join(demo, 'fonts', f), path.join(out, 'fonts', f));
+}
+
+/** Writes registry.json, r/<id>.json, schema.json, llms.txt and llms-full.txt into `out`. */
+export function build({ dir = resolveRegistry().dir, out, site = SITE } = {}) {
+  const { items, problems } = validate(dir);
+  if (problems.length) { const e = new Error(`registry: ${problems.length} problem(s)\n  ${problems.join('\n  ')}`); e.problems = problems; throw e; }
+  fs.mkdirSync(path.join(out, 'r'), { recursive: true });
+  // publish only the preview files that were rendered: a background plays live and may have none
+  for (const it of items) if (it.preview) { const have = Object.fromEntries(Object.entries(it.preview).filter(([, p]) => fs.existsSync(path.join(out, p)))); it.preview = Object.keys(have).length ? 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)) })),
+  };
+  fs.writeFileSync(path.join(out, 'registry.json'), JSON.stringify(index, null, 2));
+  fs.mkdirSync(path.join(out, 'files'), { recursive: true });
+  for (const it of items) {
+    fs.writeFileSync(path.join(out, 'r', `${it.id}.json`), JSON.stringify(resolveItem(it, site), null, 2));
+    for (const f of it.files ?? []) if (BINARY.test(f.from)) fs.copyFileSync(path.join(REPO, f.from), path.join(out, 'files', path.basename(f.from)));
+  }
+  fs.copyFileSync(path.join(dir, 'schema.json'), path.join(out, 'schema.json'));
+  publishPlayer(dir, path.join(out, 'play'));
+  fs.writeFileSync(path.join(out, 'llms.txt'), llmsTxt(items, site));
+  fs.writeFileSync(path.join(out, 'llms-full.txt'), llmsTxt(items, site, { full: true }));
+  return { count: items.length, out };
+}
+
+// ── installing ──────────────────────────────────────────────────
+
+async function fetchJson(url) {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`${url}: ${r.status} ${r.statusText}`);
+  return r.json();
+}
+
+/** One resolved resource (with file contents) from a local folder or the site. */
+export async function getItem(id, reg = resolveRegistry()) {
+  if (reg.dir) {
+    const it = loadItems(reg.dir).find((i) => i.id === id);
+    if (!it) throw new Error(`no resource "${id}" in ${reg.dir} (try \`pamo search\`)`);
+    return resolveItem(it);
+  }
+  return fetchJson(`${reg.url}/r/${id}.json`);
+}
+
+export async function getIndex(reg = resolveRegistry()) {
+  if (reg.dir) return { items: loadItems(reg.dir).map(({ _dir, ...i }) => i) };
+  return fetchJson(`${reg.url}/registry.json`);
+}
+
+const readJson = (f, fallback) => (fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')) : fallback);
+const writeJson = (f, v) => { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(v, null, 2) + '\n'); };
+
+/** Deep-merges `frag` into `base`; keys that already hold a different value are reported, and replaced only with force. */
+function mergeInto(base, frag, force, at = '', conflicts = []) {
+  for (const [k, v] of Object.entries(frag)) {
+    const key = at ? `${at}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object' && !Array.isArray(base[k])) mergeInto(base[k], v, force, key, conflicts);
+    else if (base[k] !== undefined && JSON.stringify(base[k]) !== JSON.stringify(v)) { conflicts.push(key); if (force) base[k] = v; }
+    else base[k] = v;
+  }
+  return conflicts;
+}
+
+/**
+ * Installs resources into the project at `cwd`, resolving `requires.items` first. Returns a report per resource.
+ * Never overwrites a changed file or a different brand value unless `force`.
+ */
+export async function add(ids, { cwd = process.cwd(), registry, force = false, name, set = [] } = {}) {
+  const reg = resolveRegistry(registry), done = new Map(), report = [];
+  const lockFile = path.join(cwd, 'paper-motion.json'), lock = readJson(lockFile, { registry: reg.url ?? 'local', items: {} });
+  async function one(id) {
+    if (done.has(id)) return;
+    done.set(id, true);
+    let it = await getItem(id, reg);
+    for (const dep of it.requires?.items ?? []) await one(dep);
+    // --set key=value (or --set id:key=value with several ids): the same output the site's code tabs show
+    const pairs = set.filter((x) => (x.includes(':') && x.indexOf(':') < x.indexOf('=') ? x.startsWith(`${id}:`) : ids.length === 1 && ids[0] === id)).map((x) => (x.startsWith(`${id}:`) ? x.slice(id.length + 1) : x));
+    if (pairs.length) it = { ...it, ...applyValues(it, parseSet(it, pairs)) };
+    const r = { id, type: it.type, wrote: [], skipped: [], conflicts: [], usage: it.usage, notes: it.notes ?? [] };
+    const kind = it.install?.kind ?? 'code';
+    const base = kind === 'scene' ? path.join('pieces', name ?? it.id) : '';
+    for (const f of it.files ?? []) {
+      const rel = kind === 'scene' ? path.join(base, path.basename(f.path)) : f.path, dest = path.join(cwd, rel);
+      if (f.content === undefined) {
+        // a binary asset: kept if present, else copied from the local registry or downloaded from the site
+        if (fs.existsSync(dest) && !force) continue;
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        if (reg.dir && f.from && fs.existsSync(path.join(REPO, f.from))) fs.copyFileSync(path.join(REPO, f.from), dest);
+        else { const res = await fetch(f.url); if (!res.ok) throw new Error(`${f.url}: ${res.status}`); fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer())); }
+        r.wrote.push(rel); continue;
+      }
+      if (fs.existsSync(dest) && fs.readFileSync(dest, 'utf8') !== f.content && !force) { r.skipped.push(rel); continue; }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, f.content);
+      r.wrote.push(rel);
+    }
+    if (kind === 'shader-set') {
+      const f = path.join(cwd, 'brand/shader-set/set.json'), set = readJson(f, { format: { width: 1920, height: 1080, duration: 6, fps: 30 }, entries: [] });
+      set.entries ??= [];
+      const entry = { id: it.id, source: 'paper-motion.app', ...it.install.entry }, at = set.entries.findIndex((e) => e.id === it.id);
+      if (at < 0) set.entries.push(entry);
+      else if (JSON.stringify(set.entries[at]) !== JSON.stringify(entry)) { if (force) set.entries[at] = entry; else r.conflicts.push(`shader-set entry "${it.id}" already exists`); }
+      writeJson(f, set); r.wrote.push('brand/shader-set/set.json');
+    }
+    if (kind === 'tokens') {
+      const f = path.join(cwd, 'brand/tokens.json'), tokens = readJson(f, {});
+      r.conflicts.push(...mergeInto(tokens, it.install.entry ?? {}, force).map((k) => `brand/tokens.json ${k}`));
+      writeJson(f, tokens); r.wrote.push('brand/tokens.json');
+    }
+    lock.items[it.id] = it.version;
+    report.push(r);
+  }
+  for (const id of ids) await one(id);
+  writeJson(lockFile, lock);
+  return report;
+}
+
+const rgb = (h) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16));
+/** Distance between two hex colors (0 = same, ~441 = black to white). */
+export const colorDistance = (a, b) => { const x = rgb(a), y = rgb(b); return Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2]); };
+/** How far a resource's colors sit from a brand's: the mean nearest distance (lower is closer). */
+export const colorFit = (item, brand) => {
+  if (!item.colors?.length || !brand.length) return null;
+  const mean = item.colors.reduce((s, c) => s + Math.min(...brand.map((b) => colorDistance(c, b))), 0) / item.colors.length;
+  // a resource that declares one or two colors is thin evidence of a match: nudge it behind real palettes
+  return mean + (item.colors.length < 3 ? 40 * (3 - item.colors.length) : 0);
+};
+
+/**
+ * Finds resources: free words over id/title/summary/tags/when, plus filters: type, mode (light|dark), mood,
+ * motion (still|gentle|lively), role, energy ("3", "2-4", "<=3"), near (hex colors: sorts by closeness).
+ */
+export async function search(query, opts = {}) {
+  const { items } = await getIndex(resolveRegistry(opts.registry));
+  const words = String(query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+  const hit = (i) => { const hay = [i.id, i.type, i.title, i.summary, ...(i.tags ?? []), ...(i.when ?? []), ...(i.mood ?? [])].join(' ').toLowerCase(); return words.every((w) => hay.includes(w)); };
+  const en = (v) => { if (!opts.energy) return true; const e = String(opts.energy), m = e.match(/^(\d)-(\d)$/); if (m) return v >= +m[1] && v <= +m[2]; if (e.startsWith('<=')) return v <= +e.slice(2); if (e.startsWith('>=')) return v >= +e.slice(2); return v === +e; };
+  const near = opts.near ? String(opts.near).split(',').map((c) => c.trim()).filter((c) => /^#[0-9a-f]{6}$/i.test(c)) : [];
+  let out = items.filter((i) => (!opts.type || i.type === opts.type) && (!opts.mode || i.mode === opts.mode) && (!opts.mood || (i.mood ?? []).includes(opts.mood)) && (!opts.motion || i.motion === opts.motion) && (!opts.role || i.role === opts.role) && (i.energy === undefined || en(i.energy)) && hit(i));
+  if (near.length) out = out.map((i) => ({ ...i, fit: colorFit(i, near) })).filter((i) => i.fit !== null).sort((a, b) => a.fit - b.fit);
+  return out;
+}