agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/test/fixtures/score-bad-duration.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "template": "test-gradient",
+  "durationSec": 8,
+  "seed": 1,
+  "out": "bad"
+}

package/skills/agentvfx/test/fixtures/score-bad-safety.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "template": "test-strobe",
+  "durationSec": 3,
+  "seed": 1,
+  "safety": { "mode": "gentle" },
+  "out": "bad-safety"
+}

package/skills/agentvfx/test/fixtures/score-identity-footage.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "template": "test-identity",
+  "input": { "video": "test-media/clip-01.mp4", "startSec": 0 },
+  "durationSec": 5,
+  "seed": 1,
+  "out": "identity-footage"
+}

package/skills/agentvfx/test/fixtures/score-missing-template.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "template": "does-not-exist",
+  "durationSec": 3,
+  "seed": 1,
+  "out": "missing"
+}

package/skills/agentvfx/test/fixtures/score-ok.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "template": "test-gradient",
+  "preset": "slow",
+  "durationSec": 3,
+  "seed": 1,
+  "out": "test-gradient"
+}

package/skills/agentvfx/test/fixtures/score-strobe-12hz.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "template": "test-strobe",
+  "preset": "fast",
+  "durationSec": 3,
+  "seed": 3,
+  "out": "strobe-12hz"
+}

package/skills/agentvfx/test/fixtures/score-text-probe.json

@@ -0,0 +1 @@
+{ "version": 1, "template": "test-text-probe", "durationSec": 3, "seed": 4, "out": "text-probe" }

package/skills/agentvfx/test/flash-audit.test.mjs

