paper-motion 0.3.0 → 0.4.1

package/lib/chain.mjs

@@ -13,16 +13,29 @@
 //   whip      the frame slides out sideways with a motion smear and the next slides in (0.35 s, the default)
 //   dissolve  a cross-fade (0.5 s)
 //   dip       out to the brand's ground color and back in (0.5 s)
+//   or a transition from the registry the user chose: wipe, push, zoom-through, iris, crossfade, slices, flash,
+//   scan-reveal, mask-reveal, glitch, cells, flip-3d, whip-pan (see MOVE_JOINS)
 // Each part plays from `from` (default 0) for `seconds` (default: the whole scene). A part cut before its
 // land (the beat a block declares with B.cue(s, 'land', t)) gets a warning with the length that keeps it.
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { lengthRange } from './inventory.mjs';
 
 export const JOINS = { cut: 0, whip: 0.35, dissolve: 0.5, dip: 0.5 };
-const OVERLAP = new Set(['whip', 'dissolve']);   // joins that need the outgoing part to run on under the next
-const LAND_HOLD = 0.6;                           // seconds after a land for the hit to read
+// the registry's transitions the user may have chosen, as joins between parts: [ffmpeg xfade transition, seconds].
+// So a chosen transition plays where one part becomes the next (it can also be built inside a part, by hand).
+export const MOVE_JOINS = {
+  crossfade: ['fade', 0.5], wipe: ['wipeleft', 0.5], push: ['slideleft', 0.45], 'zoom-through': ['zoomin', 0.5],
+  iris: ['circleopen', 0.55], slices: ['hrslice', 0.5], flash: ['fadewhite', 0.4], 'scan-reveal': ['wipedown', 0.5],
+  'mask-reveal': ['radial', 0.55], glitch: ['pixelize', 0.35], cells: ['dissolve', 0.5], 'flip-3d': ['squeezeh', 0.45],
+  'whip-pan': ['slideleft', 0.35],
+};
+for (const [k, [, d]] of Object.entries(MOVE_JOINS)) JOINS[k] = d;
+JOINS.whip = 0.35;   // the engine's own whip (slide + smear) wins over the registry's whip move of the same name
+const OVERLAP = new Set(['whip', 'dissolve', ...Object.keys(MOVE_JOINS)]);   // joins that need the outgoing part to run on under the next
 
 const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
 const pad = (i) => String(i + 1).padStart(2, '0');
@@ -54,8 +67,10 @@ export async function structureFromBoard(ref, option, { site }) {
   if (String(ref).includes('#')) board = await decodeBoard(String(ref).slice(String(ref).indexOf('#') + 1));
   else {
     const id = String(ref).replace(/\/$/, '').split('/').pop();
-    const res = await fetch(`${site}/api/boards/${id}`);
-    if (!res.ok) throw new Error(`board ${id}: ${res.status} from ${site} (expired, or a long link is needed)`);
+    // a full link says where its board lives; a bare id is looked up on the site (--site, or the default)
+    const from = /^https?:\/\//i.test(String(ref)) ? new URL(String(ref)).origin : site;
+    const res = await fetch(`${from}/api/boards/${id}`);
+    if (!res.ok) throw new Error(`board ${id}: ${res.status} from ${from} (expired or never stored there: pass the board's full link, the long #… link, or --site <url>)`);
     board = (await res.json()).board;
   }
   const opts = board?.options ?? [];
@@ -141,28 +156,76 @@ export function plan(chain, infos) {
     const info = infos[i], D = info.config.duration, from = p.from ?? 0;
     const join = i === 0 ? 'cut' : (p.join ?? chain.join ?? 'whip');
     if (!JOINS.hasOwnProperty(join)) throw new Error(`part ${i + 1}: join "${join}" (use ${Object.keys(JOINS).join(', ')})`);
-    let seconds = p.seconds ?? D - from;
-    if (from + seconds > D + 1e-6) { warnings.push(`${p.dir}: ${seconds} s from ${from} runs past its end (${D} s); it plays ${+(D - from).toFixed(2)} s`); seconds = D - from; }
-    const lands = info.marks.filter((m) => m.gesture === 'land').map((m) => m.t).filter((t) => t >= from);
-    const land = lands.length ? Math.max(...lands) : null;
-    if (land !== null && from + seconds < land + LAND_HOLD) warnings.push(`${p.dir}: cut at ${seconds} s loses its land at ${+(land - from).toFixed(2)} s; give it at least ${+(land - from + LAND_HOLD).toFixed(1)} s`);
-    return { ...p, from, seconds, join, D };
+    // a part plays its whole scene: another length plays it faster or slower (never cut, never looped), within limits
+    const natural = +(D - from).toFixed(3), range = lengthRange(natural);
+    let seconds = p.seconds ?? natural;
+    if (seconds < range.min - 1e-6 || seconds > range.max + 1e-6) {
+      const held = Math.min(range.max, Math.max(range.min, seconds));
+      warnings.push(`${p.dir}: ${seconds} s would play its ${natural} s scene too ${seconds < range.min ? 'fast' : 'slow'} (it takes ${range.min}–${range.max} s); it plays ${held} s`);
+      seconds = held;
+    }
+    return { ...p, from, seconds, join, D, natural, rate: natural / seconds };
   });
