@vosjs/cli 0.55.1 → 0.56.0

package/README.md

@@ -195,7 +195,7 @@ vos build port/program/program.mjs  # real functions → config.json; refuses a
 vos compare port/program --against ./piece/renders/render.mp4   # per-frame SSIM and source | vos | difference sheets; exit 1 under 0.95
 ```
 
-`inventory` reads the page as a browser renders it (computed styles, not CSS text): a HyperFrames composition's root `data-*`, its `<audio data-start data-volume>`, the scenes its timeline reveals, and each word laid out where it settles in its scene (the piece's own `window.__timelines`, seeked). A Remotion project is bundled with its own `@remotion/bundler` (its dependencies installed) and its first composition mounted the way Remotion's renderer mounts it: the `<Sequence>`s are the scenes, named by the component each holds (a sequence lying over a longer one is a transition, not a scene), the words are read nine tenths into each scene, the palette is named after the colour constants the source declares, and `<Audio>` is the score. Every scene's ground (the frame-filling colour behind it) is measured, and the scaffold stands each scene on it. A word animated one span per letter is read as one `split` word, in its letters' face. A page that paints on a canvas gets the words and faces its scripts name. `compare` needs ffmpeg on PATH; it judges every frame on its own, because one missing element is a frame's failure that an average would hide.
+`inventory` reads the page as a browser renders it (computed styles, not CSS text): a HyperFrames composition's root `data-*`, its `<audio data-start data-volume>`, the scenes its timeline reveals, and each word laid out where it settles in its scene (the piece's own `window.__timelines`, seeked). A Remotion project is bundled with its own `@remotion/bundler` (its dependencies installed) and its first composition mounted the way Remotion's renderer mounts it: the `<Sequence>`s are the scenes, named by the component each holds (a sequence lying over a longer one is a transition, not a scene), the words are read nine tenths into each scene, the palette is named after the colour constants the source declares, and `<Audio>` is the score. Every scene's ground (the frame-filling colour behind it) is measured, and the scaffold stands each scene on it. A word animated one span per letter is read as one `split` word, in its letters' face. A page that paints on a canvas gets the words and faces its scripts name. When the piece needs a painter or its code reaches for a spring or noise, the scaffold writes the PAINTER STARTER into `createContent` as `content.refs.lib`: `spring` (Remotion's spring to the frame, `durationInFrames` included), `springTo` (that spring on the timeline, one linear step per frame), `interpolate`, `bezier`, seeded simplex `noise2D`/`noise3D` (`@remotion/noise`'s character, not its values) and `random`/`rng`, written from the maths, so a port never reads another engine's source for them. `compare` needs ffmpeg on PATH; it judges every frame on its own, because one missing element is a frame's failure that an average would hide.
 
 ## The take directory
 

package/dist/{chunk-FQA7LFXG.js → chunk-XXAY42XS.js}

@@ -9308,7 +9308,9 @@ function mergeSceneTexts(perScene) {
       textPlaced.add(shape);
       out.push({
         ...t,
-        id: `${t.id}-${out.length}`,
+        // A tag-numbered id stays tag-numbered (the scaffold then names the
+        // key after the words); a real id is kept as the source wrote it.
+        id: /^[a-z][a-z0-9]*-\d+$/.test(t.id) ? `${t.tag}-${out.length}` : t.id,
         scene: shared ? null : s.scene
       });
     }
@@ -9531,6 +9533,7 @@ async function readRemotion(dir, log) {
       for (const g of read.gaps ?? []) gaps.add(g);
       perScene.push({ scene: s.name, texts: read.texts ?? [] });
     }
+    const sources = sourceTexts(dir);
     const publicDir = join21(dir, "public");
     const media = tree.audio.map((a) => {
       const name = basename7(a.src.split("?")[0]);
@@ -9550,7 +9553,8 @@ async function readRemotion(dir, log) {
       fps: c.fps,
       duration: Math.round(total * 1e3) / 1e3,
       texts: mergeSceneTexts(perScene),
-      palette: themeColors(sourceTexts(dir)),
+      palette: themeColors(sources),
+      uses: sourceUses(sources.join("\n")),
       colors: [...colors],
       gaps: [...gaps],
       media,
@@ -9666,6 +9670,15 @@ function scriptFontFamilies(code) {
   }
   return [...out];
 }
+function sourceUses(code) {
+  const out = [];
+  if (/\bspring\s*\(|\bmeasureSpring\s*\(/.test(code)) out.push("spring");
+  if (/@remotion\/noise|\bnoise[234]D\s*\(/.test(code)) out.push("noise");
+  if (/\binterpolate\s*\(/.test(code)) out.push("interpolate");
+  if (/Easing\.bezier\s*\(|cubic-bezier\(/.test(code)) out.push("bezier");
+  if (/\brandom\s*\(\s*['"\w]/.test(code)) out.push("random");
+  return out;
+}
 function catalogFamily2(family) {
   const clean = family.trim().replace(/^['"]|['"]$/g, "");
   return findFontFamily3(clean)?.family ?? null;
@@ -10017,6 +10030,7 @@ async function readInventory(source, opts) {
     gaps: read.gaps,
     variables: read.variables,
     scriptStrings,
+    uses: read.uses ?? sourceUses(read.scriptText ?? ""),
     render: render ? relative2(process.cwd(), render) : null,
     stills
   };
@@ -10027,6 +10041,191 @@ import { spawnSync as spawnSync3 } from "child_process";
 import { copyFileSync, existsSync as existsSync19, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
 import { basename as basename8, dirname as dirname7, join as join23, resolve as resolve10 } from "path";
 import { findFontFamily as findFontFamily4, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
+
+// src/plugin/painterLib.ts
+var PAINTER_LIB = `    // THE PAINTER STARTER (vos port): the maths every port re-wrote, in one
+    // place: content.refs.lib in createTimeline and onFrame.
+    const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v)
+    const hashSeed = (seed) => {
+      if (typeof seed === 'number') return seed | 0
+      let h = 2166136261
+      for (const ch of String(seed)) h = Math.imul(h ^ ch.charCodeAt(0), 16777619)
+      return h | 0
+    }
+    const rng = (seed) => {
+      let s = hashSeed(seed)
+      return () => {
+        s = (s + 0x6d2b79f5) | 0
+        let r = Math.imul(s ^ (s >>> 15), 1 | s)
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296
+      }
+    }
+    const random = (seed) => rng(seed)()
+    // interpolate(input, [a, b, ...], [x, y, ...], { extrapolateLeft, extrapolateRight, easing })
+    const interpolate = (input, inR, outR, opts = {}) => {
+      let i = 1
+      while (i < inR.length - 1 && input > inR[i]) i++
+      const a = inR[i - 1], b = inR[i]
+      let t = b === a ? 0 : (input - a) / (b - a)
+      if (t < 0) {
+        if (opts.extrapolateLeft === 'clamp') t = 0
+        else if (opts.extrapolateLeft === 'identity') return input
+      }
+      if (t > 1) {
+        if (opts.extrapolateRight === 'clamp') t = 1
+        else if (opts.extrapolateRight === 'identity') return input
+      }
+      const e = opts.easing ? opts.easing(t) : t
+      return outR[i - 1] + (outR[i] - outR[i - 1]) * e
+    }
+    // bezier(x1, y1, x2, y2): a CSS cubic-bezier as an easing function.
+    const bezier = (x1, y1, x2, y2) => {
+      const cx = 3 * x1, bx = 3 * (x2 - x1) - cx, ax = 1 - cx - bx
+      const cy = 3 * y1, by = 3 * (y2 - y1) - cy, ay = 1 - cy - by
+      const sx = (t) => ((ax * t + bx) * t + cx) * t
+      const sy = (t) => ((ay * t + by) * t + cy) * t
+      const dx = (t) => (3 * ax * t + 2 * bx) * t + cx
+      return (x) => {
+        if (x <= 0) return 0
+        if (x >= 1) return 1
+        let t = x
+        for (let k = 0; k < 8; k++) {
+          const d = dx(t)
+          if (Math.abs(d) < 1e-6) break
+          const t2 = t - (sx(t) - x) / d
+          if (t2 < 0 || t2 > 1) break
+          t = t2
+        }
+        let lo = 0, hi = 1
+        if (Math.abs(sx(t) - x) > 1e-6) {
+          t = x
+          for (let k = 0; k < 40; k++) {
+            if (sx(t) < x) lo = t; else hi = t
+            t = (lo + hi) / 2
+          }
+        }
+        return sy(t)
+      }
+    }
+    // spring({ frame, fps, config: { damping, mass, stiffness, overshootClamping }, from, to, delay })
+    const springUnit = (t, config = {}) => {
+      const m = config.mass ?? 1, k = config.stiffness ?? 100, c = config.damping ?? 10
+      const w0 = Math.sqrt(k / m), z = c / (2 * Math.sqrt(k * m))
+      if (t <= 0) return 0
+      // A damping ratio of 1 or more settles CRITICALLY at the natural
+      // frequency, as Remotion's spring does (measured to 1e-16 across
+      // overdamped configs; true overdamped motion would crawl, and
+      // \`damping: 200\` is the smooth spring sources reach for).
+      if (z >= 1) return 1 - Math.exp(-w0 * t) * (1 + w0 * t)
+      const wd = w0 * Math.sqrt(1 - z * z)
+      return 1 - Math.exp(-z * w0 * t) * (Math.cos(wd * t) + ((z * w0) / wd) * Math.sin(wd * t))
+    }
+    // The frames a spring takes to settle within half a percent and stay there.
+    const springFrames = (fps, config = {}) => {
+      let last = 0
+      for (let f = 0; f <= fps * 10; f++)
+        if (Math.abs(springUnit(f / fps, config) - 1) >= 0.005) last = f
+      return last + 1
+    }
+    // durationInFrames stretches the spring so it settles on that frame, and
+    // past it the value IS \`to\` (as Remotion's does, measured).
+    const spring = ({ frame, fps, config = {}, from = 0, to = 1, delay = 0, durationInFrames }) => {
+      const f = Math.max(0, frame - delay)
+      if (durationInFrames && f > durationInFrames) return to
+      const scale = durationInFrames ? springFrames(fps, config) / durationInFrames : 1
+      let x = springUnit((f * scale) / fps, config)
+      if (config.overshootClamping && x > 1) x = 1
+      return from + (to - from) * x
+    }
+    // springTo(tl, target, { x: [from, to] }, at, { fps, config, frames }): the
+    // spring on the timeline, one linear step per frame; returns its end time.
+    const springTo = (tl, target, props, at, opts = {}) => {
+      const fps = opts.fps || 30
+      const frames = opts.frames ?? springFrames(fps, opts.config)
+      const keys = Object.keys(props)
+      const start = {}
+      for (const k of keys) start[k] = props[k][0]
+      tl.set(target, start, at)
+      for (let f = 1; f <= frames; f++) {
+        const s = f === frames ? 1 : spring({ frame: f, fps, config: opts.config })
+        const v = { duration: 1 / fps, ease: 'none' }
+        for (const k of keys) v[k] = props[k][0] + (props[k][1] - props[k][0]) * s
+        tl.to(target, v, at + (f - 1) / fps)
+      }
+      return at + frames / fps
+    }
+    // Seeded simplex noise in [-1, 1] (Gustavson's construction).
+    const grad3 = [[1,1,0],[-1,1,0],[1,-1,0],[-1,-1,0],[1,0,1],[-1,0,1],[1,0,-1],[-1,0,-1],[0,1,1],[0,-1,1],[0,1,-1],[0,-1,-1]]
+    const perms = new Map()
+    const perm = (seed) => {
+      const key = String(seed)
+      let p = perms.get(key)
+      if (!p) {
+        const r = rng(seed)
+        const base = Array.from({ length: 256 }, (_, i) => i)
+        for (let i = 255; i > 0; i--) {
+          const j = Math.floor(r() * (i + 1))
+          const t = base[i]; base[i] = base[j]; base[j] = t
+        }
+        p = new Uint8Array(512)
+        for (let i = 0; i < 512; i++) p[i] = base[i & 255]
+        perms.set(key, p)
+      }
+      return p
+    }
+    const noise2D = (seed, x, y) => {
+      const p = perm(seed)
+      const F2 = 0.5 * (Math.sqrt(3) - 1), G2 = (3 - Math.sqrt(3)) / 6
+      const s = (x + y) * F2
+      const i = Math.floor(x + s), j = Math.floor(y + s)
+      const t = (i + j) * G2
+      const x0 = x - (i - t), y0 = y - (j - t)
+      const i1 = x0 > y0 ? 1 : 0, j1 = x0 > y0 ? 0 : 1
+      const x1 = x0 - i1 + G2, y1 = y0 - j1 + G2
+      const x2 = x0 - 1 + 2 * G2, y2 = y0 - 1 + 2 * G2
+      const ii = i & 255, jj = j & 255
+      const corner = (gi, cx, cy) => {
+        const tt = 0.5 - cx * cx - cy * cy
+        if (tt < 0) return 0
+        const g = grad3[gi % 12]
+        return tt * tt * tt * tt * (g[0] * cx + g[1] * cy)
+      }
+      return 70 * (corner(p[ii + p[jj]], x0, y0) + corner(p[ii + i1 + p[jj + j1]], x1, y1) + corner(p[ii + 1 + p[jj + 1]], x2, y2))
+    }
+    const noise3D = (seed, x, y, z) => {
+      const p = perm(seed)
+      const F3 = 1 / 3, G3 = 1 / 6
+      const s = (x + y + z) * F3
+      const i = Math.floor(x + s), j = Math.floor(y + s), k = Math.floor(z + s)
+      const t = (i + j + k) * G3
+      const x0 = x - (i - t), y0 = y - (j - t), z0 = z - (k - t)
+      let i1, j1, k1, i2, j2, k2
+      if (x0 >= y0) {
+        if (y0 >= z0) { i1 = 1; j1 = 0; k1 = 0; i2 = 1; j2 = 1; k2 = 0 }
+        else if (x0 >= z0) { i1 = 1; j1 = 0; k1 = 0; i2 = 1; j2 = 0; k2 = 1 }
+        else { i1 = 0; j1 = 0; k1 = 1; i2 = 1; j2 = 0; k2 = 1 }
+      } else {
+        if (y0 < z0) { i1 = 0; j1 = 0; k1 = 1; i2 = 0; j2 = 1; k2 = 1 }
+        else if (x0 < z0) { i1 = 0; j1 = 1; k1 = 0; i2 = 0; j2 = 1; k2 = 1 }
+        else { i1 = 0; j1 = 1; k1 = 0; i2 = 1; j2 = 1; k2 = 0 }
+      }
+      const ii = i & 255, jj = j & 255, kk = k & 255
+      const corner = (gi, cx, cy, cz) => {
+        const tt = 0.6 - cx * cx - cy * cy - cz * cz
+        if (tt < 0) return 0
+        const g = grad3[gi % 12]
+        return tt * tt * tt * tt * (g[0] * cx + g[1] * cy + g[2] * cz)
+      }
+      return 32 * (
+        corner(p[ii + p[jj + p[kk]]], x0, y0, z0) +
+        corner(p[ii + i1 + p[jj + j1 + p[kk + k1]]], x0 - i1 + G3, y0 - j1 + G3, z0 - k1 + G3) +
+        corner(p[ii + i2 + p[jj + j2 + p[kk + k2]]], x0 - i2 + 2 * G3, y0 - j2 + 2 * G3, z0 - k2 + 2 * G3) +
+        corner(p[ii + 1 + p[jj + 1 + p[kk + 1]]], x0 - 1 + 3 * G3, y0 - 1 + 3 * G3, z0 - 1 + 3 * G3))
+    }
+    const lib = { clamp, interpolate, bezier, spring, springFrames, springTo, noise2D, noise3D, random, rng }`;
+
+// src/plugin/portScaffold.ts
 var DESIGN_HEIGHT = 1080;
 function toHex(css) {
   const s = css.trim();
@@ -10220,6 +10419,9 @@ function planScaffold(inv, opts) {
     }
   ] : [];
   const painter = inv.canvases.length > 0 || inv.gaps.length > 0;
+  const uses = inv.uses ?? [];
+  const lib = painter || uses.length > 0;
+  if (uses.includes("spring")) data.fps = inv.fps ?? 30;
   const duration = Math.round((inv.duration ?? 5) * 1e3) / 1e3;
   const program = programSource({
     source: inv.source,
@@ -10230,7 +10432,9 @@ function planScaffold(inv, opts) {
     fonts,
     elements,
     scenes: inv.scenes,
-    painter
+    painter,
+    lib,
+    uses
   });
   const audio = [];
   const copies = [];
@@ -10280,6 +10484,7 @@ function planScaffold(inv, opts) {
       elements: elements.length,
       params: params.length,
       painter,
+      uses,
       scores: audio.map((a) => String(a.key)),
       extra: report
     })
@@ -10290,6 +10495,12 @@ function programSource(p) {
   const sceneTodos = p.scenes.length ? p.scenes.map(
     (s) => `    // TODO scene "${s.name}" (${s.start}s${s.duration ? ` to ${s.start + s.duration}s` : ""}): translate its motion onto ctx.elements.get(id).props / .segments here`
   ).join("\n") : "    // TODO: translate the source's motion here, one block per scene (tl.addLabel above names them)";
