paper-motion 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.2.6 · 2026-11-10
+
+- `camera()` in `paper-motion/kit`: a 3D world for a piece (`place`, `at`, `travel` with keyframes, `focus` with depth of field and gradual exits). Every recipe is rebuilt on it: a corridor the camera travels (launch, manifesto), a column it descends (three-things), a line it dollies along with a pull-back recap (explainer), a window it tilts into and punches (product-demo), a slab it swings around (before-after), a sleeve it orbits (release).
+- A new resource type, **shots**: 3–6 s camera gestures (`focus-pull`, `pass-over`, `cursor-guide`, `push-in`, `turn-in`), installed like recipes, chained before one or used alone.
+- `scramble` measures letters by layout width, so it works inside a 3D world.
+
 ## 0.2.5 · unreleased
 
+- Recipes declare `beats` (the structure as a timeline); boards draw them, and a recipe board may hold a structure of the agent's own (`--option "@Title | 18 | Hook 0-2 …"`), which `parseReply` returns as `structure`.
+- Three recipes: `manifesto` (words only, three statements and a turn), `three-things` (three cards, three mechanics) and `before-after` (two states, one wipe).
 - Font pairs keep their own stylesheet when the family is unchanged, so self-hosted faces work: the new `geist-serif` pair (Geist Serif headlines served by paper-motion.app, Geist text, Geist Mono labels) is the site's own look.
 
 ## 0.2.4 · 2026-11-09

package/bin/pamo.mjs