-  // the outgoing part runs on under an overlapping join, as far as it can
+  // under an overlapping join the outgoing part holds its last frame while the next one comes in
   for (const [i, p] of parts.entries()) {
     const next = parts[i + 1], d = next && OVERLAP.has(next.join) ? JOINS[next.join] : 0;
-    p.to = Math.min(p.D, p.from + p.seconds + d);
+    p.out = +(p.seconds + d).toFixed(3);
   }
   return { parts, warnings, total: parts.reduce((a, p) => a + p.seconds, 0) };
 }
 
+// ── is a joined render still current, and is one being made right now ──────────────────────────────────────
+/**
+ * A fingerprint of everything a joined render shows: the order, lengths and joins in chain.json, each part's
+ * files, the brand's tokens and backgrounds, the project's moves. A render made from another fingerprint is stale.
+ */
+export function chainSig(cwd, dir) {
+  const h = crypto.createHash('sha1');
+  const chain = readJson(path.join(dir, 'chain.json'), { parts: [] });
+  h.update(JSON.stringify([chain.format ?? null, chain.join ?? null, (chain.parts ?? []).map((p) => [p.dir, p.id, p.seconds ?? null, p.from ?? null, p.join ?? null])]));
+  const add = (f) => {
+    try {
+      const st = fs.statSync(f); if (st.isDirectory()) return;
+      h.update(path.basename(f));
+      if (/\.(html|json|js|mjs|css|svg)$/.test(f)) h.update(fs.readFileSync(f)); else h.update(`${st.size}:${Math.round(st.mtimeMs)}`);
+    } catch { /* gone: nothing to add */ }
+  };
+  const all = (d, skip = () => false) => { try { for (const f of fs.readdirSync(d).sort()) if (!skip(f)) add(path.join(d, f)); } catch { /* no such folder */ } };
+  for (const p of chain.parts ?? []) if (p.dir) all(path.join(dir, p.dir), (f) => f.endsWith('.md'));
+  for (const f of ['brand/tokens.json', 'brand/shader-set/set.json', 'brand/sound.json']) add(path.join(cwd, f));
+  all(path.join(cwd, 'moves'));
+  return h.digest('hex').slice(0, 16);
+}
+const sigFile = (dir) => path.join(dir, 'renders', '.sig.json');
+/** What each joined render in renders/ was made from: { "<file>": { sig, sfx, audio } }. */
+export const readSigs = (dir) => readJson(sigFile(dir), {});
+
+// the join in progress, for the studio's "updating" notice and so two joins of the same file never run at once
+const jobFile = (dir) => path.join(dir, '.job.json');
+/** The join running on this piece right now (its process still alive), or null. */
+export function readJob(dir) {
+  const j = readJson(jobFile(dir), null);
+  if (!j) return null;
+  try { process.kill(j.pid, 0); return j; } catch { return null; }
+}
+const writeJob = (dir, j) => { try { fs.writeFileSync(jobFile(dir), JSON.stringify({ pid: process.pid, at: Date.now(), ...j })); } catch { /* read-only: no notice */ } };
+const endJob = (dir) => { try { if (readJson(jobFile(dir), {}).pid === process.pid) fs.rmSync(jobFile(dir)); } catch { /* already gone */ } };
+
 /**
  * Renders every part in the brand's look and joins them into one file.
  * Must run from the project root (where brand/ is): scenes load the brand from /brand.
  */
 export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur = 1, dpr = 1, audio, sfx = true, draft = false, onStep = () => {} }) {
   if (draft) { dpr = 0.5; motionBlur = 1; }
-  return withChain({ cwd, piece }, async ({ dir, url, parts, warnings, total, config }) => {
+  // the piece's own draft and final are tracked (what they were made from, and that they are being made);
+  // a render to another file (--out) is the caller's business
+  const home = pieceDir(piece, cwd), kind = out ? null : draft ? 'assembly' : 'final', sig = kind ? chainSig(cwd, home) : null;
+  if (kind) {
+    const busy = readJob(home);
+    if (busy && busy.pid !== process.pid && busy.kind === kind) throw new Error(`this piece's ${kind === 'assembly' ? 'draft' : 'final'} is already being rendered (${busy.of ? `part ${busy.part} of ${busy.of}` : 'starting'}): wait for it, then look at piece status`);
+    writeJob(home, { kind });
+  }
+  try { return await withChain({ cwd, piece }, async ({ dir, url, parts, warnings, total, config }) => {
     const { renderVideo } = await import('./render.mjs');
     for (const w of warnings) onStep({ warning: w });
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pm-chain-'));
@@ -170,8 +233,9 @@ export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur
       const files = [];
       for (const [i, p] of parts.entries()) {
         onStep({ part: i + 1, of: parts.length, dir: p.dir });
+        if (kind) writeJob(home, { kind, part: i + 1, of: parts.length });
         const f = path.join(tmp, `${pad(i)}.mov`);
-        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.to, sfx, motionBlur, dpr });
+        await renderVideo({ url: url(p), out: f, format: 'prores', from: p.from, to: p.D, rate: p.rate, seconds: p.out, sfx, motionBlur, dpr });
         files.push(f);
       }
       const tokens = readJson(path.join(cwd, 'brand/tokens.json'), {}), sound = readJson(path.join(cwd, 'brand/sound.json'), {});
@@ -180,10 +244,12 @@ export async function renderChain({ cwd = process.cwd(), piece, out, motionBlur
       out = path.resolve(cwd, out ?? path.join(dir, 'renders', `${path.basename(dir)}${draft ? '-draft' : ''}.mp4`));
       fs.mkdirSync(path.dirname(out), { recursive: true });
       onStep({ joining: true });
+      if (kind) writeJob(home, { kind, part: parts.length, of: parts.length, joining: true });
       const j = await join({ files, parts, out, ground, fps, music: audio, lufs: sound.loudness ?? -16 });
+      if (kind) fs.writeFileSync(sigFile(home), JSON.stringify({ ...readSigs(home), [path.basename(out)]: { sig, sfx, ...(audio ? { audio } : {}) } }, null, 2) + '\n');
       return { out, total: j.seconds, planned: total, parts: parts.length, warnings, W, H };
     } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
-  });
+  }); } finally { if (kind) endJob(home); }
 }
 
 /**
@@ -205,7 +271,7 @@ export async function renderDrafts({ cwd = process.cwd(), piece, only, onStep =
       mark(p.dir, { status: 'rendering' });
       const out = path.join(dir, 'drafts', `${p.dir}.mp4`);
       try {
-        await renderVideo({ url: url(p), out, from: p.from, to: p.from + p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
+        await renderVideo({ url: url(p), out, from: p.from, to: p.D, rate: p.rate, seconds: p.seconds, dpr: 0.5, motionBlur: 1, crf: 26 });
       } catch (e) { mark(p.dir, { status: 'review', error: String(e.message ?? e).slice(0, 300) }); throw e; }
       const v = (readPiece(dir)?.parts?.[p.dir]?.v ?? 0) + 1;
       mark(p.dir, { status: 'review', v, error: undefined, note: undefined });
@@ -233,9 +299,20 @@ async function withChain({ cwd, piece }, fn) {
   try {
     const browser = await launch(), infos = [];
     try { for (const p of chain.parts) infos.push(await sceneInfo(browser, url(p))); } finally { await browser.close(); }
+    // what each scene really lasts (some depend on their content: one beat per word), for the studio's length slider
+    try {
+      fs.writeFileSync(path.join(dir, '.lengths.json'), JSON.stringify(Object.fromEntries(chain.parts.map((p, i) => [p.dir, {
+        duration: infos[i].config.duration, mtime: Math.round(fs.statSync(path.join(dir, p.dir, 'scene.html')).mtimeMs),
+      }])), null, 2) + '\n');
+    } catch { /* the slider falls back to the block's usual length */ }
     const sizes = new Set(infos.map((x) => `${x.config.width}x${x.config.height}`));
     if (sizes.size > 1) throw new Error(`parts come in different sizes (${[...sizes].join(', ')}): set the same format in each CONFIG`);
