agentvfx 0.0.0-stage → 0.3.5

package/skills/agentvfx/test/concept-collage-layout.test.mjs

@@ -0,0 +1,236 @@
+// Collage layouts (editorial model): layout data validation and packing, the three editorial presets, the text sheet,
+// the layout file shipped for the layout editor, and measured behaviour on rendered frames (type holds its place
+// while it reacts, instruments move, the old tile layouts still render outlines that hold).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadLibrary } from "../engine/core/templates.mjs";
+import { validateScore } from "../engine/core/validate.mjs";
+import { renderScore } from "../engine/node/render.mjs";
+import { analyzeAudio } from "../engine/node/audio.mjs";
+import { MAX_CELLS, ROLES, checkLayout, layoutCells, layoutToParams, packCell, packSrc, packStyle } from "../templates/brutal/collage/layout.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MUSIC = "test-media/beat-132.mp3";
+const lib = loadLibrary();
+const tpl = lib.get("collage");
+const LAYOUTS = JSON.parse(readFileSync(path.join(tpl.dir, "layouts.json"), "utf8"));
+const EDITORIAL = ["poster", "spread", "index"];
+const EXPERIMENTAL = ["glyph-flood", "glyph-flood-ko", "glyph-flood-solid", "slit-scan", "slit-scan-ko", "slit-scan-bone", "echo-stack", "echo-stack-ko", "echo-ripple", "type-eq", "type-eq-ko"];
+const SCENES = ["specimen", "wiring", "field-cut", "pattern-sheet", "anatomy", "deck", "bootlog", "tunnel", "runner", "ascii", "cube-wall", "vortex-count", "sticker-slap", "ribbon-rays", "slab-shear", "frame-loop-dial", "tilt-tiles", "marquee-stack", "lens-wrap", "liquid-type", "panel-grid", "mirror-track"];
+const TILES = ["wide-hero", "split", "mosaic"];
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-collage-layout-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+let runs = 0;
+const W = 640;
+const H = 360;
+
+const cell = (x, y, w, h, role, more = {}) => ({ x, y, w, h, role, ...more });
+const defaults = () => Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i.DEFAULT]));
+
+test("thirty-six layouts: editorial (poster, spread, index), eleven experimental type layouts and twenty-two scenes listed first, three old tile layouts kept; each matches its preset", () => {
+  assert.deepEqual(Object.keys(LAYOUTS), [...EDITORIAL, ...EXPERIMENTAL, ...SCENES, ...TILES]);
+  assert.deepEqual(Object.keys(tpl.fx.X_AGENTVFX.presets).slice(0, EDITORIAL.length + EXPERIMENTAL.length + SCENES.length), [...EDITORIAL, ...EXPERIMENTAL, ...SCENES]);
+  for (const n of [...EDITORIAL, ...EXPERIMENTAL, ...SCENES, ...TILES]) {
+    assert.deepEqual(checkLayout(LAYOUTS[n]), [], n);
+    const expected = { ...defaults(), ...(LAYOUTS[n].params ?? {}), ...layoutToParams(LAYOUTS[n]) };
+    assert.deepEqual({ ...defaults(), ...tpl.fx.X_AGENTVFX.presets[n] }, expected, `${n} preset equals its layout`);
+    assert.equal(validateScore({ version: 1, template: "collage", preset: n, input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t" }, lib).ok, true, n);
+  }
+  assert.equal(defaults().layoutMode, 0, "fixed is the default mode");
+});
+
+test("editorial layouts are not tiled partitions: no boxed tiles, overlap and edge bleed, type and live elements, vermilion accent", () => {
+  const key = (c) => `${c.x},${c.y},${c.w},${c.h},${c.role}`;
+  for (const n of EDITORIAL) {
+    const cells = layoutCells(LAYOUTS[n]);
+    assert.ok(cells.every((c) => c.frame !== undefined && c.frame !== "tile"), `${n}: every cell sets a frame other than tile`);
+    assert.ok(cells.some((c) => c.role === "footage"), `${n} has footage`);
+    assert.ok(cells.filter((c) => c.role === "type").length >= 2, `${n} has type cells`);
+    assert.ok(cells.some((c) => ["spectrum", "scope", "meter", "crosshair", "rule", "readout"].includes(c.role)), `${n} has an instrument`);
+    const area = cells.reduce((s, c) => s + c.w * c.h, 0);
+    const mirrored = new Set(cells.map((c) => key({ ...c, x: 32 - c.x - c.w })));
+    assert.ok(cells.some((c) => !mirrored.has(key(c))), `${n} is not mirror-symmetric`);
+    const overlaps = cells.some((a, i) => cells.some((b, j) => i < j && a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h));
+    assert.ok(overlaps, `${n} layers cells over each other (${area} cell units of 576)`);
+    const [r, g, b] = LAYOUTS[n].params.accentColor;
+    assert.ok(r > 0.8 && g > 0.15 && g < 0.3 && b < 0.15, `${n} accent is vermilion`);
+    assert.equal(LAYOUTS[n].params.margin, 0, `${n} runs to the frame edge`);
+  }
+  assert.ok(layoutCells(LAYOUTS.poster).some((c) => c.role === "footage" && c.w === 32 && c.h === 18), "poster footage is full bleed");
+  const idx = layoutCells(LAYOUTS.index);
+  assert.ok(idx.find((c) => c.role === "footage").w < 32, "index footage is a small plate");
+});
+
+test("checkLayout: tile cells may not overlap, editorial cells may; bad frame, fill, tone, variant, rot, src, bounds and count are rejected", () => {
+  const msgs = (l) => checkLayout(l).map((e) => `${e.path} ${e.message}`).join("|");
+  assert.deepEqual(checkLayout([cell(0, 0, 16, 18, "footage"), cell(16, 0, 16, 18, "scope")]), []);
+  assert.match(msgs([cell(0, 0, 17, 18, "footage"), cell(16, 0, 16, 18, "scope")]), /overlaps/u);
+  assert.deepEqual(checkLayout([cell(0, 0, 32, 18, "footage", { frame: "none" }), cell(4, 4, 20, 6, "spectrum", { frame: "none", variant: 1 })]), []);
+  assert.deepEqual(checkLayout([cell(0, 0, 32, 18, "footage", { frame: "none" }), cell(4, 4, 20, 6, "scope")]), [], "a tile panel may sit on an editorial cell");
+  assert.match(msgs([cell(30, 0, 3, 4, "footage")]), /out of bounds: x \+ w = 33/u);
+  assert.match(msgs([cell(0, 17, 4, 2, "footage")]), /out of bounds: y \+ h = 19/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "banner")]), /role must be one of footage, spectrum/u);
+  assert.match(msgs([cell(0.5, 0, 4, 2, "footage")]), /\[0\]\.x must be an integer/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { frame: "dotted" })]), /frame/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { fill: "red" })]), /fill/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { tone: "red" })]), /tone/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { variant: 10 })]), /variant/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { rot: 3 })]), /rot/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { src: { x: 0.3, y: 0, scale: 1 } })]), /src\.x/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { src: { x: 0, y: 0, scale: 1.55 } })]), /src\.scale/u);
+  assert.match(msgs([cell(0, 0, 4, 2, "type", { src: { x: 0, y: 0, zoom: 2 } })]), /unknown key/u);
+  assert.match(msgs([{ ...cell(0, 0, 4, 2, "footage"), z: 1 }]), /unknown key/u);
+  assert.match(msgs([]), /1 to 16 cells/u);
+  assert.match(msgs(Array.from({ length: MAX_CELLS + 1 }, (_, i) => cell(i, 0, 1, 1, "hatch", { frame: "none" }))), /1 to 16 cells/u);
+  assert.throws(() => layoutToParams([cell(0, 0, 40, 2, "footage")]), /invalid collage layout/u);
+  assert.equal(Object.keys(ROLES).length, 14);
+  assert.equal(ROLES.typefx, 13);
+  assert.equal(ROLES.scene, 14);
+});
+
+test("packing: cellN is RRXXYYWWHH, styleN is variant tone fill frame rot, srcN is scale x y; unused slots are 0", () => {
+  const c = cell(3, 8, 29, 10, "type", { frame: "none", variant: 4, tone: "ground", fill: "ink", rot: 1, src: { x: 19, y: -1.5, scale: 1.6 } });
+  assert.equal(packCell(c), 1103082910);
+  assert.equal(packStyle(c), 41210 + 1);
+  assert.equal(packSrc(c), 16 * 10000 + 58 * 100 + 17);
+  assert.equal(packStyle(cell(0, 0, 1, 1, "footage")), 0, "old cells keep style 0 = tile");
+  assert.equal(packSrc(cell(0, 0, 1, 1, "footage")), 0);
+  const p = layoutToParams([c]);
+  assert.equal(Object.keys(p).length, 48);
+  assert.equal(p.cell1, 0);
+  assert.equal(p.style15, 0);
+  assert.equal(p.src0, packSrc(c));
+  const input = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i]));
+  for (const [k, v] of Object.entries(p)) assert.ok(v >= input[k].MIN && v <= input[k].MAX, `${k} ${v} inside its input range`);
+});
+
+test("text sheet: declared slots, fonts from the engine list, atlas row matches the shader constants, every src window lands on the sheet", () => {
+  const text = tpl.fx.X_AGENTVFX.text;
+  const keys = text.map((t) => t.key);
+  for (const k of ["word", "numeral", "headline", "body", "fields", "spine", "capA", "capB", "atlas"]) assert.ok(keys.includes(k), `slot ${k}`);
+  const atlas = text.find((t) => t.key === "atlas");
+  const frag = readFileSync(path.join(tpl.dir, "main.frag"), "utf8");
+  const konst = (n) => Number(new RegExp(`const float ${n} = ([0-9.]+);`, "u").exec(frag)?.[1]);
+  assert.ok(Math.abs(konst("ATLAS_X") - atlas.x) < 1e-4 && Math.abs(konst("ATLAS_Y") - atlas.y) < 1e-4 && konst("ATLAS_PX") === atlas.size, "ATLAS_X/Y/PX equal the atlas text item");
+  assert.match(atlas.default, /^0123456789:A.*Z$/u);
+  for (const n of EDITORIAL) for (const c of layoutCells(LAYOUTS[n]).filter((q) => q.role === "type")) {
+    const s = { x: 0, y: 0, scale: 1, ...c.src };
+    assert.ok(s.x >= 0 && s.x < 32 && s.y > -10 && s.y < 18, `${n} type window starts on the sheet`);
+  }
+});
+
+test("the shipped r7 layout file lists every layout with its packed params and the text sheet", () => {
+  const file = path.join(ROOT, "test/fixtures/r7-collage-LAYOUTS.json");
+  assert.ok(existsSync(file), "r7-collage-LAYOUTS.json exists");
+  const shipped = JSON.parse(readFileSync(file, "utf8"));
+  assert.equal(shipped.format, "collage layout v3");
+  assert.equal(shipped.maxCells, 16);
+  assert.deepEqual(Object.keys(shipped.layouts), Object.keys(LAYOUTS));
+  for (const [n, e] of Object.entries(LAYOUTS)) {
+    assert.deepEqual(shipped.layouts[n].cells, layoutCells(e), `${n} cells`);
+    assert.deepEqual(shipped.layouts[n].params, { ...(e.params ?? {}), ...layoutToParams(e) }, `${n} params`);
+  }
+  assert.deepEqual(Object.keys(shipped.textSheet), tpl.fx.X_AGENTVFX.text.map((t) => t.key));
+});
+
+async function frames(params, keep, preset) {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const v = validateScore({ version: 1, template: "collage", ...(preset ? { preset } : {}), input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t", params: { construction: false, grain: 0, gridDots: 0, ...params } }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const kept = new Map();
+  await renderScore(v.value, lib, { outDir: path.join(tmp, `l-${runs++}`), width: W, height: H, features, replay: false, onFrame: (f, a) => { if (keep === "all" || keep.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+  return { kept, features };
+}
+
+const px = (rgba, x, y) => { const i = (y * W + x) * 4; return [rgba[i], rgba[i + 1], rgba[i + 2]]; };
+const isRed = ([r, g, b]) => r > 150 && g < 110 && b < 90;
+const isInk = ([r, g, b]) => r + g + b < 200;
+
+/** Numeral window of the index layout in pixels (grid cell 1,2,9,13 on a 20 px unit), clear of the level hairline rows at the ends. */
+function numeralStats(rgba) {
+  let red = 0;
+  const glyph = new Set();
+  for (let y = 50; y < 290; y++) for (let x = 24; x < 196; x++) {
+    const p = px(rgba, x, y);
+    if (isRed(p)) red += 1;
+    if (isRed(p) || isInk(p)) glyph.add(y * W + x);
+  }
+  return { red, glyph };
+}
+
+test("index: the numeral keeps its shape across all frames while its vermilion fill follows the rms (type reacts, never moves)", async () => {
+  const { kept } = await frames({ footageSat: 1 }, "all", "index");
+  const stats = [...kept.keys()].filter((f) => f >= 3).map((f) => numeralStats(kept.get(f)));
+  const reds = stats.map((s) => s.red);
+  const area = Math.max(...stats.map((s) => s.glyph.size));
+  assert.ok(area > 3000, `numeral covers pixels: ${area}`);
+  assert.ok(Math.max(...reds) > 3 * Math.min(...reds) + 400, `fill range across frames: ${Math.min(...reds)}..${Math.max(...reds)}`);
+  const base = stats[0].glyph;
+  for (const s of stats) {
+    let both = 0;
+    for (const k of s.glyph) if (base.has(k)) both += 1;
+    assert.ok(both / Math.max(s.glyph.size, base.size) > 0.8, `glyph shape overlap ${(both / Math.max(s.glyph.size, base.size)).toFixed(2)}`);
+  }
+});
+
+test("index numeral fill on the bass attacks on the onset frame and falls by half within 4 frames", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const onsets = features.meta.onsets.filter((o) => o >= 4 && o < 85 && features.frames[o].bass > 3 && features.frames[o - 1].bass < 1.3 && features.frames[o + 4].bass < 1);
+  assert.ok(onsets.length >= 1, "a clean strong onset exists");
+  const keep = onsets.flatMap((o) => [o - 1, o, o + 4]);
+  const { kept } = await frames({ style0: 10010 }, keep, "index");
+  for (const o of onsets) {
+    const [a, b, c] = [o - 1, o, o + 4].map((f) => numeralStats(kept.get(f)).red);
+    assert.ok(b > a * 1.3 + 50, `onset ${o}: fill ${a} -> ${b}`);
+    assert.ok(c <= b * 0.5 + 50, `onset ${o}: fill ${b} -> ${c} after 4 frames`);
+  }
+});
+
+test("spread: the scope line crossing both pages changes every frame while the page edge stays", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beat = features.meta.beats.find((b) => b >= 6 && b < 80);
+  const { kept } = await frames({}, [beat - 1, beat], "spread");
+  const a = kept.get(beat - 1);
+  const b = kept.get(beat);
+  let diff = 0;
+  let n = 0;
+  for (let y = 300; y < 358; y++) for (let x = 0; x < W; x++) { n += 1; diff += Math.abs(px(a, x, y)[0] - px(b, x, y)[0]) > 40 ? 1 : 0; }
+  assert.ok(diff / n > 0.004, `scope strip changed across a beat: ${(diff / n).toFixed(4)}`);
+  for (const y of [4, 8, 12]) assert.ok(px(a, 318, y)[0] < 80 && px(a, 330, y)[0] > 190 && px(b, 318, y)[0] < 80 && px(b, 330, y)[0] > 190, `page edge at x=320 holds (y ${y})`);
+});
+
+const brightAt = (rgba, x, y) => (x < 0 || y < 0 || x >= W || y >= H ? 0 : (rgba[(y * W + x) * 4] + rgba[(y * W + x) * 4 + 1] + rgba[(y * W + x) * 4 + 2]) / 3);
+
+/** Pixel rectangle of a tile cell inside the frame line (gutter and margin as the shader sets them). */
+function box(c) {
+  const U = H / 1080;
+  const m = 24 * U;
+  const g = 10 * U * 0.5;
+  const un = [(W - 2 * m) / 32, (H - 2 * m) / 18];
+  return { x0: m + c.x * un[0] + g, y0: m + c.y * un[1] + g, x1: m + (c.x + c.w) * un[0] - g, y1: m + (c.y + c.h) * un[1] - g };
+}
+
+function outlineInk(rgba, c) {
+  const b = box(c);
+  let on = 0;
+  let n = 0;
+  const hit = (x, y) => Math.max(brightAt(rgba, x, y), brightAt(rgba, x, y - 1), brightAt(rgba, x - 1, y)) > 90;
+  for (let x = Math.ceil(b.x0) + 6; x < b.x1 - 6; x++) for (const y of [b.y0, b.y1]) { n += 1; on += hit(x, Math.round(y)) ? 1 : 0; }
+  for (let y = Math.ceil(b.y0) + 6; y < b.y1 - 6; y++) for (const x of [b.x0, b.x1]) { n += 1; on += hit(Math.round(x), y) ? 1 : 0; }
+  return on / n;
+}
+
+test("old tile layouts still render: every panel outline holds across a beat (fixed), and reshuffle moves them (control)", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beat = features.meta.beats.find((b) => b >= 4 && b < 85);
+  const cells = layoutCells(LAYOUTS["wide-hero"]);
+  const fixed = (await frames({ cutMode: 2 }, [beat - 1, beat], "wide-hero")).kept;
+  for (const f of [beat - 1, beat]) assert.ok(Math.min(...cells.map((c) => outlineInk(fixed.get(f), c))) > 0.9, `wide-hero outlines hold at frame ${f}`);
+  const shuffled = (await frames({ layoutMode: 1, cutMode: 2 }, [beat - 1, beat])).kept;
+  const worst = Math.min(...[beat - 1, beat].flatMap((f) => cells.map((c) => outlineInk(shuffled.get(f), c))));
+  assert.ok(worst < 0.6, `some outline of the wide-hero grid is missing after a reshuffle: ${worst.toFixed(2)}`);
+});

package/skills/agentvfx/test/concept-collage-scenes.test.mjs

@@ -0,0 +1,305 @@
+// Collage scenes (role 14): four mixed-material compositions (specimen, wiring, field-cut, pattern-sheet), each with its own
+// text set (text item `set` + template input textSet), palette, fonts, image treatment and beat/onset behaviour. Layout data,
+// the text-set filter and measured behaviour on rendered frames: the music event frame is the attack, the cells hold their place.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadLibrary } from "../engine/core/templates.mjs";
+import { validateScore, validateTemplate } from "../engine/core/validate.mjs";
+import { createFlashAuditor } from "../engine/core/flash.mjs";
+import { renderScore } from "../engine/node/render.mjs";
+import { analyzeAudio } from "../engine/node/audio.mjs";
+import { checkLayout, layoutCells, layoutToParams, packCell, ROLES } from "../templates/brutal/collage/layout.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MUSIC = "test-media/beat-132.mp3";
+const lib = loadLibrary();
+const tpl = lib.get("collage");
+const LAYOUTS = JSON.parse(readFileSync(path.join(tpl.dir, "layouts.json"), "utf8"));
+const SCENES = { specimen: 1, wiring: 2, "field-cut": 3, "pattern-sheet": 4, anatomy: 5, deck: 6, bootlog: 7, tunnel: 8, runner: 9, ascii: 0, "cube-wall": 10, "vortex-count": 11, "sticker-slap": 12, "ribbon-rays": 13, "slab-shear": 14, "frame-loop-dial": 15, "tilt-tiles": 16, "marquee-stack": 17, "lens-wrap": 18, "liquid-type": 19, "panel-grid": 20, "mirror-track": 21 };
+const by_ = (text, key) => text.find((t) => t.key === key);
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-collage-scenes-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+const W = 640;
+const H = 360;
+let runs = 0;
+
+test("scene role: role 14 packs into the cell int range and each preset is one full-frame scene cell equal to its fx.json preset", () => {
+  assert.equal(ROLES.scene, 14);
+  const cell = { x: 0, y: 0, w: 32, h: 18, role: "scene", frame: "none", variant: 3 };
+  assert.deepEqual(checkLayout([cell]), []);
+  assert.equal(packCell(cell), 1400003218);
+  const defaults = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i.DEFAULT]));
+  const input = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i]));
+  for (const [name, variant] of Object.entries(SCENES)) {
+    const e = LAYOUTS[name];
+    assert.deepEqual(checkLayout(e), [], name);
+    const cells = layoutCells(e);
+    assert.equal(cells.length, 1, `${name} is a single scene cell`);
+    assert.deepEqual([cells[0].role, cells[0].variant, cells[0].rot ?? 0, cells[0].w, cells[0].h], ["scene", variant % 10, Math.floor(variant / 10), 32, 18], `${name}: scene id = variant + 10 * rot`);
+    const p = layoutToParams(e);
+    for (const [k, v] of Object.entries(p)) assert.ok(v >= input[k].MIN && v <= input[k].MAX, `${name} ${k} ${v} inside its input range`);
+    assert.deepEqual({ ...defaults, ...tpl.fx.X_AGENTVFX.presets[name] }, { ...defaults, ...e.params, ...p }, `${name} preset equals its layout`);
+    assert.ok(e.description.length > 120, `${name} describes itself`);
+  }
+});
+
+test("diversity: four different palettes (ground colours), four text sets, no vermilion in more than one, beats-only cuts", () => {
+  const defaults = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i.DEFAULT]));
+  const palettes = Object.keys(SCENES).map((n) => ["groundColor", "inkColor", "accentColor", "tintA", "tintB"].flatMap((k) => ({ ...defaults, ...LAYOUTS[n].params })[k].slice(0, 3)));
+  const dist = (a, b) => Math.hypot(...a.map((v, i) => v - b[i]));
+  for (let a = 0; a < palettes.length; a++) for (let b = a + 1; b < palettes.length; b++) assert.ok(dist(palettes[a], palettes[b]) > 0.8, `palette ${a} vs ${b}`);
+  assert.deepEqual(Object.keys(SCENES).map((n) => LAYOUTS[n].params.textSet).sort((a, b) => a - b), Array.from({ length: 22 }, (_, i) => i + 1));
+  assert.equal(new Set(Object.values(SCENES)).size, 22, "twenty-two different scenes");
+  const vermilion = ([r, g, b]) => r > 0.8 && g > 0.15 && g < 0.3 && b < 0.15;
+  const colours = Object.keys(SCENES).flatMap((n) => Object.entries(LAYOUTS[n].params).filter(([k]) => /Color$|^tint/u.test(k)).map(([, v]) => v));
+  assert.ok(colours.filter(vermilion).length <= 1, "vermilion appears in at most one preset");
+  for (const n of Object.keys(SCENES)) assert.equal(LAYOUTS[n].params.cutMode, 0, `${n} cuts on beats only`);
+});
+
+test("text sets: items with `set` are only in 1..16, every preset's textSet has items, base items keep set 0, bad set values are rejected", () => {
+  const text = tpl.fx.X_AGENTVFX.text;
+  const base = text.filter((t) => t.set === undefined);
+  assert.ok(base.length >= 20, "the older sheet is untouched");
+  for (let s = 1; s <= 22; s++) assert.ok(text.some((t) => t.set === s), `set ${s} has items`);
+  assert.ok(text.every((t) => t.set === undefined || (t.set >= 1 && t.set <= 22)));
+  assert.equal(by_(text, "tlF").family, "Rockwell");
+  assert.equal(by_(text, "lnWord").family, "Didot");
+  assert.equal(by_(text, "lqWord").family, "Bodoni 72");
+  assert.equal(by_(text, "mrWord").family, "Phosphate");
+  assert.equal(by_(text, "cwL0").family, "Big Shoulders Display");
+  assert.equal(by_(text, "vxLine").family, "Bebas Neue");
+  assert.equal(by_(text, "stA").family, "Impact");
+  assert.equal(by_(text, "fdLoop").family, "Georgia");
+  assert.equal(by_(text, "blLog").reveal, "type", "the boot log is typed by the engine");
+  assert.equal(by_(text, "rwA").family, "Arial Black");
+  assert.equal(by_(text, "tnWord").family, "Monument Extended");
+  assert.equal(by_(text, "dkA").box, "tab");
+  const by = Object.fromEntries(text.map((t) => [t.key, t]));
+  assert.equal(by.spWord.family, "Pretendard");
+  assert.equal(by.spWord.weight, 200);
+  assert.equal(by.spCap.family, "MesloLGS NF");
+  assert.equal(by.wL0.family, "Monument Extended");
+  assert.equal(by.fcWord.weight, 900);
+  assert.match(by.fcKo.default, /[가-힣]/u);
+  assert.equal(by.ptWord.family, undefined, "pattern-sheet label uses the generic heavy grotesk");
+  assert.equal(by.ptQL.font, "serif");
+  const input = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i]));
+  assert.deepEqual([input.textSet.MIN, input.textSet.MAX, input.textSet.DEFAULT], [0, 31, 0]);
+  const ok = validateScore({ version: 1, template: "collage", preset: "wiring", input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t", labels: { wTitle: "HALL" } }, lib);
+  assert.equal(ok.ok, true, JSON.stringify(ok.errors));
+  const withSet = (set) => ({ ...tpl.fx, X_AGENTVFX: { ...tpl.fx.X_AGENTVFX, text: [{ key: "a", default: "A", x: 0, y: 0, size: 0.1, set }] } });
+  assert.deepEqual(validateTemplate(withSet(2), "collage").errors, []);
+  for (const bad of [32, 1.5, -1, "1"]) assert.ok(validateTemplate(withSet(bad), "collage").errors.some((e) => e.path === "X_AGENTVFX.text[0].set"), String(bad));
+});
+
+async function frames(preset, keep, { audit = false, dur = 3, audio = MUSIC } = {}) {
+  const features = await analyzeAudio(path.resolve(ROOT, audio), { fps: 30 });
+  const v = validateScore({ version: 1, template: "collage", preset, input: { audio }, durationSec: dur, seed: 5, out: "t", params: { grain: 0 } }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const kept = new Map();
+  const auditor = audit ? createFlashAuditor({ fps: 30, width: W, height: H }) : null;
+  await renderScore(v.value, lib, { outDir: path.join(tmp, `t-${runs++}`), width: W, height: H, features, replay: false, onFrame: (f, a) => {
+    if (keep.includes(f)) kept.set(f, Buffer.from(a.rgba));
+    auditor?.push({ data: a.rgba, width: W, height: H });
+  } });
+  return { kept, features, flash: auditor?.finish() };
+}
+const clean = (events, lo, hi) => events.filter((e) => e >= lo && e < hi && !events.some((p) => p !== e && p > e - 5 && p < e + 6));
+const px = (rgba, x, y) => { const i = (y * W + x) * 4; return [rgba[i], rgba[i + 1], rgba[i + 2]]; };
+const count = (rgba, test, x0 = 0, y0 = 0, x1 = W, y1 = H) => { let n = 0; for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) if (test(px(rgba, x, y))) n += 1; return n; };
+const centroid = (rgba, test) => { let n = 0; let sx = 0; let sy = 0; for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) if (test(px(rgba, x, y))) { n += 1; sx += x; sy += y; } return { n, x: sx / Math.max(n, 1), y: sy / Math.max(n, 1) }; };
+
+test("specimen: the black square and semicircle snap to a new place on the beat frame and then hold", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beats = clean(features.meta.beats, 8, 85).slice(0, 2);
+  assert.ok(beats.length >= 2, `clean beats exist: ${beats}`);
+  const { kept } = await frames("specimen", beats.flatMap((b) => [b - 1, b, b + 4]));
+  const black = ([r, g, b]) => r < 30 && g < 30 && b < 40;
+  for (const b of beats) {
+    const [before, at, later] = [b - 1, b, b + 4].map((f) => centroid(kept.get(f), black));
+    assert.ok(Math.hypot(at.x - before.x, at.y - before.y) > 30, `beat ${b}: the pair moved ${Math.hypot(at.x - before.x, at.y - before.y).toFixed(1)} px on the beat frame`);
+    assert.ok(Math.hypot(later.x - at.x, later.y - at.y) < 3, `beat ${b}: the pair holds its place until the next beat`);
+  }
+});
+
+test("wiring: the crimson glyph is at full brightness on the onset frame and dim 5 frames later", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const onsets = clean(features.meta.onsets, 8, 85).slice(0, 3);
+  assert.ok(onsets.length >= 2, `clean onsets exist: ${onsets}`);
+  const { kept } = await frames("wiring", onsets.flatMap((o) => [o, o + 5]));
+  const bright = ([r, g, b]) => r > 200 && g < 60 && b < 90;
+  for (const o of onsets) {
+    const [at, after] = [o, o + 5].map((f) => count(kept.get(f), bright, 140, 14, 185, 56));
+    assert.ok(at > 120, `onset ${o}: bright glyph pixels ${at}`);
+    assert.ok(after < at * 0.1, `onset ${o}: ${at} -> ${after} after 5 frames`);
+  }
+});
+
+test("field-cut: the field cuts on a beat frame (lime, amber, ultramarine in turn) and stays under the flash limit", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const [b0, b1, , b3] = features.meta.beats;
+  assert.ok(b3 < 100 && b0 > 3, `four beats early in the clip: ${features.meta.beats.slice(0, 4)}`);
+  const { kept, flash } = await frames("field-cut", [3, b1 - 1, b1, b3 + 1], { audit: true, dur: 4, audio: MUSIC });
+  const lime = ([r, g, b]) => g > 220 && r > 150 && b < 90;
+  const amber = ([r, g, b]) => r > 230 && g > 110 && g < 175 && b < 70;
+  const blue = ([r, g, b]) => b > 200 && r < 70 && g < 70;
+  const share = (f, t) => count(kept.get(f), t) / (W * H);
+  assert.ok(share(3, lime) > 0.4, `before the first cut the lime field shows (${share(3, lime).toFixed(2)})`);
+  assert.ok(share(b1 - 1, lime) > 0.4 && share(b1 - 1, amber) < 0.05, "the frame before the second beat is still lime");
+  assert.ok(share(b1, amber) > 0.15 && share(b1, lime) < 0.05, `the beat frame is the amber field (${share(b1, amber).toFixed(2)})`);
+  assert.ok(share(b3 + 1, blue) > 0.3, `two beats later the ultramarine field shows (${share(b3 + 1, blue).toFixed(2)})`);
+  assert.equal(flash.exceeds, false, `flash gate: ${JSON.stringify(flash.worstWindow)} red ${flash.redFlashes}`);
+});
+
+test("pattern-sheet: the QR stamps re-seed on the beat frame and hold between beats; the green border stays", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beats = clean(features.meta.beats, 8, 85).slice(0, 2);
+  assert.ok(beats.length >= 2, `clean beats exist: ${beats}`);
+  const { kept } = await frames("pattern-sheet", beats.flatMap((b) => [b - 1, b, b + 3]));
+  const region = (rgba) => { const out = []; for (let y = 30; y < 92; y += 2) for (let x = 90; x < 152; x += 2) out.push(px(rgba, x, y)[0] < 100 ? 1 : 0); return out; };
+  const diff = (a, b) => region(a).filter((v, i) => v !== region(b)[i]).length;
+  for (const b of beats) {
+    assert.ok(diff(kept.get(b - 1), kept.get(b)) > 80, `beat ${b}: the stamp changed on the beat frame (${diff(kept.get(b - 1), kept.get(b))} cells)`);
+    assert.ok(diff(kept.get(b), kept.get(b + 3)) < 6, `beat ${b}: the stamp holds after the beat`);
+    const [r, g, bl] = px(kept.get(b), 8, 180);
+    assert.ok(g > 150 && r < 40 && bl < 120, "the signal-green border is there");
+  }
+});
+
+/** Pixels of the region whose colour changed by more than 40 in any channel between two frames. */
+const changed = (a, b, x0, y0, x1, y1) => { let n = 0; for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) { const p = px(a, x, y); const q = px(b, x, y); if (Math.max(Math.abs(p[0] - q[0]), Math.abs(p[1] - q[1]), Math.abs(p[2] - q[2])) > 40) n += 1; } return n; };
+const cleanBeats = async (n = 2) => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beats = clean(features.meta.beats, 8, 85).slice(0, n);
+  assert.ok(beats.length >= n, `clean beats exist: ${beats}`);
+  return beats;
+};
+
+test("bootlog: the progress bar fills three more segments on the beat frame", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("bootlog", beats.flatMap((b) => [b - 1, b]));
+  const lit = ([, g]) => g > 150;
+  for (const b of beats) {
+    const [before, at] = [b - 1, b].map((f) => count(kept.get(f), lit, 86, 311, 345, 329));
+    assert.ok(at > before + 100, `beat ${b}: bright progress pixels ${before} -> ${at}`);
+  }
+});
+
+test("tunnel: the rings jump a step deeper on the beat frame and hold until the next beat", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("tunnel", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 0, W, 60) > 0.15 * W * 60, `beat ${b}: the checker above the window changed on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 0, W, 60) < 0.02 * W * 60, `beat ${b}: the tunnel holds between beats`);
+  }
+});
+
+test("runner: the bar word swaps on the beat frame and holds", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("runner", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 217, W, 285) > 2500, `beat ${b}: the bar changed on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 217, W, 285) < 150, `beat ${b}: the bar holds between beats`);
+  }
+});
+
+/** Beats that start a new even beat count (the scenes that act every second beat), clean of other events. */
+const evenBeats = async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const cleanSet = new Set(clean(features.meta.beats, 8, 85));
+  const out = features.meta.beats.filter((b, i) => i % 2 === 1 && cleanSet.has(b));
+  assert.ok(out.length >= 1, `an even clean beat exists: ${features.meta.beats}`);
+  return out.slice(0, 2);
+};
+
+test("cube-wall: the cubes turn mid-way on the beat that starts a new pair of beats and are at rest 4 frames later", async () => {
+  const beats = await evenBeats();
+  const { kept } = await frames("cube-wall", beats.flatMap((b) => [b - 1, b + 1, b + 5, b + 6]));
+  for (const b of beats) {
+    const turn = changed(kept.get(b - 1), kept.get(b + 1), 180, 20, 460, 340);
+    const hold = changed(kept.get(b + 5), kept.get(b + 6), 180, 20, 460, 340);
+    assert.ok(turn > 4000, `beat ${b}: the wall changed while the cubes turn (${turn})`);
+    assert.ok(hold < turn * 0.3, `beat ${b}: the wall is nearly still once the turn is done (${hold} vs ${turn})`);
+  }
+});
+
+test("sticker-slap: a new sticker lands on the beat that starts a new pair of beats", async () => {
+  const beats = await evenBeats();
+  const { kept } = await frames("sticker-slap", beats.flatMap((b) => [b - 1, b + 1, b + 5, b + 6]));
+  for (const b of beats) {
+    const slap = changed(kept.get(b - 1), kept.get(b + 1), 0, 0, W, H);
+    const hold = changed(kept.get(b + 5), kept.get(b + 6), 0, 0, W, H);
+    assert.ok(slap > 3000, `beat ${b}: the frame changed when the sticker slapped on (${slap})`);
+    assert.ok(hold < slap * 0.5, `beat ${b}: the pile is calmer after the slap (${hold} vs ${slap})`);
+  }
+});
+
+test("slab-shear: the slabs shift on the beat frame and hold between beats", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("slab-shear", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 0, W, H) > 3000, `beat ${b}: the slabs changed on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 0, W, H) < 600, `beat ${b}: the slabs hold between beats`);
+  }
+});
+
+test("frame-loop-dial: the split-flap digits change on the beat and the border text jumps ahead on an onset", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("frame-loop-dial", beats.flatMap((b) => [b - 1, b + 4]));
+  for (const b of beats) assert.ok(changed(kept.get(b - 1), kept.get(b + 4), 400, 130, 536, 230) > 150, `beat ${b}: the flap digits changed`);
+});
+
+test("marquee-stack: every row jumps on the beat frame and holds between beats", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("marquee-stack", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 20, 380, 280) > 5000, `beat ${b}: the rows jumped on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 20, 380, 280) < 800, `beat ${b}: the rows hold between beats`);
+  }
+});
+
+test("lens-wrap: the floor steps toward the viewer on the beat frame and holds", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("lens-wrap", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 280, W, 330) > 150, `beat ${b}: the floor lines moved on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 280, W, 330) < 100, `beat ${b}: the floor holds between beats`);
+  }
+});
+
+test("liquid-type: the ripple phase steps on the beat frame and holds", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("liquid-type", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 0, W, 240) > 1500, `beat ${b}: the word moved on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 0, W, 240) < 500, `beat ${b}: the word holds between beats`);
+  }
+});
+
+test("tilt-tiles and mirror-track: the rows or targets step on a beat and hold between beats", async () => {
+  const beats = await evenBeats();
+  const { kept } = await frames("tilt-tiles", beats.flatMap((b) => [b - 1, b, b + 3, b + 4]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 0, 0, W, H) > 8000, `tilt-tiles beat ${b}: the rows jumped`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 4), 0, 0, W, H) < 2500, `tilt-tiles beat ${b}: the rows hold`);
+  }
+  const m = await cleanBeats();
+  const mk = (await frames("mirror-track", m.flatMap((b) => [b - 1, b, b + 3, b + 4]))).kept;
+  for (const b of m) {
+    assert.ok(changed(mk.get(b - 1), mk.get(b), 100, 20, 560, 280) > 300, `mirror-track beat ${b}: the targets jumped`);
+    assert.ok(changed(mk.get(b + 3), mk.get(b + 4), 100, 20, 560, 280) < 150, `mirror-track beat ${b}: the targets hold`);
+  }
+});
+
+test("anatomy: the red scan band jumps on the beat frame and the wireframe settles within 3 frames", async () => {
+  const beats = await cleanBeats();
+  const { kept } = await frames("anatomy", beats.flatMap((b) => [b - 1, b, b + 3, b + 5]));
+  for (const b of beats) {
+    assert.ok(changed(kept.get(b - 1), kept.get(b), 190, 20, 470, 340) > 1500, `beat ${b}: the panel changed on the beat frame`);
+    assert.ok(changed(kept.get(b + 3), kept.get(b + 5), 190, 20, 470, 340) < 300, `beat ${b}: the panel is settled after 3 frames`);
+  }
+});