paper-motion 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
+
+## 0.2.3 · unreleased
+
+- Boards get short links and a return channel: `pamo board --url` stores the board on the site (`/b/<id>`, 90 days) and falls back to the long link; `--wait [minutes]` prints the reply line when the user chooses in the browser; `--long`, `--forget <id>`. `lib/live-board.js` gains `shortenBoard`, `awaitChoice`, `forgetBoard`; the search filters move to `lib/find.mjs` (shared with the site's MCP at `/mcp`).
+
+## 0.2.2 · 2026-11-09
+
+- Every background is a color family: `recolor(item, palette)` in `lib/customize.mjs`, `pamo add <background> --palette <id|brand>`, boards with a `--look` show backgrounds recolored and their reply lines carry the values. A background's CSS `background` is a param; `B.shader` paints it.
+- Two recipes: `product-demo` and `release`.
+- Six halftone backgrounds filter `material-b.jpg`, rendered by the engine, instead of an image hosted by Paper.
+
+## 0.2.1 · 2026-11-08
+
+Fixes found by making paper-motion's own launch video as a fresh user.
+
+- The CLI's default site is `https://paper-motion.vercel.app` until the `paper-motion.app` domain is connected, so `search`, `add` and `board --url` work without `PAPER_MOTION_SITE`.
+- `pamo add` scaffolds what a recipe reads but boards never settle: `brand/motion.json` (pace) and `brand/sound.json` (cues) with defaults when missing, and the brand's name through `--brand "Name"`. Without a name it says so instead of rendering "brand".
+- `llms.txt` step 4 says that `add` never overwrites a value already in the project and that re-choosing needs `--force`.
+- Recipes dim the background layer behind type (`CONFIG.backgroundOpacity`, with a vignette on launch, explainer and end-card) and size card bodies and the action line for phones.
+- Registry items can set `preview.at`, the poster time in seconds; the five recipes use it so their posters land on a readable frame. `registry build` keeps non-string preview fields when it drops missing files.
+
+## 0.2.0 · 2026-11-08
+
+paper-motion.app: a registry of named resources and the commands that use it.
+
+- `pamo registry build` publishes `registry.json`, `r/<id>.json`, `llms.txt` and `llms-full.txt` from `registry/`; `pamo registry previews` renders a clip and a poster per move and recipe, and `build` publishes only previews that exist.
+- `pamo add <id…>` installs resources as code the user owns: moves into `moves/`, backgrounds into `brand/shader-set/set.json`, palettes and font pairs into `brand/tokens.json`, recipes into `pieces/<id>/`. `--set key=value` writes the user's values through the same generator the site uses (`lib/customize.mjs`); `paper-motion.json` records what was installed. `pamo list` and `pamo search` read the index; `search` filters by the choosing metadata (when, mood, energy, role, colors, motion…) and `--near` ranks by color fit.
+- `pamo board --url` builds and validates live board links (`/b#payload`, deflate + base64url, nothing reaches a server): 2–4 labelled options the user compares in their own look, tunes and chooses; the reply is one line the agent parses with `lib/live-board.js`. `lib/board.mjs` remains the rendered board.
+- `paper-motion/moves` grows from 12 to 38: transitions (whip, cells, slices, iris, glitch, flip3D, flash), text (scramble, popIn, flipIn, roll, odometer, barReveal), camera and energy (shake, punch, orbit, rgbSplit, drawOn) and component transitions (magicMove, whipPan, diveIn, flipLift, squashDrop, snapScroll, unfold, tileSwirl). Each move is its own file under `runtime/moves/`; shared helpers are `paper-motion/kit`; one whip blur filter per stage.
+- `pamo new --move` accepts any transition in the library; `pamo board --motion-blur n` renders option boards with real motion blur.
+- `PAPER_MOTION_SITE` overrides the site URL everywhere the engine writes links. OG images are rendered by the engine.
+- Examples: the Halo explainer and the Orbit keynote. Sound effects keep their gains next to a voice.
+- The engine ships no audio. A user's own recording (`pamo keys`) gives real keystrokes; without one they are synthesized.
+
+## 0.1.0 · 2026-11-08
+
+First public release of the engine as the unscoped npm package `paper-motion` (previously `@paper-motion/engine`, private).
+
+- `pamo` CLI: `setup`, `doctor`, `new`, `still`, `render` (mp4, prores, gif, webm; `--motion-blur`, `--dpr`, `--loudness`, `--audio`), `preview`, `board`, `shaders`, `examples`, `status`, `keys`, `shader-set`.
+- Runtime: scenes as pure functions of time, Paper Shaders by name with their React props, seamless shader loops, `paper-motion/brand` (`loadBrand`, `B.shader`, `B.style`, `B.cue`, `B.sound`), `paper-motion/moves` (12 moves), synthesized sound effects mixed into renders.
+- Dependencies are found wherever npm puts them, so an install does not re-install them inside the package. Four bundled examples: breath, signal, install-loop, chrome-endcard.

package/README.md

@@ -55,6 +55,10 @@ All 30 [Paper Shaders](https://shaders.paper.design), a library of moves (wipes,
 frame, terminal typing), synthesized sound effects or real keystrokes split from your own recording, option boards,
 wordmarks and the brand sheet.
 
+## Changes
+
+[CHANGELOG.md](./CHANGELOG.md) lists what each npm release changed.
+
 ## License
 
 MIT. Paper Shaders are © Paper Design (Apache-2.0).

package/bin/pamo.mjs

@@ -322,12 +322,12 @@ async function main() {
     case 'board': {
       if (args.url) {
         // the live form: a paper-motion.app link the user opens to compare, tune and choose
-        const { encodeBoard, boardUrl } = await import('../lib/live-board.js');
+        const { encodeBoard, boardUrl, shortenBoard, awaitChoice } = await import('../lib/live-board.js');
         const { getIndex, resolveRegistry, SITE, getItem } = await import('../lib/registry.mjs');
         const { parseSet, setArgs } = await import('../lib/customize.mjs');
         const reg = resolveRegistry(args.registry), { items } = await getIndex(reg), index = Object.fromEntries(items.map((i) => [i.id, i]));
         const opts = process.argv.flatMap((a, i, all) => (a === '--option' ? [all[i + 1]] : a.startsWith('--option=') ? [a.slice(9)] : [])).filter(Boolean);
-        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette,font] --option id[:key=value,…] [--note "why"] … [--kit] [--site url]\n  Prints a live board link. Values after the colon are your adjustments; the reply line the user pastes carries every non-default value.'); process.exit(args.help ? 0 : 1); }
+        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette,font] --option id[:key=value,…] [--note "why"] … [--kit] [--wait [minutes]] [--long] [--site url]\n       board --forget <id>\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  --wait keeps running until the user chooses in the browser (10 min by default) and prints the reply line, the same one they could paste. --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
         const LABELS = ['A', 'B', 'C', 'D'];
         const parseOne = async (spec) => {
           const [id, kv] = spec.split(':'), it = index[id];
@@ -347,7 +347,26 @@ async function main() {
         const look = {};
         if (typeof args.look === 'string') for (const spec of args.look.split(',')) { const o = await parseOne(spec.trim()); const t = index[o.id]?.type; if (t === 'palette') look.palette = o; else if (t === 'font-pair') look.font = o; else throw new Error(`--look takes a palette and a font pair, not "${o.id}"`); }
         const board = { v: 1, kind: args.kit ? 'kit' : 'resource', title: String(args.title), ...(args.ask ? { ask: String(args.ask) } : {}), ...(args.reply ? { reply: String(args.reply) } : {}), ...(Object.keys(look).length ? { look } : {}), options };
-        try { const frag = await encodeBoard(board, index); console.log(boardUrl(typeof args.site === 'string' ? args.site : SITE, frag)); }
+        const site = typeof args.site === 'string' ? args.site : SITE;
+        let frag, short = null;
+        try { frag = await encodeBoard(board, index); } catch (e) { console.error(e.message); process.exit(1); }
+        // the short link when the site stores it; the long one (the board in the fragment) when it cannot
+        if (!args.long) { try { short = await shortenBoard(site, board); } catch (e) { console.error(`(${e.message}; sharing the long link)`); } }
+        console.log(short ? short.url : boardUrl(site, frag));
+        if (short && args.wait) {
+          const minutes = Number.isFinite(Number(args.wait)) && args.wait !== true ? Number(args.wait) : 10;
+          console.error(`waiting up to ${minutes} min for the choice on ${short.id} (the user can still paste the line)…`);
+          const choice = await awaitChoice(site, short.id, { timeout: minutes * 60 * 1000 });
+          if (!choice) { console.error('no choice yet; ask the user to paste the line from the board'); process.exit(3); }
+          console.log(choice.line);
+        } else if (!short && args.wait) console.error('--wait needs the short link; the user will paste the line instead');
+        break;
+      }
+      if (args.forget) {
+        const { forgetBoard } = await import('../lib/live-board.js');
+        const { SITE } = await import('../lib/registry.mjs');
+        const id = String(args.forget);
+        try { await forgetBoard(typeof args.site === 'string' ? args.site : SITE, id); console.log(`forgot board ${id}`); }
         catch (e) { console.error(e.message); process.exit(1); }
         break;
       }
@@ -579,10 +598,10 @@ async function main() {
 
     case 'add': {
       const ids = args._.slice(1);
-      if (!ids.length || args.help) { console.error('Usage: add <id> [<id>...] [--set key=value ...] [--force] [--name piece] [--brand "Name"] [--registry url|dir]\n  --set writes your values into the installed copy (with several ids: --set id:key=value). --force replaces values already in the project. --brand names the brand in brand/tokens.json; palettes, fonts and recipes also write brand/motion.json and brand/sound.json defaults when missing. --registry picks where resources come from (default: the site).'); process.exit(args.help ? 0 : 1); }
+      if (!ids.length || args.help) { console.error('Usage: add <id> [<id>...] [--set key=value ...] [--palette id|brand] [--force] [--name piece] [--brand "Name"] [--registry url|dir]\n  --set writes your values into the installed copy (with several ids: --set id:key=value). --palette installs backgrounds recolored into a palette (a registry palette, or "brand" for brand/tokens.json); --set still wins. --force replaces values already in the project. --brand names the brand in brand/tokens.json; palettes, fonts and recipes also write brand/motion.json and brand/sound.json defaults when missing. --registry picks where resources come from (default: the site).'); process.exit(args.help ? 0 : 1); }
       const { add } = await import('../lib/registry.mjs');
       const set = process.argv.flatMap((a, i, all) => (a === '--set' ? [all[i + 1]] : a.startsWith('--set=') ? [a.slice(6)] : [])).filter(Boolean);
-      const report = await add(ids.filter((x) => !set.includes(x)), { registry: args.registry, force: !!args.force, name: typeof args.name === 'string' ? args.name : undefined, brand: typeof args.brand === 'string' ? args.brand : undefined, set });
+      const report = await add(ids.filter((x) => !set.includes(x) && x !== args.palette), { registry: args.registry, force: !!args.force, name: typeof args.name === 'string' ? args.name : undefined, brand: typeof args.brand === 'string' ? args.brand : undefined, set, palette: typeof args.palette === 'string' ? args.palette : undefined });
       for (const r of report) {
         console.log(`✓ ${r.id} (${r.type})${r.wrote.length ? ` → ${[...new Set(r.wrote)].join(', ')}` : ''}`);
         for (const f of r.skipped) console.log(`  kept your ${f} (it differs; --force to replace)`);

package/lib/customize.mjs

@@ -4,12 +4,71 @@
 
 export const MOVE_TYPES = ['component', 'transition', 'text', 'camera'];
 
+/**
+ * A resource's params. A background whose entry paints a CSS `background` behind the shader gets it as a virtual
+ * color param, so recoloring, `--set background=#…` and the reply line can carry it like any other value.
+ */
+export const paramsOf = (item) => {
+  const ps = item.params ?? [];
+  const bg = item.type === 'background' ? item.install?.entry?.background : undefined;
+  return typeof bg === 'string' && !ps.some((p) => p.name === 'background') ? [...ps, { name: 'background', type: 'color', default: bg, description: 'the color behind the shader', group: 'main' }] : ps;
+};
+
 /** Param defaults by name. */
-export const defaults = (item) => Object.fromEntries((item.params ?? []).map((p) => [p.name, p.default]));
+export const defaults = (item) => Object.fromEntries(paramsOf(item).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));
+export const changed = (item, values) => paramsOf(item).filter((p) => p.name in values && !same(values[p.name], p.default));
+
+// ── color families: a background in a palette ──────────────────
+
+const HEX = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i;
+const srgb = (h) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+const lin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const unlin = (c) => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+const lum = (h) => { const [r, g, b] = srgb(h).map(lin); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+const hex = (rgbLin) => `#${rgbLin.map((c) => Math.round(Math.min(1, Math.max(0, unlin(c))) * 255).toString(16).padStart(2, '0')).join('')}`;
+/** `color` moved toward black or white until its luminance is `y`: the hue stays, the tone changes. */
+function atLuminance(color, y) {
+  const c = srgb(color).map(lin), yc = lum(color);
+  if (Math.abs(yc - y) < 1e-4) return color.slice(0, 7);
+  if (y > yc) { const t = yc >= 1 ? 0 : (y - yc) / (1 - yc); return hex(c.map((v) => v + t * (1 - v))); }
+  const t = yc <= 0 ? 0 : 1 - y / yc;
+  return hex(c.map((v) => v * (1 - t)));
+}
+
+/** The hexes of a palette (the values of a palette resource, or `brand/tokens.json`'s colors with hexes). */
+export function paletteColors(pal) {
+  const out = [];
+  for (const k of ['ground', 'figure', 'muted', 'surface', 'accent']) { const v = pal?.[k]; const h = typeof v === 'string' ? v : v?.hex; if (HEX.test(h ?? '')) out.push(h); }
+  for (const h of pal?.ramp ?? []) if (HEX.test(h)) out.push(h);
+  return [...new Set(out.map((h) => h.slice(0, 7).toLowerCase()))];
+}
+
+/**
+ * A background's color values in a palette: every color the resource uses keeps its own tone (a dark background
+ * stays dark, a bright highlight stays bright, transparency stays) and takes the hue of the palette color nearest in
+ * tone, so each background becomes a family: the same material in any brand's colors. Returns the values to apply.
+ */
+export function recolor(item, pal) {
+  const ladder = paletteColors(pal).map((h) => ({ h, y: lum(h) }));
+  if (item.type !== 'background' || !ladder.length) return {};
+  const one = (v) => {
+    const m = typeof v === 'string' && v.match(HEX);
+    if (!m) return v;
+    if (m[2] && parseInt(m[2], 16) === 0) return v; // fully transparent: nothing to color
+    const y = lum(v);
+    const near = ladder.reduce((a, b) => (Math.abs(b.y - y) < Math.abs(a.y - y) ? b : a));
+    return atLuminance(near.h, y) + (m[2] ? m[2] : '');
+  };
+  const out = {};
+  for (const p of paramsOf(item)) {
+    if (p.type === 'color') out[p.name] = one(p.default);
+    else if (p.type === 'colors' && Array.isArray(p.default)) out[p.name] = p.default.map(one);
+  }
+  return out;
+}
 
 /** A JS literal: strings in single quotes, `ease.*` left as code, arrays and objects inline. */
 export function literal(v) {
@@ -35,7 +94,7 @@ export function parseSet(item, 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(', ')})`);
+    if (!paramsOf(item).some((p) => p.name === k)) throw new Error(`"${item.id}" has no param "${k}" (params: ${paramsOf(item).map((p) => p.name).join(', ')})`);
     try { out[k] = JSON.parse(raw); } catch { out[k] = raw; }
   }
   return out;
@@ -57,7 +116,9 @@ function moveFile(item, content, values) {
 
 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])) } };
+  const props = { ...e.props, ...Object.fromEntries((item.params ?? []).map((p) => [p.name, values[p.name] ?? p.default])) };
+  const bg = typeof e.background === 'string' && typeof values.background === 'string' ? values.background : e.background;
+  return { ...e, props, ...(bg !== undefined ? { background: bg } : {}) };
 }
 
 function paletteTokens(item, values) {
@@ -79,8 +140,8 @@ function fontTokens(item, values) {
 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; }
+    const m = k.match(/^(proof|step|shot)(\d)(Label|Title|Body|Image|Caption)$/);
+    if (m) { const g = { proof: 'proof', step: 'steps', shot: 'shots' }[m[1]]; (groups[g] ??= [])[m[2] - 1] ??= {}; groups[g][m[2] - 1][m[3].toLowerCase()] = v; continue; }
     if (k === 'format') cfg.format = String(v).split('x').map(Number);
     else cfg[k] = v === '' ? null : v;
   }

package/lib/find.mjs

@@ -0,0 +1,28 @@
+// Finding resources in the index: free words plus the choosing metadata. Plain ESM with no Node imports, so the
+// same function serves `pamo search` and the site's MCP (`search` tool); the site copies this file next to customize.mjs.
+
+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);
+};
+
+/**
+ * Filters index items: free words over id/title/summary/tags/when/mood, plus type, mode (light|dark), mood,
+ * motion (still|gentle|lively), role, energy ("3", "2-4", "<=3", ">=2") and near (hex colors, comma-separated:
+ * sorts by closeness and adds `fit`).
+ */
+export function find(items, query, opts = {}) {
+  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;
+}

package/lib/live-board.js

@@ -95,6 +95,37 @@ export async function decodeBoard(fragment) {
 
 export const boardUrl = (site, fragment) => `${site.replace(/\/$/, '')}/b#${fragment}`;
 
+/**
+ * Stores a board on the site and returns its short link `{ id, url, expires }` (`POST /api/boards`). Throws when
+ * the site refuses or is unreachable; callers fall back to the fragment link.
+ */
+export async function shortenBoard(site, board) {
+  const r = await fetch(`${site.replace(/\/$/, '')}/api/boards`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ board }) });
+  if (!r.ok) { let msg = `${r.status}`; try { msg = (await r.json()).error ?? msg; } catch { /* keep the status */ } throw new Error(`the site did not store the board (${msg})`); }
+  return r.json();
+}
+
+/**
+ * Waits for the choice made on a stored board: polls `GET /api/boards/<id>/choice` every `every` ms until one
+ * exists or `timeout` ms pass. Resolves `{ line, label?, none?, text?, at }`, or null on timeout.
+ */
+export async function awaitChoice(site, id, { timeout = 10 * 60 * 1000, every = 2000, signal } = {}) {
+  const base = `${site.replace(/\/$/, '')}/api/boards/${id}/choice`, until = Date.now() + timeout;
+  while (Date.now() < until && !signal?.aborted) {
+    const r = await fetch(base, { cache: 'no-store' });
+    if (r.status === 200) return r.json();
+    if (r.status !== 204) throw new Error(`the site answered ${r.status} while waiting for the choice`);
+    await new Promise((res) => setTimeout(res, every));
+  }
+  return null;
+}
+
+/** Forgets a stored board and its choice (`DELETE /api/boards/<id>`). */
+export async function forgetBoard(site, id) {
+  const r = await fetch(`${site.replace(/\/$/, '')}/api/boards/${id}`, { method: 'DELETE' });
+  if (!r.ok && r.status !== 404) throw new Error(`the site answered ${r.status}`);
+}
+
 // ── 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

package/lib/registry.mjs

@@ -5,7 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { apply as applyValues, parseSet } from './customize.mjs';
+import { apply as applyValues, defaults, paletteColors, parseSet, recolor } from './customize.mjs';
+import { find } from './find.mjs';
 
 const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = path.resolve(ENGINE, '..', '..');
@@ -116,9 +117,12 @@ export function llmsTxt(items, site, { full = false } = {}) {
    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.
+   (format below): a short link (\`${site}/b/<id>\`, stored for 90 days) when the site answers, the long form
+   with the board in the URL fragment otherwise. The user opens it, sees the options live in their look, may tune one,
+   and chooses. The choice comes back as one line: \`paper-motion: B · mesh-sage --set speed=0.8 (bg-1)\`, or
+   \`paper-motion: none of bg-1, calmer ones\`. With \`--wait\` the command keeps running and prints that line the
+   moment they choose (10 min by default); without it, they paste the line in the chat. The reply carries every value
+   that differs from the defaults, your pre-tuning included, so installing it reproduces what they saw.
 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,
@@ -137,6 +141,11 @@ ${site}/registry.json is the index; every item carries, beside id, type, title,
 - \`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).
+  **Every background is a color family**: a board with a \`look.palette\` shows each background recolored into that
+  palette (each of its colors keeps its tone and takes the nearest palette hue, so a dark one stays dark), and the
+  reply line carries the resulting values. Without a board, \`pamo add <background> --palette <palette-id|brand>\`
+  installs it that way (\`brand\` reads \`brand/tokens.json\`). So choose backgrounds by \`motion\`, \`mood\` and
+  texture first; the color comes from the palette.
 - Font pairs: \`voice\` (serif, sans, display, mono). Recipes: \`duration\`, \`formats\`.
 
 \`pamo search\` filters by them: \`pamo search --type background --mode dark --near "#0a0f1f,#eef1f8,#3d6bff"\`
@@ -150,6 +159,13 @@ 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 MCP server
+
+The same registry as tools, with no install: add \`${site}/mcp\` (streamable HTTP, no auth) to your agent. Tools:
+\`search\` (the filters above), \`resource\` (one record in full), \`recolor\` (a background's values in a palette),
+\`board\` (creates a short link and, with \`wait\`, returns the user's choice) and \`board_choice\`. Installing is
+still \`npx paper-motion add\` in the user's project, or your own file tools from the record.
+
 ## The board link format
 
 \`${site}/b#<payload>\` where payload = base64url(deflate-raw(JSON)). The JSON:
@@ -165,6 +181,9 @@ one-line \`--note\` for each; share the link.
     { "label": "D", "id": "grain-slate", "values": {} } ] }
 \`\`\`
 
+Short links: \`POST ${site}/api/boards\` with \`{ "board": … }\` returns \`{ id, url }\`; \`GET /api/boards/<id>/choice\`
+answers 204 until the user chooses, then \`{ line, label }\`. Boards expire after 90 days; \`DELETE /api/boards/<id>\` forgets one.
+
 Rules: 2–4 options, labels A–D, one resource type per \`resource\` board; \`kind: "kit"\` makes each option
 \`{ "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.
@@ -275,8 +294,19 @@ function mergeInto(base, frag, force, at = '', conflicts = []) {
 const MOTION_DEFAULT = { pace: 'medium', camera: 'still', text: 'rise', color: 'constant', ending: 'wordmark', timing: null, moves: [] };
 const SOUND_DEFAULT = { palette: 'soft', lowpass: 2400, cues: { transition: { type: 'sweep', dur: 0.7, gain: 0.07 }, land: { type: 'thud', gain: 0.09 }, text: { type: 'tick', freq: 900, gain: 0.04 }, bed: null }, keys: { bank: null, style: 'creamy', gain: 0.12 }, music: null, loudness: -14 };
 
-export async function add(ids, { cwd = process.cwd(), registry, force = false, name, brand, set = [] } = {}) {
+export async function add(ids, { cwd = process.cwd(), registry, force = false, name, brand, set = [], palette } = {}) {
   const reg = resolveRegistry(registry), done = new Map(), report = [];
+  // --palette <id|brand>: backgrounds install recolored into that palette (the registry's, or brand/tokens.json)
+  let pal = null;
+  if (palette === 'brand') {
+    const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {});
+    pal = { ...(tokens.colors ?? {}), ramp: tokens.ramp };
+    if (!paletteColors(pal).length) throw new Error('--palette brand: brand/tokens.json has no colors yet (pamo add <palette> first)');
+  } else if (palette) {
+    const p = await getItem(palette, reg);
+    if (p.type !== 'palette') throw new Error(`--palette takes a palette id (or "brand"), not "${palette}" (${p.type})`);
+    pal = defaults(p);
+  }
   const scaffold = (r) => {
     // a brand folder a recipe can run on: its name, a pace and sound cues (silent pieces are the usual surprise)
     const tokensFile = path.join(cwd, 'brand/tokens.json'), tokens = readJson(tokensFile, {});
@@ -295,7 +325,10 @@ export async function add(ids, { cwd = process.cwd(), registry, force = false, n
     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)) };
+    if (pairs.length || (pal && it.type === 'background')) {
+      const parsed = parseSet(it, pairs), explicit = Object.fromEntries(pairs.map((x) => x.slice(0, x.indexOf('='))).map((k) => [k, parsed[k]]));
+      it = { ...it, ...applyValues(it, { ...parsed, ...(pal ? recolor(it, pal) : {}), ...explicit }) };
+    }
     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) : '';
@@ -336,16 +369,7 @@ export async function add(ids, { cwd = process.cwd(), registry, force = false, n
   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);
-};
+export { colorDistance, colorFit } from './find.mjs';
 
 /**
  * Finds resources: free words over id/title/summary/tags/when, plus filters: type, mode (light|dark), mood,
@@ -353,11 +377,5 @@ export const colorFit = (item, brand) => {
  */
 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;
+  return find(items, query, opts);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",
@@ -35,7 +35,8 @@
     "templates/",
     "examples/",
     "!examples/**/renders/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18.17"

package/runtime/brand.js

@@ -53,6 +53,8 @@ export async function loadBrand(root = '/brand') {
       if (!e?.shader) throw new Error(`paper-motion/brand: no shader entry "${id}" in brand/shader-set/set.json`);
       const props = { ...e.props };
       if (e.image) props.image = e.image === 'wordmark' ? B.wordmark.onDark ?? B.wordmark.onLight : e.image === 'wordmark-dark' ? B.wordmark.onLight ?? B.wordmark.onDark : `${root}/${e.image}`;
+      // the color behind the shader (entries with a transparent colorBack rely on it)
+      if (e.background) { const node = typeof el === 'string' ? document.querySelector(el) : el; if (node && !node.style.background) node.style.background = e.background; }
       const layer = s.shader(el, e.shader, props, { ...(e.loop ? { loop: e.loop } : {}), ...options });
       // the entry's periodic motion, as in its rendered loop (static shaders stay alive)
       if (e.motion) { const D = set.format?.duration ?? s.duration, { param, from, to, cycles = 1 } = e.motion; s.update((t) => layer.set({ [param]: from + (to - from) * (0.5 - 0.5 * Math.cos((2 * Math.PI * cycles * t) / D)) })); }