-    return await fn({ dir, chain, url, config: infos[0].config, ...plan(chain, infos) });
+    const planned = plan(chain, infos);
+    // the length the brief asked for ("unos 20 s", "~20s", "16:9 · 20 s"): say so when the chain drifts from it
+    const brief = readJson(path.join(dir, 'piece.json'), null)?.brief?.format ?? '';
+    const want = Number(String(brief).match(/(\d+(?:[.,]\d+)?)\s*(?:s\b|sec|seg)/i)?.[1]?.replace(',', '.'));
+    if (want > 0 && Math.abs(planned.total - want) > Math.max(1.5, want * 0.08)) planned.warnings.push(`the chain runs ${planned.total.toFixed(1)} s and the brief asks for about ${want} s: change some parts' seconds in chain.json, or the brief`);
+    return await fn({ dir, chain, url, config: infos[0].config, ...planned });
   } finally { await server.close(); }
 }
 
@@ -264,7 +341,7 @@ async function join({ files, parts, out, ground, fps, music, lufs }) {
     const j = parts[i].join, d = JOINS[j];
     if (OVERLAP.has(j)) {
       const off = Math.max(0, len - d);
-      g.push(`${v}${V[i]}xfade=transition=${j === 'whip' ? 'slideleft' : 'fade'}:duration=${d}:offset=${off.toFixed(3)}[x${i}]`);
+      g.push(`${v}${V[i]}xfade=transition=${j === 'whip' ? 'slideleft' : MOVE_JOINS[j]?.[0] ?? 'fade'}:duration=${d}:offset=${off.toFixed(3)}[x${i}]`);
       g.push(`${a}${A[i]}acrossfade=d=${d}:c1=tri:c2=tri[y${i}]`);
       if (j === 'whip') smears.push([off + d * 0.12, off + d * 0.88]);
       len = off + lens[i].duration;

package/lib/customize.mjs

@@ -63,8 +63,15 @@ export function recolor(item, pal) {
     return atLuminance(near.h, y) + (m[2] ? m[2] : '');
   };
   const out = {};
+  // the color behind everything takes the brand's ground exactly (its alpha kept), so the frame edge matches the brand
+  const ground = typeof pal?.ground === 'string' ? pal.ground : pal?.ground?.hex;
+  const behind = (name, v) => {
+    if (!/back/i.test(name) || !HEX.test(ground ?? '')) return null;
+    const m = typeof v === 'string' && v.match(HEX);
+    return m ? ground.slice(0, 7) + (m[2] ?? '') : null;
+  };
   for (const p of paramsOf(item)) {
-    if (p.type === 'color') out[p.name] = one(p.default);
+    if (p.type === 'color') out[p.name] = behind(p.name, p.default) ?? one(p.default);
     else if (p.type === 'colors' && Array.isArray(p.default)) out[p.name] = p.default.map(one);
   }
   return out;
@@ -124,7 +131,38 @@ function backgroundEntry(item, values) {
 function paletteTokens(item, values) {
   const e = item.install.entry ?? {};
   const colors = Object.fromEntries(Object.entries(e.colors ?? {}).map(([role, c]) => [role, { ...c, hex: values[role] ?? c.hex }]));
-  return { ...e, colors, ramp: values.ramp ?? e.ramp };
+  return { ...e, colors, ramp: tunedRamp(e, colors, values.ramp) };
+}
+
+/**
+ * The ramp after the colors were tuned: steps equal to a role's old color take its new one; the steps between keep
+ * their tone and take the hue of the nearest new color. A ramp given explicitly wins.
+ */
+function tunedRamp(e, colors, given) {
+  const ramp = e.ramp;
+  if (!Array.isArray(ramp) || (Array.isArray(given) && !same(given, ramp))) return given ?? ramp;
+  const old = Object.fromEntries(Object.entries(e.colors ?? {}).map(([role, c]) => [String(c.hex).toLowerCase(), role]));
+  const fresh = Object.values(colors).map((c) => c.hex).filter((h) => HEX.test(h ?? ''));
+  if (Object.entries(e.colors ?? {}).every(([role, c]) => colors[role].hex === c.hex)) return ramp;
+  // a ramp from one role to another (ground → accent, the usual): the steps between are mixed again from the new ends,
+  // at the same place along the way (by tone), so the ramp keeps its hue
+  const a0 = old[String(ramp[0]).toLowerCase()], a1 = old[String(ramp.at(-1)).toLowerCase()];
+  if (a0 && a1 && a0 !== a1) {
+    const [y0, y1] = [lum(ramp[0]), lum(ramp.at(-1))], [n0, n1] = [srgb(colors[a0].hex).map(lin), srgb(colors[a1].hex).map(lin)];
+    return ramp.map((h, i) => {
+      if (i === 0) return colors[a0].hex;
+      if (i === ramp.length - 1) return colors[a1].hex;
+      const t = Math.min(1, Math.max(0, (lum(h) - y0) / ((y1 - y0) || 1)));
+      return hex(n0.map((c, k) => c + t * (n1[k] - c)));
+    });
+  }
+  const ladder = fresh.map((h) => ({ h, y: lum(h) }));
+  return ramp.map((h) => {
+    const role = old[String(h).toLowerCase()];
+    if (role) return colors[role].hex;
+    const y = lum(h), near = ladder.reduce((a, b) => (Math.abs(b.y - y) < Math.abs(a.y - y) ? b : a));
+    return atLuminance(near.h, y);
+  });
 }
 
 function fontTokens(item, values) {