agentvfx 0.0.0-stage → 0.3.5

package/skills/agentvfx/engine/core/flash.mjs

@@ -0,0 +1,240 @@
+// Flash audit for agentvfx, adapted from lit-typographic-motion 1.0.45 engine/core/flash.mjs (MIT).
+// Pure report: frames are read, never modified (spec Amendment A1: stage mode keeps full intensity).
+//
+// Method: each RGBA frame is area-averaged onto a 320x180 linear-light grid. A flash is a pair of
+// OPPOSING luminance changes of the SAME area (WCAG 2.2 / BT.1702-3), so the test is per cell first:
+// a cell registers a transition when its luminance moves at least 0.1 from the extreme it reached
+// since its last transition, in the direction opposite to that last transition, while the darker of
+// the two is below 0.8. Continued motion the same way is not a new transition. A frame-level
+// transition exists when, on that one frame, the cells that registered a transition in one
+// direction cover more than 25% of some 1/3 x 1/3 window of the grid. Cells that brighten and
+// cells that darken in the same frame (a moving edge) never combine into a transition pair; a
+// frame where both directions fill a window counts as a single alternating transition. Red uses
+// the same method on (R-G-B)x320 over saturated-red cells (R/(R+G+B) >= 0.8). Verdicts: BT.1702-3
+// (more than 6 transitions in any 1 s), any red flash, and the IRIS-style extended rule (at least 4
+// transitions in each of 4 consecutive seconds, at any frame offset; reported alone, not folded
+// into `exceeds`).
+import { FLASH, LINEAR_LUT } from "./flash-constants.mjs";
+
+export { LINEAR_LUT };
+
+/**
+ * The audit grid for a frame: 6x6 px cells and the 640x360 window, transposed for a portrait
+ * frame (180x320 cells, a 60x107 window) so the 10-degree field keeps its size in either format.
+ */
+export function gridFor(width = 1920, height = 1080) {
+  const [gw, gh] = FLASH.grid;
+  const [ww, wh] = FLASH.windowCells;
+  return width >= height ? { gw, gh, ww, wh } : { gw: gh, gh: gw, ww: wh, wh: ww };
+}
+
+/**
+ * Per-cell hysteresis. `hi`/`lo` are the extremes since the cell's last counted transition, `last`
+ * is that transition's direction (0 = none yet). A transition counts only against `last`.
+ */
+class CellTracker {
+  constructor(cells, delta, ceiling) {
+    this.delta = delta;
+    this.ceiling = ceiling;
+    this.hi = new Float32Array(cells);
+    this.lo = new Float32Array(cells);
+    this.last = new Int8Array(cells);
+  }
+
+  start(values) {
+    this.hi.set(values);
+    this.lo.set(values);
+  }
+
+  /** Feed cell i's value; returns +1 / -1 when it counts a transition, else 0. */
+  update(i, v) {
+    const { hi, lo, last, delta, ceiling } = this;
+    let dir = 0;
+    if (last[i] !== 1 && v - lo[i] >= delta && Math.min(v, lo[i]) < ceiling) dir = 1;
+    else if (last[i] !== -1 && hi[i] - v >= delta && Math.min(v, hi[i]) < ceiling) dir = -1;
+    if (dir) {
+      hi[i] = v; lo[i] = v; last[i] = dir;
+    } else {
+      if (v > hi[i]) hi[i] = v;
+      if (v < lo[i]) lo[i] = v;
+    }
+    return dir;
+  }
+}
+
+/** Streaming detector. Each frame is { R, G, B }: linear 0..1 cell averages on the grid. */
+export class FlashDetector {
+  constructor(grid = gridFor()) {
+    const { gw, gh, ww, wh } = grid;
+    this.grid = grid;
+    this.cells = gw * gh;
+    this.windowLimit = FLASH.windowArea * ww * wh;
+    this.frames = 0;
+    this.lum = new CellTracker(this.cells, FLASH.delta, FLASH.darkCeiling);
+    this.red = new CellTracker(this.cells, FLASH.redDelta, Infinity);
+    this.prevL = new Float32Array(this.cells);
+    this.sat = new Int32Array((gw + 1) * (gh + 1));
+  }
+
+  /**
+   * Feed one frame; returns { up, down, redUp, redDown, stepArea, edge }. The four flags say that,
+   * on this frame, the cells registering a transition that way cover a window; `edge` says this
+   * frame moved any cell that way.
+   */
+  push({ R, G, B }) {
+    const CELLS = this.cells;
+    const L = new Float32Array(CELLS);
+    const V = new Float32Array(CELLS);
+    for (let i = 0; i < CELLS; i++) {
+      L[i] = 0.2126 * R[i] + 0.7152 * G[i] + 0.0722 * B[i];
+      const sum = R[i] + G[i] + B[i];
+      V[i] = sum > 0 && R[i] / sum >= FLASH.redRatio ? Math.max(0, R[i] - G[i] - B[i]) * FLASH.redScale : 0;
+    }
+    const maps = { up: new Uint8Array(CELLS), down: new Uint8Array(CELLS), redUp: new Uint8Array(CELLS), redDown: new Uint8Array(CELLS) };
+    const edge = { up: false, down: false, redUp: false, redDown: false };
+    let stepCells = 0;
+    if (this.frames === 0) {
+      this.lum.start(L);
+      this.red.start(V);
+    } else {
+      for (let i = 0; i < CELLS; i++) {
+        if (Math.abs(L[i] - this.prevL[i]) >= FLASH.delta) stepCells += 1;
+        const l = this.lum.update(i, L[i]);
+        if (l) { maps[l > 0 ? "up" : "down"][i] = 1; edge[l > 0 ? "up" : "down"] = true; }
+        const r = this.red.update(i, V[i]);
+        if (r) { maps[r > 0 ? "redUp" : "redDown"][i] = 1; edge[r > 0 ? "redUp" : "redDown"] = true; }
+      }
+    }
+    this.prevL = L;
+    this.frames += 1;
+    const result = { stepArea: +(stepCells / CELLS).toFixed(4), edge };
+    for (const dir of ["up", "down", "redUp", "redDown"]) result[dir] = edge[dir] && this.windowHit(maps[dir]);
+    return result;
+  }
+
+  // Largest window count of this frame's transition map via a summed-area table.
+  windowHit(map) {
+    const { gw: GW, gh: GH, ww: WW, wh: WH } = this.grid;
+    const sat = this.sat;
+    const stride = GW + 1;
+    for (let y = 0; y < GH; y++) {
+      let row = 0;
+      for (let x = 0; x < GW; x++) {
+        row += map[y * GW + x];
+        sat[(y + 1) * stride + x + 1] = sat[y * stride + x + 1] + row;
+      }
+    }
+    if (sat[GH * stride + GW] <= this.windowLimit) return false;
+    for (let y = 0; y + WH <= GH; y++) {
+      for (let x = 0; x + WW <= GW; x++) {
+        const count = sat[(y + WH) * stride + x + WW] - sat[y * stride + x + WW] - sat[(y + WH) * stride + x] + sat[y * stride + x];
+        if (count > this.windowLimit) return true;
+      }
+    }
+    return false;
+  }
+}
+
+/** Area-average an RGBA8 frame of any size onto its audit grid in linear light. */
+export function cellsFromRgba(bytes, width, height, lut = LINEAR_LUT, { gw: GW, gh: GH } = gridFor(width, height)) {
+  const CELLS = GW * GH;
+  const R = new Float32Array(CELLS);
+  const G = new Float32Array(CELLS);
+  const B = new Float32Array(CELLS);
+  const count = new Float32Array(CELLS);
+  for (let y = 0; y < height; y++) {
+    const cy = Math.min(GH - 1, Math.floor((y * GH) / height)) * GW;
+    for (let x = 0; x < width; x++) {
+      const c = cy + Math.min(GW - 1, Math.floor((x * GW) / width));
+      const o = (y * width + x) * 4;
+      R[c] += lut[bytes[o]];
+      G[c] += lut[bytes[o + 1]];
+      B[c] += lut[bytes[o + 2]];
+      count[c] += 1;
+    }
+  }
+  for (let i = 0; i < CELLS; i++) {
+    const n = count[i] || 1;
+    R[i] /= n; G[i] /= n; B[i] /= n;
+  }
+  return { R, G, B };
+}
+
+// Consecutive same-direction transitions collapse into one edge; an edge is one "transition".
+function edgesIn(events, start, span) {
+  let edges = 0;
+  let last = 0;
+  for (const t of events) {
+    if (t.frame < start || t.frame >= start + span || t.dir === last) continue;
+    edges += 1;
+    last = t.dir;
+  }
+  return edges;
+}
+
+function summarize(general, red, count, fps) {
+  const span = Math.round(fps);
+  let worst = { startFrame: 0, transitions: 0 };
+  for (const { frame } of general) {
+    const transitions = edgesIn(general, frame, span);
+    if (transitions > worst.transitions) worst = { startFrame: frame, transitions };
+  }
+  const perSecond = [];
+  for (let s = 0; s * span < count; s++) {
+    perSecond.push({ second: s, transitions: edgesIn(general, s * span, span), redTransitions: edgesIn(red, s * span, span) });
+  }
+  let extendedFlashing = false;
+  for (let s0 = 0; !extendedFlashing && s0 + FLASH.extendedSeconds * span <= count; s0++) {
+    extendedFlashing = Array.from({ length: FLASH.extendedSeconds }, (_, k) => edgesIn(general, s0 + k * span, span))
+      .every((n) => n >= FLASH.extendedMinTransitions);
+  }
+  const redFlashes = Math.floor(edgesIn(red, 0, count) / 2);
+  return {
+    exceeds: worst.transitions > FLASH.maxTransitionsPerSecond || redFlashes > 0,
+    worstWindow: { ...worst, startSec: +(worst.startFrame / fps).toFixed(3) },
+    flashesPerSecondMax: Math.floor(worst.transitions / 2),
+    redFlashes,
+    extendedFlashing,
+    perSecond,
+    limits: { ...FLASH, fps, frames: count },
+  };
+}
+
+// One event per frame: a lone direction is that direction; both directions filling windows on the
+// same frame (opposite areas moving against each other) is one transition, alternating with the last.
+function frameDir(up, down, last) {
+  if (up && down) return last === 1 ? -1 : 1;
+  return up ? 1 : down ? -1 : 0;
+}
+
+/**
+ * Streaming auditor: push RGBA frames one at a time (only transition events are kept, never the
+ * frames), then finish() for the report. Reports only; the pushed bytes are not modified.
+ */
+export function createFlashAuditor({ fps, width, height }) {
+  if (!(Number.isFinite(fps) && fps > 0)) throw new TypeError("createFlashAuditor: fps must be a positive number");
+  const grid = gridFor(width, height);
+  const detector = new FlashDetector(grid);
+  const general = [];
+  const red = [];
+  return {
+    push(frame) {
+      const frameIndex = detector.frames;
+      const r = detector.push(cellsFromRgba(frame.data, frame.width, frame.height, LINEAR_LUT, grid));
+      const dir = frameDir(r.up, r.down, general.at(-1)?.dir ?? 0);
+      if (dir) general.push({ frame: frameIndex, dir });
+      const redDir = frameDir(r.redUp, r.redDown, red.at(-1)?.dir ?? 0);
+      if (redDir) red.push({ frame: frameIndex, dir: redDir });
+    },
+    finish: () => summarize(general, red, detector.frames, fps),
+  };
+}
+
+/** Audit a whole frame sequence ({ width, height, data } RGBA sRGB) at `fps`. */
+export function auditFlash(frames, { fps }) {
+  if (!(Number.isFinite(fps) && fps > 0)) throw new TypeError("auditFlash: fps must be a positive number");
+  const first = frames[0] ?? { width: 1920, height: 1080 };
+  const auditor = createFlashAuditor({ fps, width: first.width, height: first.height });
+  for (const frame of frames) auditor.push(frame);
+  return auditor.finish();
+}

