agentvfx 0.0.0-stage → 0.3.5

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

@@ -0,0 +1,319 @@
+// Raw WebGL2 plumbing: HDR render targets, full-screen shader passes, a compositor and Canvas2D
+// layers uploaded as sRGB textures. Re-expressed without three.js from the mechanism of
+// mexicat/pdoom-video app/src/engine/gl.ts (MIT, see ../NOTICE).
+//
+// Every look-library pass draws through `Pass.draw`, the one uniform-setter wrapper: it records
+// the uniforms and counts draws per pass for the render log (MO-SH-00a), so no pass can draw
+// without leaving a trace the gate can check.
+import { GLSL_COMMON } from "./glsl-common.mjs";
+import { SCALE, W, H, PW, PH } from "./scale.mjs";
+
+export { SCALE, W, H, PW, PH };
+
+const VERT = `#version 300 es
+precision highp float;
+out vec2 vUv;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  vUv = p;
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}`;
+
+/** Per-frame render-log recorder shared by every pass. */
+export class Tracker {
+  constructor() {
+    this.frame = new Map();
+    this.recordUniforms = true;
+  }
+  reset() {
+    this.frame = new Map();
+  }
+  entry(pass) {
+    let e = this.frame.get(pass);
+    if (!e) {
+      e = { draws: 0, uniforms: {} };
+      this.frame.set(pass, e);
+    }
+    return e;
+  }
+  draw(pass, uniforms) {
+    const e = this.entry(pass);
+    e.draws += 1;
+    if (this.recordUniforms) {
+      for (const [name, value] of Object.entries(uniforms)) {
+        if (value && typeof value === "object" && value.isTexture) continue;
+        e.uniforms[name] = Array.isArray(value) ? value.map((v) => +(+v).toFixed(6)) : typeof value === "number" ? +value.toFixed(6) : value;
+      }
+    }
+  }
+  lines() {
+    return [...this.frame.entries()].map(([pass, e]) => ({ pass, draws: e.draws, uniforms: e.uniforms }));
+  }
+}
+
+export class GL {
+  constructor(canvas) {
+    const gl = canvas.getContext("webgl2", { antialias: false, alpha: false, depth: false, stencil: false, preserveDrawingBuffer: true, premultipliedAlpha: false, powerPreference: "high-performance" });
+    if (!gl) throw new Error("NO_WEBGL2: canvas.getContext('webgl2') returned null");
+    if (!gl.getExtension("EXT_color_buffer_float")) throw new Error("NO_WEBGL2: EXT_color_buffer_float is unavailable, so HDR render targets cannot be drawn");
+    this.gl = gl;
+    this.canvas = canvas;
+    this.vao = gl.createVertexArray();
+    this.tracker = new Tracker();
+    this.programs = new Map();
+  }
+
+  renderer() {
+    const gl = this.gl;
+    const ext = gl.getExtension("WEBGL_debug_renderer_info");
+    return ext ? String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)) : "unknown (debug-info extension unavailable)";
+  }
+
+  /** A render target in physical px. `format` is "half" (RGBA16F, linear HDR) or "rgba8". */
+  target(width = PW, height = PH, format = "half") {
+    const gl = this.gl;
+    const tex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    if (format === "half") gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA16F, width, height);
+    else gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, width, height);
+    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);
+    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(`framebuffer incomplete (${status}) for ${format} ${width}x${height}`);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    return { fbo, tex: { isTexture: true, handle: tex }, width, height, format };
+  }
+
+  bind(target) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, target ? target.fbo : null);
+    gl.viewport(0, 0, target ? target.width : PW, target ? target.height : PH);
+  }
+
+  clear(target, rgb = [0, 0, 0], alpha = 0) {
+    const gl = this.gl;
+    this.bind(target);
+    gl.disable(gl.BLEND);
+    gl.clearColor(rgb[0], rgb[1], rgb[2], alpha);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+  }
+
+  program(frag) {
+    const cached = this.programs.get(frag);
+    if (cached) return cached;
+    const gl = this.gl;
+    const compile = (type, source) => {
+      const shader = gl.createShader(type);
+      gl.shaderSource(shader, source);
+      gl.compileShader(shader);
+      if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) throw new Error(`shader compile failed: ${gl.getShaderInfoLog(shader)}`);
+      return shader;
+    };
+    const fragSource = `#version 300 es\nprecision highp float;\nprecision highp int;\nin vec2 vUv;\nout vec4 fragColor;\n${GLSL_COMMON}\n${frag}`;
+    const program = gl.createProgram();
+    gl.attachShader(program, compile(gl.VERTEX_SHADER, VERT));
+    gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fragSource));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(`program link failed: ${gl.getProgramInfoLog(program)}`);
+    const uniforms = new Map();
+    const count = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+    for (let i = 0; i < count; i++) {
+      const info = gl.getActiveUniform(program, i);
+      const name = info.name.replace(/\[0\]$/u, "");
+      uniforms.set(name, { location: gl.getUniformLocation(program, info.name), type: info.type, size: info.size });
+    }
+    const entry = { program, uniforms };
+    this.programs.set(frag, entry);
+    return entry;
+  }
+
+  setUniforms(entry, values) {
+    const gl = this.gl;
+    let unit = 0;
+    for (const [name, value] of Object.entries(values)) {
+      const u = entry.uniforms.get(name);
+      if (!u) continue;
+      const v = typeof value === "boolean" ? (value ? 1 : 0) : value;
+      switch (u.type) {
+        case gl.FLOAT: gl.uniform1f(u.location, v); break;
+        case gl.FLOAT_VEC2: gl.uniform2fv(u.location, v); break;
+        case gl.FLOAT_VEC3: gl.uniform3fv(u.location, v); break;
+        case gl.FLOAT_VEC4: gl.uniform4fv(u.location, v); break;
+        case gl.INT: case gl.BOOL: gl.uniform1i(u.location, v); break;
+        case gl.UNSIGNED_INT: gl.uniform1ui(u.location, v >>> 0); break;
+        case gl.SAMPLER_2D:
+          gl.activeTexture(gl.TEXTURE0 + unit);
+          gl.bindTexture(gl.TEXTURE_2D, v ? v.handle : null);
+          gl.uniform1i(u.location, unit);
+          unit += 1;
+          break;
+        default: throw new Error(`unsupported uniform type for ${name}`);
+      }
+    }
+  }
+
+  blend(mode) {
+    const gl = this.gl;
+    if (mode === "replace") {
+      gl.disable(gl.BLEND);
+      return;
+    }
+    gl.enable(gl.BLEND);
+    if (mode === "normal") {
+      // Premultiplied colour over the target; the target's alpha (glyph coverage) is kept.
+      gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
+      gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ZERO, gl.ONE);
+    } else if (mode === "glyph") {
+      // Glyph ink: colour over, coverage = max(target, glyph) so alpha carries the glyph mask.
+      gl.blendEquationSeparate(gl.FUNC_ADD, gl.MAX);
+      gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE);
+    } else if (mode === "add") {
+      gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
+      gl.blendFuncSeparate(gl.ONE, gl.ONE, gl.ONE, gl.ONE);
+    } else throw new Error(`unknown blend mode ${mode}`);
+  }
+
+  /** Download a target's RGBA8 pixels through a pixel-pack buffer and a fence (no GPU stall). */
+  async readPixelsAsync(target, out) {
+    const gl = this.gl;
+    const bytes = target.width * target.height * 4;
+    const buffer = out ?? new Uint8Array(bytes);
+    if (!this.pbo || this.pboBytes !== bytes) {
+      if (this.pbo) gl.deleteBuffer(this.pbo);
+      this.pbo = gl.createBuffer();
+      gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+      gl.bufferData(gl.PIXEL_PACK_BUFFER, bytes, gl.STREAM_READ);
+      this.pboBytes = bytes;
+    }
+    this.bind(target);
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+    gl.readPixels(0, 0, target.width, target.height, gl.RGBA, gl.UNSIGNED_BYTE, 0);
+    const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    gl.flush();
+    for (;;) {
+      const state = gl.clientWaitSync(sync, 0, 0);
+      if (state === gl.ALREADY_SIGNALED || state === gl.CONDITION_SATISFIED) break;
+      if (state === gl.WAIT_FAILED) throw new Error("clientWaitSync failed during pixel readback");
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    gl.deleteSync(sync);
+    gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, buffer);
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+    return buffer;
+  }
+}
+
+/**
+ * A full-screen fragment pass. `frag` declares its uniforms and writes `fragColor`; `vUv` (0..1,
+ * y up) and GLSL_COMMON are provided. `pass` names the look-library pass it belongs to (null for
+ * engine plumbing); only named passes are logged.
+ */
+export class Pass {
+  constructor(glw, frag, { pass = null } = {}) {
+    this.glw = glw;
+    this.frag = frag;
+    this.pass = pass;
+    this.entry = glw.program(frag);
+  }
+  draw(target, uniforms = {}, { blend = "replace" } = {}) {
+    const { glw } = this;
+    const gl = glw.gl;
+    glw.bind(target);
+    gl.useProgram(this.entry.program);
+    glw.setUniforms(this.entry, uniforms);
+    glw.blend(blend);
+    gl.bindVertexArray(glw.vao);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.bindVertexArray(null);
+    if (this.pass) glw.tracker.draw(this.pass, uniforms);
+  }
+}
+
+const COMPOSITE_FRAG = /* glsl */ `
+uniform sampler2D src; uniform float opacity; uniform vec3 tint;
+void main() {
+  // Canvas2D layers are uploaded unpremultiplied as SRGB8_ALPHA8, so RGB arrives already linear
+  // and is premultiplied here.
+  vec4 c = texture(src, vUv);
+  float a = c.a * opacity;
+  fragColor = vec4(c.rgb * tint * a, a);
+}`;
+
+/** Draws a texture over a target: `normal` keeps the target's glyph mask, `glyph` adds to it. */
+export class Compositor {
+  constructor(glw) {
+    this.pass = new Pass(glw, COMPOSITE_FRAG);
+  }
+  draw(texture, target, { mode = "normal", opacity = 1, tint = [1, 1, 1], logAs = null } = {}) {
+    this.pass.pass = logAs;
+    this.pass.draw(target, { src: texture, opacity, tint }, { blend: mode });
+    this.pass.pass = null;
+  }
+}
+
+/**
+ * A logical 1920x1080 Canvas2D surface uploaded as an sRGB texture. The context is CPU-backed
+ * (willReadFrequently) so its rasterization does not depend on GPU raster scheduling, and it is
+ * pre-scaled so drawing code works in logical px at every output scale.
+ */
+export class Layer2D {
+  constructor(glw, width = W, height = H) {
+    this.glw = glw;
+    this.width = width;
+    this.height = height;
+    this.canvas = document.createElement("canvas");
+    this.canvas.width = Math.round(width * SCALE);
+    this.canvas.height = Math.round(height * SCALE);
+    this.ctx = this.canvas.getContext("2d", { willReadFrequently: true, alpha: true });
+    const gl = glw.gl;
+    this.handle = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, this.handle);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.SRGB8_ALPHA8, this.canvas.width, this.canvas.height);
+    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);
+    this.texture = { isTexture: true, handle: this.handle };
+    this.clear();
+  }
+  clear() {
+    const c = this.ctx;
+    c.setTransform(SCALE, 0, 0, SCALE, 0, 0);
+    c.globalAlpha = 1;
+    c.globalCompositeOperation = "source-over";
+    c.filter = "none";
+    c.shadowBlur = 0;
+    c.clearRect(0, 0, this.width, this.height);
+  }
+  upload() {
+    const gl = this.glw.gl;
+    gl.bindTexture(gl.TEXTURE_2D, this.handle);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, this.canvas);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    return this.texture;
+  }
+  /** Re-upload only a logical-px rectangle of the canvas (the rest of the texture is kept). */
+  uploadRegion(x, y, w, h) {
+    const gl = this.glw.gl;
+    const px = Math.max(0, Math.floor(x * SCALE));
+    const py = Math.max(0, Math.floor(y * SCALE));
+    const pw = Math.min(this.canvas.width - px, Math.ceil((x + w) * SCALE) - px);
+    const ph = Math.min(this.canvas.height - py, Math.ceil((y + h) * SCALE) - py);
+    const region = this.ctx.getImageData(px, py, pw, ph);
+    gl.bindTexture(gl.TEXTURE_2D, this.handle);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, px, this.canvas.height - py - ph, pw, ph, gl.RGBA, gl.UNSIGNED_BYTE, region);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    return this.texture;
+  }
+}

