agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/plates/terminalcore/textures.py

@@ -0,0 +1,79 @@
+"""Procedural terminal-screen images (bitmap font drawn by font.py, text composed here). No external assets."""
+import random
+
+import bpy
+import numpy as np
+
+from font import glyph
+
+W, H = 768, 1152
+CW, CH, PX = 12, 18, 2
+COLS, ROWS = W // CW, H // CH
+
+_WORDS = ["SYNC", "NODE", "LINK", "RELAY", "CARRIER", "BUFFER", "PHASE", "VECTOR", "SIGNAL", "KERNEL", "UPLINK",
+          "TRACE", "DAEMON", "CACHE", "SECTOR", "ARRAY", "RASTER", "BEACON", "LATCH", "OSC", "MUX", "DECK"]
+_STATE = ["OK", "OK", "OK", "LOCKED", "NOMINAL", "DRIFT", "WARN", "STANDBY", "ARMED", "OK"]
+
+
+def _hex(rng, n):
+    return "".join(rng.choice("0123456789ABCDEF") for _ in range(n))
+
+
+def _line(rng, kind):
+    if kind == 0:
+        return f"[{rng.randint(0, 9999):04d}.{rng.randint(0, 99):02d}] {rng.choice(_WORDS)}_{rng.randint(0, 31):02d} {rng.choice(_STATE)} 0x{_hex(rng, 6)}"
+    if kind == 1:
+        return f"0x{_hex(rng, 4)}: " + " ".join(_hex(rng, 2) for _ in range(rng.randint(8, 14)))
+    if kind == 2:
+        n = rng.randint(0, 20)
+        return f"> {rng.choice(_WORDS)} --{rng.choice(_WORDS).lower()} [{'#' * n}{'.' * (20 - n)}] {n * 5:3d}%"
+    if kind == 3:
+        return f"{rng.choice(_WORDS)}.{rng.choice(_WORDS)} = {rng.random() * 100:7.3f} // {rng.choice(_STATE)}"
+    return ""
+
+
+def _draw_char(buf, ch, col, row):
+    g = glyph(ch)
+    y0, x0 = row * CH + 2, col * CW
+    for gy, r in enumerate(g):
+        for gx, v in enumerate(r):
+            if v:
+                buf[y0 + gy * PX:y0 + gy * PX + PX, x0 + gx * PX:x0 + gx * PX + PX] = 1.0
+
+
+def _blur(a):
+    a = a + 0.5 * (np.roll(a, 1, 0) + np.roll(a, -1, 0))
+    a = a + 0.5 * (np.roll(a, 1, 1) + np.roll(a, -1, 1))
+    return a / 4.0
+
+
+def terminal_pixels(seed, density=0.75):
+    """Float luminance image HxW (top row first) holding a wrapping scroll of fake terminal output."""
+    rng = random.Random(seed)
+    buf = np.zeros((H, W), dtype=np.float32)
+    for row in range(ROWS):
+        if rng.random() > density:
+            continue
+        kind = rng.choice([0, 0, 1, 1, 2, 3])
+        indent = 3 + rng.choice([0, 0, 0, 2, 4])
+        text = (" " * indent + _line(rng, kind))[:COLS - 5]
+        bright = 1.0 if rng.random() > 0.2 else 0.55
+        row_buf = np.zeros_like(buf)
+        for col, ch in enumerate(text):
+            if ch != " ":
+                _draw_char(row_buf, ch, col, row)
+        buf = np.maximum(buf, row_buf * bright)
+    _draw_char(buf, "BLOCK", rng.randint(4, 30), 20)
+    return np.clip(_blur(buf) * 1.35, 0.0, 1.0)
+
+
+def make_image(name, seed, density=0.75):
+    pix = terminal_pixels(seed, density)
+    rgba = np.repeat(np.flipud(pix)[:, :, None], 4, axis=2)
+    rgba[:, :, 3] = 1.0
+    img = bpy.data.images.new(name, W, H, alpha=False, float_buffer=False)
+    img.colorspace_settings.name = "Non-Color"
+    img.pixels.foreach_set(rgba.ravel())
+    img.update()
+    img.pack()
+    return img

package/skills/agentvfx/plates/terminalcore/wall.py