package/skills/agentvfx/engine/core/mark.mjs

@@ -0,0 +1,25 @@
+// agentvfx (Apache-2.0, see LICENSE). Local replacement for the plugin's lib/mark.mjs: the generator
+// tag and the credit line that ffmpeg writes into every MP4, plus an optional comment (the stage-mode flashing notice).
+// The credit also goes to CREDIT.txt next to the film, so it is easy to paste when the film is published.
+export const GENERATOR = "agentvfx";
+export const CREDIT_TEXT = "Made with agentvfx by Woojin Go - https://github.com/wjgoarxiv/agentvfx";
+export const CREDIT_SHORT = "VFX: agentvfx (github.com/wjgoarxiv/agentvfx)";
+
+export function creditText() {
+  return `${CREDIT_TEXT}
+
+Publishing this film? A credit is appreciated, not required. The film carries a small on-screen credit; you can
+keep it in the frame, or switch it off ("credit": { "overlay": false }) and put the line above in the description,
+caption or credits. Where space is short: ${CREDIT_SHORT}
+Licence: Apache-2.0. See LICENSE and NOTICE in https://github.com/wjgoarxiv/agentvfx.
+`;
+}
+
+export function ffmpegMetadataArgs({ comment = null } = {}) {
+  const args = ["-metadata", `encoder_tool=${GENERATOR}`, "-metadata", `description=${CREDIT_TEXT}`];
+  if (comment) args.push("-metadata", `comment=${comment}`);
+  return args;
+}
+
+// The on-screen credit burned into a corner of every render unless the score sets "credit": { "overlay": false }.
+export const CREDIT_OVERLAY = "made with agentvfx";