+  const springHint = p.uses.includes("spring") ? `
+    // The source springs: content.refs.lib.springTo(tl, target, { y: [120, 0] }, at,
+    //   { fps: ctx.data.fps, config: { damping: 200 } }) puts Remotion's spring on
+    //   the timeline frame by frame (spring({ frame, fps, config }) for a value).` : "";
+  const libBlock = p.lib ? `
+${PAINTER_LIB}` : "";
   const painterContent = p.painter ? `
     // THE PAINTER (vos-port rule 6): one canvas, only for what no element can
     // say (the inventory's gaps and canvases). It reads every value from
@@ -10309,30 +10520,8 @@ function programSource(p) {
     plane.renderOrder = 100.995
     plane.frustumCulled = false
     ctx.overlayScene.add(plane)
-    // The starter's helpers: Remotion's interpolate, a seeded PRNG, smooth noise.
-    const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v)
-    const interpolate = (v, [a, b], [x, y], ease = (t) => t) =>
-      x + (y - x) * ease(clamp01((v - a) / (b - a)))
-    const rand = (seed) => () => {
-      seed |= 0
-      seed = (seed + 0x6d2b79f5) | 0
-      let r = Math.imul(seed ^ (seed >>> 15), 1 | seed)
-      r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r
-      return ((r ^ (r >>> 14)) >>> 0) / 4294967296
-    }
-    const hash = (x, y) => {
-      const s = Math.sin(x * 127.1 + y * 311.7) * 43758.5453
-      return s - Math.floor(s)
-    }
-    const noise2 = (x, y) => {
-      const xi = Math.floor(x), yi = Math.floor(y)
-      const xf = x - xi, yf = y - yi
-      const u = xf * xf * (3 - 2 * xf), v = yf * yf * (3 - 2 * yf)
-      const a = hash(xi, yi), b = hash(xi + 1, yi), c = hash(xi, yi + 1), d = hash(xi + 1, yi + 1)
-      return (a + (b - a) * u + (c - a) * v + (a - b - c + d) * u * v) * 2 - 1
-    }
-    return { objects: [], refs: { canvas, g: canvas.getContext('2d'), tex, lib: { interpolate, rand, noise2 } } }` : `
-    return { objects: [], refs: {} }`;
+    return { objects: [], refs: { canvas, g: canvas.getContext('2d'), tex${p.lib ? ", lib" : ""} } }` : `
+    return { objects: [], refs: {${p.lib ? " lib " : ""}} }`;
   const painterFrame = p.painter ? `
     // Paint the procedural layer from ctx.time and ctx.data, then upload it.
     const { canvas, g, tex } = content.refs