@@ -647,18 +647,22 @@ async function main() {
         const only = typeof args.only === 'string' ? args.only.split(',') : null;
         const out = path.resolve(args.out ?? path.join(reg.dir, '..', 'apps', 'web', 'public', 'previews'));
         fs.mkdirSync(out, { recursive: true });
-        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe'].includes(i.type) && (!only || only.includes(i.id)));
-        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5 };
+        const items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe', 'shot'].includes(i.type) && (!only || only.includes(i.id)));
+        const POSTER = { component: 1.5, transition: 1.4, text: 2.6, camera: 0.9, recipe: 2.5, shot: 1.8 };
         const demo = path.join(reg.dir, '_demo', 'index.html');
         const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-previews-'));
         try {
           for (const [k, it] of items.entries()) {
             process.stdout.write(`\r${k + 1}/${items.length} ${it.id.padEnd(16)}`);
             const mp4 = path.join(tmp, `${it.id}.mp4`);
-            if (it.type === 'recipe') {
+            if (it.type === 'recipe' || it.type === 'shot') {
               // a recipe renders whole, wired to the demo brand in registry/_demo/brand (served as /brand)
               const here = process.cwd(), copy = path.join(reg.dir, '_demo', `.${it.id}.recipe.html`);
-              fs.copyFileSync(path.join(reg.dir, 'recipe', it.id, 'scene.html'), copy);
+              // the demo brand's copy goes in through the same generator `pamo add --set` uses (preview.values)
+              const { apply: applyValues } = await import('../lib/customize.mjs');
+              const sceneFile = { path: 'scene.html', content: fs.readFileSync(path.join(reg.dir, it.type, it.id, 'scene.html'), 'utf8') };
+              const out = applyValues({ ...it, files: [sceneFile] }, it.preview?.values ?? {});
+              fs.writeFileSync(copy, out.files[0].content);
               process.chdir(path.join(reg.dir, '_demo'));
               try { await withServer(copy, (url) => renderVideo({ url: url('?render'), out: mp4, sfx: false, crf: 18, motionBlur: Number(args['motion-blur'] ?? 3) })); }
               finally { process.chdir(here); fs.rmSync(copy, { force: true }); }

package/lib/customize.mjs

@@ -141,8 +141,12 @@ function fontTokens(item, values) {
 function recipeConfig(values) {
   const cfg = {}, groups = {};
   for (const [k, v] of Object.entries(values)) {
-    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; }
+    const m = k.match(/^(proof|step|shot|thing)(\d)(Label|Title|Body|Image|Caption)$/);
+    if (m) { const g = { proof: 'proof', step: 'steps', shot: 'shots', thing: 'things' }[m[1]]; (groups[g] ??= [])[m[2] - 1] ??= {}; groups[g][m[2] - 1][m[3].toLowerCase()] = v; continue; }
+    const ba = k.match(/^(before|after)(Tag|Line|Image)$/);
+    if (ba) { (cfg[ba[1]] ??= {})[ba[2].toLowerCase()] = v; continue; }
+    const st = k.match(/^statement(\d)$/);
+    if (st) { (cfg.statements ??= [])[st[1] - 1] = v; continue; }
     if (k === 'format') cfg.format = String(v).split('x').map(Number);
     else cfg[k] = v === '' ? null : v;
   }
@@ -154,10 +158,17 @@ function recipeScene(content, values) {
   const start = content.indexOf('const CONFIG = {');
   if (start < 0) return content;
   const end = content.indexOf('\n};', start) + 3;
-  const body = Object.entries(cfg).map(([k, v]) => (Array.isArray(v) && v.length && typeof v[0] === 'object'
+  // the original entries, by key (an entry runs until the next top-level key), so settings that are not params
+  // (backgroundOpacity, turnWord, a card's label…) survive a --set
+  const original = content.slice(start + 'const CONFIG = {\n'.length, end - 3).split(/\n(?=  \w+: )/);
+  const kept = new Map(original.map((e) => [e.match(/^  (\w+):/)?.[1], e]).filter(([k]) => k));
+  const render = (k, v) => (Array.isArray(v) && v.length && typeof v[0] === 'object'
     ? `  ${k}: [\n${v.map((o) => `    ${literal(o)},`).join('\n')}\n  ],`
-    : `  ${k}: ${v === null ? 'null' : literal(v)},`)).join('\n');
-  return `${content.slice(0, start)}const CONFIG = {\n${body}\n};${content.slice(end)}`;
+    : `  ${k}: ${v === null ? 'null' : literal(v)},`);
+  const lines = [];
+  for (const [k, e] of kept) lines.push(k in cfg ? render(k, cfg[k]) : e);
+  for (const [k, v] of Object.entries(cfg)) if (!kept.has(k)) lines.push(render(k, v));
+  return `${content.slice(0, start)}const CONFIG = {\n${lines.join('\n')}\n};${content.slice(end)}`;
 }
 
 // ── the public API ──────────────────────────────────────────────
@@ -171,7 +182,7 @@ export function apply(item, values) {
   const files = (item.files ?? []).map((f) => {
     if (f.content === undefined) return f;
     if (MOVE_TYPES.includes(item.type)) return { ...f, content: moveFile(item, f.content, v) };
-    if (item.type === 'recipe' && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
+    if ((item.type === 'recipe' || item.type === 'shot') && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
     return f;
   });
   let entry = item.install?.entry;
@@ -216,7 +227,7 @@ export function code(item, values, { showAll = false, site = 'https://paper-moti
       { key: 'tokens', label: 'tokens.json', lang: 'json', code: JSON.stringify(e, null, 2) },
       { key: 'css', label: 'CSS variables', lang: 'css', code: `${Object.values(f).map((x) => `@import url('${x.css}');`).filter((x, i, a) => a.indexOf(x) === i).join('\n')}\n\n:root {\n${Object.entries(f).map(([r, x]) => `  --font-${r}: '${x.family}', ${cat(x.family)};`).join('\n')}\n  --display-weight: ${e.type.display.weight};\n  --display-tracking: ${e.type.display.tracking};\n}` },
     ];
-  } else if (item.type === 'recipe') {
+  } else if (item.type === 'recipe' || item.type === 'shot') {
     const scene = out.files.find((f) => /scene\.html$/.test(f.path));
     tabs = [{ key: 'scene', label: 'scene.html', lang: 'html', code: scene?.content ?? '' }];
   }

package/lib/live-board.js

@@ -9,7 +9,7 @@
 export const BOARD_VERSION = 1;
 export const MAX_PAYLOAD = 8 * 1024;
 const LABELS = ['A', 'B', 'C', 'D'];
-const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe'];
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot'];
 
 /**
  * @typedef {{ v: 1, kind: 'resource'|'kit', title: string, ask?: string, reply?: string,

package/lib/registry.mjs

@@ -12,8 +12,8 @@ const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const REPO = path.resolve(ENGINE, '..', '..');
 // 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' };
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot'];
+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', shot: 'Shots' };
 
 /** The registry to use: an explicit folder or URL, $PAPER_MOTION_REGISTRY, this repo's registry/ when present, else the site. */
 export function resolveRegistry(given) {
@@ -119,7 +119,9 @@ export function llmsTxt(items, site, { full = false } = {}) {
    "no brand yet"; three words for the feel and one thing it must never look like; the one action at the end.
    Mirror it back before proposing anything. **You never choose a look for the user.** These decisions always go
    through a board, in this order, one board each: palette · font pair · background(s) · moves by role (how things
-   enter, how one thing becomes the next, how text arrives; let them pick several with \`choose\`) · recipe. Skip a
+   enter, how one thing becomes the next, how text arrives; let them pick several with \`choose\`) · recipe or shots
+   (shots are 3–6 s camera gestures: a close-up, a pass over a component, a cursor that clicks; they chain before a
+   recipe or stand alone). Skip a
    board only when the brand folder already settles that decision, and say so.
 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
@@ -155,10 +157,13 @@ ${site}/registry.json is the index; every item carries, beside id, type, title,
   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\` and \`beats\` (the structure as a
-  timeline: name, from, to, what). A recipe board shows the beats, so the user chooses a rhythm, not a name; you may add
-  one option that is a **structure of your own** for this brief (\`structure\` instead of \`id\`, format below), which you
-  then build from scratch.
+- Font pairs: \`voice\` (serif, sans, display, mono). Recipes and shots: \`duration\`, \`formats\` and \`beats\` (the structure as a
+  timeline: name, from, to, what). A recipe board plays each structure as a sketch, so the user chooses a rhythm, not a
+  name; you may add one option that is a **structure of your own** for this brief (\`structure\` instead of \`id\`,
+  format below), which you then build from scratch. Give the recipe board \`choose: [1, 3]\`: picking several recipes in
+  order means **one piece made of those blocks in that order**, each block's closing beat dropped except the last; the
+  reply reads \`A+C · manifesto · three-things\`, and you build that sequence from scratch, using each recipe's scene as
+  the reference for its block.
 
 \`pamo search\` filters by them: \`pamo search --type background --mode dark --near "#0a0f1f,#eef1f8,#3d6bff"\`
 sorts backgrounds by color fit (the mean distance from each of theirs to the nearest of yours; lower is closer; pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-motion",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",

package/runtime/brand.js

@@ -5,6 +5,7 @@
 //   const s = scene({ ..., background: B.color('ground') });
 //   B.style(title, 'display'); B.shader(s, '#bg', 'mesh-ground'); B.cue(s, 'transition', 2.4); B.sound(s);
 import { PACE } from './moves.js';
+import { mixColor } from './core.js';
 
 const get = (p, json) => fetch(p).then((r) => (r.ok ? (json ? r.json() : r.text()) : null)).catch(() => null);
 const sections = (md) => Object.fromEntries((md ?? '').split(/^## /m).slice(1).map((b) => { const i = b.indexOf('\n'); return [b.slice(0, i).trim(), b.slice(i + 1).trim()]; }));
@@ -33,6 +34,15 @@ export async function loadBrand(root = '/brand') {
     name: wm.text ?? tokens?.brand ?? 'brand',
     /** A color by role (ground, figure, muted, surface, accent…), with a fallback. */
     color: (role, fallback = '#888888') => C[role]?.hex ?? fallback,
+    /**
+     * The surface for cards and panels, lifted toward the figure when the brand's own surface is too close to the
+     * ground to read (a black brand with a near-black surface would draw black cards on black).
+     */
+    surface: (lift = 0.14) => {
+      const g = C.ground?.hex ?? '#000000', s = C.surface?.hex ?? g, f = C.figure?.hex ?? '#ffffff';
+      const lum = (h) => { const n = parseInt(h.slice(1, 7), 16); return (0.2126 * (n >> 16) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255; };
+      return Math.abs(lum(s) - lum(g)) < 0.06 ? mixColor(g, f, lift) : s;
+    },
     ramp: tokens?.ramp ?? [C.ground?.hex, C.surface?.hex, C.accent?.hex].filter(Boolean),
     /** CSS font-family for a font key (display, text, mono). */
     font: fam,

package/runtime/kit.js

@@ -96,3 +96,76 @@ export function copy(el) {
 }
 
 export const partsOf = (el) => new Map([...el.querySelectorAll('[data-part]')].map((e) => [e.dataset.part, e]));
+
+// ── a 3D camera over a world ────────────────────────────────────
+// A recipe is a world the camera moves through, not a deck of cards. `stage` gets the perspective; `world` holds
+// children placed in space with `place()`; the camera's position is applied to the world as its inverse.
+//   const cam = camera(stage, world, { perspective: 2000 });
+//   cam.place(title, { z: -1200, yaw: 8 });
+//   s.update((t) => { cam.travel(t, [[0, { z: 1400 }], [3, { z: -200, yaw: 6 }, ease.inOutCubic]]); cam.focus(0, 900); });
+// Rules: never set opacity < 1 on `world` (it flattens its children); fade the placed elements instead.
+const CAM = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0, roll: 0, zoom: 1 };
+export function camera(stage, world, { perspective = 2000, origin = '50% 50%' } = {}) {
+  Object.assign(stage.style, { perspective: `${perspective}px`, perspectiveOrigin: origin });
+  Object.assign(world.style, { position: 'absolute', inset: 0, transformStyle: 'preserve-3d', transformOrigin: '50% 50%' });
+  const placed = [];
+  let pos = { ...CAM };
+  const P = perspective;
+  const cam = {
+    /** Where the camera is (the last `at`/`travel`). */
+    get pos() { return pos; },
+    /** Puts an element in the world, centred on its own box: { x, y, z, yaw, pitch, roll, scale }. */
+    place(el, p = {}) {
+      const q = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0, roll: 0, scale: 1, ...p };
+      Object.assign(el.style, { position: 'absolute', left: '50%', top: '50%', transformStyle: 'preserve-3d', backfaceVisibility: 'hidden' });
+      el.style.transform = `translate(-50%, -50%) translate3d(${q.x}px, ${q.y}px, ${q.z}px) rotateY(${q.yaw}deg) rotateX(${q.pitch}deg) rotateZ(${q.roll}deg) scale(${q.scale})`;
+      el._pmPlace = q;
+      if (!placed.includes(el)) placed.push(el);
+      return el;
+    },
+    /** Moves the camera: the world gets the inverse transform. Fields missing keep the current value. */
+    at(p) {
+      pos = { ...pos, ...p };
+      world.style.transform = `scale(${pos.zoom}) rotateZ(${-pos.roll}deg) rotateX(${-pos.pitch}deg) rotateY(${-pos.yaw}deg) translate3d(${-pos.x}px, ${-pos.y}px, ${-pos.z}px)`;
+      return pos;
+    },
+    /** Keyframes for the camera: [[t, { x, y, z, yaw, pitch, roll, zoom }, ease?], …]. Fields carry over between frames. */
+    travel(t, frames) {
+      const full = [];
+      let acc = { ...CAM, ...frames[0][1] };
+      for (const [time, p, e] of frames) { acc = { ...acc, ...p }; full.push([time, acc, e]); }
+      if (t <= full[0][0]) return cam.at(full[0][1]);
+      for (let i = 1; i < full.length; i++) {
+        const [t1, v1, e = ease.inOutCubic] = full[i], [t0, v0] = full[i - 1];
+        if (t <= t1) { const q = e(clamp((t - t0) / (t1 - t0))); return cam.at(Object.fromEntries(Object.keys(CAM).map((k) => [k, lerp(v0[k], v1[k], q)]))); }
+      }
+      return cam.at(full[full.length - 1][1]);
+    },
+    /**
+     * Depth of field and presence. Blur follows DEPTH: distance from the focal plane `z` ahead of the camera (sharp
+     * within a third of `range`, up to `max` px). Presence follows DISTANCE in 3D from the point the camera looks at:
+     * a place is whole within `fade`·0.4 and gone by `fade` (default `range`·0.85), so the next place is never
+     * peeking into frame while the camera rests, and while it travels the two overlap instead of leaving an empty
+     * frame. A place passing the lens softens and fades over the last stretch: it finishes its exit, never cuts.
+     * `fade: Infinity` keeps everything present (a focus pull where only the blur should change).
+     */
+    focus(z = 0, range = 800, max = 12, { fade = range * 0.85 } = {}) {
+      const fx = pos.x, fy = pos.y, fz = pos.z - z;          // the point in focus
+      for (const el of placed) {
+        const q = el._pmPlace;
+        const blur = clamp((Math.abs(q.z - fz) - range * 0.33) / range) * max;
+        const dist = Math.hypot(q.x - fx, q.y - fy, q.z - fz);
+        const present = fade === Infinity ? 1 : 1 - clamp((dist - fade * 0.4) / Math.max(1, fade * 0.6));
+        const toLens = pos.z - q.z;                          // distance left before it passes the camera
+        const near = clamp((toLens - P * 0.03) / (P * 0.1));   // the last stretch before the lens, whatever the focus range
+        const b = Math.max(blur, (1 - near) * max, (1 - present) * max * 0.6);
+        el.style.filter = b > 0.3 ? `blur(${b.toFixed(1)}px)` : 'none';
+        const o = Math.min(near, present);
+        el.style.opacity = String(o);
+        el.style.visibility = o < 0.005 ? 'hidden' : '';
+      }
+    },
+  };
+  cam.at({});
+  return cam;
+}

package/runtime/moves/scramble.js

@@ -6,7 +6,8 @@ export function scramble(el, t, { start = 0, duration = 1.4, fps = 30, rate = 2,
   const cs = chars(el);
   if (!el._labText) {
     el._labText = cs.map((c) => c.textContent);
-    cs.forEach((c) => { c.style.width = `${c.getBoundingClientRect().width}px`; c.style.textAlign = 'center'; });
+    // layout width, not the on-screen rect: inside a 3D world the rect is scaled by perspective
+    cs.forEach((c) => { c.style.width = `${c.offsetWidth}px`; c.style.textAlign = 'center'; });
     const r = rng(seed); el._labJit = cs.map(() => r.next());
   }
   const n = cs.length, tick = Math.floor((t * fps) / rate);

package/runtime/moves/word-rise.js

@@ -5,6 +5,8 @@ import { words } from '../kit.js';
 export function wordRise(el, t, { start = 0, each = 0.08, duration = 0.5, curve = ease.outExpo } = {}) {
   words(el).forEach((w, i) => {
     const q = curve(progress(t, start + i * each, start + i * each + duration));
-    w.style.transform = `translateY(${(1 - q) * 110}%)`;
+    // fully below the mask line, and hidden until it moves: tall glyphs overflow a tight line-height box
+    w.style.transform = `translateY(${(1 - q) * 125}%)`;
+    w.style.opacity = q > 0.001 ? 1 : 0;
   });
 }