paper-motion 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.2.7 · 2026-11-10
+
+- A new resource type, **blocks**: 29 ready-made 4–8 s moments (annotations, interfaces, code, data, type, brand, effects), installed like recipes and customized through their `CONFIG`; each recomposes for 16:9, 9:16 and 1:1.
+- `pamo registry previews` renders blocks; `pamo add --set` writes their values into `CONFIG`.
+
 ## 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).

package/bin/pamo.mjs

@@ -647,15 +647,15 @@ 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', '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 items = loadItems(reg.dir).filter((i) => ['component', 'transition', 'text', 'camera', 'recipe', 'shot', 'block'].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, block: 2.5 };
         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' || it.type === 'shot') {
+            if (it.type === 'recipe' || it.type === 'shot' || it.type === 'block') {
               // 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`);
               // the demo brand's copy goes in through the same generator `pamo add --set` uses (preview.values)

package/lib/customize.mjs

@@ -138,6 +138,9 @@ function fontTokens(item, values) {
 }
 
 /** A recipe's CONFIG object from flat values (proof1Title… → proof[0].title, "1920x1080" → [1920, 1080]). */
+// resources whose file is a whole scene, customized through its CONFIG
+const SCENE_TYPES = ['recipe', 'shot', 'block'];
+
 function recipeConfig(values) {
   const cfg = {}, groups = {};
   for (const [k, v] of Object.entries(values)) {
@@ -182,7 +185,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' || item.type === 'shot') && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
+    if (SCENE_TYPES.includes(item.type) && /scene\.html$/.test(f.path)) return { ...f, content: recipeScene(f.content, v) };
     return f;
   });
   let entry = item.install?.entry;
@@ -227,7 +230,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' || item.type === 'shot') {
+  } else if (SCENE_TYPES.includes(item.type)) {
     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', 'shot'];
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot', 'block'];
 
 /**
  * @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', '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' };
+const TYPES = ['component', 'transition', 'text', 'camera', 'background', 'palette', 'font-pair', 'recipe', 'shot', 'block'];
+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', block: 'Blocks' };
 
 /** 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) {
@@ -121,7 +121,8 @@ export function llmsTxt(items, site, { full = false } = {}) {
    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 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
+   recipe or stand alone) · blocks for the moments inside it (ready-made 4–8 s pieces: annotations on a screen, a
+   form, a terminal, code typing, a chart, captions, a logo sting; each recomposes for 16:9, 9:16 and 1:1). 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
@@ -157,7 +158,7 @@ ${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 and shots: \`duration\`, \`formats\` and \`beats\` (the structure as a
+- Font pairs: \`voice\` (serif, sans, display, mono). Recipes, shots and blocks: \`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

package/package.json

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