package/skills/agentvfx/engine/core/palettes.mjs

@@ -0,0 +1,36 @@
+// agentvfx (Apache-2.0, see LICENSE). Shared palettes, usable by any template that declares a `palette` input.
+// Each palette is a list of sRGB hex stops; templates sample it as a ramp (index 0..1) or as a cyclic
+// ramp. Brutal palettes are black, white and one acid accent, in the spirit of festival HUD
+// colour grammar; the names are neutral and no existing colour system is copied.
+
+export const PALETTES = Object.freeze({
+  "brutal-acid": ["#000000", "#ffffff", "#c8ff00"],
+  "brutal-red": ["#000000", "#ffffff", "#ff2a00"],
+  mono: ["#000000", "#ffffff"],
+  rainbow: ["#ff0040", "#ff8000", "#ffee00", "#30ff40", "#00e5ff", "#2040ff", "#b000ff", "#ff00c8"],
+  thermal: ["#0010ff", "#6a00ff", "#ff00d0", "#ff0030", "#ff7a00", "#ffee00", "#00ffe0"],
+  "paper-grey": ["#d9d9d6", "#0a0a0a", "#ff2a6d"],
+  "acid-data": ["#000000", "#b6ff00", "#1f4dff"],
+  "hazard-orange": ["#141414", "#8c8c88", "#ff5a00"],
+  "flesh-pink": ["#ffffff", "#ff3c8e", "#111111"],
+  "lilac-terminal": ["#0b0613", "#b69cff", "#ff6ad5"],
+  "blood-red": ["#000000", "#d10000", "#ffffff"],
+  "clinic-mint": ["#f2f4f1", "#7fe3c1", "#b8a4ff"],
+});
+
+export const PALETTE_NAMES = Object.freeze(Object.keys(PALETTES));
+
+/** "#rrggbb" -> [r, g, b] in 0..1 (sRGB). */
+export function hexToRgb(hex) {
+  const m = /^#([0-9a-f]{6})$/iu.exec(hex);
+  if (!m) throw new Error(`not a #rrggbb colour: ${hex}`);
+  const n = parseInt(m[1], 16);
+  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
+}
+
+/** A palette name or a custom list of 2-8 hex stops -> list of [r, g, b]. */
+export function resolvePalette(value) {
+  const stops = typeof value === "string" ? PALETTES[value] : value;
+  if (!Array.isArray(stops)) throw new Error(`unknown palette: ${value}`);
+  return stops.map(hexToRgb);
+}