@@ -0,0 +1,103 @@
+"""The CRT bank: rack frame, instanced monitors with per-object screen variants, status LEDs, cable tray + cables."""
+import math
+import random
+
+import bpy
+
+import crt
+from crt import SLOT_PLASTIC, SLOT_GLASS, SLOT_VENT, SLOT_STEEL, SLOT_LED
+from room import add_box
+
+COLS, ROWS = 9, 5
+BAY, PITCH, BASE_Z = 0.56, 0.5, 0.24
+FRONT_Y = -0.05
+HERO = (2, 4)  # row, column of the monitor the close-up shot holds on
+
+# (image seed, tint, strength, rows per second) ; None image = unpowered glass
+VARIANTS = {
+    "green_a": (11, (0.20, 1.00, 0.34), 6.0, 5.0),
+    "green_b": (23, (0.28, 1.00, 0.40), 5.5, 2.5),
+    "amber": (37, (1.00, 0.52, 0.07), 6.5, 3.5),
+    "cold": (51, (0.62, 0.85, 1.00), 5.0, 6.0),
+}
+WEIGHTS = ["green_a"] * 5 + ["green_b"] * 4 + ["amber"] * 4 + ["cold"] * 2 + [None] * 3
+
+
+def monitor_position(r, c):
+    x0 = -(COLS - 1) / 2 * BAY
+    return x0 + c * BAY, FRONT_Y, BASE_Z + r * PITCH + PITCH / 2
+
+
+def build_rack(coll, mats):
+    x0 = -(COLS - 1) / 2 * BAY - BAY / 2
+    height = ROWS * PITCH
+    for k in range(COLS + 1):
+        add_box(coll, f"post_{k}", (x0 + k * BAY, 0.22, BASE_Z + height / 2), (0.04, 0.54, height), mats["steel"], 0.004)
+    for r in range(ROWS + 1):
+        add_box(coll, f"shelf_{r}", (0, 0.22, BASE_Z + r * PITCH), (COLS * BAY, 0.54, 0.018), mats["steel"], 0.003)
+
+
+def build_monitors(coll, mats, screens, rng):
+    mesh, _ = crt.build_crt_mesh()
+    for m in (mats["plastic"], mats["glass_base"], mats["vent"], mats["steel"], mats["led"]):
+        mesh.materials.append(m)
+    objs = {}
+    for r in range(ROWS):
+        for c in range(COLS):
+            ob = bpy.data.objects.new(f"crt_{r}_{c}", mesh)
+            x, y, _ = monitor_position(r, c)
+            s = rng.uniform(0.9, 1.06)
+            ob.location = (x + rng.uniform(-0.012, 0.012), y + (0.0 if rng.random() > 0.2 else rng.uniform(0.0, 0.06)), BASE_Z + r * PITCH + 0.22 * s)
+            ob.rotation_euler = (0, 0, math.radians(rng.uniform(-2.2, 2.2)))
+            ob.scale = (s, s, s)
+            coll.objects.link(ob)
+            key = "green_a" if (r, c) == HERO else rng.choice(WEIGHTS)
+            slot = ob.material_slots[SLOT_GLASS]
+            slot.link = "OBJECT"
+            slot.material = screens[key] if key else mats["glass_off"]
+            objs[(r, c)] = ob
+    return objs
+
+
+def build_tray_and_cables(coll, mats, rng):
+    steel, rub = mats["steel"], mats["rubber"]
+    tray_z, tray_y = 3.02, -0.55
+    for side in (-0.2, 0.2):
+        add_box(coll, "tray_rail", (0, tray_y + side, tray_z), (5.6, 0.03, 0.09), steel, 0.004)
+    for i in range(46):
+        add_box(coll, "tray_rung", (-2.7 + i * 0.118, tray_y, tray_z - 0.04), (0.025, 0.44, 0.012), steel, 0.002)
+    for i in range(6):
+        pts = [(-2.8 + j * 1.12, tray_y + rng.uniform(-0.12, 0.12), tray_z + 0.02 + rng.uniform(0, 0.05)) for j in range(6)]
+        crt.add_cable(f"bundle_{i}", pts, rng.uniform(0.016, 0.026), rub, coll, seed=i, sag=0.03)
+    x0 = -(COLS - 1) / 2 * BAY - BAY / 2
+    for k in (1, 3, 4, 6, 8):
+        x = x0 + k * BAY
+        bottom = BASE_Z + rng.choice([1, 2, 3]) * PITCH
+        pts = [(x - 0.02, tray_y, tray_z), (x - 0.02, -0.25, tray_z - 0.25), (x + 0.015, FRONT_Y - 0.06, tray_z - 0.7),
+               (x + 0.02, FRONT_Y - 0.06, (tray_z + bottom) / 2), (x, FRONT_Y - 0.05, bottom + 0.1), (x, 0.25, bottom - 0.02)]
+        crt.add_cable(f"drop_{k}", pts, rng.uniform(0.014, 0.022), rub, coll, seed=k, sag=0.0)
+    for i in range(4):
+        x = rng.uniform(-1.6, 1.6)
+        pts = [(x, -1.15, 0.3), (x + rng.uniform(-0.3, 0.3), -1.4, 0.03), (x + rng.uniform(-1, 1), -2.2, 0.02),
+               (x + rng.uniform(-1.6, 1.6), -3.2, 0.02), (x + rng.uniform(-2, 2), -4.4, 0.02), (x + rng.uniform(-2, 2), -6.0, 0.02)]
+        crt.add_cable(f"floor_{i}", pts, rng.uniform(0.02, 0.034), rub, coll, seed=40 + i, sag=0.0)
+
+
+def build_status_array(coll, mats, rng):
+    """Rows of tiny status LEDs set into the lintel face."""
+    me = bpy.data.meshes.new("led_chip")
+    import bmesh
+    bm = bmesh.new()
+    bmesh.ops.create_cube(bm, size=1.0)
+    bm.to_mesh(me)
+    bm.free()
+    me.materials.append(mats["led"])
+    y_face = -0.35 - 0.975
+    for row in range(3):
+        for i in range(48):
+            if rng.random() < 0.3:
+                continue
+            ob = bpy.data.objects.new("led", me)
+            ob.scale = (0.014, 0.004, 0.009)
+            ob.location = (-2.6 + i * 0.11 + (0.5 if i % 12 > 5 else 0) * 0.0, y_face - 0.002, 3.28 + row * 0.1)
+            coll.objects.link(ob)