@@ -0,0 +1,150 @@
+// Flash audit: synthetic sequences built in memory, verdicts per WCAG 2.2 / BT.1702-3 / IRIS rules.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { auditFlash, createFlashAuditor, gridFor, LINEAR_LUT, FlashDetector } from "../engine/core/flash.mjs";
+
+const W = 320;
+const H = 180;
+const FPS = 30;
+
+/** Frame sequence: `stateAt(i)` says whether frame i is lit; `lit` is its colour, `box` limits the lit area. */
+function sequence(seconds, stateAt, { lit = [255, 255, 255], box = null } = {}) {
+  const frames = [];
+  for (let i = 0; i < seconds * FPS; i++) {
+    const data = new Uint8Array(W * H * 4);
+    const on = stateAt(i);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const inside = !box || (x < box.w && y < box.h);
+        const o = (y * W + x) * 4;
+        if (on && inside) { data[o] = lit[0]; data[o + 1] = lit[1]; data[o + 2] = lit[2]; }
+        data[o + 3] = 255;
+      }
+    }
+    frames.push({ width: W, height: H, data });
+  }
+  return frames;
+}
+
+// Square wave with `transitionsPerSecond` edges per second (30 fps, so 30 / n frames per half period).
+const wave = (transitionsPerSecond) => (i) => Math.floor((i * transitionsPerSecond) / FPS) % 2 === 1;
+
+test("Given black/white at 2 flashes/s When audited Then within limits", () => {
+  const r = auditFlash(sequence(4, wave(4)), { fps: FPS });
+  assert.equal(r.exceeds, false);
+  assert.equal(r.redFlashes, 0);
+  assert.ok(r.worstWindow.transitions <= 6);
+});
+
+test("Given black/white at 4 flashes/s When audited Then exceeds", () => {
+  const r = auditFlash(sequence(4, wave(8)), { fps: FPS });
+  assert.equal(r.exceeds, true);
+  assert.ok(r.worstWindow.transitions > 6);
+  assert.ok(r.flashesPerSecondMax >= 3);
+});
+
+test("Given saturated red/black at 2 flashes/s When audited Then the red rule makes it exceed", () => {
+  const r = auditFlash(sequence(4, wave(4), { lit: [255, 0, 0] }), { fps: FPS });
+  assert.equal(r.exceeds, true);
+  assert.ok(r.redFlashes > 0);
+});
+
+test("Given a 2% white square at 6 flashes/s When audited Then within limits (area under threshold)", () => {
+  const r = auditFlash(sequence(4, wave(12), { box: { w: 48, h: 24 } }), { fps: FPS });
+  assert.equal(r.exceeds, false);
+  assert.equal(r.worstWindow.transitions, 0);
+});
+
+test("Given 5 transitions/s for 5 s When audited Then extendedFlashing is set but exceeds is not", () => {
+  const r = auditFlash(sequence(5, wave(5)), { fps: FPS });
+  assert.equal(r.extendedFlashing, true);
+  assert.equal(r.exceeds, false);
+});
+
+test("Given 5 transitions/s for 3 s When audited Then extendedFlashing is false", () => {
+  assert.equal(auditFlash(sequence(3, wave(5)), { fps: FPS }).extendedFlashing, false);
+});
+
+test("Given a static frame sequence When audited Then nothing is reported", () => {
+  const r = auditFlash(sequence(2, () => true), { fps: FPS });
+  assert.equal(r.exceeds, false);
+  assert.equal(r.flashesPerSecondMax, 0);
+  assert.equal(r.perSecond.length, 2);
+});
+
+test("Given the same frames When pushed one by one Then the streaming result equals auditFlash", () => {
+  const frames = sequence(4, wave(8));
+  const auditor = createFlashAuditor({ fps: FPS, width: W, height: H });
+  for (const f of frames) auditor.push(f);
+  assert.deepEqual(auditor.finish(), auditFlash(frames, { fps: FPS }));
+});
+
+test("Given frames When audited Then the frame bytes are untouched (report only)", () => {
+  const frames = sequence(1, wave(8));
+  const before = frames.map((f) => Buffer.from(f.data).toString("base64"));
+  auditFlash(frames, { fps: FPS });
+  assert.deepEqual(frames.map((f) => Buffer.from(f.data).toString("base64")), before);
+});
+
+test("Given the analysis.mjs imports Then LINEAR_LUT, gridFor and FlashDetector keep their contracts", () => {
+  assert.equal(LINEAR_LUT.length, 256);
+  assert.equal(LINEAR_LUT[0], 0);
+  assert.ok(Math.abs(LINEAR_LUT[255] - 1) < 1e-6);
+  assert.deepEqual(gridFor(), { gw: 320, gh: 180, ww: 107, wh: 60 });
+  assert.deepEqual(gridFor(1080, 1920), { gw: 180, gh: 320, ww: 60, wh: 107 });
+  assert.equal(typeof FlashDetector, "function");
+});
+
+/** Frame sequence from a per-pixel grey code value: `grey(i, x, y)` in 0..255. */
+function greySequence(seconds, grey) {
+  const frames = [];
+  for (let i = 0; i < seconds * FPS; i++) {
+    const data = new Uint8Array(W * H * 4);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const o = (y * W + x) * 4;
+        const v = grey(i, x, y);
+        data[o] = v; data[o + 1] = v; data[o + 2] = v; data[o + 3] = 255;
+      }
+    }
+    frames.push({ width: W, height: H, data });
+  }
+  return frames;
+}
+
+test("Given a hard-edged white bar (1/4 frame wide) sliding at 400 px/s When audited Then motion is not a flash", () => {
+  const barW = W / 4;
+  const span = W + barW;
+  const frames = greySequence(4, (i, x) => {
+    const left = ((Math.round((i * 400) / FPS) % span) + span) % span - barW;
+    return x >= left && x < left + barW ? 255 : 0;
+  });
+  const r = auditFlash(frames, { fps: FPS });
+  assert.equal(r.exceeds, false);
+  assert.equal(r.redFlashes, 0);
+  assert.ok(r.flashesPerSecondMax <= 3, `flashesPerSecondMax ${r.flashesPerSecondMax}`);
+});
+
+test("Given a high-contrast sine grating (period 40 px) drifting at 60 px/s When audited Then motion is not a flash", () => {
+  const frames = greySequence(4, (i, x) => Math.round(127.5 + 127.5 * Math.sin((2 * Math.PI * (x - (60 * i) / FPS)) / 40)));
+  const r = auditFlash(frames, { fps: FPS });
+  assert.equal(r.exceeds, false);
+  assert.equal(r.redFlashes, 0);
+  assert.ok(r.flashesPerSecondMax <= 3, `flashesPerSecondMax ${r.flashesPerSecondMax}`);
+});
+
+// WCAG: opposing changes count when they happen in the same area. Here each half brightens while the
+// other darkens, alternating every 3 frames, so each half alone makes 10 transitions/s (5 flashes/s)
+// over 50% of any window inside it: that is a genuine failure (exceeds stays true). What must not
+// happen is the two opposite halves being summed into a second, phantom transition per frame.
+test("Given one half brightening while the other darkens, alternating every 3 frames When audited Then it counts only each half's own transitions", () => {
+  const frames = greySequence(4, (i, x) => ((Math.floor(i / 3) % 2 === 0) === (x < W / 2) ? 255 : 0));
+  const r = auditFlash(frames, { fps: FPS });
+  assert.equal(r.exceeds, true);
+  assert.ok(r.worstWindow.transitions <= 10, `worst window transitions ${r.worstWindow.transitions}`);
+  assert.ok(r.flashesPerSecondMax <= 5, `flashesPerSecondMax ${r.flashesPerSecondMax}`);
+});
+
+test("Given an audit with a missing fps When called Then it throws a TypeError", () => {
+  assert.throws(() => auditFlash([], {}), TypeError);
+});