package/skills/agentvfx/engine/core/schedule.mjs

@@ -0,0 +1,85 @@
+// agentvfx (Apache-2.0, see LICENSE). The score compositor's timeline: for each frame, which layers are active
+// (base stack, cuts, hits), their parameter values (preset, params, audio bindings) and their local
+// time. Pure and deterministic; the page only draws what this returns.
+import { resolveParams } from "./templates.mjs";
+
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+
+/** Resolve a `t` / `beat` / `onset` reference to a frame index. */
+export function resolveFrame(ref, { fps, features }, path) {
+  if (ref.t !== undefined) return Math.round(ref.t * fps);
+  const kind = ref.beat !== undefined ? "beat" : "onset";
+  const list = kind === "beat" ? features?.meta?.beats : features?.meta?.onsets;
+  if (!list) throw Object.assign(new Error(`${path}.${kind}: needs an audio source (input.audio or a video with sound)`), { path: `${path}.${kind}` });
+  const idx = ref[kind];
+  if (idx >= list.length) throw Object.assign(new Error(`${path}.${kind}: index ${idx} but the track has ${list.length} ${kind}s`), { path: `${path}.${kind}` });
+  return list[idx];
+}
+
+const layerRef = (l) => (typeof l === "string" ? { template: l } : l);
+
+/** Feature value for a binding ("bands.12" or a scalar name) on one frame of features. */
+function featureValue(frame, feature) {
+  if (!frame) return 0;
+  if (feature.startsWith("bands.")) return Number(frame.bands?.[Number(feature.slice(6))] ?? 0);
+  return Number(frame[feature] ?? 0);
+}
+
+/**
+ * Build the per-frame plan. Returns { frameCount, frames: [{ layers: [{key, template, params, t}] }],
+ * templatesUsed: Set, events: [frame...] } where events are the frames of hits and cuts (for strips).
+ */
+export function buildSchedule(score, lib, { features = null } = {}) {
+  const fps = score.fps;
+  const frameCount = Math.round(score.durationSec * fps);
+  const ctx = { fps, features };
+  const used = new Set();
+  const resolve = (ref) => {
+    const tpl = lib.get(ref.template);
+    used.add(ref.template);
+    const text = tpl.fx.X_AGENTVFX.text;
+    const labels = text ? Object.fromEntries(text.map((t) => [t.key, score.labels?.[t.key] ?? t.default])) : null;
+    const styled = text && score.textStyle ? text.filter((t) => score.textStyle[t.key]) : [];
+    const textStyle = styled.length ? Object.fromEntries(styled.map((t) => [t.key, score.textStyle[t.key]])) : null;
+    return { template: ref.template, params: resolveParams(tpl.fx, ref), inputs: tpl.fx.INPUTS ?? [], labels, textStyle };
+  };
+  const initial = [{ template: score.template, preset: score.preset, params: score.params }, ...(score.stack ?? []).map(layerRef)].map(resolve);
+  const cuts = (score.cuts ?? []).map((c, i) => ({ frame: resolveFrame(c, ctx, `cuts[${i}]`), index: i, layers: c.layers.map(layerRef).map(resolve) }))
+    .sort((a, b) => a.frame - b.frame || a.index - b.index);
+  const hits = (score.hits ?? []).map((h, i) => ({ start: resolveFrame(h, ctx, `hits[${i}]`), index: i, duration: h.durationFrames, layer: resolve({ template: h.template, preset: h.preset, params: h.params }) }));
+
+  const bindings = (score.bindings ?? []).map((b) => ({ ...b, state: 0 }));
+  const frames = [];
+  for (let f = 0; f < frameCount; f++) {
+    let base = { id: "b", layers: initial };
+    for (const c of cuts) if (c.frame <= f) base = { id: `c${c.index}`, layers: c.layers };
+    const featureFrame = features?.frames?.[f] ?? null;
+    const bound = {};
+    for (const b of bindings) {
+      const raw = featureValue(featureFrame, b.feature);
+      const ms = raw > b.state ? b.attackMs : b.releaseMs;
+      const k = isNum(ms) && ms > 0 ? Math.exp(-1000 / (fps * ms)) : 0;
+      b.state = k * b.state + (1 - k) * raw;
+      bound[b.param] = b.offset + b.gain * b.state;
+    }
+    const applyBindings = (layer) => {
+      if (layer.template !== score.template || !bindings.length) return layer.params;
+      const params = { ...layer.params };
+      for (const input of layer.inputs) {
+        if (bound[input.NAME] === undefined) continue;
+        let v = bound[input.NAME];
+        if (isNum(input.MIN)) v = Math.max(input.MIN, v);
+        if (isNum(input.MAX)) v = Math.min(input.MAX, v);
+        params[input.NAME] = input.TYPE === "long" ? Math.round(v) : input.TYPE === "bool" ? v > 0.5 : v;
+      }
+      return params;
+    };
+    const layers = base.layers.map((l, i) => ({ key: `${base.id}:${i}`, template: l.template, params: applyBindings(l), t: f / fps, ...(l.labels ? { labels: l.labels } : {}), ...(l.textStyle ? { textStyle: l.textStyle } : {}) }));
+    for (const h of hits) {
+      if (f >= h.start && f < h.start + h.duration) layers.push({ key: `h${h.index}`, template: h.layer.template, params: h.layer.params, t: (f - h.start) / fps, ...(h.layer.labels ? { labels: h.layer.labels } : {}), ...(h.layer.textStyle ? { textStyle: h.layer.textStyle } : {}) });
+    }
+    frames.push({ layers });
+  }
+  const events = [...new Set([...cuts.map((c) => c.frame), ...hits.map((h) => h.start)])].filter((f) => f >= 0 && f < frameCount).sort((a, b) => a - b);
+  return { frameCount, fps, frames, templatesUsed: used, events };
+}