package/skills/agentvfx/engine/web/glsl-common.mjs

@@ -0,0 +1,78 @@
+// Shared GLSL ES 3.0 header prepended to every full-screen pass. Adapted in structure from
+// mexicat/pdoom-video app/src/engine/glsl/common.ts (MIT, see ../NOTICE): output-scale-aware
+// fragment coordinates, colour transfer helpers and pure noise. The noise here is this engine's
+// own integer-hash value noise, seeded through `uint` uniforms (MO-SH-01), so every pass that needs
+// randomness is a pure function of (pixel, seed, t).
+import { SCALE } from "./scale.mjs";
+
+export const GLSL_COMMON = /* glsl */ `
+#define PI 3.14159265359
+#define TAU 6.28318530718
+const float PX_SCALE = ${SCALE.toFixed(1)};
+#define FRAG_PX (gl_FragCoord.xy / PX_SCALE)
+const vec2 LOGICAL = vec2(1920.0, 1080.0);
+
+float sat(float x) { return clamp(x, 0.0, 1.0); }
+vec3 sat(vec3 x) { return clamp(x, 0.0, 1.0); }
+float luma(vec3 c) { return dot(c, vec3(0.2126, 0.7152, 0.0722)); }
+mat2 rot2(float a) { float c = cos(a), s = sin(a); return mat2(c, -s, s, c); }
+
+vec3 toSRGB(vec3 c) { c = max(c, 0.0); return mix(12.92 * c, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c)); }
+vec3 toLinear(vec3 c) { return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c)); }
+
+// 32-bit integer hash (xorshift-multiply). Deterministic on every WebGL2 implementation because it
+// only uses uint multiply, xor and shifts.
+uint uhash(uint x) {
+  x ^= x >> 16u; x *= 0x7feb352du;
+  x ^= x >> 15u; x *= 0x846ca68bu;
+  x ^= x >> 16u;
+  return x;
+}
+uint uhash2(uvec2 v) { return uhash(v.x ^ uhash(v.y + 0x9e3779b9u)); }
+uint uhash3(uvec3 v) { return uhash(v.x ^ uhash(v.y ^ uhash(v.z + 0x85ebca6bu))); }
+float unit(uint h) { return float(h >> 8u) * (1.0 / 16777216.0); }
+float hashCell(ivec2 c, uint seed) { return unit(uhash3(uvec3(uint(c.x), uint(c.y), seed))); }
+float hashCell3(ivec3 c, uint seed) { return unit(uhash(uhash3(uvec3(c)) ^ seed)); }
+
+vec2 quintic(vec2 t) { return t * t * t * (t * (t * 6.0 - 15.0) + 10.0); }
+vec3 quintic(vec3 t) { return t * t * t * (t * (t * 6.0 - 15.0) + 10.0); }
+
+// Value noise in [-1, 1].
+float vnoise(vec2 p, uint seed) {
+  ivec2 i = ivec2(floor(p)); vec2 f = quintic(fract(p));
+  float a = hashCell(i, seed), b = hashCell(i + ivec2(1, 0), seed);
+  float c = hashCell(i + ivec2(0, 1), seed), d = hashCell(i + ivec2(1, 1), seed);
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y) * 2.0 - 1.0;
+}
+float vnoise(vec3 p, uint seed) {
+  ivec3 i = ivec3(floor(p)); vec3 f = quintic(fract(p));
+  float n000 = hashCell3(i, seed), n100 = hashCell3(i + ivec3(1, 0, 0), seed);
+  float n010 = hashCell3(i + ivec3(0, 1, 0), seed), n110 = hashCell3(i + ivec3(1, 1, 0), seed);
+  float n001 = hashCell3(i + ivec3(0, 0, 1), seed), n101 = hashCell3(i + ivec3(1, 0, 1), seed);
+  float n011 = hashCell3(i + ivec3(0, 1, 1), seed), n111 = hashCell3(i + ivec3(1, 1, 1), seed);
+  float x00 = mix(n000, n100, f.x), x10 = mix(n010, n110, f.x), x01 = mix(n001, n101, f.x), x11 = mix(n011, n111, f.x);
+  return mix(mix(x00, x10, f.y), mix(x01, x11, f.y), f.z) * 2.0 - 1.0;
+}
+float fbm(vec3 p, int octaves, uint seed) {
+  float sum = 0.0, amp = 0.5;
+  for (int i = 0; i < 8; i++) {
+    if (i >= octaves) break;
+    sum += amp * vnoise(p, seed + uint(i) * 101u);
+    p = p * 2.02 + vec3(17.1, 9.3, 4.7);
+    amp *= 0.5;
+  }
+  return sum;
+}
+// Divergence-free flow direction from the gradient of a scalar noise field.
+vec2 curl(vec2 p, float z, uint seed) {
+  const float e = 0.02;
+  float n1 = vnoise(vec3(p + vec2(0.0, e), z), seed), n2 = vnoise(vec3(p - vec2(0.0, e), z), seed);
+  float n3 = vnoise(vec3(p + vec2(e, 0.0), z), seed), n4 = vnoise(vec3(p - vec2(e, 0.0), z), seed);
+  return vec2(n1 - n2, n4 - n3) / (2.0 * e);
+}
+
+// Ordered-dither thresholds in [0, 1).
+float bayer2(ivec2 p) { int x = p.x & 1, y = p.y & 1; return float((x ^ y) * 2 + y) / 4.0; }
+float bayer4(ivec2 p) { return (bayer2(p / 2) + bayer2(p) * 4.0) / 4.0; }
+float bayer8(ivec2 p) { return (bayer4(p / 2) + bayer2(p) * 16.0) / 4.0; }
+`;

