agentvfx 0.0.0-stage → 0.3.5

package/skills/agentvfx/engine/web/render.mjs

@@ -0,0 +1,388 @@
+// agentvfx (Apache-2.0, see LICENSE). The render page: WebGL2 multipass renderer for template layers with
+// persistent RGBA16F buffers. The host (engine/node/render.mjs) calls window.__litPrepare once, then
+// window.__litStep(f, plan) for every frame in order, and captures the canvas after each step.
+// No requestAnimationFrame, no wall clock: time comes only from the plan.
+import { VERT, buildFragment, OUTPUT_FRAG } from "./prelude.mjs";
+import { drawTextLayer, warmFonts } from "./text.mjs";
+
+const TEXT_UNIT = 14;
+
+const canvas = document.getElementById("c");
+let gl = null;
+let W = 0;
+let H = 0;
+let fps = 30;
+let seed01 = 0;
+let palette = [];
+let probeNondeterminism = false;
+const programs = new Map(); // `${template}#${pass}` -> { prog, uniforms }
+const templates = new Map(); // id -> { inputs, passes: [{ target, persistent }] }
+const instances = new Map(); // layer key -> { targets: Map, out: { tex, fbo } }
+let vao = null;
+let outputProgram = null;
+let blackTex = null;
+let creditProgram = null;
+let creditTex = null;
+let footageTex = null;
+let hasFootage = false;
+let audioTex = null;
+let fftTex = null;
+
+function compile(type, src, label) {
+  const sh = gl.createShader(type);
+  gl.shaderSource(sh, src);
+  gl.compileShader(sh);
+  if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) throw new Error(`shader compile failed (${label}): ${gl.getShaderInfoLog(sh)}`);
+  return sh;
+}
+
+function link(fragSrc, label) {
+  const prog = gl.createProgram();
+  gl.attachShader(prog, compile(gl.VERTEX_SHADER, VERT, `${label} vert`));
+  gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fragSrc, label));
+  gl.linkProgram(prog);
+  if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) throw new Error(`program link failed (${label}): ${gl.getProgramInfoLog(prog)}`);
+  const uniforms = new Map();
+  const n = gl.getProgramParameter(prog, gl.ACTIVE_UNIFORMS);
+  for (let i = 0; i < n; i++) {
+    const info = gl.getActiveUniform(prog, i);
+    const name = info.name.replace(/\[0\]$/u, "");
+    uniforms.set(name, gl.getUniformLocation(prog, info.name));
+  }
+  return { prog, uniforms };
+}
+
+function floatTexture(w, h, data = null) {
+  const tex = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, w, h, 0, gl.RGBA, gl.FLOAT, data);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return tex;
+}
+
+function target(w, h) {
+  const tex = floatTexture(w, h);
+  const fbo = gl.createFramebuffer();
+  gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+  const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+  if (status !== gl.FRAMEBUFFER_COMPLETE) throw new Error(`RGBA16F framebuffer incomplete (0x${status.toString(16)})`);
+  gl.viewport(0, 0, w, h);
+  gl.clearColor(0, 0, 0, 0);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+  return { tex, fbo };
+}
+
+function dropTarget(t) {
+  gl.deleteTexture(t.tex);
+  gl.deleteFramebuffer(t.fbo);
+}
+
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+async function fetchText(url) {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`could not load ${url} (${r.status})`);
+  return r.text();
+}
+
+async function prepare(opts) {
+  W = opts.width;
+  H = opts.height;
+  fps = opts.fps;
+  seed01 = opts.seed01;
+  palette = opts.palette ?? [];
+  probeNondeterminism = Boolean(opts.probeNondeterminism);
+  canvas.width = W;
+  canvas.height = H;
+  canvas.style.width = `${W}px`;
+  canvas.style.height = `${H}px`;
+  gl = canvas.getContext("webgl2", { alpha: false, antialias: false, depth: false, stencil: false, preserveDrawingBuffer: true, premultipliedAlpha: false, powerPreference: "high-performance" });
+  if (!gl) throw new Error("BLOCKED_NO_WEBGL2: no WebGL2 context");
+  if (!gl.getExtension("EXT_color_buffer_float")) throw new Error("BLOCKED_NO_WEBGL2: EXT_color_buffer_float missing");
+  gl.getExtension("OES_texture_float_linear");
+  vao = gl.createVertexArray();
+  outputProgram = link(OUTPUT_FRAG, "output");
+  blackTex = floatTexture(1, 1, new Float32Array([0, 0, 0, 1]));
+  if (opts.credit) {
+    creditProgram = link(CREDIT_FRAG, "credit");
+    creditTex = creditTexture(opts.credit);
+  }
+  audioTex = floatTexture(512, 2, new Float32Array(512 * 2 * 4).fill(0.5));
+  fftTex = floatTexture(512, 1, new Float32Array(512 * 4));
+  for (const [id, t] of Object.entries(opts.templates)) {
+    const passes = t.passes;
+    const targets = passes.map((p) => p.target).filter(Boolean);
+    templates.set(id, { inputs: t.inputs, passes, text: t.text ?? null });
+    if (t.text) await warmFonts(t.text, H);
+    for (let i = 0; i < passes.length; i++) {
+      const body = await fetchText(`/lit/templates/${t.rel}/${passes[i].file}`);
+      programs.set(`${id}#${i}`, link(buildFragment({ inputs: t.inputs, targets, body }), `${id} ${passes[i].file}`));
+    }
+  }
+  const dbg = gl.getExtension("WEBGL_debug_renderer_info");
+  return { ok: true, renderer: dbg ? String(gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL)) : "unknown" };
+}
+
+function instanceFor(key, templateId) {
+  let inst = instances.get(key);
+  if (!inst) {
+    const tpl = templates.get(templateId);
+    const targets = new Map();
+    for (const p of tpl.passes) {
+      if (p.target && !targets.has(p.target)) targets.set(p.target, { pair: [target(W, H), target(W, H)], read: 0, persistent: Boolean(p.persistent) });
+    }
+    inst = { targets, out: target(W, H), text: null };
+    if (tpl.text) {
+      const c = document.createElement("canvas");
+      c.width = W;
+      c.height = H;
+      const tex = gl.createTexture();
+      gl.bindTexture(gl.TEXTURE_2D, tex);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, W, H, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      inst.text = { canvas: c, ctx: c.getContext("2d", { willReadFrequently: false }), tex };
+    }
+    instances.set(key, inst);
+  }
+  return inst;
+}
+
+function setParam(u, input, value) {
+  const loc = u.get(input.NAME);
+  if (loc === undefined || loc === null) return;
+  switch (input.TYPE) {
+    case "float": gl.uniform1f(loc, value); break;
+    case "long": gl.uniform1i(loc, value | 0); break;
+    case "bool": gl.uniform1i(loc, value ? 1 : 0); break;
+    case "color": gl.uniform4f(loc, srgbToLinear(value[0]), srgbToLinear(value[1]), srgbToLinear(value[2]), value[3]); break;
+    case "point2D": gl.uniform2f(loc, value[0], value[1]); break;
+    default: break;
+  }
+}
+
+function setCommon(u, { t, frame, passIndex, input, hasInput, audio }) {
+  const set1f = (n, v) => { const l = u.get(n); if (l) gl.uniform1f(l, v); };
+  const set1i = (n, v) => { const l = u.get(n); if (l) gl.uniform1i(l, v); };
+  set1f("TIME", t);
+  set1f("TIMEDELTA", 1 / fps);
+  set1i("FRAMEINDEX", frame);
+  set1i("PASSINDEX", passIndex);
+  if (u.get("RENDERSIZE")) gl.uniform2f(u.get("RENDERSIZE"), W, H);
+  set1f("SEED", probeNondeterminism ? crypto.getRandomValues(new Uint32Array(1))[0] / 4294967296 : seed01);
+  set1i("HAS_INPUT", hasInput ? 1 : 0);
+  if (u.get("PALETTE")) {
+    const flat = new Float32Array(24);
+    palette.slice(0, 8).forEach((c, i) => flat.set(c, i * 3));
+    gl.uniform3fv(u.get("PALETTE"), flat);
+  }
+  set1i("PALETTE_COUNT", Math.min(8, palette.length));
+  const a = audio ?? {};
+  const scal = { AUDIO_RMS: "rms", AUDIO_PEAK: "peak", AUDIO_BASS: "bass", AUDIO_MID: "mid", AUDIO_TREB: "treb", AUDIO_BASS_ATT: "bass_att", AUDIO_MID_ATT: "mid_att", AUDIO_TREB_ATT: "treb_att", AUDIO_FLUX: "flux", AUDIO_ONSET: "onset", AUDIO_BEAT: "beat", AUDIO_BEATPHASE: "beatPhase", AUDIO_BPM: "bpm" };
+  for (const [name, key] of Object.entries(scal)) set1f(name, Number(a[key] ?? 0));
+  if (u.get("AUDIO_BANDS")) gl.uniform1fv(u.get("AUDIO_BANDS"), new Float32Array(Array.from({ length: 32 }, (_, i) => Number(a.bands?.[i] ?? 0))));
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(gl.TEXTURE_2D, input);
+  set1i("inputImage", 0);
+  gl.activeTexture(gl.TEXTURE1);
+  gl.bindTexture(gl.TEXTURE_2D, audioTex);
+  set1i("audio", 1);
+  gl.activeTexture(gl.TEXTURE2);
+  gl.bindTexture(gl.TEXTURE_2D, fftTex);
+  set1i("audioFFT", 2);
+}
+
+function uploadAudio(audio) {
+  if (!audio) return;
+  if (audio.wave) {
+    const d = new Float32Array(512 * 2 * 4);
+    for (let row = 0; row < 2; row++) {
+      const src = row === 0 ? (audio.waveL ?? audio.wave) : (audio.waveR ?? audio.wave);
+      for (let i = 0; i < 512; i++) {
+        const v = 0.5 + 0.5 * Number(src[i] ?? 0);
+        d.set([v, v, v, 1], (row * 512 + i) * 4);
+      }
+    }
+    gl.bindTexture(gl.TEXTURE_2D, audioTex);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, 512, 2, gl.RGBA, gl.FLOAT, d);
+  }
+  if (audio.spec) {
+    const d = new Float32Array(512 * 4);
+    for (let i = 0; i < 512; i++) {
+      const v = Number(audio.spec[i] ?? 0);
+      d.set([v, v, v, 1], i * 4);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, fftTex);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, 512, 1, gl.RGBA, gl.FLOAT, d);
+  }
+}
+
+function renderLayer(layer, inputTex, hasInput, audio) {
+  const tpl = templates.get(layer.template);
+  if (!tpl) throw new Error(`template not prepared: ${layer.template}`);
+  const inst = instanceFor(layer.key, layer.template);
+  const written = new Set();
+  const frame = Math.round(layer.t * fps);
+  if (inst.text) {
+    const set = Number(layer.params?.textSet ?? 0);
+    const items = tpl.text.some((s) => s.set) ? tpl.text.filter((s) => (s.set ?? 0) === set) : tpl.text;
+    const specs = layer.textStyle ? items.map((s) => ({ ...s, ...layer.textStyle[s.key] })) : items;
+    drawTextLayer(inst.text.ctx, W, H, specs, layer.labels, layer.t, frame, Math.floor(seed01 * 4294967296));
+    gl.bindTexture(gl.TEXTURE_2D, inst.text.tex);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, inst.text.canvas);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+  }
+  for (let i = 0; i < tpl.passes.length; i++) {
+    const pass = tpl.passes[i];
+    const { prog, uniforms } = programs.get(`${layer.template}#${i}`);
+    const last = i === tpl.passes.length - 1;
+    let dest;
+    if (last) dest = inst.out;
+    else {
+      if (!pass.target) throw new Error(`${layer.template}: pass ${i} has no TARGET`);
+      const tg = inst.targets.get(pass.target);
+      dest = tg.pair[1 - tg.read];
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, dest.fbo);
+    gl.viewport(0, 0, W, H);
+    gl.useProgram(prog);
+    setCommon(uniforms, { t: layer.t, frame, passIndex: i, input: inputTex, hasInput, audio });
+    let unit = 3;
+    for (const [name, tg] of inst.targets) {
+      const loc = uniforms.get(name);
+      if (!loc) continue;
+      const tex = written.has(name) ? tg.pair[1 - tg.read].tex : tg.pair[tg.read].tex;
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, tex);
+      gl.uniform1i(loc, unit);
+      unit += 1;
+    }
+    gl.activeTexture(gl.TEXTURE0 + TEXT_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, inst.text ? inst.text.tex : blackTex);
+    if (uniforms.get("TEXTMASK")) gl.uniform1i(uniforms.get("TEXTMASK"), TEXT_UNIT);
+    if (uniforms.get("HAS_TEXT")) gl.uniform1i(uniforms.get("HAS_TEXT"), inst.text ? 1 : 0);
+    for (const input of tpl.inputs) if (layer.params[input.NAME] !== undefined) setParam(uniforms, input, layer.params[input.NAME]);
+    gl.bindVertexArray(vao);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    if (!last) written.add(pass.target);
+  }
+  for (const name of written) {
+    const tg = inst.targets.get(name);
+    tg.read = 1 - tg.read;
+  }
+  return inst.out.tex;
+}
+
+function step(f, plan) {
+  uploadAudio(plan.audio);
+  const active = new Set(plan.layers.map((l) => l.key));
+  for (const [key, inst] of instances) {
+    if (active.has(key)) continue;
+    for (const tg of inst.targets.values()) tg.pair.forEach(dropTarget);
+    dropTarget(inst.out);
+    if (inst.text) gl.deleteTexture(inst.text.tex);
+    instances.delete(key);
+  }
+  let tex = plan.footage && hasFootage ? footageTex : blackTex;
+  let hasInput = Boolean(plan.footage && hasFootage);
+  for (const layer of plan.layers) {
+    tex = renderLayer(layer, tex, hasInput, plan.audio);
+    hasInput = true;
+  }
+  gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  gl.viewport(0, 0, W, H);
+  gl.useProgram(outputProgram.prog);
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.uniform1i(outputProgram.uniforms.get("src"), 0);
+  gl.uniform1i(outputProgram.uniforms.get("FRAMEINDEX"), f);
+  gl.uniform1f(outputProgram.uniforms.get("SEED"), probeNondeterminism ? crypto.getRandomValues(new Uint32Array(1))[0] / 4294967296 : seed01);
+  gl.bindVertexArray(vao);
+  gl.drawArrays(gl.TRIANGLES, 0, 3);
+  if (creditTex) {
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.useProgram(creditProgram.prog);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, creditTex);
+    gl.uniform1i(creditProgram.uniforms.get("credit"), 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.disable(gl.BLEND);
+  }
+  gl.finish();
+  const err = gl.getError();
+  if (err !== gl.NO_ERROR) throw new Error(`WebGL error 0x${err.toString(16)} on frame ${f}`);
+  return { frame: f, layers: plan.layers.length };
+}
+
+const CREDIT_FRAG = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 fragColor;
+uniform sampler2D credit;
+void main() { fragColor = texture(credit, vUv); }`;
+
+/** The credit as a frame-sized RGBA texture: small text in the bottom-right corner, white with a dark edge. */
+function creditTexture(text) {
+  const c = document.createElement("canvas");
+  c.width = W;
+  c.height = H;
+  const ctx = c.getContext("2d");
+  const px = Math.max(11, Math.round(H * 0.022));
+  ctx.font = `600 ${px}px "Helvetica Neue", Helvetica, Arial, sans-serif`;
+  ctx.textAlign = "right";
+  ctx.textBaseline = "alphabetic";
+  const x = W - Math.round(px * 1.1);
+  const y = H - Math.round(px * 0.9);
+  ctx.lineJoin = "round";
+  ctx.lineWidth = Math.max(2, px * 0.18);
+  ctx.strokeStyle = "rgba(0, 0, 0, 0.55)";
+  ctx.strokeText(text, x, y);
+  ctx.fillStyle = "rgba(255, 255, 255, 0.8)";
+  ctx.fillText(text, x, y);
+  const tex = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, c);
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return tex;
+}
+
+/** Footage frame upload: RGBA8 sRGB bytes of the footage's own size. */
+function footage(bytes, w, h) {
+  if (!footageTex) {
+    footageTex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, footageTex);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.SRGB8_ALPHA8, w, h);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  }
+  gl.bindTexture(gl.TEXTURE_2D, footageTex);
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+  gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, bytes);
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+  hasFootage = true;
+  return true;
+}
+
+window.__litPrepare = (opts) => prepare(opts).catch((e) => ({ ok: false, error: String(e.message ?? e) }));
+window.__litStep = (f, plan) => step(f, plan);
+window.__litFootageFetch = async (url, w, h) => {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`footage frame ${url} missing (${r.status})`);
+  return footage(new Uint8Array(await r.arrayBuffer()), w, h);
+};
+window.__litStageState = () => ({ ready: Boolean(gl), width: W, height: H });

package/skills/agentvfx/engine/web/scale.mjs

@@ -0,0 +1,15 @@
+// Output scale, read once from the page URL (`?scale=2` renders 3840x2160). Scenes keep laying out
+// in logical 1920x1080 px at every scale. Adapted from mexicat/pdoom-video app/src/engine/scale.ts
+// (MIT, see ../NOTICE).
+function readScale() {
+  if (typeof location === "undefined") return 1;
+  const value = Math.round(Number(new URLSearchParams(location.search).get("scale") ?? "1"));
+  return Number.isFinite(value) && value >= 1 ? Math.min(value, 4) : 1;
+}
+
+/** Physical px per logical px (integer 1..4). */
+export const SCALE = readScale();
+export const W = 1920;
+export const H = 1080;
+export const PW = W * SCALE;
+export const PH = H * SCALE;

package/skills/agentvfx/engine/web/text.mjs

@@ -0,0 +1,158 @@
+// agentvfx (Apache-2.0, see LICENSE). Engine text layer, drawn in the render page with Canvas 2D and system fonts
+// (nothing bundled). Output is a mask: R = glyph and line ink, G = solid box/bar fill. Templates colour
+// it. Reveal modes are frame-deterministic: "type" prints characters over time with a block cursor,
+// "decode" settles each character out of seeded random glyphs.
+
+export const FONT_STACKS = Object.freeze({
+  display: { family: '"DIN Condensed", "Avenir Next Condensed", "Arial Narrow", sans-serif', weight: 700, stretchY: 1.0 },
+  tall: { family: '"Avenir Next Condensed", "Helvetica Neue", "Arial Narrow", sans-serif', weight: 300, stretchY: 1.75 },
+  grotesk: { family: '"Helvetica Neue", Helvetica, Arial, sans-serif', weight: 800, stretchY: 1.0 },
+  mono: { family: 'Menlo, "SF Mono", Monaco, "Courier New", monospace', weight: 400, stretchY: 1.0 },
+  serif: { family: '"Times New Roman", Times, serif', weight: 400, stretchY: 1.0 },
+});
+
+const SCRAMBLE = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&*+=<>/\\";
+const INK = "rgb(255,0,0)";
+const FILL = "rgb(0,255,0)";
+/** Glyph ink colour per item `channel`: r (default) is the shared sheet, g and b are extra independent sheets. */
+export const CHANNEL_INK = Object.freeze({ r: INK, g: FILL, b: "rgb(0,0,255)" });
+
+function hash(a, b, c) {
+  let x = (Math.imul(a | 0, 0x9e3779b1) ^ Math.imul(b | 0, 0x85ebca77) ^ Math.imul(c | 0, 0xc2b2ae3d)) >>> 0;
+  x ^= x >>> 16;
+  x = Math.imul(x, 0x7feb352d) >>> 0;
+  x ^= x >>> 15;
+  return x >>> 0;
+}
+
+/** The visible string for one item at time t (seconds). */
+export function revealText(spec, text, t, frame, seedInt) {
+  const start = spec.revealStart ?? 0;
+  const dur = Math.max(1e-3, spec.revealDur ?? 1);
+  const p = Math.min(1, Math.max(0, (t - start) / dur));
+  if (spec.reveal === "type") {
+    if (t < start) return "";
+    const n = Math.floor(p * text.length);
+    const blink = Math.floor(t * 4) % 2 === 0;
+    return text.slice(0, n) + (p < 1 || blink ? "█" : "");
+  }
+  if (spec.reveal === "decode") {
+    if (t < start) return "";
+    const tick = Math.floor(frame / 2);
+    return [...text].map((ch, i) => {
+      if (ch === " " || ch === "\n") return ch;
+      const settle = (i + 1) / text.length;
+      return p >= settle ? ch : SCRAMBLE[hash(i, tick, seedInt) % SCRAMBLE.length];
+    }).join("");
+  }
+  return text;
+}
+
+function roundRect(ctx, x, y, w, h, r) {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath();
+}
+
+/** Installed font family names an item may name: letters (any script), digits, spaces, dots, hyphens, underscores. */
+export const FAMILY_PATTERN = /^[\p{L}\p{N} ._-]{1,64}$/u;
+
+/**
+ * The CSS font stack of one item: its generic `font` stack, with an installed `family` (referenced by name only, nothing is
+ * bundled) put in front so an absent family falls through to the generic stack.
+ */
+export function fontStack(spec) {
+  const base = FONT_STACKS[spec.font ?? "display"];
+  const family = typeof spec.family === "string" && FAMILY_PATTERN.test(spec.family) ? `"${spec.family}", ` : "";
+  return { ...base, family: `${family}${base.family}` };
+}
+
+/** Draw every text item of a layer into ctx (cleared first). */
+export function drawTextLayer(ctx, W, H, specs, labels, t, frame, seedInt) {
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.globalCompositeOperation = "source-over";
+  ctx.fillStyle = "black";
+  ctx.fillRect(0, 0, W, H);
+  ctx.globalCompositeOperation = "lighter";
+  ctx.textBaseline = "alphabetic";
+  for (const spec of specs) {
+    const raw = labels?.[spec.key] ?? spec.default;
+    const text = revealText(spec, raw, t, frame, seedInt);
+    const font = fontStack(spec);
+    const px = Math.max(4, spec.size * H);
+    const sy = font.stretchY;
+    ctx.font = `${spec.weight ?? font.weight} ${px}px ${font.family}`;
+    ctx.letterSpacing = `${(spec.tracking ?? 0) * px}px`;
+    const lines = text.split("\n");
+    const lh = px * sy * (spec.lineHeight ?? 1.15);
+    const widths = lines.map((l) => ctx.measureText(l).width);
+    const maxW = Math.max(1, ...widths, spec.box && spec.box !== "none" ? ctx.measureText(raw.split("\n")[0]).width : 0);
+    const align = spec.align ?? "left";
+    const x0 = spec.x * W;
+    const yTop = spec.y * H;
+    const left = align === "left" ? x0 : align === "center" ? x0 - maxW / 2 : x0 - maxW;
+    const blockH = lh * lines.length;
+    const ink = CHANNEL_INK[spec.channel ?? "r"];
+    const pad = px * 0.28;
+    const stroke = Math.max(1.5, px * 0.035);
+    if (spec.box === "bar") {
+      ctx.fillStyle = FILL;
+      ctx.fillRect(left - pad, yTop - pad * 0.6, maxW + 2 * pad, blockH + pad * 0.8);
+    } else if (spec.box === "frame") {
+      ctx.strokeStyle = INK;
+      ctx.lineWidth = stroke;
+      roundRect(ctx, left - pad, yTop - pad * 0.6, maxW + 2 * pad, blockH + pad * 0.8, pad * 0.6);
+      ctx.stroke();
+    } else if (spec.box === "tab") {
+      // index card: square box with the top-right corner cut at 45 degrees and a solid spine on the left edge
+      const bx = left - pad;
+      const by = yTop - pad * 0.6;
+      const bw = maxW + 2 * pad;
+      const bh = blockH + pad * 0.8;
+      const cut = Math.min(bh * 0.42, px * 0.5);
+      ctx.strokeStyle = INK;
+      ctx.lineWidth = stroke;
+      ctx.beginPath();
+      ctx.moveTo(bx, by);
+      ctx.lineTo(bx + bw - cut, by);
+      ctx.lineTo(bx + bw, by + cut);
+      ctx.lineTo(bx + bw, by + bh);
+      ctx.lineTo(bx, by + bh);
+      ctx.closePath();
+      ctx.stroke();
+      ctx.fillStyle = INK;
+      ctx.fillRect(bx - stroke * 0.5, by, Math.max(stroke * 2.5, px * 0.09), bh);
+    }
+    lines.forEach((line, i) => {
+      const w = widths[i];
+      const lx = align === "left" ? left : align === "center" ? x0 - w / 2 : x0 - w;
+      const baseline = yTop + lh * i + px * sy * 0.82;
+      ctx.save();
+      ctx.translate(lx, baseline);
+      ctx.scale(1, sy);
+      if (spec.style === "outline") {
+        ctx.strokeStyle = ink;
+        ctx.lineWidth = stroke / sy;
+        ctx.strokeText(line, 0, 0);
+      } else {
+        ctx.fillStyle = ink;
+        ctx.fillText(line, 0, 0);
+      }
+      ctx.restore();
+    });
+  }
+}
+
+/** Make sure the system faces (the generic stacks and every item's named family) are resolved before the first frame (no fallback race). */
+export async function warmFonts(specs, H) {
+  if (!document.fonts?.load) return;
+  const stacks = [...Object.values(FONT_STACKS), ...specs.filter((s) => s.family).map(fontStack)];
+  const loads = specs.flatMap((s) => stacks.map((f) => (
+    document.fonts.load(`${s.weight ?? f.weight} ${Math.max(4, s.size * H)}px ${f.family}`, s.default || "A").catch(() => null)
+  )));
+  await Promise.all(loads);
+}

package/skills/agentvfx/plates/terminalcore/README.md

@@ -0,0 +1,61 @@
+# terminalcore plate
+
+Procedural, fully self-made Blender scene (no downloaded assets, HDRIs, textures or font files) that renders
+ray-traced background footage in a Terminalcore / CRT-futurism / cybernetic-brutalist look, to be fed to
+agentvfx templates as `input.video`.
+
+What is in the scene
+- Board-formed raw concrete room (tie holes, panel joints, streaks), polished reflective floor, brutalist piers + lintel.
+- A rack bank of 45 chunky CRT monitors: bevelled bezels, curved dusty glass with real reflections, vents, knobs, LEDs.
+- Screens are emissive and procedural: terminal text drawn from a hand-made 5x7 bitmap font (`font.py`), scrolling,
+  with scanlines, edge vignette, flicker and a slow hum bar. Green / amber / cold-white phosphor, a few dead tubes.
+- Cable tray, thick cables (drops, floor runs), status-LED array in the lintel, steel rack hardware.
+- Volumetric haze (world scatter) with one cold key light entering through a slit window in the left wall.
+- Cycles (Metal GPU), OIDN denoise, AgX view transform, shallow depth of field, compositor bloom, light handheld wander.
+
+Shots
+- `wall`    wide, slow push-in across the whole CRT wall.
+- `closeup` one CRT close, oblique slide, text scrolling, glass reflections, DOF falloff over neighbouring tubes.
+
+- `gallery` the same CRT wall as a clean, hyper-real exhibition-room installation (see below).
+
+Gallery variant (`--shot gallery`)
+- Room: architectural cast-concrete panels (1.2 x 2.35 m, real 5 mm joints with tiny bevels, dark reveal gaps at floor and
+  ceiling, round form-tie holes, per-panel tone shift, pores, clouding), polished sealed concrete floor with soft reflections and
+  saw-cut joints, concrete soffit with three flush linear light slots, track rails with grazing spots, a wall-wash over the back wall.
+- Installation: strict 9 x 5 grid of identical CRTs (no jitter, mirrored amber/green layout, a few dark tubes) in a black
+  powder-coat frame on a dark polished plinth; cables hidden behind the frame; one pale stone bench for scale. No text or branding.
+- Look: AgX, exposure +0.15, haze only a touch (density 0.002), light bloom, lighter film grain in the encode.
+- Camera: level, centred, one-point perspective with lens shift; steady 1.4 m dolly-in (-9.8 to -8.4), no shake, so the bench base keeps a clear margin above the bottom edge on the last frame. DOF is deep (f/11).
+- Powered-off tubes are dark tinted glass (`glass_off` in `gallery_mats.py`): soft low-gloss reflection, no mirror glints of the ceiling slots. The bench is honed limestone with cloudy tone, thin veins, hone grain and a 13 mm edge bevel.
+- Cost: measured 2.0 s/frame at 640x360, 56 samples, preview quality (240 s for the 4 s / 120-frame clip).
+- Files: `gallery.py` (build + installation + bench), `gallery_room.py` (shell, ceiling, lights, haze), `gallery_mats.py` (materials).
+- The screen layout is `LAYOUT` in `gallery.py` (bottom row first, columns mirrored); light intensity scales with `--key`.
+
+Usage (from the agentvfx skill root)
+
+    node scripts/plate.mjs --scene terminalcore --shot wall --out ../../gallery/plates/terminalcore-wall \
+         --width 640 --height 360 --seconds 4 --fps 30 --samples 40
+
+Writes `film.mp4` (H.264, yuv420p, light grain + vignette added in post; `--no-post` to skip), `still_first|mid|last.png`,
+`plate.json` (measured seconds per frame) and `blender.log`.
+
+Quality: `--quality preview` (default) is the fast look-dev path. `--quality final` raises samples to 256 (unless `--samples` is
+given), tightens the adaptive threshold (0.01), uses the accurate OIDN denoise, enables Cycles camera motion blur (shutter 0.5; the camera
+is keyframed on every frame because Cycles does not see a frame-change handler) and encodes at crf 14. Film grain stays the light
+encode-time grain. Measured: 1920x1080 final, gallery, Metal GPU: about 109 s/frame (one test frame), so a 120-frame clip is roughly 3.6 h.
+
+Options: `--quality preview|final`, `--frame N` renders one test still (`still_NNN.png`, no video), `--exposure EV`, `--bloom X` (0 = off), `--key X`
+(key-light multiplier), `--haze X` (haze density multiplier), `--keep-frames`. Blender is found via `BLENDER_PATH`, `PATH`, or the macOS app bundle; ffmpeg via
+`FFMPEG_PATH` / `PATH`.
+
+Then use the clip as footage: pass the resulting `film.mp4` as the template's `input.video`.
+
+Files: `scene.py` (entry, render setup, animation), `room.py` (shell, haze, key light), `wall.py` (rack, monitors, cables),
+`crt.py` (monitor mesh), `materials.py` + `nodekit.py` (procedural shaders), `textures.py` + `font.py` (terminal text),
+`shots.py` (camera moves).
+
+Limits: preview-oriented defaults (640x360, 40 samples). For finals use `--quality final` and raise `--width/--height`
+(time scales roughly with pixels x samples). Preview has no motion blur; final has camera motion blur only (the gallery dolly is slow,
+about 12 mm per frame, so the blur is subtle; the scrolling screen text is a shader value and is not blurred). A faint film grain is
+added in the encode step rather than in Cycles.