package/skills/agentvfx/references/plates.md

@@ -0,0 +1,22 @@
+# Plates: Blender-rendered background footage
+
+A plate is a short procedural Blender render used as `input.video` footage under an agentvfx template.
+Scenes live in `plates/<scene>/scene.py`; `scripts/plate.mjs` runs Blender headless (Cycles, Metal GPU, OIDN denoise),
+then encodes the frames to H.264 `film.mp4` with ffmpeg.
+
+    node scripts/plate.mjs --scene terminalcore --shot wall|closeup|gallery --out <dir> \
+         --width 640 --height 360 --seconds 4 --fps 30 --samples 40
+
+- Output: `<dir>/film.mp4`, `still_first|mid|last.png`, `plate.json` (measured s/frame), `blender.log`.
+- `--frame N` renders a single still for look-dev; `--quality preview|final`, `--exposure`, `--bloom`, `--key`, `--haze` tune the grade.
+- Requirements: Blender 5.x (`BLENDER_PATH` or the macOS app bundle) and ffmpeg (`FFMPEG_PATH` or `PATH`).
+- Everything is generated in code (geometry, shaders, bitmap font, terminal text); no downloaded assets.
+- Preview defaults are small and fast (`--quality preview`). For finals add `--quality final` and raise `--width/--height`:
+  256 samples, accurate denoise, camera motion blur (camera keyframed per frame), crf 14. Gallery at 1920x1080 final measured
+  about 109 s/frame (one test frame). Time scales with pixels x samples; schedule full finals deliberately.
+
+Available scenes: `terminalcore` (see `plates/terminalcore/README.md`), shots `wall` and `closeup` (dark brutalist, handheld)
+and `gallery` (clean hyper-real concrete exhibition room, CRT wall as an installation, steady dolly, lighter grain; own
+exposure/haze/bloom defaults). Example: `--shot gallery --out gallery/plates/terminalcore-gallery` (measured 2.0 s/frame at 640x360, 56 samples, Metal GPU: 240 s for 120 frames).
+Adding a scene: create `plates/<name>/scene.py` that accepts the same `--shot --out --width --height --seconds --fps --samples --frame` args
+and writes numbered PNGs to `<out>/frames/f_####.png` (or `<out>/still_NNN.png` with `--frame`).

