paper-motion 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.

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

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

@@ -6,6 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 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,
@@ -155,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:
@@ -170,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.
@@ -355,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,
@@ -372,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.2",
+  "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",