agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/templates/spectrum/waveform-line/pass0.frag

@@ -0,0 +1,48 @@
+// waveform-line pass 0: persistent `wstate`.
+//   texel (0, 0)        : clock (hit count, last hit frame, kick count, last kick frame)
+//   row 1, column x     : the smoothed waveform value for screen column x (the live line)
+//   rows 2 .. 25        : a shift register, row 1 + d holds the line as it was d frames ago
+// The live line is the 512-sample trigger-aligned waveform (audio texture row 0) low-passed with a
+// 65-tap triangular window of +-smoothWin samples, compressed with tanh(gain * w) and added to a slow
+// travelling sine pair scaled by the RMS envelope, so it keeps flowing between frames instead of
+// showing a raw 10 ms slice. The history rows give delayed copies for the multi-layer look.
+// clock texel: (hit count, last hit frame, kick count, last kick frame). A hit is an onset whose spectral
+// flux reaches hitFlux; a kick is an onset whose bass ratio reaches kickBass.
+vec4 clockStep(vec4 ev) {
+  if (AUDIO_ONSET > 0.5 && AUDIO_FLUX >= hitFlux) { ev.x += 1.0; ev.y = float(FRAMEINDEX); }
+  if (AUDIO_ONSET > 0.5 && AUDIO_BASS >= kickBass) { ev.z += 1.0; ev.w = float(FRAMEINDEX); }
+  return ev;
+}
+float liveLine(float u) {
+  float w = 0.0;
+  float wsum = 0.0;
+  for (int k = -32; k <= 32; k++) {
+    float wt = 33.0 - abs(float(k));
+    w += wt * (texture(audio, vec2(clamp(u + float(k) * smoothWin / 32.0 / 512.0, 0.0, 1.0), 0.25)).r * 2.0 - 1.0);
+    wsum += wt;
+  }
+  float v = tanh(gain * w / wsum);
+  float env = clamp(AUDIO_RMS * 2.5, 0.05, 1.0);
+  float s1 = sin(6.2832 * (u * 2.0 - TIME * 0.9));
+  float s2 = sin(6.2832 * (u * 3.3 + TIME * 0.6 + 0.3));
+  return v + flow * env * 0.5 * (s1 + 0.6 * s2);
+}
+
+void main() {
+  ivec2 px = ivec2(gl_FragCoord.xy);
+  vec4 prev = texelFetch(wstate, px, 0);
+  if (px.y == 0) {
+    fragColor = px.x == 0 ? clockStep(prev) : vec4(0.0);
+    return;
+  }
+  if (px.y == 1) {
+    float u = (float(px.x) + 0.5) / RENDERSIZE.x;
+    fragColor = vec4(liveLine(clamp((u - 0.08) / 0.84, 0.0, 1.0)), 0.0, 0.0, 1.0);
+    return;
+  }
+  if (px.y <= 25) {
+    fragColor = texelFetch(wstate, ivec2(px.x, px.y - 1), 0);
+    return;
+  }
+  fragColor = vec4(0.0);
+}

package/skills/agentvfx/templates/spectrum/waveform-line/pass1.frag