package/skills/agentvfx/test/flash.test.mjs

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+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 { runJob, FLASH_COMMENT } from "../engine/node/job.mjs";
+import { auditFlash } from "../engine/core/flash.mjs";
+
+const lib = loadLibrary({ includeTest: true });
+const FIX = fileURLToPath(new URL("./fixtures/", import.meta.url));
+const W = 320;
+const H = 180;
+const strobe = (extra = {}) => {
+  const raw = JSON.parse(readFileSync(path.join(FIX, "score-strobe-12hz.json"), "utf8"));
+  const r = validateScore({ ...raw, ...extra }, lib);
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  return r.value;
+};
+
+function decode(file) {
+  const p = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1"], { maxBuffer: 1 << 30 });
+  const frames = [];
+  for (let o = 0; o + W * H * 4 <= p.stdout.length; o += W * H * 4) frames.push({ width: W, height: H, data: p.stdout.subarray(o, o + W * H * 4) });
+  return frames;
+}
+const comment = (file) => spawnSync("ffprobe", ["-v", "error", "-show_entries", "format_tags=comment", "-of", "default=nw=1:nk=1", file], { encoding: "utf8" }).stdout.trim();
+const centreLuma = (f) => f.data[((H >> 1) * W + (W >> 1)) * 4];
+
+test("stage mode at 12 flashes/s keeps every flash, writes SAFETY.txt and the MP4 comment", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-flash-"));
+  try {
+    const gate = await runJob(strobe(), lib, { outDir: dir, width: W, height: H, replay: false });
+    assert.equal(gate.flash.exceeds, true);
+    assert.ok(existsSync(path.join(dir, "SAFETY.txt")));
+    assert.equal(comment(path.join(dir, "film.mp4")), FLASH_COMMENT);
+    const frames = decode(path.join(dir, "film.mp4"));
+    assert.equal(frames.length, 90);
+    // 12 Hz at 30 fps: on for frames where fract(t*12) < 0.5. Every frame must keep full black or white.
+    const expected = frames.map((_, f) => ((f / 30) * 12 + 1e-4) % 1 < 0.5);
+    frames.forEach((fr, f) => assert.equal(centreLuma(fr) > 200, expected[f], `frame ${f} luma ${centreLuma(fr)}`));
+    for (const k of ["sheet", "poster"]) assert.ok(existsSync(gate.stills[k]), k);
+    assert.ok(gate.stills.strips.length >= 1 && gate.stills.strips.every((s) => existsSync(s.file)));
+    assert.ok(existsSync(path.join(dir, "gate-report.json")));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("safeVariant adds film.safe.mp4 within limits next to the untouched full-intensity film", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-flash-"));
+  try {
+    const gate = await runJob(strobe({ safety: { safeVariant: true } }), lib, { outDir: dir, width: W, height: H, replay: false });
+    assert.equal(gate.flash.exceeds, true, "master keeps full intensity");
+    assert.ok(existsSync(path.join(dir, "film.mp4")));
+    assert.ok(existsSync(path.join(dir, "film.safe.mp4")), JSON.stringify(gate.safeVariant));
+    assert.equal(gate.safeVariant.flash.exceeds, false);
+    assert.equal(auditFlash(decode(path.join(dir, "film.safe.mp4")), { fps: 30 }).exceeds, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a hit schedule is thinned for broadcast-safe and the substitutions are listed", async () => {
+  const hits = Array.from({ length: 10 }, (_, i) => ({ t: 0.5 + i * 0.1, template: "test-strobe", preset: "hold", durationFrames: 1 }));
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-flash-"));
+  try {
+    const gate = await runJob(strobe({ template: "test-gradient", preset: undefined, hits, safety: { safeVariant: true } }), lib, { outDir: dir, width: W, height: H, replay: false });
+    assert.ok(gate.safeVariant.substitutions.length >= 6, JSON.stringify(gate.safeVariant.substitutions));
+    assert.equal(gate.safeVariant.flash.exceeds, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("an unknown safety.mode is rejected naming safety.mode", () => {
+  const raw = JSON.parse(readFileSync(path.join(FIX, "score-strobe-12hz.json"), "utf8"));
+  const r = validateScore({ ...raw, safety: { mode: "gentle" } }, lib);
+  assert.ok(r.errors.some((e) => e.path === "safety.mode"));
+});

package/skills/agentvfx/test/footage.test.mjs

@@ -0,0 +1,88 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+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 { runJob } from "../engine/node/job.mjs";
+
+const lib = loadLibrary({ includeTest: true });
+const ROOT = fileURLToPath(new URL("../", import.meta.url));
+const ff = (args) => {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", ...args], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+};
+const probe = (file, sel) => JSON.parse(spawnSync("ffprobe", ["-v", "error", "-count_frames", "-show_entries", sel, "-of", "json", file], { encoding: "utf8" }).stdout);
+const score = (video, extra = {}) => {
+  const r = validateScore({ version: 1, template: "test-identity", input: { video }, durationSec: 3, seed: 1, out: "f", ...extra }, lib);
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  return r.value;
+};
+
+test("a 29.97 fps clip renders exactly durationSec*fps frames, with audio within 50 ms of the video", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-foot-"));
+  try {
+    const clip = path.join(dir, "src.mp4");
+    ff(["-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30000/1001", "-f", "lavfi", "-i", "sine=frequency=330:sample_rate=48000", "-t", "5", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-shortest", clip]);
+    const out = path.join(dir, "out");
+    await runJob(score(clip), lib, { outDir: out, width: 320, height: 180, replay: false });
+    const film = path.join(out, "film.mp4");
+    const v = probe(film, "stream=codec_type,nb_read_frames,duration");
+    const vs = v.streams.find((s) => s.codec_type === "video");
+    const as = v.streams.find((s) => s.codec_type === "audio");
+    assert.equal(Number(vs.nb_read_frames), 90);
+    assert.ok(as, "has an audio stream");
+    assert.ok(Math.abs(Number(as.duration) - Number(vs.duration)) <= 0.05, `audio ${as.duration} vs video ${vs.duration}`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("colour bars through identity keep each bar's mean RGB within 4/255", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-foot-"));
+  try {
+    const clip = path.join(dir, "bars.mp4");
+    ff(["-f", "lavfi", "-i", "smptehdbars=size=1280x720:rate=30", "-t", "4", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "4", "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709", clip]);
+    const out = path.join(dir, "out");
+    await runJob(score(clip), lib, { outDir: out, width: 640, height: 360, replay: false });
+    const grab = (file) => {
+      const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-frames:v", "1", "-vf", "scale=640:360:flags=area:in_color_matrix=bt709,format=rgb24", "-f", "rawvideo", "pipe:1"], { maxBuffer: 1 << 28 });
+      return r.stdout;
+    };
+    const a = grab(clip);
+    const b = grab(path.join(out, "film.mp4"));
+    // Top band: seven bars across the width; sample the centre of each bar at 1/3 height.
+    for (let i = 0; i < 7; i++) {
+      const x0 = Math.round(((i + 0.3) / 7) * 640 * 0.75);
+      const x1 = Math.round(((i + 0.7) / 7) * 640 * 0.75);
+      const mean = (buf) => {
+        const s = [0, 0, 0];
+        let n = 0;
+        for (let y = 100; y < 140; y++) for (let x = x0; x < x1; x++) { const o = (y * 640 + x) * 3; s[0] += buf[o]; s[1] += buf[o + 1]; s[2] += buf[o + 2]; n++; }
+        return s.map((v) => v / n);
+      };
+      const ma = mean(a);
+      const mb = mean(b);
+      for (let c = 0; c < 3; c++) assert.ok(Math.abs(ma[c] - mb[c]) <= 4, `bar ${i} ch ${c}: ${ma[c].toFixed(1)} vs ${mb[c].toFixed(1)}`);
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a missing video is a named error on input.video", async () => {
+  await assert.rejects(runJob(score("nope/missing.mp4"), lib, { outDir: mkdtempSync(path.join(tmpdir(), "agentvfx-foot-")), width: 320, height: 180, replay: false }), /input\.video/u);
+});
+
+test("test media is present with a licence for every file", () => {
+  const sources = readFileSync(path.join(ROOT, "test-media/SOURCES.md"), "utf8");
+  assert.ok(existsSync(path.join(ROOT, "test-media/beat-132.mp3")), "beat-132.mp3");
+  for (const f of ["clip-01.mp4", "clip-02.mp4"]) {
+    assert.ok(existsSync(path.join(ROOT, "test-media", f)), f);
+    const section = sources.split(`## ${f}`)[1] ?? "";
+    assert.match(section.split("\n## ")[0], /Licence: /u, `licence for ${f}`);
+  }
+});

package/skills/agentvfx/test/glitch.test.mjs

@@ -0,0 +1,272 @@
+// Task 13: glitch/retro family (rgb-split, block-glitch, vhs, pixel-sort). Render tests run at 320x180.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } 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 { renderScore } from "../engine/node/render.mjs";
+import { runJob } from "../engine/node/job.mjs";
+import { analyzeAudio } from "../engine/node/audio.mjs";
+import { openFootage } from "../engine/node/footage.mjs";
+
+const lib = loadLibrary();
+const ROOT = fileURLToPath(new URL("../", import.meta.url));
+const IDS = ["rgb-split", "block-glitch", "vhs", "pixel-sort"];
+const W = 320;
+const H = 180;
+const STILL = `testsrc2=size=${W}x${H}:rate=30,trim=end_frame=1,loop=loop=-1:size=1`;
+
+function makeClip(dir, lavfi) {
+  const clip = path.join(dir, "in.mp4");
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", lavfi, "-t", "4", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "8", clip], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  return clip;
+}
+const score = (template, clip, params = {}, extra = {}) => {
+  const v = validateScore({ version: 1, template, input: { video: clip }, params, durationSec: 3, seed: 7, out: "t", credit: { overlay: false }, ...extra }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  return v.value;
+};
+
+/** Render a score at 320x180 and keep the frames asked for. Returns { report, kept, shas, input }. */
+async function render(sc, { frames = [0], features = null, replay = false } = {}) {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-"));
+  const first = openFootage(sc.input.video, { fps: sc.fps, durationSec: sc.durationSec, longEdge: W });
+  const input = Buffer.from(await first.frame(0).finally(() => first.close()));
+  const footage = openFootage(sc.input.video, { fps: sc.fps, durationSec: sc.durationSec, longEdge: W });
+  const kept = new Map();
+  const shas = [];
+  try {
+    const report = await renderScore(sc, lib, { outDir: dir, width: W, height: H, footage, features, replay, onFrame: (f, a) => { shas[f] = a.rgbaSha256; if (frames === "all" || frames.includes(f)) kept.set(f, Buffer.from(a.rgba)); } });
+    return { report, kept, shas, input };
+  } finally {
+    footage.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+/** 48 kHz mono 16-bit WAV with a short decaying 2 kHz click at each time (seconds). */
+function clickWav(times, seconds) {
+  const sr = 48000;
+  const data = Buffer.alloc(Math.floor(seconds * sr) * 2);
+  for (const t of times) {
+    for (let k = 0; k < 96; k++) data.writeInt16LE(Math.round(Math.sin((2 * Math.PI * 2000 * k) / sr) * Math.exp(-k / 24) * 0.9 * 32767), (Math.floor(t * sr) + k) * 2);
+  }
+  const head = Buffer.alloc(44);
+  head.write("RIFF", 0);
+  head.writeUInt32LE(36 + data.length, 4);
+  head.write("WAVEfmt ", 8);
+  head.writeUInt32LE(16, 16);
+  head.writeUInt16LE(1, 20);
+  head.writeUInt16LE(1, 22);
+  head.writeUInt32LE(sr, 24);
+  head.writeUInt32LE(sr * 2, 28);
+  head.writeUInt16LE(2, 32);
+  head.writeUInt16LE(16, 34);
+  head.write("data", 36);
+  head.writeUInt32LE(data.length, 40);
+  return Buffer.concat([head, data]);
+}
+const px = (buf, x, y, c = 0) => buf[(y * W + x) * 4 + c];
+const lumaByte = (buf, x, y) => (px(buf, x, y, 0) + px(buf, x, y, 1) + px(buf, x, y, 2)) / 3;
+
+test("the family ships four validated templates with presets, honest flash flags and a demo each", () => {
+  for (const id of IDS) {
+    const t = lib.get(id);
+    assert.ok(t, `${id} is in the library`);
+    assert.equal(t.family, "glitch");
+    assert.deepEqual(validateTemplate(t.fx, id).errors, []);
+    assert.ok(Object.keys(t.fx.X_AGENTVFX.presets).length >= 3);
+    assert.ok(["none", "possible", "strobe"].includes(t.fx.X_AGENTVFX.flash));
+    if (t.fx.X_AGENTVFX.flash === "strobe") assert.ok(t.fx.X_AGENTVFX.safeSubstitute, `${id} strobes, so it needs a safeSubstitute`);
+    const demos = readdirSync(t.dir).filter((f) => /^demo-.*\.json$/u.test(f));
+    assert.ok(demos.length >= 1, `${id} has a demo`);
+    for (const d of demos) {
+      const s = JSON.parse(readFileSync(path.join(t.dir, d), "utf8"));
+      const v = validateScore(s, lib);
+      assert.equal(v.ok, true, `${id}/${d}: ${JSON.stringify(v.errors)}`);
+      assert.ok(existsSync(path.join(ROOT, s.input.video)), `${id}/${d}: footage exists`);
+      assert.equal(s.durationSec, 4);
+    }
+  }
+});
+
+for (const id of IDS) {
+  test(`${id}: renders every frame, passes the determinism replay and carries a flash report`, async () => {
+    const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+    try {
+      const clip = makeClip(tmp, `testsrc2=size=${W}x${H}:rate=30`);
+      const out = path.join(tmp, "out");
+      const gate = await runJob(score(id, clip), lib, { outDir: out, width: W, height: H, replay: true });
+      assert.equal(gate.render.frames, 90);
+      assert.equal(gate.determinism.pass, true);
+      assert.equal(typeof gate.flash.flashesPerSecondMax, "number");
+      assert.equal(typeof gate.flash.exceeds, "boolean");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+}
+
+test("pixel-sort: spans of a luma-threshold window come out monotonic; short spans are exactly sorted", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    // Noise 60..200 with bright walls (255): 30-wide spans left of x=150, one long span 150..299.
+    const clip = makeClip(tmp, "color=c=gray:size=320x180:rate=30,format=yuv420p,geq=lum='if(gte(X,300),255,if(lt(X,150),if(lt(mod(X,36),30),60+140*random(1),255),60+140*random(1)))':cb=128:cr=128,trim=end_frame=1,loop=loop=-1:size=1");
+    const sc = score("pixel-sort", clip, { cellSize: 1, threshLo: 0.15, threshHi: 0.9, rowVar: 0, rowsFrac: 1, sweep: 0, cutJitter: 0, softness: 0, saturation: 1, punch: 1, stutterHz: 1 });
+    const { kept, input } = await render(sc, { frames: [0, 40] });
+    const lo = 0.15 * 255;
+    const hi = 0.9 * 255;
+    let rows = 0;
+    let moved = 0;
+    let total = 0;
+    for (const f of [0, 40]) {
+      const out = kept.get(f);
+      for (let y = 0; y < H; y++) {
+        const lum = Array.from({ length: W }, (_, x) => lumaByte(input, x, y));
+        if (lum.some((v) => Math.abs(v - lo) <= 4 || Math.abs(v - hi) <= 4)) continue;
+        rows += 1;
+        const mask = lum.map((v) => v >= lo && v <= hi);
+        for (let x = 0; x < W; ) {
+          if (!mask[x]) {
+            assert.ok(Math.abs(px(out, x, y) - lum[x]) <= 4, `walls are untouched at ${x},${y}`);
+            x += 1;
+            continue;
+          }
+          let e = x;
+          while (e + 1 < W && mask[e + 1] && (e + 1) % 256 !== 0) e += 1;
+          const span = lum.slice(x, e + 1);
+          const got = span.map((_, k) => px(out, x + k, y));
+          for (let k = 1; k < got.length; k++) assert.ok(got[k] >= got[k - 1] - 3, `monotonic in span ${x}..${e} row ${y}: ${got[k - 1]} then ${got[k]}`);
+          if (span.length <= 32) {
+            const sorted = [...span].sort((a, b) => a - b);
+            sorted.forEach((v, k) => assert.ok(Math.abs(v - got[k]) <= 4, `short span ${x}..${e} row ${y} is the exact sorted multiset`));
+          }
+          span.forEach((v, k) => { total += 1; if (Math.abs(v - got[k]) > 8) moved += 1; });
+          x = e + 1;
+        }
+      }
+    }
+    assert.ok(rows >= 200, `tested ${rows} rows`);
+    assert.ok(moved / total > 0.5, `sorting moved ${(100 * moved / total).toFixed(0)}% of span pixels`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("pixel-sort: vertical axis with descend sorts columns brightest first", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    const clip = makeClip(tmp, "color=c=gray:size=320x180:rate=30,format=yuv420p,geq=lum='60+140*random(1)':cb=128:cr=128,trim=end_frame=1,loop=loop=-1:size=1");
+    const sc = score("pixel-sort", clip, { sortAxis: 1, descend: true, cellSize: 1, threshLo: 0.1, threshHi: 0.95, rowVar: 0, rowsFrac: 1, sweep: 0, cutJitter: 0, softness: 0, saturation: 1, punch: 1 });
+    const { kept } = await render(sc);
+    const out = kept.get(0);
+    for (let x = 0; x < W; x += 7) for (let y = 1; y < H; y++) assert.ok(px(out, x, y) <= px(out, x, y - 1) + 3, `column ${x} descends at row ${y}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("block-glitch: same seed renders byte-identical frames twice; each burst gets its own pattern", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    const clip = makeClip(tmp, STILL);
+    const sc = score("block-glitch", clip, { burstProb: 1, burstRate: 2.5, burstFrames: 8, holdFrames: 2, grain: 0 });
+    const a = await render(sc, { frames: "all" });
+    const b = await render(sc, { frames: "all" });
+    assert.deepEqual(a.shas, b.shas, "two renders with one seed are byte-identical");
+    const other = await render(score("block-glitch", clip, { burstProb: 1, burstRate: 2.5, burstFrames: 8, holdFrames: 2, grain: 0 }, { seed: 8 }), { frames: [1, 2] });
+    // The output dither differs per frame index, so "same pattern" means a tiny mean difference, not equal bytes.
+    const diff = (x, y) => x.reduce((s, v, i) => s + Math.abs(v - y[i]), 0) / x.length;
+    assert.ok(diff(other.kept.get(1), a.kept.get(1)) > 6, "another seed gives another pattern");
+    // burst period 12 frames: bursts start at 0, 12, 24, 36 ...; the first frame of each burst differs
+    const firsts = [0, 12, 24, 36, 48].map((f) => a.kept.get(f));
+    for (let i = 0; i < firsts.length; i++) for (let j = i + 1; j < firsts.length; j++) assert.ok(diff(firsts[i], firsts[j]) > 6, `burst ${i} and ${j} differ (the seed advances per burst)`);
+    assert.ok(diff(a.kept.get(0), a.kept.get(2)) > 6, "the pattern re-seeds inside a burst (holdFrames)");
+    assert.ok(diff(a.kept.get(0), a.kept.get(1)) < 2, "and is held between re-seeds");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("block-glitch: lockMode onset starts a burst on every detected onset and stays clean between them", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    const clip = makeClip(tmp, STILL);
+    const music = path.join(tmp, "clicks.wav");
+    writeFileSync(music, clickWav([0.4, 1.3, 2.2], 3.2));
+    const features = await analyzeAudio(music, { fps: 30 });
+    const onsets = features.meta.onsets.filter((f) => f < 85);
+    assert.ok(onsets.length >= 2 && onsets.length <= 4, `three clicks give about three onsets (${onsets.length})`);
+    const sc = score("block-glitch", clip, { lockMode: 1, burstProb: 1, burstFrames: 7, density: 0.5, idleDensity: 0, grain: 0, fringe: 0, saturation: 1, punch: 1, joltAmt: 0 }, { input: { video: clip, audio: music } });
+    const { kept, input } = await render(sc, { frames: "all", features });
+    const changed = (f) => {
+      let n = 0;
+      for (let i = 0; i < W * H; i += 5) if (Math.abs(kept.get(f)[i * 4 + 1] - input[i * 4 + 1]) > 20) n += 1;
+      return n / (W * H / 5);
+    };
+    for (const o of onsets) assert.ok(changed(o + 1) > 0.05, `burst at onset ${o}: ${changed(o + 1).toFixed(3)}`);
+    const quiet = [...Array(85).keys()].filter((f) => f < onsets[0] || onsets.every((o) => f > o + 8 || f < o));
+    assert.ok(quiet.length > 5);
+    for (const f of quiet) assert.ok(changed(f) < 0.01, `frame ${f} between bursts stays clean: ${changed(f).toFixed(3)}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+const BAR = `color=c=black:size=${W}x${H}:rate=30,format=yuv420p,drawbox=x=158:y=0:w=4:h=${H}:color=white:t=fill,drawbox=x=58:y=0:w=4:h=${H}:color=white:t=fill,drawbox=x=258:y=0:w=4:h=${H}:color=white:t=fill`;
+const centroid = (buf, y, c, x0, x1) => {
+  let s = 0;
+  let m = 0;
+  for (let x = x0; x < x1; x++) {
+    s += x * px(buf, x, y, c);
+    m += px(buf, x, y, c);
+  }
+  return s / Math.max(m, 1);
+};
+const calm = { burstProb: 0, jitter: 0, tear: 0, scanlines: 0, grain: 0, punch: 1, saturation: 1, splitAmount: 120, splitTaps: 3 };
+
+test("rgb-split: red and blue copies of a white bar sit splitAmount apart; radial mode splits outward", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    const clip = makeClip(tmp, BAR);
+    const axis = (await render(score("rgb-split", clip, calm))).kept.get(0);
+    const sep = centroid(axis, 90, 0, 120, 200) - centroid(axis, 90, 2, 120, 200);
+    assert.ok(Math.abs(Math.abs(sep) - 40) < 6, `axis split ${sep.toFixed(1)} px (expected 40)`);
+    const rad = (await render(score("rgb-split", clip, { ...calm, splitMode: 1 }))).kept.get(0);
+    const left = centroid(rad, 90, 0, 20, 100) - centroid(rad, 90, 2, 20, 100);
+    const right = centroid(rad, 90, 0, 220, 300) - centroid(rad, 90, 2, 220, 300);
+    assert.ok(left * right < 0 && Math.abs(left) > 8 && Math.abs(right) > 8, `radial split flips sign across the centre (${left.toFixed(1)} / ${right.toFixed(1)})`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("vhs: chroma bleeds past a red box edge, bottom rows skew (head switching), scanlines modulate brightness", async () => {
+  const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-glitch-src-"));
+  try {
+    const clip = makeClip(tmp, `color=c=0x808080:size=${W}x${H}:rate=30,format=yuv420p,drawbox=x=100:y=20:w=60:h=100:color=red:t=fill,drawbox=x=200:y=0:w=6:h=${H}:color=white:t=fill`);
+    const base = { trackAmount: 0, wobble: 0, dropouts: 0, tapeNoise: 0, flicker: 0, chromaNoise: 0, lumaBlur: 0.05, ringing: 0, scanlines: 0, headSwitch: 0, saturation: 1 };
+    const redness = (buf, x, y) => px(buf, x, y, 0) - px(buf, x, y, 2);
+    const sharp = (await render(score("vhs", clip, { ...base, chromaBleed: 0 }))).kept.get(0);
+    const bleed = (await render(score("vhs", clip, { ...base, chromaBleed: 80 }))).kept.get(0);
+    assert.ok(redness(bleed, 164, 70) > redness(sharp, 164, 70) + 25, `chroma smears right of the box: ${redness(sharp, 164, 70)} -> ${redness(bleed, 164, 70)}`);
+    const skew = (await render(score("vhs", clip, { ...base, chromaBleed: 0, headSwitch: 1, headHeight: 0.1 }))).kept.get(0);
+    const rowsDiff = (a, b, y0, y1) => {
+      let s = 0;
+      for (let y = y0; y < y1; y++) for (let x = 0; x < W; x++) s += Math.abs(lumaByte(a, x, y) - lumaByte(b, x, y));
+      return s / ((y1 - y0) * W);
+    };
+    assert.ok(rowsDiff(skew, sharp, H - 8, H) > 20, "the bottom rows are skewed and noisy");
+    assert.ok(rowsDiff(skew, sharp, 20, 120) < 3, "and the rest of the frame is untouched");
+    const lined = (await render(score("vhs", clip, { ...base, chromaBleed: 0, scanlines: 1 }))).kept.get(0);
+    let dark = 0;
+    for (let y = 20; y < 120; y++) dark = Math.max(dark, Math.abs(lumaByte(lined, 20, y) - lumaByte(sharp, 20, y)));
+    assert.ok(dark > 25, `scanlines darken rows by up to ${dark.toFixed(0)}/255`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});