@@ -10356,7 +10545,7 @@ export default {
   elements: ${j(p.elements)},
 
   createContent(ctx) {
-    ctx.scene.background = new ctx.THREE.Color(ctx.data.bg)${painterContent}
+    ctx.scene.background = new ctx.THREE.Color(ctx.data.bg)${libBlock}${painterContent}
   },
 
   createTimeline(ctx, content, duration) {
@@ -10375,7 +10564,7 @@ export default {
         if (s.until != null && s.until < duration) tl.set(p, { opacity: 0 }, s.until)
       }
     }
-${sceneTodos}
+${sceneTodos}${springHint}
     tl.to({}, { duration }, 0)
     return tl
   },
@@ -10401,6 +10590,9 @@ function reportText(inv, r) {
     "",
     `- ${r.elements} words as bound text elements, ${Object.keys(inv.palette).length} palette colours the source names (its custom properties or colour constants), ${r.params} knobs.`,
     `- ${inv.scenes.length} scenes as labels${inv.scenes.length ? "" : " (none declared: name them as you translate)"}.`,
+    ...r.painter || r.uses.length ? [
+      `- the painter starter as \`content.refs.lib\`${r.uses.length ? ` (the source uses ${r.uses.join(", ")})` : ""}: \`spring\` (Remotion's, to the frame, \`durationInFrames\` included) and \`springTo\` (a spring on the timeline, a step per frame), \`interpolate\`, \`bezier\`, \`noise2D\`/\`noise3D\` (simplex: \`@remotion/noise\`'s character, not its values, so match blobs by eye), \`random\`/\`rng\`. Use these instead of reading the source engine's code.`
+    ] : [],
     ...r.scores.length ? [
       `- the score as a doc.json track (${r.scores.join(", ")}, copied beside the program; vos push uploads it).`
     ] : [],
@@ -14497,4 +14689,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-FQA7LFXG.js.map
+//# sourceMappingURL=chunk-XXAY42XS.js.map