@@ -0,0 +1,86 @@
+// waveform-line pass 1: draw the 512-sample waveform (audio texture row 0, trigger aligned) into the
+// persistent `trace` buffer. trace = max(previous * echo, this frame's line): the line leaves a fading
+// echo of itself. rgb = colour * coverage, a = coverage. Display: 0 digital (LED columns filled from
+// the centre line), 1 lines (thick polyline, exact distance to the 14 nearest segments), 2 dots.
+float waveAt(float x, float x0, float span) {
+  float w = 0.0;
+  for (int k = -2; k <= 2; k++) {
+    w += texture(audio, vec2(clamp((x - x0) / span + float(k) * smoothWin / 512.0, 0.0, 1.0), 0.25)).r;
+  }
+  return amplitude * tanh(gain * (w * 0.4 - 1.0));
+}
+
+float segDist(vec2 p, vec2 a, vec2 b) {
+  vec2 pa = p - a;
+  vec2 ba = b - a;
+  return length(pa - ba * clamp(dot(pa, ba) / max(dot(ba, ba), 1.0e-6), 0.0, 1.0));
+}
+
+vec3 shade(float t, float u) {
+  vec3 c = colorMode == 1 ? paletteCycle(u + paletteShift + TIME * 0.05) : (colorMode == 2 ? paletteRamp(t) : mix(insideColor.rgb, outsideColor.rgb, t));
+  if (hueInterpolation != 0.0) {
+    vec3 h = rgb2hsv(c);
+    h.x = fract(h.x + hueInterpolation * u);
+    c = hsv2rgb(h);
+  }
+  return c;
+}
+
+void main() {
+  vec2 res = RENDERSIZE;
+  vec2 px = vUv * res;
+  float unit = res.y / 1080.0;
+  vec4 ev = texelFetch(clock, ivec2(0, 0), 0);
+  float since = ev.x > 0.5 ? (float(FRAMEINDEX) - ev.y) * TIMEDELTA : 99.0;
+  float hit = step(0.5, exp(-since / 0.1)) * hitBoost;
+  float x0 = res.x * 0.03;
+  float span = res.x * 0.94;
+  float mid = res.y * 0.5;
+  float th = max(thickness * unit * (1.0 + hit), 1.0);
+  float cov = 0.0;
+  float amp = 0.0;
+  float u = clamp((px.x - x0) / span, 0.0, 1.0);
+  for (int side = 0; side < 2; side++) {
+    float sgn = side == 0 ? 1.0 : -1.0;
+    if (side == 1 && !mirror) break;
+    if (displayMode == 1) {
+      float step1 = max(span / 512.0, 1.0);
+      float dmin = 1.0e9;
+      vec2 prevPt = vec2(px.x - 7.0 * step1, mid + sgn * waveAt(px.x - 7.0 * step1, x0, span) * res.y);
+      for (int k = -6; k <= 7; k++) {
+        float xk = px.x + float(k) * step1;
+        vec2 pt = vec2(xk, mid + sgn * waveAt(xk, x0, span) * res.y);
+        dmin = min(dmin, segDist(px, prevPt, pt));
+        prevPt = pt;
+      }
+      cov = max(cov, clamp(th * 0.5 - dmin + 0.5, 0.0, 1.0) * (px.x >= x0 && px.x <= x0 + span ? 1.0 : 0.0));
+      amp = max(amp, abs(waveAt(px.x, x0, span)) / max(amplitude, 0.001));
+    } else {
+      float cell = max(span / float(columns), 2.0);
+      float c = floor((px.x - x0) / cell);
+      float xc = x0 + (c + 0.5) * cell;
+      float w = sgn * waveAt(xc, x0, span) * res.y;
+      float dyv = px.y - mid;
+      vec2 lp = vec2(px.x - xc, dyv);
+      amp = max(amp, abs(w) / max(amplitude * res.y, 1.0));
+      if (px.x >= x0 && px.x <= x0 + span) {
+        if (displayMode == 0) {
+          float rowH = cell;
+          float rr = floor(abs(dyv) / rowH);
+          bool lit = dyv * w >= 0.0 && abs(dyv) <= abs(w) + rowH * 0.5;
+          float inCell = abs(dyv) - rr * rowH;
+          float blk = clamp(0.5 - max(abs(lp.x) - cell * (0.5 - 0.08), abs(inCell - rowH * 0.5) - rowH * 0.42), 0.0, 1.0);
+          cov = max(cov, lit ? blk : 0.0);
+        } else {
+          float rad = max(cell * 0.5 * (0.35 + 0.65 * min(abs(w) / (amplitude * res.y), 1.0)), th * 0.5);
+          cov = max(cov, clamp(rad - length(vec2(lp.x, dyv - w)) + 0.5, 0.0, 1.0));
+        }
+      }
+    }
+  }
+  vec3 line = shade(clamp(amp * amp, 0.0, 1.0) * 0.6, u);
+  line = mix(line, vec3(1.4), hit);
+  vec4 prev = texelFetch(trace, ivec2(gl_FragCoord.xy), 0);
+  vec4 cur = vec4(line * cov, cov);
+  fragColor = max(prev * echo, cur);
+}

package/skills/agentvfx/test/_render_light.mjs

