paper-motion 0.2.0 → 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

@@ -31,7 +31,7 @@ Installed globally (`npm i -g paper-motion`), the same commands run as `paper-mo
 
 ### Resources from paper-motion.app
 
-The registry at [paper-motion.app](https://paper-motion.app) holds named moves, backgrounds, palettes, font pairs and recipes. Agents pick them for a brand, propose options as a board link, and install what the user chooses as code the user owns.
+The registry at [paper-motion.app](https://paper-motion.vercel.app) holds named moves, backgrounds, palettes, font pairs and recipes. Agents pick them for a brand, propose options as a board link, and install what the user chooses as code the user owns.
 
 ```bash
 npx paper-motion search --type background --mode dark --near "#0a0f1f,#eef1f8,#3d6bff"   # find resources by mood, mode, color fit
@@ -41,7 +41,7 @@ npx paper-motion board --url --title "Backgrounds" --look cobalt,geist \
 npx paper-motion list background                                                          # every resource of a type
 ```
 
-`https://paper-motion.app/llms.txt` explains the flow to an agent.
+`https://paper-motion.vercel.app/llms.txt` explains the flow to an agent.
 
 ## Inside a scene
 
@@ -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,14 +579,15 @@ 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] [--registry url|dir]\n  --set writes your values into the installed copy (with several ids: --set id:key=value). --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, 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)`);
         for (const c of r.conflicts) console.log(`  kept your value at ${c} (--force to replace)`);
+        for (const n of r.notes.filter((x) => x.startsWith('the brand'))) console.log(`  ${n}`);
       }
       const last = report.filter((r) => ids.includes(r.id) && r.usage);
       if (last.length === 1) console.log(`\nUsage:\n${last[0].usage.split('\n').map((l) => `  ${l}`).join('\n')}`);
@@ -637,7 +638,7 @@ async function main() {
             } else await withServer(demo, (url) => renderVideo({ url: url(`?render&demo=${it.id}`), out: mp4, from: 0, to: 5, sfx: false, crf: 16, motionBlur: Number(args['motion-blur'] ?? 4) }));
             const vf = 'scale=1280:-2';
             const a = spawnSync('ffmpeg', ['-v', 'error', '-y', '-i', mp4, '-vf', vf, '-c:v', 'libvpx-vp9', '-crf', '38', '-b:v', '0', '-row-mt', '1', '-an', path.join(out, `${it.id}.webm`)]);
-            const b = spawnSync('ffmpeg', ['-v', 'error', '-y', '-ss', String(POSTER[it.type] ?? 1.5), '-i', mp4, '-frames:v', '1', '-vf', vf, '-q:v', '4', path.join(out, `${it.id}.jpg`)]);
+            const b = spawnSync('ffmpeg', ['-v', 'error', '-y', '-ss', String(it.preview?.at ?? POSTER[it.type] ?? 1.5), '-i', mp4, '-frames:v', '1', '-vf', vf, '-q:v', '4', path.join(out, `${it.id}.jpg`)]);
             if (a.status || b.status) throw new Error(`ffmpeg failed for ${it.id}: ${a.stderr}${b.stderr}`);
           }
         } finally { fs.rmSync(tmp, { recursive: true, force: true }); }

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;
   }
@@ -120,7 +181,7 @@ export function apply(item, values) {
 }
 
 /** 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' } = {}) {
+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(' ')}` : ''}`;

package/lib/live-board.js

@@ -1,6 +1,6 @@
 // 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))>
+//   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.
 

package/lib/registry.mjs

@@ -5,11 +5,12 @@
 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, '..', '..');
-export const SITE = (process.env.PAPER_MOTION_SITE ?? 'https://paper-motion.app').replace(/\/$/, '');
+// until the paper-motion.app domain is connected, the live site is the vercel URL
+export const SITE = (process.env.PAPER_MOTION_SITE ?? 'https://paper-motion.vercel.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' };
 
@@ -121,7 +122,10 @@ export function llmsTxt(items, site, { full = false } = {}) {
 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.
+   whose prompt carries the whole \`pamo add\` command. \`add\` never overwrites a value already in the project: when
+   the user re-chooses or re-tunes something you installed before, pass \`--force\`. A recipe also reads
+   \`brand/motion.json\` (pace) and \`brand/sound.json\` (cues; without it the piece is silent) and the brand's name
+   from \`tokens.json\` \`brand\`: write those from the interview before rendering.
 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.
 
@@ -133,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"\`
@@ -208,7 +217,7 @@ export function build({ dir = resolveRegistry().dir, out, site = SITE } = {}) {
   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; }
+  for (const it of items) if (it.preview) { const have = Object.fromEntries(Object.entries(it.preview).filter(([, p]) => typeof p !== 'string' || fs.existsSync(path.join(out, p)))); it.preview = Object.values(have).some((p) => typeof p === 'string') ? 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)) })),
@@ -267,8 +276,33 @@ function mergeInto(base, frag, force, at = '', 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 = [] } = {}) {
+// what a recipe reads beside the tokens and the shader set; written once, when the project has none
+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 = [], 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, {});
+    if (brand && (force || !tokens.brand)) { tokens.brand = brand; writeJson(tokensFile, tokens); r.wrote.push('brand/tokens.json brand'); }
+    for (const [file, def] of [['brand/motion.json', MOTION_DEFAULT], ['brand/sound.json', SOUND_DEFAULT]]) {
+      const f = path.join(cwd, file);
+      if (!fs.existsSync(f)) { writeJson(f, def); r.wrote.push(`${file} (defaults)`); }
+    }
+    if (!tokens.brand && !brand) r.notes.push('the brand has no name yet: pamo add --brand "Name" (recipes show it as the wordmark)');
+  };
   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;
@@ -277,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) : '';
@@ -309,6 +346,7 @@ export async function add(ids, { cwd = process.cwd(), registry, force = false, n
       r.conflicts.push(...mergeInto(tokens, it.install.entry ?? {}, force).map((k) => `brand/tokens.json ${k}`));
       writeJson(f, tokens); r.wrote.push('brand/tokens.json');
     }
+    if (kind === 'tokens' || kind === 'scene') scaffold(r);
     lock.items[it.id] = it.version;
     report.push(r);
   }

package/package.json

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