agentvfx 0.0.0-stage → 0.3.5

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

@@ -0,0 +1,153 @@
+// Collage experimental type (role typefx): layout data and packing for the new role and the sheet channel, the three presets
+// glyph-flood / slit-scan / echo-stack and the G / B text sheets they read, and measured behaviour on rendered frames:
+// every effect attacks on the music event frame and relaxes within a few frames (snappy), while 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 } from "../engine/core/validate.mjs";
+import { renderScore } from "../engine/node/render.mjs";
+import { analyzeAudio } from "../engine/node/audio.mjs";
+import { checkLayout, layoutCells, layoutToParams, packSrc } 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 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 WORD_VARIANT = { "glyph-flood": 2, "glyph-flood-ko": 2, "glyph-flood-solid": 2, "slit-scan": 3, "slit-scan-ko": 3, "slit-scan-bone": 3, "echo-stack": 4, "echo-stack-ko": 4, "echo-ripple": 5, "type-eq": 6, "type-eq-ko": 6 };
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-collage-typefx-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+const W = 640;
+const H = 360;
+let runs = 0;
+
+const cell = (x, y, w, h, role, more = {}) => ({ x, y, w, h, role, ...more });
+
+test("typefx role and src.sheet: packing puts the sheet in the millions digit, bad sheets and out-of-range values are rejected", () => {
+  const c = cell(0, 0, 32, 18, "typefx", { frame: "none", variant: 3, src: { x: -2, y: -0.5, scale: 1.2, sheet: "b" } });
+  assert.deepEqual(checkLayout([c]), []);
+  assert.equal(packSrc(c), 2000000 + 12 * 10000 + 16 * 100 + 19);
+  assert.equal(packSrc(cell(0, 0, 4, 4, "type", { src: { x: 1, y: 1, scale: 1, sheet: "g" } })), 1000000 + 10 * 10000 + 22 * 100 + 22, "type cells take a sheet too");
+  assert.equal(packSrc(cell(0, 0, 4, 4, "type", { src: { x: 1, y: 1, scale: 1 } })), 10 * 10000 + 22 * 100 + 22, "default sheet is r (digit 0)");
+  assert.equal(packSrc(cell(0, 0, 4, 4, "typefx")), 10 * 10000 + 20 * 100 + 20, "a typefx cell without src still reads the sheet origin");
+  assert.match(checkLayout([cell(0, 0, 4, 4, "typefx", { src: { x: 0, y: 0, scale: 1, sheet: "x" } })]).map((e) => e.message).join("|"), /one of r, g, b/u);
+  assert.equal(checkLayout([cell(0, 0, 4, 4, "typefx", { variant: 6 })]).length, 0, "variants up to 9 are valid for typefx");
+  const p = layoutToParams([c, cell(0, 0, 32, 18, "typefx", { frame: "none", variant: 1 })]);
+  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`);
+  assert.equal(p.cell1, 1300003218, "typefx is role 13");
+});
+
+test("experimental presets: valid layouts that equal their preset, vermilion family, full-bleed, typefx cells, G / B sheet windows", () => {
+  const defaults = Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i.DEFAULT]));
+  for (const n of EXPERIMENTAL) {
+    const e = LAYOUTS[n];
+    assert.deepEqual(checkLayout(e), [], n);
+    assert.deepEqual({ ...defaults, ...tpl.fx.X_AGENTVFX.presets[n] }, { ...defaults, ...e.params, ...layoutToParams(e) }, `${n} preset equals its layout`);
+    const cells = layoutCells(e);
+    assert.ok(cells.every((c) => c.frame === "none"), `${n}: no boxed tiles`);
+    assert.ok(cells.filter((c) => c.role === "typefx").length >= 2, `${n} has typefx cells`);
+    assert.equal(e.params.margin, 0, `${n} runs to the frame edge`);
+    assert.ok(typeof e.description === "string" && e.description.length > 80, `${n} describes itself`);
+    const vermilion = ([r, g, b]) => r > 0.8 && g > 0.15 && g < 0.3 && b < 0.15;
+    assert.ok(vermilion(e.params.accentColor) || vermilion(e.params.groundColor), `${n} uses vermilion as accent or ground`);
+    for (const c of cells.filter((q) => q.role === "typefx")) assert.ok(["g", "b"].includes(c.src?.sheet), `${n}: every typefx cell reads the G or B sheet`);
+    assert.ok(cells.some((c) => c.role === "typefx" && c.variant === WORD_VARIANT[n]), `${n} has its word cell (typefx variant ${WORD_VARIANT[n]})`);
+    assert.ok(cells.some((c) => c.role === "typefx" && c.variant === 1), `${n} has a micro-type field`);
+  }
+  const layoutOf = (n) => JSON.stringify(layoutCells(LAYOUTS[n]));
+  assert.equal(new Set(EXPERIMENTAL.map(layoutOf)).size, EXPERIMENTAL.length, "every preset is its own composition");
+  const warp = (n) => ({ ...defaults, ...tpl.fx.X_AGENTVFX.presets[n] }).typeWarp;
+  assert.ok(warp("slit-scan-ko") < 0.6 && warp("slit-scan-bone") < 0.6 && warp("slit-scan") === 1, "the calmer slit-scan variants lower typeWarp");
+  const word = (n) => layoutCells(LAYOUTS[n]).find((c) => c.role === "typefx" && c.variant === WORD_VARIANT[n]);
+  assert.deepEqual(["glyph-flood", "slit-scan", "echo-stack"].map((n) => word(n).src.sheet), ["g", "b", "g"]);
+  assert.equal(word("glyph-flood-solid").tone, "accent", "the solid glyph variant fills with the accent");
+});
+
+test("text sheet: the experimental words are on G and B, in Monument Extended / Pretendard, the micro-type lines in MesloLGS NF / Pretendard, the editorial sheet stays on R", () => {
+  const text = tpl.fx.X_AGENTVFX.text.filter((t) => t.set === undefined);
+  const by =Object.fromEntries(text.map((t) => [t.key, t]));
+  const channels = { mega: "g", mega2: "g", megaK: "g", echo: "g", echoK: "g", microK: "g", slit: "b", slitK: "b", eq: "b", eqK: "b", microM: "b" };
+  for (const [k, ch] of Object.entries(channels)) assert.equal(by[k].channel, ch, `${k} channel`);
+  assert.ok(text.filter((t) => !(t.key in channels)).every((t) => t.channel === undefined || t.channel === "r"), "the editorial sheet stays on R");
+  for (const k of ["mega", "mega2", "echo", "eq"]) assert.equal(by[k].family, "Monument Extended", `${k} is Monument Extended`);
+  for (const k of ["megaK", "echoK", "microK", "slit", "slitK", "eqK"]) assert.equal(by[k].family, "Pretendard", `${k} is Pretendard`);
+  assert.equal(by.microM.family, "MesloLGS NF");
+  for (const k of ["capA", "capB", "body", "fields", "atlas"]) assert.equal(by[k].family, "MesloLGS NF", `${k} caption/counter text is MesloLGS NF`);
+  for (const k of ["megaK", "echoK", "slitK", "eqK"]) assert.match(by[k].default, /[가-힣]/u, `${k} is Hangul`);
+  for (const t of Object.values(by)) assert.ok(t.default.length >= 1 && t.size <= 1, `${t.key} has text`);
+  const v = validateScore({ version: 1, template: "collage", preset: "glyph-flood", input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t", labels: { mega: "R", mega2: "Q", echo: "NODE", slit: "HALL", eqK: "빛" }, textStyle: { mega: { family: "Pretendard", weight: 700 } } }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+});
+
+async function frames(preset, keep, params = {}) {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const v = validateScore({ version: 1, template: "collage", preset, input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t", params: { grain: 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, `t-${runs++}`), width: W, height: H, features, replay: false, onFrame: (f, a) => { if (keep.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+  return { kept, features };
+}
+
+/** Events (onsets or beats) with no other event in the 4 frames before and the 5 after, so the pulse attacks clean and has fully fallen by e + 5. */
+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 isVermilion = ([r, g, b]) => r > 170 && g < 110 && b < 80;
+
+test("echo-stack: the stack is at its fullest on the beat frame (more vermilion copies) and has fallen back by 5 frames later", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beats = clean(features.meta.beats, 8, 85).slice(0, 3);
+  assert.ok(beats.length >= 2, `clean beats exist: ${beats}`);
+  const { kept } = await frames("echo-stack", beats.flatMap((b) => [b - 1, b, b + 5]));
+  for (const b of beats) {
+    const [before, at, after] = [b - 1, b, b + 5].map((f) => count(kept.get(f), isVermilion));
+    assert.ok(at >= before * 0.98 && at > 18000, `beat ${b}: vermilion ${before} -> ${at}`);
+    assert.ok(after < at * 0.6, `beat ${b}: vermilion ${at} -> ${after} after 5 frames`);
+  }
+});
+
+test("typeWarp scales the warp: declared 0..1.5 with default 1, and 0 holds the echo stack still across a beat", async () => {
+  const input = tpl.fx.INPUTS.find((i) => i.NAME === "typeWarp");
+  assert.deepEqual([input.MIN, input.MAX, input.DEFAULT], [0, 1.5, 1]);
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const b = clean(features.meta.beats, 8, 85)[0];
+  const { kept } = await frames("echo-stack", [b, b + 5], { typeWarp: 0 });
+  const [at, after] = [b, b + 5].map((f) => count(kept.get(f), isVermilion));
+  assert.ok(Math.abs(at - after) < at * 0.03, `beat ${b}: vermilion ${at} vs ${after} with the warp off`);
+  assert.ok(at < 12000, `only the front pair of copies is drawn: ${at}`);
+});
+
+test("glyph-flood: the hot extrusion jumps out on the onset frame and is back within 5 frames; the cut-out letter keeps its place", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const onsets = clean(features.meta.onsets, 8, 85).slice(0, 3);
+  const { kept } = await frames("glyph-flood", onsets.flatMap((o) => [o - 1, o, o + 5]));
+  for (const o of onsets) {
+    const [before, at, after] = [o - 1, o, o + 5].map((f) => count(kept.get(f), isVermilion, 48, 0, W, H));
+    assert.ok(at > before * 1.1 + 1500, `onset ${o}: vermilion ${before} -> ${at}`);
+    assert.ok(after < at * 0.9, `onset ${o}: vermilion ${at} -> ${after} after 5 frames`);
+    const a = kept.get(o - 1);
+    const b = kept.get(o + 5);
+    let same = 0;
+    for (let y = 120; y < 240; y++) same += Math.abs(px(a, 320, y)[0] - px(b, 320, y)[0]) < 40 ? 1 : 0;
+    assert.ok(same > 100, `the glyph interior column holds its place between onsets (${same} of 120 rows unchanged)`);
+  }
+});
+
+test("slit-scan: a beat smears the word into a pale streak on its frame and the streak is gone 5 frames later", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beats = clean(features.meta.beats, 8, 85).slice(0, 3);
+  assert.ok(beats.length >= 2, `clean beats exist: ${beats}`);
+  const { kept } = await frames("slit-scan", beats.flatMap((b) => [b - 1, b, b + 5]));
+  const pale = ([r, g, b]) => r > 200 && g > 110 && g < 236 && b > 90 && r - g > 8;
+  for (const b of beats) {
+    const [before, at, after] = [b - 1, b, b + 5].map((f) => count(kept.get(f), pale, 0, 24, 320, H));
+    assert.ok(at > before && at > 15000, `beat ${b}: pale smear ${before} -> ${at}`);
+    assert.ok(after < 500, `beat ${b}: pale smear ${at} -> ${after} after 5 frames`);
+  }
+});

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

@@ -0,0 +1,84 @@
+// Concept C "collage": validation, snappy-motion declarations, measured responsiveness on rendered
+// frames, and layout regeneration on beats.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, 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";
+
+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 tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-collage-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+let runs = 0;
+
+function score(preset, params = {}) {
+  const v = validateScore({ version: 1, template: "collage", ...(preset ? { preset } : {}), input: { audio: MUSIC }, durationSec: 3, seed: 5, out: "t", params }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  return v.value;
+}
+
+async function frames(preset, params, keep) {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const kept = new Map();
+  await renderScore(score(preset, params), lib, { outDir: path.join(tmp, `c-${runs++}`), width: 320, height: 180, features, replay: false, onFrame: (f, a) => { if (keep.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+  return { kept, features };
+}
+
+/** Bright pixels in the top channel row (bass) of the solo level meter, rows 12..40 of 180. */
+const lit = (rgba) => { let c = 0; for (let y = 12; y < 40; y++) for (let x = 0; x < 320; x++) { const i = (y * 320 + x) * 4; if (rgba[i] + rgba[i + 1] + rgba[i + 2] > 380) c += 1; } return c; };
+const diff = (a, b) => { let c = 0; for (let i = 0; i < a.length; i += 4) if (Math.abs(a[i + 1] - b[i + 1]) > 40) c += 1; return c / (a.length / 4); };
+
+test("collage validates, ships 4 presets incl. release 0.06 and 0.12, and a demo score each", () => {
+  assert.ok(tpl, "collage is in the library");
+  const presets = tpl.fx.X_AGENTVFX.presets;
+  assert.ok(Object.keys(presets).length >= 3);
+  for (const p of Object.keys(presets)) score(p);
+  const rel = (p) => ({ ...Object.fromEntries(tpl.fx.INPUTS.map((i) => [i.NAME, i.DEFAULT])), ...presets[p] }).release;
+  const values = Object.keys(presets).map(rel);
+  assert.ok(values.includes(0.06) && values.includes(0.12), `release values ${values}`);
+  assert.equal(tpl.fx.X_AGENTVFX.spdx, "Apache-2.0");
+  assert.ok(tpl.fx.X_AGENTVFX.safeSubstitute);
+  for (const d of readdirSync(tpl.dir).filter((f) => f.startsWith("demo-"))) assert.equal(validateScore(JSON.parse(readFileSync(path.join(tpl.dir, d), "utf8")), lib).ok, true);
+});
+
+test("snappy declarations: release default <= 0.07 s, no attack or settle style parameter", () => {
+  const names = tpl.fx.INPUTS.map((i) => i.NAME);
+  assert.ok(tpl.fx.INPUTS.find((i) => i.NAME === "release").DEFAULT <= 0.07);
+  assert.deepEqual(names.filter((n) => /attack|settle|smooth|easing|lag/iu.test(n)), []);
+});
+
+test("level meter: lights within 1 frame of a strong bass onset and drops 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("bone-lime", { cutMode: 3, soloPanel: 4, grain: 0, gridDots: 0, construction: false }, keep);
+  for (const o of onsets) {
+    const before = lit(kept.get(o - 1));
+    const at = lit(kept.get(o));
+    const after = lit(kept.get(o + 4));
+    assert.ok(at > before * 1.3, `onset ${o}: lit ${before} -> ${at}`);
+    assert.ok(after <= at * 0.5, `onset ${o}: lit ${at} -> ${after} after 4 frames`);
+  }
+});
+
+test("layoutMode reshuffle (opt-in): the layout is rebuilt on a beat and holds between cuts", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const beat = features.meta.beats.find((b) => b >= 4 && b < 85);
+  const keep = [beat - 1, beat, beat + 1, beat + 2];
+  const live = (await frames("bone-lime", { layoutMode: 1, construction: false, grain: 0 }, keep)).kept;
+  const frozen = (await frames("bone-lime", { layoutMode: 1, construction: false, grain: 0, cutMode: 3 }, keep)).kept;
+  const cut = diff(live.get(beat - 1), live.get(beat));
+  const still = diff(frozen.get(beat - 1), frozen.get(beat));
+  assert.ok(cut > 0.2, `pixels changed on the beat: ${cut}`);
+  assert.ok(cut > still * 2, `cut ${cut} vs frozen layout ${still}`);
+  assert.ok(diff(live.get(beat), live.get(beat + 1)) < cut, "layout holds after the cut");
+});

package/skills/agentvfx/test/concept-lattice.test.mjs

@@ -0,0 +1,133 @@
+// Concept B "lattice": validation, snappy-motion declarations, and a rendered responsiveness probe
+// (the lattice deforms on the frame of a kick and is mostly back to order within four frames).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readdirSync, 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";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MUSIC = "test-media/beat-132.mp3";
+const lib = loadLibrary();
+const tpl = lib.get("lattice");
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-lattice-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+let runs = 0;
+
+const score = (preset, extra = {}) => {
+  const v = validateScore({ version: 1, template: "lattice", preset, durationSec: 3, seed: 5, out: "t", ...extra }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  return v.value;
+};
+const releaseOf = (preset) => tpl.fx.X_AGENTVFX.presets[preset].release ?? tpl.fx.INPUTS.find((i) => i.NAME === "release").DEFAULT;
+
+test("lattice validates: every preset and demo, 4 s demos with the shared music", () => {
+  assert.ok(tpl, "lattice is in the library");
+  const presets = Object.keys(tpl.fx.X_AGENTVFX.presets);
+  assert.ok(presets.length >= 3);
+  for (const p of presets) score(p);
+  const demos = readdirSync(tpl.dir).filter((f) => f.startsWith("demo-"));
+  assert.ok(demos.length >= 3);
+  for (const d of demos) {
+    const demo = JSON.parse(readFileSync(path.join(tpl.dir, d), "utf8"));
+    const v = validateScore(demo, lib);
+    assert.equal(v.ok, true, `${d}: ${JSON.stringify(v.errors)}`);
+    assert.equal(demo.durationSec, 4);
+    assert.equal(demo.input.audio, MUSIC);
+    assert.ok(existsSync(path.join(ROOT, demo.input.video)));
+  }
+  assert.equal(tpl.fx.X_AGENTVFX.spdx, "Apache-2.0");
+  assert.ok(tpl.fx.X_AGENTVFX.safeSubstitute);
+});
+
+test("lattice knobs: colours, grid size and headline font/text are settable from a score", () => {
+  const palettes = ["graphite-ice", "phosphor", "bone-ink"];
+  for (const p of palettes) assert.ok(tpl.fx.X_AGENTVFX.presets[p]?.dotColor, `palette preset ${p}`);
+  assert.equal(tpl.fx.X_AGENTVFX.presets.vermilion && Object.keys(tpl.fx.X_AGENTVFX.presets.vermilion).length, 0, "vermilion stays the default");
+  const colours = { groundColor: [0.1, 0.1, 0.1, 1], dotColor: [0.2, 0.9, 0.3, 1], hotColor: [1, 1, 1, 1] };
+  assert.deepEqual(score("vermilion", { params: colours }).params, colours);
+  assert.equal(validateScore({ version: 1, template: "lattice", durationSec: 3, seed: 5, params: { dotColor: [2, 0, 0, 1] } }, lib).ok, false, "out-of-range colour rejected");
+  for (const pitch of [8, 80]) score("vermilion", { params: { pitch } });
+  assert.equal(validateScore({ version: 1, template: "lattice", durationSec: 3, seed: 5, params: { pitch: 81 } }, lib).ok, false);
+  score("vermilion", { labels: { headline: "ZONE" }, textStyle: { headline: { font: "mono", size: 0.12, x: 0.1, y: 0.4 } } });
+});
+
+test("lattice grid size is resolution independent: the same pitch gives the same number of columns at 640x360 and 960x540", async () => {
+  const quiet = { mediaAmount: 0, headline: 0, jitter: 0, sparkle: 0, tearShear: 0, ghost: 0, links: 0, dotBase: 0.3 };
+  const columns = async (w, h) => {
+    const kept = new Map();
+    await renderScore(score("vermilion", { params: quiet, fps: 24 }), lib, { outDir: path.join(tmp, `r-${runs++}`), width: w, height: h, replay: false, onFrame: (f, a) => { if (f === 2) kept.set(f, Buffer.from(a.rgba)); } });
+    const px = kept.get(2);
+    const prof = Array.from({ length: w }, (_, x) => { let s = 0; for (let y = 0; y < h; y++) s += px[(y * w + x) * 4 + 0]; return s / h; });
+    const mid = (Math.min(...prof) + Math.max(...prof)) / 2;
+    let n = 0;
+    for (let x = 1; x < w; x++) if (prof[x - 1] < mid && prof[x] >= mid) n++;
+    return n;
+  };
+  const small = await columns(640, 360);
+  const big = await columns(960, 540);
+  const expected = 1920 / 22;
+  assert.ok(Math.abs(small - expected) <= 3, `640x360 shows ${small} columns, expected about ${expected.toFixed(1)}`);
+  assert.ok(Math.abs(big - expected) <= 3, `960x540 shows ${big} columns, expected about ${expected.toFixed(1)}`);
+});
+
+test("lattice declares snappy motion: release default <= 0.07 s, one preset at 0.12, no attack smoothing anywhere", () => {
+  const rel = tpl.fx.INPUTS.find((i) => i.NAME === "release");
+  assert.ok(rel.DEFAULT <= 0.07, `release default ${rel.DEFAULT}`);
+  const rels = Object.keys(tpl.fx.X_AGENTVFX.presets).map(releaseOf);
+  assert.ok(rels.includes(0.12), "a 0.12 s preset to compare");
+  assert.ok(rels.every((r) => r <= 0.12 && r >= rel.MIN));
+  for (const i of tpl.fx.INPUTS) assert.ok(!/attack|settle|lag|inertia|smooth|easing|glide/iu.test(i.NAME), `no smoothing-style param: ${i.NAME}`);
+  const src = tpl.passes.map((f) => readFileSync(path.join(tpl.dir, f), "utf8").replace(/\/\/.*$/gmu, "")).join("\n");
+  assert.ok(!/attack|settle|smoothstep\s*\(\s*0\.0\s*,\s*1\.0\s*,\s*AUDIO/iu.test(src), "no attack/settle in shader code");
+  assert.ok(/max\(\s*clamp\(\(AUDIO_TREB/u.test(src), "running envelope is max(raw, decayed previous): instant attack");
+});
+
+/** Render frames 0..n of a score at 320x180 and return the RGBA of each wanted frame. */
+async function frames(s, keep, features) {
+  const kept = new Map();
+  await renderScore(s, lib, { outDir: path.join(tmp, `r-${runs++}`), width: 320, height: 180, features, replay: false, onFrame: (f, a) => { if (keep.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+  return kept;
+}
+/** Peak disturbance: the largest mean |difference| over any 16x16 block (amplitude, not the area the wave has reached). */
+const dev = (a, b) => {
+  const B = 16;
+  let best = 0;
+  for (let by = 0; by < Math.floor(180 / B); by++) {
+    for (let bx = 0; bx < Math.floor(320 / B); bx++) {
+      let s = 0;
+      for (let y = 0; y < B; y++) for (let x = 0; x < B; x++) { const i = ((by * B + y) * 320 + bx * B + x) * 4; s += Math.abs(a[i] - b[i]) + Math.abs(a[i + 1] - b[i + 1]) + Math.abs(a[i + 2] - b[i + 2]); }
+      best = Math.max(best, s / (B * B));
+    }
+  }
+  return best;
+};
+
+test("lattice: silence is a perfect static grid; a kick deforms it on the same frame and it is mostly back within 4 frames", async () => {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30 });
+  const fr = features.frames;
+  const kickBass = tpl.fx.INPUTS.find((i) => i.NAME === "kickBass").DEFAULT;
+  const f = fr.findIndex((x, i) => i >= 8 && x.bass >= kickBass && x.bass > 1.5 * fr[i - 1].bass
+    && fr.slice(i - 6, i).every((y) => !y.onset) && fr.slice(i + 1, i + 6).every((y) => !y.onset));
+  assert.ok(f > 0, "an isolated kick exists in the test music");
+  const quiet = { mediaAmount: 0, headline: 0, jitter: 0, sparkle: 0, tearShear: 0 };
+  const keep = [f - 1, f, f + 1, f + 2, f + 4];
+  const rest = await frames(score("vermilion", { params: quiet }), keep, null);
+  const floor = dev(rest.get(f - 1), rest.get(f + 4));
+  assert.ok(floor < 2, `silent lattice only differs by the output dither: ${floor.toFixed(3)}`);
+  const run = async (preset) => {
+    const k = await frames(score(preset, { params: quiet, input: { audio: MUSIC } }), keep, features);
+    const ref = preset === "vermilion" ? rest : await frames(score(preset, { params: quiet }), keep, null);
+    return keep.map((n) => Math.max(dev(k.get(n), ref.get(n)) - floor, 0));
+  };
+  const [before, onset, , , after] = await run("vermilion");
+  assert.ok(onset > 3 * before + 1,`deformed on the onset frame: ${onset.toFixed(2)} vs ${before.toFixed(2)} before`);
+  assert.ok(after <= 0.5 * onset, `drops by half within 4 frames: ${after.toFixed(2)} vs ${onset.toFixed(2)}`);
+  const slow = await run("violet-slow");
+  assert.ok(slow[4] / slow[1] > after / onset, "release 0.12 lingers longer than release 0.06");
+});

package/skills/agentvfx/test/concept-signal-cut.test.mjs

@@ -0,0 +1,172 @@
+// signal-cut concept (design A): validation of every preset and demo, snappy-response declarations
+// (release default <= 0.07 s, one preset at 0.12, no attack smoothing parameter) and a render probe on the
+// real clip and music: the field cut lands on the beat frame and is gone within four frames.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, 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 { openFootage } from "../engine/node/footage.mjs";
+import { auditFlash, LINEAR_LUT } from "../engine/core/flash.mjs";
+import { FLASH } from "../engine/core/flash-constants.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CLIP = "test-media/clip-01.mp4";
+const MUSIC = "test-media/beat-132.mp3";
+const lib = loadLibrary();
+const tpl = lib.get("signal-cut");
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-signal-cut-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+const W = 320;
+const H = 180;
+
+const score = (preset, extra = {}) => {
+  const v = validateScore({ version: 1, template: "signal-cut", preset, input: { video: CLIP, audio: MUSIC }, durationSec: 3, seed: 7, out: "t", ...extra }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  return v.value;
+};
+
+async function frames(s, keep) {
+  const features = await analyzeAudio(path.resolve(ROOT, MUSIC), { fps: 30, durationSec: s.durationSec });
+  const footage = openFootage(path.resolve(ROOT, CLIP), { fps: 30, durationSec: s.durationSec, longEdge: W });
+  const kept = new Map();
+  try {
+    await renderScore(s, lib, { outDir: mkdtempSync(path.join(tmp, "r-")), width: W, height: H, footage, features, replay: false, onFrame: (f, a) => { if (keep.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+  } finally {
+    footage.close();
+  }
+  return { kept, features };
+}
+/** Share of pixels that are the acid field colour (200, 255, 0). */
+const fieldShare = (rgba) => {
+  let n = 0;
+  for (let i = 0; i < W * H; i++) if (rgba[i * 4] > 150 && rgba[i * 4 + 1] > 200 && rgba[i * 4 + 2] < 60) n += 1;
+  return n / (W * H);
+};
+
+test("signal-cut is declared: family, 3+ presets, strobe class with a safe substitute, demos validate", () => {
+  assert.ok(tpl, "signal-cut is in the library");
+  const x = tpl.fx.X_AGENTVFX;
+  assert.equal(x.input, "footage");
+  assert.equal(x.spdx, "Apache-2.0");
+  assert.ok(Object.keys(x.presets).length >= 3);
+  assert.equal(x.flash, "strobe");
+  assert.equal(x.safeSubstitute.params.fieldCut, 0);
+  for (const preset of Object.keys(x.presets)) score(preset);
+  const demos = readdirSync(tpl.dir).filter((f) => f.startsWith("demo-"));
+  assert.ok(demos.length >= 3);
+  for (const d of demos) {
+    const demo = JSON.parse(readFileSync(path.join(tpl.dir, d), "utf8"));
+    assert.equal(validateScore(demo, lib).ok, true, d);
+    assert.equal(demo.durationSec, 4);
+    assert.ok(existsSync(path.join(ROOT, demo.input.video)));
+    assert.equal(demo.input.audio, MUSIC);
+  }
+});
+
+test("signal-cut is snappy by declaration: release default <= 0.07 s, a 0.12 s preset, no attack smoothing parameter", () => {
+  const inputs = tpl.fx.INPUTS;
+  const release = inputs.find((i) => i.NAME === "release");
+  assert.ok(release.DEFAULT <= 0.07, `release default ${release.DEFAULT}`);
+  const x = tpl.fx.X_AGENTVFX;
+  const resolved = (p) => score(p).params?.release ?? release.DEFAULT;
+  assert.ok(Object.keys(x.presets).some((p) => (x.presets[p].release ?? release.DEFAULT) === 0.12), "one preset releases at 0.12 s");
+  assert.ok(resolved("lime") <= 0.07);
+  assert.equal(inputs.some((i) => /attack|smooth|settle|lag|damp|inertia/iu.test(i.NAME)), false, "no attack or smoothing parameter");
+  const pass0 = readFileSync(path.join(tpl.dir, "pass0.frag"), "utf8");
+  assert.ok(/max\(target, held\)/u.test(pass0), "follower is max(target, held): instant attack");
+});
+
+test("signal-cut: the field cut lands on the beat frame and is gone within four frames", async () => {
+  const { kept, features } = await frames(score("lime"), Array.from({ length: 70 }, (_, i) => i));
+  const beat = features.meta.beats.find((b) => b >= 10 && b < 60);
+  assert.ok(beat !== undefined, "a beat inside the window");
+  const before = fieldShare(kept.get(beat - 1));
+  const on = fieldShare(kept.get(beat));
+  const later = fieldShare(kept.get(beat + 4));
+  assert.ok(on > 0.25, `field colour covers the frame on the beat frame: ${on}`);
+  assert.ok(before < on * 0.5, `no field colour the frame before: ${before}`);
+  assert.ok(later < on * 0.5, `field cut dropped by half within four frames: ${on} -> ${later}`);
+});
+
+test("signal-cut: fieldCut 0 (the safe substitute) removes the cut but the slabs still move", async () => {
+  const { kept, features } = await frames(score("lime", { params: { fieldCut: 0, stampFrames: 0 } }), Array.from({ length: 70 }, (_, i) => i));
+  const beat = features.meta.beats.find((b) => b >= 10 && b < 60);
+  assert.ok(fieldShare(kept.get(beat)) < 0.3, `no solid field without the cut: ${fieldShare(kept.get(beat)).toFixed(3)} at beat ${beat}`);
+  let d = 0;
+  for (let i = 0; i < W * H * 4; i++) d += Math.abs(kept.get(beat)[i] - kept.get(beat - 1)[i]);
+  assert.ok(d / (W * H * 4) > 3, "frame still changes on the beat");
+});
+
+// slabContrast crushes green and blue on warm footage, so a hard scene cut in warm footage used to read as a
+// saturated-red transition with the safe values on (the plate behind the live preview does exactly this).
+test("signal-cut: hard cuts between warm and neutral footage never make a saturated-red transition", async () => {
+  const clip = path.join(tmp, "warm-cuts.mp4");
+  const lavfi = `color=c=0x8c453f:size=${W}x${H}:rate=30:d=1,format=yuv420p[a];color=c=0x303030:size=${W}x${H}:rate=30:d=1,format=yuv420p[b];[a][b]concat=n=2:v=1,loop=loop=3:size=60`;
+  const made = spawnSync("ffmpeg", ["-v", "error", "-y", "-filter_complex", lavfi, "-t", "4", "-c:v", "libx264", "-crf", "12", "-pix_fmt", "yuv420p", clip], { encoding: "utf8" });
+  assert.equal(made.status, 0, made.stderr);
+  const v = validateScore({ version: 1, template: "signal-cut", preset: "lime", params: tpl.fx.X_AGENTVFX.safeSubstitute.params, input: { video: CLIP }, durationSec: 4, seed: 7, out: "t" }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const footage = openFootage(clip, { fps: 30, durationSec: 4, longEdge: W });
+  const seq = [];
+  try {
+    await renderScore(v.value, lib, { outDir: mkdtempSync(path.join(tmp, "r-")), width: W, height: H, footage, replay: false, onFrame: (f, a) => { seq[f] = { width: W, height: H, data: Buffer.from(a.rgba) }; } });
+  } finally {
+    footage.close();
+  }
+  assert.equal(auditFlash(seq, { fps: 30 }).redFlashes, 0);
+});
+
+// The declared safe substitute is what the engine renders as film.safe.mp4. Before it also held the stamp, the
+// idle/live dimming and the beat shifts, every preset still flashed 8+ times a second (orange also in red) and the
+// engine withheld the safe film.
+test("signal-cut: every preset passes the flash audit with the safe substitute (real clip and music)", async () => {
+  const features = await analyzeAudio(path.join(ROOT, MUSIC), { fps: 30, durationSec: 5 });
+  for (const preset of Object.keys(tpl.fx.X_AGENTVFX.presets)) {
+    const v = validateScore({ version: 1, template: "signal-cut", preset, params: tpl.fx.X_AGENTVFX.safeSubstitute.params, input: { video: CLIP, audio: MUSIC }, durationSec: 5, seed: 7, out: "t" }, lib);
+    assert.equal(v.ok, true, JSON.stringify(v.errors));
+    const footage = openFootage(path.join(ROOT, CLIP), { fps: 30, durationSec: 5, longEdge: W });
+    const seq = [];
+    try {
+      await renderScore(v.value, lib, { outDir: mkdtempSync(path.join(tmp, "s-")), width: W, height: H, footage, features, replay: false, onFrame: (f, a) => { seq[f] = { width: W, height: H, data: Buffer.from(a.rgba) }; } });
+    } finally {
+      footage.close();
+    }
+    const r = auditFlash(seq, { fps: 30 });
+    assert.equal(r.exceeds, false, `${preset}: ${JSON.stringify(r.worstWindow)}`);
+    assert.equal(r.redFlashes, 0, preset);
+  }
+});
+
+// The field colour fills the frame on every beat in the stage film, so a saturated-red field colour makes every cut a red
+// flash (orange at (1, 0.235, 0) gave 20 in 5 s). Each preset's field colour must sit below the auditor's red rule.
+test("signal-cut: every preset's field colour is below the red-flash rule in linear light", () => {
+  const def = tpl.fx.INPUTS.find((i) => i.NAME === "fieldColor").DEFAULT;
+  for (const [preset, p] of Object.entries(tpl.fx.X_AGENTVFX.presets)) {
+    const [r, g, b] = (p.fieldColor ?? def).slice(0, 3).map((c) => LINEAR_LUT[Math.round(c * 255)]);
+    assert.ok(r / (r + g + b) < FLASH.redRatio, `${preset}: red share ${(r / (r + g + b)).toFixed(3)}`);
+  }
+});
+
+// The stage film may strobe, but never in saturated red: the cut shows the raw footage for a frame or two between field
+// states, and deep-red footage (a lit red dress in the test clip) then read as red flashes in the orange demo.
+test("signal-cut: the orange stage demo on the real clip has no red flashes", async () => {
+  const demo = JSON.parse(readFileSync(path.join(tpl.dir, "demo-orange.json"), "utf8"));
+  const v = validateScore({ ...demo, durationSec: 4 }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const features = await analyzeAudio(path.join(ROOT, MUSIC), { fps: 30, durationSec: 4 });
+  const footage = openFootage(path.join(ROOT, CLIP), { fps: 30, durationSec: 4, longEdge: W });
+  const seq = [];
+  try {
+    await renderScore(v.value, lib, { outDir: mkdtempSync(path.join(tmp, "o-")), width: W, height: H, footage, features, replay: false, onFrame: (f, a) => { seq[f] = { width: W, height: H, data: Buffer.from(a.rgba) }; } });
+  } finally {
+    footage.close();
+  }
+  assert.equal(auditFlash(seq, { fps: 30 }).redFlashes, 0);
+});

package/skills/agentvfx/test/credit-overlay.test.mjs

@@ -0,0 +1,58 @@
+// The on-screen credit: platforms strip MP4 metadata, so every render burns a small "made with agentvfx" mark into the
+// bottom-right corner unless the score opts out with "credit": { "overlay": false }. The mark is static, so it cannot add
+// a flash, and it touches nothing outside its corner.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadLibrary } from "../engine/core/templates.mjs";
+import { validateScore } from "../engine/core/validate.mjs";
+import { renderScore } from "../engine/node/render.mjs";
+
+const lib = loadLibrary({ includeTest: true });
+const W = 640;
+const H = 360;
+const base = { version: 1, template: "test-gradient", durationSec: 3, seed: 3, out: "t" };
+
+test("credit defaults to an on-screen overlay and only accepts { overlay: boolean }", () => {
+  const v = validateScore(base, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  assert.deepEqual(v.value.credit, { overlay: true });
+  assert.deepEqual(validateScore({ ...base, credit: { overlay: false } }, lib).value.credit, { overlay: false });
+  const bad = validateScore({ ...base, credit: { overlay: "no" } }, lib);
+  assert.ok(bad.errors.some((e) => e.path === "credit.overlay"), JSON.stringify(bad.errors));
+  const unknown = validateScore({ ...base, credit: { size: 3 } }, lib);
+  assert.ok(unknown.errors.some((e) => e.path === "credit.size"), JSON.stringify(unknown.errors));
+});
+
+async function frame(score, f = 30) {
+  const v = validateScore(score, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-overlay-"));
+  let kept = null;
+  try {
+    await renderScore(v.value, lib, { outDir: dir, width: W, height: H, replay: false, onFrame: (i, a) => { if (i === f) kept = Buffer.from(a.rgba); } });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  return kept;
+}
+
+test("the overlay marks the bottom-right corner and nothing else; overlay false leaves the frame untouched", async () => {
+  const on = await frame(base);
+  const off = await frame({ ...base, credit: { overlay: false } });
+  let inside = 0;
+  let outside = 0;
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const i = (y * W + x) * 4;
+      const d = Math.abs(on[i] - off[i]) + Math.abs(on[i + 1] - off[i + 1]) + Math.abs(on[i + 2] - off[i + 2]);
+      if (d <= 6) continue;
+      if (x > W * 0.55 && y > H * 0.85) inside += 1;
+      else outside += 1;
+    }
+  }
+  assert.ok(inside > 150, `credit pixels in the corner: ${inside}`);
+  assert.equal(outside, 0, "nothing changes outside the corner");
+});