@@ -0,0 +1,38 @@
+// usage: node test/_render_light.mjs [outDir]   (default ./out/ under the current directory; renders the light-family demos)
+import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = path.resolve(process.argv[2] ?? "out");
+
+const jobs = [
+  ["templates/light/bloom-glow/demo-neon-night.json", "bloom-glow-neon-night"],
+  ["templates/light/anamorphic-streak/demo-anamorphic-cinema.json", "anamorphic-streak-anamorphic-cinema"],
+  ["templates/light/god-rays/demo-golden-hour.json", "god-rays-golden-hour"],
+  ["templates/light/light-leak/demo-vintage-burn.json", "light-leak-vintage-burn"],
+  ["templates/light/neon-saber/demo-saber-laser.json", "neon-saber-saber-laser"],
+  ["templates/light/lens-flare/demo-sun-ghosts.json", "lens-flare-sun-ghosts"],
+  ["templates/light/light-sweep/demo-logo-sweep.json", "light-sweep-logo-sweep"],
+  ["templates/light/bloom-glow/demo-clip01-low.json", "bloom-glow-clip01-low"],
+  ["templates/light/light-sweep/demo-onset.json", "light-sweep-onset"],
+];
+
+let failed = 0;
+for (const [score, name] of jobs) {
+  const out = path.join(outDir, name);
+  mkdirSync(out, { recursive: true });
+  const started = Date.now();
+  console.log(`START ${out}`);
+  const r = spawnSync("node", ["scripts/vfx.mjs", "render", score, "--out", out], { stdio: "inherit", cwd: root });
+  const sec = ((Date.now() - started) / 1000).toFixed(1);
+  if (r.status !== 0) {
+    failed += 1;
+    console.log(`FAIL ${out} status=${r.status} sec=${sec}`);
+  } else {
+    console.log(`OK ${out} sec=${sec}`);
+  }
+}
+console.log(failed === 0 ? "RENDER_ALL_OK" : `RENDER_FAILED ${failed}`);
+process.exit(failed === 0 ? 0 : 1);

package/skills/agentvfx/test/audio-stereo.test.mjs

