paper-motion 0.1.0 → 0.2.1

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.vercel.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.vercel.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 };
+}