package/skills/agentvfx/engine/web/init.js

@@ -0,0 +1,23 @@
+// agentvfx (Apache-2.0, see LICENSE). Injected before any page script: the page has no wall clock and no
+// unseeded randomness. Math.random is a seeded mulberry32; Date and performance.now are frozen at 0
+// (time comes only from the frame index the host passes to window.__litStep).
+(() => {
+  let s = __LIT_SEED__ >>> 0;
+  const rand = () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  Object.defineProperty(Math, "random", { value: rand, writable: false, configurable: false });
+  const RealDate = Date;
+  class FrozenDate extends RealDate {
+    constructor(...a) { super(...(a.length ? a : [0])); }
+    static now() { return 0; }
+  }
+  window.Date = FrozenDate;
+  if (window.performance) Object.defineProperty(window.performance, "now", { value: () => 0, configurable: false });
+  window.requestAnimationFrame = () => { throw new Error("requestAnimationFrame is not available on the render page"); };
+  window.__LIT_SEED = __LIT_SEED__ >>> 0;
+})();

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

@@ -0,0 +1,150 @@
+// agentvfx (Apache-2.0, see LICENSE). The GLSL prelude prepended to every template pass, and the program source
+// builder. Contract: references/template-format.md. Importable in Node (tests) and in the page.
+// Helper credits: value noise and fbm after The Book of Shaders ch.11/13 (https://thebookofshaders.com),
+// cosine palette after Inigo Quilez (https://iquilezles.org/articles/palettes/), hsv conversions after
+// Sam Hocevar's public-domain formulation; all re-written here.
+
+/** Score seed (integer) -> SEED uniform in [0, 1): an integer hash so nearby seeds give unrelated values. */
+export function seedToUnit(seed) {
+  let x = seed >>> 0;
+  x ^= x >>> 16;
+  x = Math.imul(x, 0x7feb352d) >>> 0;
+  x ^= x >>> 15;
+  x = Math.imul(x, 0x846ca68b) >>> 0;
+  x ^= x >>> 16;
+  return (x >>> 0) / 4294967296;
+}
+
+export const VERT = `#version 300 es
+precision highp float;
+out vec2 vUv;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  vUv = p;
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}`;
+
+export const PRELUDE_HEAD = `#version 300 es
+precision highp float;
+precision highp int;
+precision highp sampler2D;
+in vec2 vUv;
+out vec4 fragColor;
+uniform float TIME;
+uniform float TIMEDELTA;
+uniform int FRAMEINDEX;
+uniform int PASSINDEX;
+uniform vec2 RENDERSIZE;
+uniform float SEED;
+uniform sampler2D inputImage;
+uniform bool HAS_INPUT;
+uniform vec3 PALETTE[8];
+uniform int PALETTE_COUNT;
+uniform float AUDIO_RMS, AUDIO_PEAK, AUDIO_BASS, AUDIO_MID, AUDIO_TREB, AUDIO_BASS_ATT, AUDIO_MID_ATT,
+              AUDIO_TREB_ATT, AUDIO_FLUX, AUDIO_ONSET, AUDIO_BEAT, AUDIO_BEATPHASE, AUDIO_BPM;
+uniform sampler2D audio;
+uniform sampler2D audioFFT;
+uniform float AUDIO_BANDS[32];
+uniform sampler2D TEXTMASK;   // engine text layer: R = glyph/line ink, G = solid box/bar fill (0..1); items with channel g or b draw their glyph ink into G or B
+uniform bool HAS_TEXT;
+#define isf_FragNormCoord vUv
+#define IMG_NORM_PIXEL(img, uv) texture(img, uv)
+#define IMG_THIS_NORM_PIXEL(img) texture(img, vUv)
+#define IMG_PIXEL(img, px) texture(img, (px) / vec2(textureSize(img, 0)))
+#define IMG_THIS_PIXEL(img) texture(img, vUv)
+#define IMG_SIZE(img) vec2(textureSize(img, 0))
+`;
+
+export const PRELUDE_HELPERS = `
+float hash12(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * 0.1031 + SEED * 17.17);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+vec2 hash22(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973) + SEED * 17.17);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.xx + p3.yz) * p3.zy);
+}
+float vnoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = hash12(i);
+  float b = hash12(i + vec2(1.0, 0.0));
+  float c = hash12(i + vec2(0.0, 1.0));
+  float d = hash12(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float fbm(vec2 p, int octaves) {
+  float v = 0.0;
+  float a = 0.5;
+  float norm = 0.0;
+  for (int i = 0; i < 8; i++) {
+    if (i >= octaves) break;
+    v += a * vnoise(p);
+    norm += a;
+    p = mat2(1.6, 1.2, -1.2, 1.6) * p + 7.31;
+    a *= 0.5;
+  }
+  return norm > 0.0 ? v / norm : 0.0;
+}
+float luma(vec3 c) { return dot(c, vec3(0.2126, 0.7152, 0.0722)); }
+vec3 rgb2hsv(vec3 c) {
+  vec4 K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);
+  vec4 p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g));
+  vec4 q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r));
+  float d = q.x - min(q.w, q.y);
+  float e = 1.0e-10;
+  return vec3(abs(q.z + (q.w - q.y) / (6.0 * d + e)), d / (q.x + e), q.x);
+}
+vec3 hsv2rgb(vec3 c) {
+  vec3 p = abs(fract(c.xxx + vec3(1.0, 2.0 / 3.0, 1.0 / 3.0)) * 6.0 - 3.0);
+  return c.z * mix(vec3(1.0), clamp(p - 1.0, 0.0, 1.0), c.y);
+}
+vec3 cosPalette(float t, vec3 a, vec3 b, vec3 c, vec3 d) { return a + b * cos(6.28318530718 * (c * t + d)); }
+vec3 paletteRamp(float t) {
+  int n = max(PALETTE_COUNT, 1);
+  if (n == 1) return PALETTE[0];
+  float x = clamp(t, 0.0, 1.0) * float(n - 1);
+  int i = int(floor(x));
+  int j = min(i + 1, n - 1);
+  return mix(PALETTE[i], PALETTE[j], x - float(i));
+}
+vec3 paletteCycle(float t) {
+  int n = max(PALETTE_COUNT, 1);
+  float x = fract(t) * float(n);
+  int i = int(floor(x)) % n;
+  int j = (i + 1) % n;
+  return mix(PALETTE[i], PALETTE[j], x - floor(x));
+}
+vec3 srgbToLinear(vec3 c) { return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c)); }
+vec3 linearToSrgb(vec3 c) { c = max(c, 0.0); return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c)); }
+mat2 rot(float a) { float c = cos(a); float s = sin(a); return mat2(c, s, -s, c); }
+`;
+
+const UNIFORM_TYPE = { float: "float", long: "int", bool: "bool", color: "vec4", point2D: "vec2", image: "sampler2D", audio: "sampler2D", audioFFT: "sampler2D" };
+
+/** Fragment source for one pass: prelude + input uniforms + target samplers + the template body. */
+export function buildFragment({ inputs = [], targets = [], body }) {
+  const decl = inputs.filter((i) => UNIFORM_TYPE[i.TYPE] && !["inputImage", "audio", "audioFFT"].includes(i.NAME))
+    .map((i) => `uniform ${UNIFORM_TYPE[i.TYPE]} ${i.NAME};`);
+  const tdecl = targets.map((t) => `uniform sampler2D ${t};`);
+  return `${PRELUDE_HEAD}${decl.join("\n")}\n${tdecl.join("\n")}\n${PRELUDE_HELPERS}\n#line 1\n${body}\n`;
+}
+
+/** The output pass: linear light -> sRGB with a seeded sub-LSB dither, drawn to the canvas. */
+export const OUTPUT_FRAG = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 fragColor;
+uniform sampler2D src;
+uniform int FRAMEINDEX;
+uniform float SEED;
+float h(vec2 p) { vec3 p3 = fract(vec3(p.xyx) * 0.1031 + SEED * 3.7); p3 += dot(p3, p3.yzx + 33.33); return fract((p3.x + p3.y) * p3.z); }
+vec3 toSrgb(vec3 c) { c = clamp(c, 0.0, 1.0); return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c)); }
+void main() {
+  vec3 c = toSrgb(texture(src, vUv).rgb);
+  float d = h(gl_FragCoord.xy + float(FRAMEINDEX % 64) * 7.0) - 0.5;
+  fragColor = vec4(c + d / 255.0, 1.0);
+}`;

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

@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>html, body { margin: 0; padding: 0; background: #000; overflow: hidden; } canvas { display: block; }</style>
+</head>
+<body>
+<canvas id="c"></canvas>
+<script type="module" src="/lit/engine/render.mjs"></script>
+</body>
+</html>