@@ -0,0 +1,45 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { analyzeAudio } from "../engine/node/audio.mjs";
+import { seedToUnit } from "../engine/web/prelude.mjs";
+
+test("waveL and waveR carry the two channels (L = 440 Hz sine, R = silence)", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-stereo-"));
+  try {
+    const wav = path.join(dir, "lr.wav");
+    const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000:duration=2", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono", "-filter_complex", "[0:a][1:a]join=inputs=2:channel_layout=stereo[a]", "-map", "[a]", "-t", "2", wav], { encoding: "utf8" });
+    assert.equal(r.status, 0, r.stderr);
+    const f = await analyzeAudio(wav, { fps: 30 });
+    const fr = f.frames[20];
+    const p2p = (a) => Math.max(...a) - Math.min(...a);
+    // ffmpeg's sine source has amplitude 1/8, so peak-to-peak is 0.25.
+    assert.ok(p2p(fr.waveL) > 0.2, `left p2p ${p2p(fr.waveL)}`);
+    assert.ok(p2p(fr.waveR) < 0.01, `right p2p ${p2p(fr.waveR)}`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("no band is dead: a 40 Hz sine lights band 1", async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-band-"));
+  try {
+    const wav = path.join(dir, "b.wav");
+    const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", "sine=frequency=40:sample_rate=48000:duration=2", "-ac", "2", wav], { encoding: "utf8" });
+    assert.equal(r.status, 0, r.stderr);
+    const f = await analyzeAudio(wav, { fps: 30 });
+    assert.ok(f.frames[30].bands[1] > 0.3, `band 1 = ${f.frames[30].bands[1]}`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("seedToUnit spreads small integer seeds", () => {
+  const v = [1, 2, 3, 7, 31].map(seedToUnit);
+  for (const x of v) assert.ok(x >= 0 && x < 1);
+  const spread = Math.max(...v) - Math.min(...v);
+  assert.ok(spread > 0.3, `spread ${spread}`);
+});

package/skills/agentvfx/test/audio.test.mjs

@@ -0,0 +1,257 @@
+// Lane audio — TDD tests for engine/node/audio.mjs
+// Task 7 acceptance criteria (plans/agentvfx-v1.md). WAV fixtures are
+// generated at runtime under os.tmpdir() and removed afterwards.
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  analyzeAudio,
+  writeFeatures,
+  summarize,
+} from '../engine/node/audio.mjs';
+
+const SR = 48000;
+const FPS = 30;
+let dir;
+let clickPath;
+let click140;
+let click174;
+let sinePath;
+let sineLoudPath;
+let noisePath;
+let leftPath;
+
+function wavBytes({ seconds, channels, fn }) {
+  const n = Math.floor(seconds * SR);
+  const data = Buffer.alloc(n * channels * 2);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const s = fn(t, i);
+    const ch = Array.isArray(s) ? s : [s, s];
+    for (let c = 0; c < channels; c++) {
+      const v = Math.max(-1, Math.min(1, ch[c] ?? 0));
+      data.writeInt16LE(Math.round(v * 32767), (i * channels + c) * 2);
+    }
+  }
+  const header = Buffer.alloc(44);
+  header.write('RIFF', 0);
+  header.writeUInt32LE(36 + data.length, 4);
+  header.write('WAVE', 8);
+  header.write('fmt ', 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20); // PCM
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(SR, 24);
+  header.writeUInt32LE(SR * channels * 2, 28);
+  header.writeUInt16LE(channels * 2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write('data', 36);
+  header.writeUInt32LE(data.length, 40);
+  return Buffer.concat([header, data]);
+}
+
+// 120 BPM click: 16 clicks at k*0.5 s, short decaying 2 kHz blip.
+function clickFn(t) {
+  const phase = t % 0.5;
+  const k = Math.floor(phase * SR);
+  if (k >= 96) return 0;
+  return Math.sin(2 * Math.PI * 2000 * phase) * Math.exp(-k / 24) * 0.9;
+}
+
+// Click train at a given BPM; returns { bytes, times } with click times in seconds.
+function clickTrack(bpm, seconds) {
+  const period = 60 / bpm;
+  const times = [];
+  for (let k = 0; ; k++) {
+    const t = k * period;
+    if (t > seconds - 0.15) break;
+    times.push(t);
+  }
+  const fn = (t) => {
+    let v = 0;
+    for (const c of times) {
+      const dt = t - c;
+      if (dt >= 0 && dt * SR < 96) {
+        const k = Math.floor(dt * SR);
+        v += Math.sin(2 * Math.PI * 2000 * dt) * Math.exp(-k / 24) * 0.9;
+      }
+    }
+    return v;
+  };
+  return { bytes: wavBytes({ seconds, channels: 2, fn }), times };
+}
+
+// Deterministic pseudo-random noise (LCG) at fixed amplitude.
+function noiseFn(amp, seed) {
+  let s = seed;
+  return () => {
+    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+    return ((s / 0x100000000) * 2 - 1) * amp;
+  };
+}
+
+before(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'lane-audio-'));
+  clickPath = join(dir, 'click-120.wav');
+  click140 = join(dir, 'click-140.wav');
+  click174 = join(dir, 'click-174.wav');
+  sinePath = join(dir, 'sine-440.wav');
+  sineLoudPath = join(dir, 'sine-440-loud.wav');
+  noisePath = join(dir, 'noise-mid.wav');
+  leftPath = join(dir, 'hard-left.wav');
+  await writeFile(clickPath, wavBytes({ seconds: 8, channels: 2, fn: clickFn }));
+  await writeFile(click140, clickTrack(140, 6).bytes);
+  await writeFile(click174, clickTrack(174, 6).bytes);
+  await writeFile(
+    sinePath,
+    wavBytes({ seconds: 8, channels: 2, fn: (t) => Math.sin(2 * Math.PI * 440 * t) * 0.5 }),
+  );
+  await writeFile(
+    sineLoudPath,
+    wavBytes({ seconds: 4, channels: 2, fn: (t) => Math.sin(2 * Math.PI * 440 * t) * 1.0 }),
+  );
+  await writeFile(noisePath, wavBytes({ seconds: 4, channels: 2, fn: noiseFn(0.8, 12345) }));
+  await writeFile(
+    leftPath,
+    wavBytes({
+      seconds: 4,
+      channels: 2,
+      fn: (t) => [Math.sin(2 * Math.PI * 440 * t) * 0.5, 0],
+    }),
+  );
+});
+
+after(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('audio features — 120 BPM click track (8 s)', () => {
+  it('detects every click as an onset within ±1 frame at 30 fps', async () => {
+    const f = await analyzeAudio(clickPath, { fps: FPS });
+    assert.equal(f.frames.length, 240);
+    const expectedClicks = Array.from({ length: 16 }, (_, k) => k * 0.5);
+    for (const c of expectedClicks) {
+      const frame = Math.round(c * FPS);
+      const hit = f.meta.onsets.some((o) => Math.abs(o - frame) <= 1);
+      assert.ok(hit, `click at ${c}s (frame ${frame}) has no onset within ±1 frame`);
+    }
+    assert.equal(f.meta.onsets.length, 16);
+  });
+
+  it('estimates bpm 120 ± 1', async () => {
+    const f = await analyzeAudio(clickPath, { fps: FPS });
+    assert.ok(Math.abs(f.meta.bpm - 120) <= 1, `bpm was ${f.meta.bpm}`);
+    const s = summarize(f);
+    assert.ok(Math.abs(s.bpm - 120) <= 1);
+    assert.equal(s.onsetCount, 16);
+    assert.equal(s.frames, 240);
+  });
+});
+
+describe('audio features — 440 Hz sine', () => {
+  it('gives the 440 Hz band the maximum mean value', async () => {
+    const f = await analyzeAudio(sinePath, { fps: FPS });
+    // log-spaced band edges, 30 Hz–16 kHz, 32 bands (mirrors implementation)
+    const edges = Array.from({ length: 33 }, (_, k) => 30 * Math.pow(16000 / 30, k / 32));
+    let want = -1;
+    for (let k = 0; k < 32; k++) {
+      if (edges[k] <= 440 && 440 < edges[k + 1]) want = k;
+    }
+    assert.notEqual(want, -1);
+    const means = Array(32).fill(0);
+    for (const fr of f.frames) fr.bands.forEach((v, k) => { means[k] += v; });
+    for (let k = 0; k < 32; k++) means[k] /= f.frames.length;
+    let best = 0;
+    for (let k = 1; k < 32; k++) if (means[k] > means[best]) best = k;
+    assert.equal(best, want, `max band was ${best}, want ${want}`);
+    assert.ok(means[want] > 0.5, `440 Hz band mean was ${means[want]}`);
+  });
+});
+
+for (const [bpm, file] of [[140, 'click140'], [174, 'click174']]) {
+  const getPath = () => (file === 'click140' ? click140 : click174);
+  describe(`audio features — ${bpm} BPM click track (6 s)`, () => {
+    it('detects every click as an onset within ±1 frame at 30 fps', async () => {
+      const f = await analyzeAudio(getPath(), { fps: FPS });
+      assert.equal(f.frames.length, 180);
+      const { times } = clickTrack(bpm, 6);
+      for (const c of times) {
+        const frame = Math.round(c * FPS);
+        const hit = f.meta.onsets.some((o) => Math.abs(o - frame) <= 1);
+        assert.ok(hit, `click at ${c}s (frame ${frame}) has no onset within ±1 frame`);
+      }
+      assert.equal(f.meta.onsets.length, times.length);
+    });
+
+    it(`estimates bpm ${bpm} ± 1`, async () => {
+      const f = await analyzeAudio(getPath(), { fps: FPS });
+      assert.ok(Math.abs(f.meta.bpm - bpm) <= 1, `bpm was ${f.meta.bpm}`);
+    });
+  });
+}
+
+describe('audio features — windowing', () => {
+  it('startSec=1, durationSec=5 at 30 fps gives exactly 150 frames', async () => {
+    const f = await analyzeAudio(sinePath, { fps: FPS, startSec: 1, durationSec: 5 });
+    assert.equal(f.frames.length, 150);
+    assert.equal(f.meta.frames, 150);
+    assert.ok(Math.abs(f.frames[0].t - 0) < 1e-9, `first frame t was ${f.frames[0].t}`);
+  });
+
+  it('a 440 Hz sine yields non-flat wave on every frame after the first', async () => {
+    const f = await analyzeAudio(sineLoudPath, { fps: FPS });
+    for (let i = 1; i < f.frames.length; i++) {
+      const w = f.frames[i].wave;
+      let lo = Infinity;
+      let hi = -Infinity;
+      for (const v of w) {
+        if (v < lo) lo = v;
+        if (v > hi) hi = v;
+      }
+      assert.ok(hi - lo > 1.5, `frame ${i} wave peak-to-peak was ${hi - lo}`);
+    }
+  });
+
+  it('a track starting mid-loud-noise has no onset at frame 0', async () => {
+    const f = await analyzeAudio(noisePath, { fps: FPS });
+    assert.ok(!f.meta.onsets.includes(0), `onsets were ${f.meta.onsets.slice(0, 8)}`);
+  });
+
+  it('RMS of a full-scale sine is within 0.5 dB of -3.01 dBFS', async () => {
+    const f = await analyzeAudio(sineLoudPath, { fps: FPS });
+    const mean = f.frames.reduce((a, fr) => a + fr.rmsDb, 0) / f.frames.length;
+    assert.ok(Math.abs(mean - -3.01) <= 0.5, `mean rmsDb was ${mean}`);
+  });
+});
+
+describe('audio features — hard-left signal', () => {
+  it('reports mean balance < -0.9', async () => {
+    const f = await analyzeAudio(leftPath, { fps: FPS });
+    const mean = f.frames.reduce((a, fr) => a + fr.balance, 0) / f.frames.length;
+    assert.ok(mean < -0.9, `mean balance was ${mean}`);
+  });
+});
+
+describe('audio features — determinism and errors', () => {
+  it('writes byte-identical JSON for identical input twice', async () => {
+    const a = await analyzeAudio(sinePath, { fps: FPS });
+    const b = await analyzeAudio(sinePath, { fps: FPS });
+    const p1 = join(dir, 'a.json');
+    const p2 = join(dir, 'b.json');
+    await writeFeatures(a, p1);
+    await writeFeatures(b, p2);
+    const [b1, b2] = await Promise.all([readFile(p1), readFile(p2)]);
+    assert.ok(b1.equals(b2), 'writeFeatures output differed between runs');
+  });
+
+  it('rejects with an error naming the path when the file is missing', async () => {
+    const missing = join(dir, 'does-not-exist.wav');
+    await assert.rejects(analyzeAudio(missing, { fps: FPS }), (err) => {
+      assert.ok(err instanceof Error);
+      assert.ok(String(err.message).includes(missing), `message was: ${err.message}`);
+      return true;
+    });
+  });
+});

package/skills/agentvfx/test/brutal.test.mjs

@@ -0,0 +1,190 @@
+// Brutal family (plan task 14, first slice): hud-deck, halftone-field, boot-log. Validation of every preset and
+// demo, 90-frame render + determinism + flash report per template, text ink, halftone dot structure,
+// window shapes, audio-following panels and the beat flare.
+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 { runJob } from "../engine/node/job.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 IDS = ["hud-deck", "halftone-field", "boot-log"];
+const tmp = mkdtempSync(path.join(tmpdir(), "agentvfx-brutal-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+let runs = 0;
+
+const score = (template, preset, extra = {}) => {
+  const v = validateScore({ version: 1, template, ...(preset ? { preset } : {}), durationSec: 3, seed: 7, out: "t", ...extra }, lib);
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  return v.value;
+};
+
+/** Render a score at w x h and keep the RGBA of the wanted frames (audio features from `audio` when given). */
+async function frames(s, keep, [w, h] = [640, 360], audio = null) {
+  const features = audio ? await analyzeAudio(path.resolve(ROOT, audio), { fps: 30 }) : null;
+  const kept = new Map();
+  await renderScore(s, lib, { outDir: path.join(tmp, `r-${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 };
+}
+/** Pixels in the (fractional) region whose channel `ch` is above `min`. */
+function count(rgba, [w, h], [x0, y0, x1, y1], ch, min) {
+  let n = 0;
+  for (let y = Math.round(y0 * h); y < Math.round(y1 * h); y++) for (let x = Math.round(x0 * w); x < Math.round(x1 * w); x++) if (rgba[(y * w + x) * 4 + ch] > min) n += 1;
+  return n;
+}
+const px = (rgba, w, x, y) => { const o = (y * w + x) * 4; return [rgba[o], rgba[o + 1], rgba[o + 2]]; };
+
+test("every preset of every brutal template validates, with at least three presets, a flash class and demos", () => {
+  for (const id of IDS) {
+    const tpl = lib.get(id);
+    assert.ok(tpl, `${id} is in the library`);
+    assert.equal(tpl.family, "brutal");
+    assert.ok(Object.keys(tpl.fx.X_AGENTVFX.presets).length >= 3, `${id} has at least 3 presets`);
+    assert.ok(["none", "possible", "strobe"].includes(tpl.fx.X_AGENTVFX.flash));
+    for (const preset of Object.keys(tpl.fx.X_AGENTVFX.presets)) score(id, preset, tpl.fx.X_AGENTVFX.input === "footage" ? { input: { video: "test-media/clip-01.mp4" } } : {});
+    const demos = readdirSync(tpl.dir).filter((f) => f.startsWith("demo-"));
+    assert.ok(demos.length >= 3, `${id} has demo scores`);
+    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);
+      if (demo.input?.video) assert.ok(existsSync(path.join(ROOT, demo.input.video)));
+      assert.equal(demo.input.audio, MUSIC);
+    }
+  }
+});
+
+for (const id of IDS) {
+  test(`${id}: demo renders every frame, passes determinism, reports flashes, muxes audio`, async () => {
+    const tpl = lib.get(id);
+    const demo = JSON.parse(readFileSync(path.join(tpl.dir, readdirSync(tpl.dir).filter((f) => f.startsWith("demo-")).sort()[0]), "utf8"));
+    const s = validateScore({ ...demo, durationSec: 3, out: "t" }, lib).value;
+    const gate = await runJob(s, lib, { outDir: path.join(tmp, `job-${id}`), width: 320, height: 180, cwd: ROOT });
+    assert.equal(gate.render.frames, 90);
+    assert.equal(gate.determinism.pass, true, JSON.stringify(gate.determinism));
+    assert.equal(typeof gate.flash.exceeds, "boolean");
+    assert.equal(typeof gate.flash.flashesPerSecondMax, "number");
+  });
+}
+
+test("hud-deck: label text draws ink in the desk and the tall title, and labels override", async () => {
+  const size = [640, 360];
+  const { kept } = await frames(score("hud-deck", "night"), [75], size);
+  const f = kept.get(75);
+  assert.ok(count(f, size, [0.012, 0.745, 0.2, 0.82], 0, 160) > 250, "artist label in the desk");
+  assert.ok(count(f, size, [0.012, 0.84, 0.2, 0.915], 0, 160) > 250, "track label in the desk");
+  assert.ok(count(f, size, [0.7, 0.88, 0.99, 0.975], 0, 160) > 200, "tall title bottom right");
+  const wide = await frames(score("hud-deck", "night", { labels: { title: "WWWWWWWWWW" } }), [75], size);
+  assert.ok(count(wide.kept.get(75), size, [0.4, 0.88, 0.99, 0.975], 0, 160) > count(f, size, [0.4, 0.88, 0.99, 0.975], 0, 160), "longer title -> more ink");
+});
+
+test("hud-deck: spectrum graph and waveform follow the music and sit at the floor in silence", async () => {
+  const size = [960, 540];
+  const music = await frames(score("hud-deck", "night", { input: { audio: MUSIC } }), [60], size, MUSIC);
+  const quiet = await frames(score("hud-deck", "night"), [60], size);
+  const above = [0.3, 0.75, 0.68, 0.9];
+  const loud = count(music.kept.get(60), size, above, 0, 200);
+  assert.ok(loud > 30, `spectrum line above the floor with music: ${loud}`);
+  assert.ok(count(quiet.kept.get(60), size, above, 0, 200) < 8, "silent spectrum stays on the floor");
+  const waveBox = [0.02, 0.915, 0.26, 0.96];
+  assert.ok(count(music.kept.get(60), size, waveBox, 0, 150) > count(quiet.kept.get(60), size, waveBox, 0, 150) + 40, "waveform strip draws the wave");
+});
+
+test("hud-deck: the window is a chamfered octagon in the octagon preset, a rect otherwise", async () => {
+  const size = [640, 360];
+  const solid = { params: { mediaMode: 3, winBg: [1, 1, 1, 1], tone: [1, 1, 1, 1], flare: 0, tearAmount: 0 } };
+  const oct = await frames(score("hud-deck", "octagon", solid), [70], size);
+  const rect = await frames(score("hud-deck", "octagon", { params: { ...solid.params, winShape: 0 } }), [70], size);
+  const corner = [Math.round((0.55 - 0.29) * 640) + 6, Math.round((0.47 - 0.35) * 360) + 6];
+  const centre = [320, 190];
+  assert.ok(px(oct.kept.get(70), 640, ...corner)[0] < 40, "octagon corner is ground");
+  assert.ok(px(rect.kept.get(70), 640, ...corner)[0] > 200, "rect corner is the window");
+  assert.ok(px(oct.kept.get(70), 640, ...centre)[0] > 200, "octagon centre is the window");
+});
+
+test("hud-deck: the white-hot light bar breathes with the beat", async () => {
+  const size = [640, 360];
+  const base = await frames(score("hud-deck", "night", { input: { audio: MUSIC } }), Array.from({ length: 80 }, (_, i) => i), size, MUSIC);
+  const off = await frames(score("hud-deck", "night", { input: { audio: MUSIC }, params: { flare: 0 } }), Array.from({ length: 80 }, (_, i) => i), size, MUSIC);
+  const beat = base.features.meta.beats.find((b) => b >= 20 && b < 65);
+  assert.ok(beat !== undefined, "a beat inside the window");
+  const band = [0.3542 - 0.2, 0.3657 - 0.05, 0.3542 + 0.2, 0.3657 + 0.05];
+  const light = (f) => { let s = 0; const a = base.kept.get(f); const b = off.kept.get(f); for (let y = Math.round(band[1] * 360); y < Math.round(band[3] * 360); y++) for (let x = Math.round(band[0] * 640); x < Math.round(band[2] * 640); x++) s += Math.max(0, a[(y * 640 + x) * 4 + 1] - b[(y * 640 + x) * 4 + 1]); return s; };
+  assert.ok(light(beat + 1) > 1000, `flare adds light on the beat: ${light(beat + 1)}`);
+  assert.ok(light(beat + 1) > light(Math.min(beat + 10, 79)) * 1.1, "brighter on the beat than between beats");
+});
+
+test("halftone-field: single-tone dot lattice at the set pitch, binary dither and glyph screens stay on two colours", async () => {
+  const size = [960, 540];
+  const params = { cell: 24, dotAngle: 0, tearAmount: 0, kickGain: 0, textKnock: 0 };
+  const field = [20, 20, 255];
+  const dot = [203, 189, 255];
+  const region = [0.36, 0.56, 0.64, 0.9];
+  const lin = (v) => (v / 255 <= 0.04045 ? v / 255 / 12.92 : ((v / 255 + 0.055) / 1.055) ** 2.4);
+  const srgb = (c) => 255 * (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+  const twoTone = (rgba, lim) => {
+    let on = 0;
+    let all = 0;
+    for (let y = Math.round(region[1] * 540); y < Math.round(region[3] * 540); y++) {
+      for (let x = Math.round(region[0] * 960); x < Math.round(region[2] * 960); x++) {
+        const p = px(rgba, 960, x, y);
+        const t = Math.min(1, Math.max(0, (lin(p[0]) - lin(field[0])) / (lin(dot[0]) - lin(field[0]))));
+        const err = Math.max(...p.map((v, i) => Math.abs(v - srgb(lin(field[i]) + (lin(dot[i]) - lin(field[i])) * t))));
+        all += 1;
+        if (err <= lim) on += 1;
+      }
+    }
+    return on / all;
+  };
+  const a = await frames(score("halftone-field", "ultramarine", { params }), [40], size);
+  const f = a.kept.get(40);
+  assert.ok(twoTone(f, 12) > 0.99, `dot screen is one tone: ${twoTone(f, 12)}`);
+  const prof = [];
+  for (let x = Math.round(region[0] * 960); x < Math.round(region[2] * 960); x++) { let s = 0; for (let y = Math.round(region[1] * 540); y < Math.round(region[3] * 540); y++) s += px(f, 960, x, y)[0]; prof.push(s); }
+  const mean = prof.map((_, i) => { let s = 0; let n = 0; for (let k = Math.max(0, i - 12); k <= Math.min(prof.length - 1, i + 12); k++) { s += prof[k]; n += 1; } return s / n; });
+  const z = prof.map((v, i) => v - mean[i]);
+  const ac = (lag) => { let s = 0; for (let i = 0; i + lag < z.length; i++) s += z[i] * z[i + lag]; return s; };
+  assert.ok(ac(12) > 0.3 * ac(0), `pitch 24 design px = 12 px at 960x540: lag-12 autocorrelation ${(ac(12) / ac(0)).toFixed(2)}`);
+  assert.ok(ac(12) > ac(6) + 0.4 * ac(0), "half-pitch lag is anti-phase");
+  const lo = Math.min(...prof);
+  const hi = Math.max(...prof);
+  assert.ok(hi > lo * 1.01, "dot area varies with the image tone");
+  const dither = await frames(score("halftone-field", "dither", { params: { tearAmount: 0, kickGain: 0, textKnock: 0 } }), [40], size);
+  assert.ok(twoTone(dither.kept.get(40), 6) > 0.995, `ordered dither is binary: ${twoTone(dither.kept.get(40), 6)}`);
+});
+
+test("halftone-field: pink and cyan micro bars hang on the image edges and the tall headline draws ink", async () => {
+  const size = [640, 360];
+  const { kept } = await frames(score("halftone-field", "ultramarine", { input: { audio: MUSIC } }), [60], size, MUSIC);
+  const f = kept.get(60);
+  const pink = count(f, size, [0.03, 0.15, 0.1, 0.95], 0, 230);
+  assert.ok(pink > 40, `edge bars on the left edge: ${pink}`);
+  assert.ok(count(f, size, [0.04, 0.1, 0.45, 0.5], 0, 215) > 200, "headline ink");
+});
+
+test("boot-log: the log types out, the headline decodes only after the log, then holds still", async () => {
+  const size = [640, 360];
+  const quiet = { params: { flickerAmount: 0, scanAmount: 0, tearAmount: 0, streakAmount: 0, dustAmount: 0 } };
+  const { kept } = await frames(score("boot-log", "phosphor", { ...quiet, durationSec: 4 }), [8, 40, 85, 112, 119], size);
+  const logBox = [0.03, 0.24, 0.45, 0.62];
+  const headBox = [0.03, 0.68, 0.45, 0.84];
+  const lit = (f, box) => count(kept.get(f), size, box, 1, 140);
+  assert.ok(lit(8, logBox) < lit(40, logBox), "log grows while typing");
+  assert.ok(lit(40, logBox) < lit(85, logBox), "log keeps typing");
+  assert.ok(lit(40, headBox) < 12, "headline hidden before the decode");
+  assert.ok(lit(112, headBox) > 120, "headline drawn after the decode");
+  let diff = 0;
+  const a = kept.get(112);
+  const b = kept.get(119);
+  for (let y = Math.round(headBox[1] * 360); y < Math.round(headBox[3] * 360); y++) for (let x = Math.round(headBox[0] * 640); x < Math.round(headBox[2] * 640); x++) diff += Math.abs(a[(y * 640 + x) * 4 + 1] - b[(y * 640 + x) * 4 + 1]);
+  assert.ok(diff / ((headBox[2] - headBox[0]) * 640 * (headBox[3] - headBox[1]) * 360) < 2.5, "decoded headline is stable");
+});