package/skills/agentvfx/engine/core/templates.mjs

@@ -0,0 +1,43 @@
+// agentvfx (Apache-2.0, see LICENSE). The template library: every templates/<family>/<id>/fx.json, keyed by
+// X_AGENTVFX.id. Test templates live under templates/_test/ and are loaded only on request.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const TEMPLATES_ROOT = fileURLToPath(new URL("../../templates/", import.meta.url));
+
+/** Map id -> { id, dir, rel, family, fx, passes: [file...] }. Throws on a duplicate id or unreadable JSON. */
+export function loadLibrary({ root = TEMPLATES_ROOT, includeTest = false } = {}) {
+  const lib = new Map();
+  if (!existsSync(root)) return lib;
+  for (const family of readdirSync(root).sort()) {
+    const fdir = path.join(root, family);
+    if (!statSync(fdir).isDirectory()) continue;
+    if (family === "_test" && !includeTest) continue;
+    if (family.startsWith(".") || (family.startsWith("_") && family !== "_test")) continue;
+    for (const name of readdirSync(fdir).sort()) {
+      const dir = path.join(fdir, name);
+      const file = path.join(dir, "fx.json");
+      if (!statSync(dir).isDirectory() || !existsSync(file)) continue;
+      let fx;
+      try {
+        fx = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        throw new Error(`${path.relative(root, file)}: invalid JSON (${error.message})`);
+      }
+      const id = fx?.X_AGENTVFX?.id ?? name;
+      if (lib.has(id)) throw new Error(`duplicate template id ${id} (${path.relative(root, lib.get(id).dir)} and ${path.relative(root, dir)})`);
+      const passes = readdirSync(dir).filter((f) => /^(main|pass\d+)\.frag$/u.test(f)).sort();
+      lib.set(id, { id, dir, rel: path.relative(root, dir).split(path.sep).join("/"), family, fx, passes });
+    }
+  }
+  return lib;
+}
+
+/** Defaults from INPUTS, then the named preset, then explicit params. */
+export function resolveParams(fx, { preset = null, params = {} } = {}) {
+  const out = {};
+  for (const input of fx.INPUTS ?? []) if (input.DEFAULT !== undefined) out[input.NAME] = input.DEFAULT;
+  if (preset) Object.assign(out, fx.X_AGENTVFX.presets[preset]);
+  return Object.assign(out, params);
+}