package/skills/agentvfx/references/template-format.md

@@ -0,0 +1,149 @@
+# Template format
+
+A template is a folder `templates/<family>/<id>/` with:
+
+- `fx.json`: ISF 2.0-compatible JSON plus one namespaced key `X_AGENTVFX`
+- `main.frag`: the last (or only) pass
+- optional `pass0.frag`, `pass1.frag`, ...: earlier passes, in `PASSES` order
+- optional `demo-<preset>.json`: FX scores that render the gallery clips
+
+`vfx.mjs validate` checks every template; `vfx.mjs list` shows them.
+
+## fx.json
+
+```json
+{
+  "DESCRIPTION": "one line: what it looks like",
+  "CREDIT": "agentvfx",
+  "ISFVSN": "2",
+  "CATEGORIES": ["psychedelic"],
+  "INPUTS": [
+    { "NAME": "tideSpeed", "TYPE": "float", "MIN": 0, "MAX": 3, "DEFAULT": 0.6 },
+    { "NAME": "tideWaves", "TYPE": "long", "MIN": 1, "MAX": 3, "DEFAULT": 2 },
+    { "NAME": "halo", "TYPE": "bool", "DEFAULT": false },
+    { "NAME": "tint", "TYPE": "color", "DEFAULT": [1, 0, 0.5, 1] },
+    { "NAME": "center", "TYPE": "point2D", "DEFAULT": [0.5, 0.5] }
+  ],
+  "PASSES": [
+    { "TARGET": "smoothLuma", "FLOAT": true },
+    { "TARGET": "trail", "PERSISTENT": true, "FLOAT": true },
+    {}
+  ],
+  "X_AGENTVFX": {
+    "id": "sacred",
+    "family": "psychedelic",
+    "input": "footage",
+    "spdx": "LicenseRef-agentvfx",
+    "flash": "none",
+    "fps": 30,
+    "palette": true,
+    "presets": { "a": { "tideSpeed": 0.4 }, "b": {}, "c": {} },
+    "audioBind": { "tideSpeed": "bass" },
+    "safeSubstitute": { "params": { "flashAmount": 0 } },
+    "credits": ["iq cosine palette, https://iquilezles.org/articles/palettes/"]
+  }
+}
+```
+
+- INPUT types: `float`, `long` (int; optional `VALUES` / `LABELS`), `bool`, `color` (`[r,g,b,a]` 0..1, sRGB),
+  `point2D`, `image`, `audio`, `audioFFT`.
+- `X_AGENTVFX.input`: `generative` (no clip), `footage` (needs `input.video`), `either`.
+- `spdx`: LicenseRef-agentvfx (the agentvfx licence, the library's own), MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or CC0-1.0 only. Shaders are written fresh;
+  algorithms are credited by name and URL in `credits` and in comments. No Shadertoy ports, no Lygia, no
+  hydra-synth, no MilkDrop presets.
+- `flash`: `none`, `possible` (can flash at some settings) or `strobe` (flashes by design).
+- At least 3 presets. Preset values are range-checked against `INPUTS`.
+
+## Passes
+
+With no `PASSES`, `main.frag` is the only pass. With `PASSES`, pass *i* is `pass<i>.frag`, except the
+last, which is `main.frag`. A pass with `TARGET` renders into a named buffer that every later pass
+(and, if `PERSISTENT`, every pass of the next frame) can sample as `uniform sampler2D <TARGET>`.
+Buffers are RGBA16F (`FLOAT` is accepted for ISF compatibility; all buffers are float). A persistent
+buffer holds the previous frame's value when it is read before it is written in the current frame.
+Frames are rendered strictly in order, so persistent buffers are deterministic.
+
+## The prelude (prepended to every pass by the engine; do not redeclare)
+
+```glsl
+#version 300 es
+precision highp float; precision highp int; precision highp sampler2D;
+in vec2 vUv;                 // 0..1, origin bottom-left
+out vec4 fragColor;          // LINEAR-light RGB, alpha 1
+uniform float TIME;          // seconds = FRAMEINDEX / fps
+uniform float TIMEDELTA;     // 1 / fps
+uniform int FRAMEINDEX;
+uniform int PASSINDEX;
+uniform vec2 RENDERSIZE;     // pixels of the current pass target
+uniform float SEED;          // 0..1 from the score seed
+uniform sampler2D inputImage;    // footage frame or the layer below; linear light; black when absent
+uniform bool HAS_INPUT;
+uniform vec3 PALETTE[8];     // linear light, from the score palette (or the template default)
+uniform int PALETTE_COUNT;
+// audio (zero when no audio): per frame, normalised as in references/audio.md
+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;     // 512x2: row 0 = wave L/mono, row 1 = wave R, values 0..1 (0.5 = silence)
+uniform sampler2D audioFFT;  // 512x1 spectrum 0..1, low to high
+uniform float AUDIO_BANDS[32];
+#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))
+```
+
+Each declared INPUT becomes a uniform of the same name: float → `float`, long → `int`, bool → `bool`,
+color → `vec4` (converted to linear), point2D → `vec2`, image/audio/audioFFT → `sampler2D`.
+
+## Common helpers (also in the prelude)
+
+```glsl
+float hash12(vec2 p);            // seeded by SEED, 0..1
+vec2  hash22(vec2 p);
+float vnoise(vec2 p);            // value noise 0..1
+float fbm(vec2 p, int octaves);  // 0..1
+float luma(vec3 linRgb);         // Rec.709 luminance of linear RGB
+vec3  rgb2hsv(vec3 c);  vec3 hsv2rgb(vec3 c);   // on linear values; fine for effects
+vec3  cosPalette(float t, vec3 a, vec3 b, vec3 c, vec3 d);  // iq: a + b*cos(6.28318*(c*t + d))
+vec3  paletteRamp(float t);      // PALETTE as a clamped ramp, t 0..1
+vec3  paletteCycle(float t);     // PALETTE as a cyclic ramp, t wraps
+vec3  srgbToLinear(vec3 c);  vec3 linearToSrgb(vec3 c);
+mat2  rot(float a);
+```
+
+The engine converts the last pass's linear output to sRGB with blue-noise dither before readback.
+No `#version` line, no `precision` line and no `out` declaration in template files.
+
+## Text layer (engine-drawn type)
+
+A template may declare `X_AGENTVFX.text`: a list of text items the engine draws every frame with Canvas 2D and
+system fonts into `uniform sampler2D TEXTMASK` (R = glyph and line ink, G = solid box/bar fill; `HAS_TEXT` is
+true). The template colours the mask (e.g. `mix(bg, ink, m.r)`). Scores override strings with
+`"labels": { "<key>": "..." }`.
+
+```json
+"text": [
+  { "key": "artist", "default": "ARTIST NAME", "x": 0.03, "y": 0.06, "size": 0.07, "font": "display", "style": "outline", "box": "tab" },
+  { "key": "title", "default": "TRACK TITLE", "x": 0.97, "y": 0.05, "size": 0.09, "font": "tall", "align": "right" },
+  { "key": "log", "default": "BOOT 0x7G75\nCACHE OK", "x": 0.1, "y": 0.2, "size": 0.025, "font": "mono", "reveal": "type", "revealStart": 0, "revealDur": 2 },
+  { "key": "tag", "default": "HEADLINE", "x": 0.5, "y": 0.45, "size": 0.12, "font": "grotesk", "align": "center", "box": "bar" }
+]
+```
+
+- `x`, `y`: top-left of the block as fractions of the frame (align moves the anchor); `size`: cap size as a fraction of frame height.
+- `font`: `display` (condensed, DIN-like), `tall` (ultra-tall thin condensed), `grotesk` (heavy Helvetica-like), `mono` (Menlo-like), `serif`.
+- `style`: `fill` or `outline`; `box`: `none`, `frame` (rounded outline), `tab` (outline with a folder tab), `bar` (solid fill in G).
+- `reveal`: `none`, `type` (typewriter with a block cursor), `decode` (seeded random glyphs settle left to right) over `revealStart` .. `revealStart + revealDur` seconds. Deterministic per frame and seed.
+- `\n` makes new lines; `lineHeight` (default 1.15), `tracking` (em).
+- `family`: an installed font family named directly, e.g. `"family": "Pretendard", "weight": 900` (also accepted in `textStyle`). The CSS stack becomes `"<family>", <the generic stack of `font`>`, so on a machine without that family the item silently falls back to the generic `font` (`display`, `tall`, `grotesk`, `mono`, `serif`); `font` still decides the vertical stretch (`tall`) and the fallback. Names are limited to letters, digits, spaces, `.`, `_`, `-` (up to 64 characters). The engine waits for the face to resolve (`document.fonts.load`) before the first frame. Only the font name is referenced: no font file is read, copied or bundled by the skill, and nothing here grants a licence for any font. Installed on the author's Mac and used by the collage experimental presets: `Monument Extended` (weights 400 / 800; commercial font, licensed to the user, never redistribute it with this skill), `Pretendard` (100..900, Hangul and Latin; SIL OFL 1.1) and `MesloLGS NF` (monospace, Apache-2.0). Glyph widths differ per font, so a layout tuned for one face moves a little when the fallback is used.
+- `channel`: `r` (default), `g` or `b`. The glyph ink goes into that mask channel, so a template can keep up to three independent sheets of type that overlap on the page and read each one with `TEXTMASK.r / .g / .b`. (`box: "bar"` fill always goes to G, so keep box items off the `g` sheet.)
+- `set`: integer 0..9 (default 0). A template that declares any item with a `set` draws only the items whose `set` equals its `textSet` input (an INPUT of type long, default 0), so presets can each own a whole text sheet without sharing page space. Templates without `set` items are unaffected.
+- A score may restyle any declared item without editing the template: `"textStyle": { "<key>": { "font": "mono", "size": 0.12, "x": 0.05, "y": 0.6, "tracking": 0.1, "align": "left", "weight": 700 } }` (every field optional; merged over the template's item; unknown keys, fonts and out-of-range values are validation errors). `labels` changes the string, `textStyle` the look.
+- System fonts only; nothing is bundled. Text never quotes third-party marks or slogans.
+
+## House style
+
+Defaults are aggressive and stage-grade (spec Amendment A1): saturated colour, hard contrast, strobe,
+glitch and noise at full strength. Never tame a default. A gentler look is a preset, not the default.

package/skills/agentvfx/references/web.md

@@ -0,0 +1,63 @@
+# agentvfx on a page
+
+`node scripts/export-web.mjs <templateId...> --out <dir>` writes three files and nothing else:
+
+- `agentvfx.js` — the WebGL2 runtime, with the engine prelude inlined
+- `templates.js` — `export default { <id>: { fx, passes } }` for the ids you named
+- `demo.html` — a hero canvas, a hit button, an audio file input, and a text headline
+
+The folder loads from disk. It does not fetch fonts, scripts, or media. Copy it into the site and import it as a module.
+
+```js
+import { AgentVfx } from "./agentvfx.js";
+import templates from "./templates.js";
+
+const fx = await AgentVfx.mount(canvas, {
+  templates,
+  template: "sacred",
+  preset: "sacred-classic",
+  params: { tideSpeed: 0.4 },
+  palette: "rainbow",
+  source: image,
+  dpr: 1,
+});
+```
+
+`source` may be omitted (generative), an `<img>`, a `<video>`, or another canvas. `AgentVfx.textSource({ text, font, color, background, width, height })` returns a canvas you can pass as `source`.
+
+`fx.set(params)` replaces input values. `fx.trigger(id, { preset, params, durationMs })` draws that template over the current frame for `durationMs` (default 400). `fx.audio(elementOrStream)` connects an AnalyserNode and fills `AUDIO_*`, the 512×2 `audio` wave texture, the 512×1 `audioFFT` texture, and `AUDIO_BANDS[32]`. `fx.pause()`, `fx.resume()`, and `fx.destroy()` stop, continue, and release the context. `fx.renderAt(t)` paints one frame at time `t` in seconds and holds it, for tests and stills.
+
+The canvas backing store follows its CSS size times `devicePixelRatio`, capped at `dpr` (default 1.5). A `ResizeObserver` rebuilds the targets. An `IntersectionObserver` pauses the loop when the canvas is fully off screen. A lost WebGL context is restored on `webglcontextrestored`.
+
+`prefers-reduced-motion: reduce` paints one still frame and ignores `trigger()`, unless `motion: "always"` is set. A template whose `X_AGENTVFX.flash` is `"strobe"` logs one `console.warn` that names WCAG 2.3.1. The effect still runs when motion is allowed.
+
+Live flash guard. Every shown frame is read back on the render audit's grid and checked with the audit's own detector. A frame that would make a seventh luminance transition, or a second saturated-red transition, within one second is replaced by the previous frame before the browser shows it; motion then stops, the runtime logs a `console.warn`, and calls `onFlashGuard({ template, reason, shownTransitions, shownRedTransitions })` if you passed one to `mount`. `fx.resume()` starts again with a fresh guard. A good handler resets the parameters the visitor changed and resumes once, and falls back to a still or an audited video loop if it trips again. Sliders, pointer mappings and hits can all push a template past the limit even with its `safeSubstitute` values, so keep the guard on; `flashGuard: false` turns it off for a page that does its own checking. The guard costs one small readback per shown frame. If a pass fails to compile, the runtime logs `console.error` with the template id and the pass, clears the canvas, and does not throw into the page.
+
+## Recipes
+
+Hero background. Fix the canvas to the viewport, `pointer-events: none`, and mount a generative or footage template behind the copy. Cap `dpr` at 1 on a full-bleed 4K wall if the GPU falls behind; the default cap is 1.5.
+
+```html
+<canvas id="hero" style="position:fixed;inset:0;width:100%;height:100%;pointer-events:none"></canvas>
+```
+
+Section transition. On the way into a section, `trigger` a short hit (a few hundred milliseconds) and `set` the base template's mix or speed. Remove the hit by letting `durationMs` end. Do not leave a second canvas running for a transition that is already over; call `destroy()` if the section unmounts.
+
+Hover glitch on a button. Keep the button as a real `<button>` above the canvas. On `pointerenter` and `click`, call `trigger` with a short `durationMs`. The canvas itself stays `pointer-events: none` so the button still receives the click. Under reduced motion the hit does not fire.
+
+Glitch or decode headline. Draw the words with `textSource` and pass that canvas as `source` on a small canvas sitting over the heading box. The DOM heading stays in the document for selection and screen readers; the canvas is decorative.
+
+```js
+const plate = AgentVfx.textSource({ text: "AGENTVFX", font: "700 64px sans-serif", color: "#fff", background: "#000", width: 960, height: 180 });
+await AgentVfx.mount(headCanvas, { templates, template: "sacred", source: plate });
+```
+
+Audio-reactive player. Point `<audio>` at a file the visitor picked, or at a same-origin file, then `fx.audio(audio)`. The element must be allowed to play (a click or the file input). The runtime reconnects the element through the AnalyserNode so the sound still comes out of the speakers.
+
+Image hover Sacred. Mount Sacred with the `<img>` as `source` on a canvas that covers the image. On `pointerenter`, `set` a faster `tideSpeed` or `trigger` a short hit; on `pointerleave`, `set` the quiet preset back. The `<img>` can stay in the page underneath, with the canvas `pointer-events: none` except when the canvas is the control.
+
+Performance budget. One live canvas per view, not one per card, unless the extras are paused. The loop stops off screen. Prefer `dpr: 1` for a full-viewport hero and the default 1.5 cap for a small headline. Persistent buffers are RGBA16F at the canvas size, so a 4K canvas is expensive; scale the CSS box down rather than uploading a 4K source and displaying it small. `pause()` when a tab or modal hides the effect. `destroy()` on teardown.
+
+## with frontend-ui-ux
+
+Put the canvas on its own layer: `position: absolute` or `fixed`, inset to the frame it decorates. `pointer-events: none` unless that canvas is the control the person is meant to use. DOM text, buttons, and links sit above it and stay readable; do not run a full-frame strobe under body copy without a still fallback. The effect never blocks input. Size the canvas to the section, not the document, and let the off-screen pause drop the work when the section scrolls away. Reduced motion is the default. `motion: "always"` is an explicit author choice, not the layout default.