paper-motion 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
+
+## 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

@@ -579,10 +579,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/registry.mjs

@@ -5,7 +5,7 @@
 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';
 
 const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = path.resolve(ENGINE, '..', '..');
@@ -137,6 +137,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"\`
@@ -275,8 +280,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 +311,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) : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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)) })); }