package/skills/agentvfx/engine/core/util.mjs

@@ -0,0 +1,167 @@
+// Pure math, easing and seeded-randomness helpers shared by the page engine and the Node side.
+// Adapted from mexicat/pdoom-video app/src/engine/util.ts (MIT, see ../NOTICE). Every function is a
+// deterministic function of its arguments: nothing here may read a clock or an unseeded RNG
+// (MO-A-23), because the determinism gate hashes frames rendered by two separate processes.
+
+export const clamp = (x, a = 0, b = 1) => (x < a ? a : x > b ? b : x);
+export const lerp = (a, b, t) => a + (b - a) * t;
+export const invLerp = (a, b, x) => (a === b ? 0 : (x - a) / (b - a));
+export const remap = (x, a, b, c, d, clamped = true) => {
+  const t = invLerp(a, b, x);
+  return lerp(c, d, clamped ? clamp(t) : t);
+};
+export const smoothstep = (a, b, x) => {
+  const t = clamp((x - a) / (b - a));
+  return t * t * (3 - 2 * t);
+};
+export const fract = (x) => x - Math.floor(x);
+export const mod = (x, m) => ((x % m) + m) % m;
+export const TAU = Math.PI * 2;
+
+// Cubic bezier easing, solved by a fixed 40-step bisection so the value never depends on a
+// convergence tolerance.
+function bezier(x1, y1, x2, y2) {
+  const coord = (t, a, b) => 3 * a * t * (1 - t) ** 2 + 3 * b * t * t * (1 - t) + t ** 3;
+  return (x) => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 40; i++) {
+      const mid = (lo + hi) / 2;
+      if (coord(mid, x1, x2) < x) lo = mid;
+      else hi = mid;
+    }
+    return coord((lo + hi) / 2, y1, y2);
+  };
+}
+
+// The named easing set (MO-A-08). Scenes pick from these names; ad hoc curves are not allowed.
+export const ease = Object.freeze({
+  linear: (t) => t,
+  outQuad: (t) => 1 - (1 - t) * (1 - t),
+  inOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2),
+  outCubic: (t) => 1 - (1 - t) ** 3,
+  inOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+  outExpo: (t) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t)),
+  // Film tokens from the preset bibles (MO-B-01..03).
+  slam: bezier(0.16, 1, 0.3, 1),
+  drift: bezier(0.37, 0, 0.63, 1),
+  surgePunch: bezier(0.16, 1, 0.3, 1),
+});
+
+/** Eased progress of x through [a, b], clamped. */
+export const prog = (x, a, b, fn = ease.linear) => fn(clamp((x - a) / (b - a)));
+
+/**
+ * Piecewise interpolation through keyframes `[[time, value, easeName], ...]`; the ease on key i
+ * shapes the segment that ends at key i. Only names from `ease` are accepted.
+ */
+export function keys(t, ks) {
+  if (ks.length === 0) return 0;
+  if (t <= ks[0][0]) return ks[0][1];
+  for (let i = 1; i < ks.length; i++) {
+    const [time, value, name = "inOutCubic"] = ks[i];
+    if (t <= time) {
+      const [pt, pv] = ks[i - 1];
+      const fn = ease[name];
+      if (!fn) throw new Error(`unknown ease: ${name}`);
+      return lerp(pv, value, fn((t - pt) / (time - pt)));
+    }
+  }
+  return ks[ks.length - 1][1];
+}
+
+/** Damped spring response to a step at time 0 (the rare deliberate overshoot, MO-A-08). */
+export const springStep = (t, freq = 4, damping = 0.35) => {
+  if (t <= 0) return 0;
+  const w = TAU * freq;
+  return 1 - Math.exp(-damping * w * t) * Math.cos(w * Math.sqrt(1 - damping * damping) * t);
+};
+
+/** Exponential decay after an event at t0 (1 at t0, half-life hl). */
+export const pulse = (t, t0, hl = 0.12) => (t < t0 ? 0 : 0.5 ** ((t - t0) / hl));
+
+// ---- seeded randomness (MO-SH-01, MO-A-23) ----
+
+/** FNV-1a 32-bit over the UTF-8 bytes of `text`; offset basis 0x811c9dc5, prime 0x01000193. */
+export function fnv1a32(text) {
+  let hash = 0x811c9dc5;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+/** MO-SH-01: the one seed formula for every pass in every product. */
+export const passSeed = (runSeed, sceneId, shotIndex, pass) => fnv1a32(`${runSeed}:${sceneId}:${shotIndex}:${pass}`);
+
+/** mulberry32 PRNG in unsigned 32-bit arithmetic. Returns a function yielding [0, 1). */
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Stateless hash of numbers to [0, 1). */
+export function hash(...xs) {
+  let h = 2166136261 >>> 0;
+  for (const x of xs) {
+    h ^= Math.floor(x * 1000003) | 0;
+    h = Math.imul(h, 16777619);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0x5bd1e995);
+    h ^= h >>> 15;
+  }
+  return (h >>> 0) / 4294967296;
+}
+
+const quintic = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+export function noise1(x, seed = 0) {
+  const i = Math.floor(x);
+  return lerp(hash(i, seed) * 2 - 1, hash(i + 1, seed) * 2 - 1, quintic(x - i));
+}
+
+// ---- colour ----
+
+export const srgbToLinear = (s) => (s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4);
+export const linearToSrgb = (l) => (l <= 0.0031308 ? 12.92 * l : 1.055 * l ** (1 / 2.4) - 0.055);
+
+export function hexToRgb(hex) {
+  const n = Number.parseInt(hex.replace("#", ""), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+export const hexToLinear = (hex) => hexToRgb(hex).map((v) => srgbToLinear(v / 255));
+
+/** WCAG relative luminance of an sRGB hex colour. */
+export function relativeLuminance(hex) {
+  const [r, g, b] = hexToLinear(hex);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export const contrastRatio = (la, lb) => (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+
+/** HSL hue (degrees) and saturation (0..1) of 0..255 sRGB values. */
+export function hsl(r, g, b) {
+  const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h;
+  if (max === rn) h = ((gn - bn) / d) % 6;
+  else if (max === gn) h = (bn - rn) / d + 2;
+  else h = (rn - gn) / d + 4;
+  return { h: mod(h * 60, 360), s, l };
+}
+export const hueDistance = (a, b) => {
+  const d = Math.abs(mod(a, 360) - mod(b, 360));
+  return Math.min(d, 360 - d);
+};