paper-motion 0.2.0 → 0.2.1

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
 

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 ...] [--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); }
       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)), { registry: args.registry, force: !!args.force, name: typeof args.name === 'string' ? args.name : undefined, brand: typeof args.brand === 'string' ? args.brand : undefined, set });
       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

@@ -120,7 +120,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

@@ -9,7 +9,8 @@ import { apply as applyValues, parseSet } 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.
 
@@ -208,7 +212,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 +271,22 @@ 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 = [] } = {}) {
   const reg = resolveRegistry(registry), done = new Map(), report = [];
+  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;
@@ -309,6 +327,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.1",
   "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
   "keywords": [
     "video",