agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/LICENSE

@@ -0,0 +1,172 @@
+# agentvfx licence
+
+Copyright (c) 2026 Woojin Go (wjgoarxiv)
+
+Required Notice: Copyright (c) 2026 Woojin Go (https://github.com/wjgoarxiv/agentvfx)
+
+The agentvfx licence has two parts that apply together: the Additional Terms in Part 1, and the licence text in Part 2,
+which is the PolyForm Noncommercial License 1.0.0 reproduced unchanged. Part 1 adds a permission, a credit condition
+and a restriction to Part 2; it does not change any wording of Part 2. "These terms" in Part 2 means Parts 1 and 2
+together, so everything granted in Part 1 is one of "your licenses" and is subject to Acceptance, Patent Defense and
+Violations. To meet "Notices" in Part 2, give each recipient of the software this whole file, or its URL
+(https://github.com/wjgoarxiv/agentvfx/blob/main/LICENSE); the polyformproject.org URL alone is not enough.
+
+## Part 1. Additional Terms
+
+### 1. Creator permission
+
+If you are an individual (a natural person), you may run the software to render video, images and audio ("output"),
+and use that output in your own creative work for any purpose, including commercial purposes. For example, you may
+release your own music video, earn advertising, subscription, sponsorship or tip income on your own channel, or play
+the output in your own live or VJ performance.
+
+For this permission:
+
+- you count as an individual if you are a sole proprietor (for example a registered 개인사업자) or self-employed,
+  as long as the work is your own;
+- several individuals making a work together under their own names, such as a band, count as individuals together,
+  as long as none of them acts for a company or other organisation in doing so;
+- sponsored content on your own channel or in your own work is covered.
+
+This permission does not cover:
+
+- work for an employer, or on behalf of a company or other organisation (a noncommercial organisation keeps only the
+  permissions it already has in Part 2);
+- output made for someone else to publish or use as theirs, such as a client's advertisement or a deliverable for a
+  label or a brand;
+- selling, licensing or offering the software, its templates or presets, or rendering as a service, or offering output
+  on its own as a product (stock footage, loops, packs, NFTs); output may be sold only as part of a larger work of
+  your own.
+
+Any other commercial use needs a commercial licence from the licensor. Ask at
+https://github.com/wjgoarxiv/agentvfx/issues.
+
+### 2. No AI training
+
+Under any permission, you may not use the software, its source, shaders, templates or presets to train, fine-tune or
+evaluate a machine-learning model, or to build a dataset for that purpose. Using an AI agent to operate the software
+for your own use is not training and is allowed.
+
+### 3. Output
+
+As far as the law allows, you own the output you make. The licensor claims no rights in your output except in any part
+of the software or templates that the output contains. People who only watch, host, stream or receive output need no
+licence from the licensor, and they are not bound by these terms. You are, and you remain responsible for what you
+publish or hand over.
+
+### 4. Credit
+
+If you publish, stream, publicly show or give anyone output made with agentvfx, under any permission, including
+Part 2, you must credit agentvfx.
+
+By default every render burns a small "agentvfx" credit into a corner of the frame. While that credit is visible in
+what you publish, you need nothing more; do not crop, cover or edit it out.
+
+If you switch it off in the score (`"credit": { "overlay": false }`), or the output carries no on-screen credit (for
+example a web export), you must instead credit agentvfx in text where viewers can reasonably find it (the description,
+caption, credits, or a page the output links to):
+
+    Made with agentvfx by Woojin Go - https://github.com/wjgoarxiv/agentvfx
+
+Where space is short, `VFX: agentvfx (github.com/wjgoarxiv/agentvfx)` is enough. Every render writes the text credit
+to CREDIT.txt next to the film and into the MP4 metadata; leave both in place.
+
+When you give output to someone who will publish it, pass the credit on with it: leave the on-screen credit in the
+frame, or give them the text line and CREDIT.txt. The credit is a condition of every licence under these terms. A
+missing credit can be added within the period that "Violations" in Part 2 allows.
+
+### 5. Web export
+
+If you use scripts/export-web.mjs, keep the LICENSE file it writes with the exported folder.
+
+### 6. Names
+
+These terms give no right to use the name "agentvfx", the name "Woojin Go" or the agentvfx logo, except to give the
+credit in section 4 and to say truthfully where a work comes from. If you share a changed copy of the software (a fork),
+you must give it a name that does not contain "agentvfx", you must not present it as agentvfx or as made or endorsed by
+the licensor, and you must say that it is changed from agentvfx, with a link to https://github.com/wjgoarxiv/agentvfx.
+
+### 7. Earlier copies and third-party portions
+
+Copies obtained under the MIT License before 5 November 2026 keep that licence for those copies only. Every version
+this repository publishes is under these terms. Portions adapted from mexicat/pdoom-video remain under their own
+MIT License, and the capture engine copied from lit-typographic-motion is MIT in its own repository; see
+skills/agentvfx/NOTICE for the files and the notice.
+
+---
+
+Part 2 follows, unchanged.
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/skills/agentvfx/NOTICE

@@ -0,0 +1,44 @@
+agentvfx is licensed under the agentvfx licence (see LICENSE), except for the portions adapted from mexicat/pdoom-video. Those stay under the MIT License printed below, and any of them may be taken out and reused under that licence, including for commercial use.
+
+Adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), listed from the source-file header comments:
+  engine/core/util.mjs
+  engine/web/gl.mjs
+  engine/web/glsl-common.mjs
+  engine/web/scale.mjs
+  engine/node/chrome.mjs
+
+Copied and adapted from LitClaude lit-typographic-motion 1.0.45 (MIT, (c) 2026 wjgoarxiv, the same author). It stays MIT in its own repository, its pdoom-video portions keep the notice below, and the copies here are offered under the agentvfx licence:
+  engine/core/constants.mjs
+  engine/core/flash.mjs
+  engine/node/board.mjs
+  engine/node/encode.mjs
+  engine/node/frame-worker.mjs
+  engine/node/stage-capture.mjs
+  engine/node/stage-serve.mjs
+
+Anything adapted later may add to these lists; a file whose header says "MIT, see NOTICE" is covered by this notice.
+
+
+Portions of this engine are adapted from mexicat/pdoom-video
+(https://github.com/mexicat/pdoom-video), commit
+ca251e3dddda422b364385eb484b5a3593a0990d.
+
+Copyright (c) 2026 Giacomo Magnanini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/agentvfx/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: agentvfx
+description: Agent-directed, music-reactive VFX clips from an FX score. WebGL2 shader templates (psychedelic, spectrum, scope, impact, light, glitch, neo-brutalist collage and lattice), optional Blender background plates, a flash audit on every render, silent ping-pong loops, and a web export for live use in apps and sites. Use when someone asks for a VFX clip, a visualizer, a festival or stage loop, a music-reactive background, or a live shader effect for a web page.
+license: LicenseRef-agentvfx. Noncommercial use; see LICENSE for the complete terms.
+---
+
+# agentvfx
+
+You direct; the engine renders. You never write shader code for a clip. You pick a template, a preset and a few typed parameters, write them into an FX score (JSON), and the engine renders it in headless Chrome (WebGL2), encodes H.264 with ffmpeg, and audits it for flashes.
+
+Run every command from this folder (the skill root). Paths inside a score resolve against the current directory.
+
+## 1. Check the machine
+
+    node scripts/vfx.mjs doctor
+
+`ok: true` means Chrome with GPU WebGL2 and ffmpeg were found. Otherwise read `blockers` and tell the user what to install (`CHROME_PATH`, `FFMPEG_PATH`). Blender 5.x is needed only for plates (`BLENDER_PATH`).
+
+## 2. Pick a look
+
+    node scripts/vfx.mjs list            # family, template id, input kind, presets
+    node scripts/vfx.mjs list --json     # with descriptions
+
+`input` says what a template needs: `generative` (nothing), `footage` (`input.video`), or `either`. Start from a preset; change two or three parameters at most per round. Show the user the result before inventing more.
+
+## 3. Write the score
+
+Schema: `schemas/fx-score.schema.json`. Minimal:
+
+```json
+{ "version": 1, "template": "lattice", "preset": "vermilion-fine",
+  "input": { "video": "test-media/clip-01.mp4", "audio": "test-media/beat-132.mp3" },
+  "durationSec": 4, "seed": 47, "out": "my-lattice" }
+```
+
+- `durationSec` is 3–5. `seed` makes the render repeatable.
+- `params` override the preset (names and ranges come from the template's `fx.json`).
+- `bindings` tie a parameter to an audio feature (`bass`, `onset`, `beat`, `bands.N`, …) with `gain`, `offset`, `attackMs`, `releaseMs`. Keep attack on the onset frame and release short (about 60 ms): snappy reads as professional, heavy smoothing reads as a demo.
+- `hits` fire an extra template on an onset or beat; `cuts` hard-cut the stack on a beat; `stack` layers up to two templates over the base.
+- `labels` and `textStyle` set the engine's text layer (installed fonts by name; generic fallback when missing).
+
+Check it without rendering:
+
+    node scripts/vfx.mjs validate my-score.json
+
+## 4. Render and look
+
+    node scripts/vfx.mjs render my-score.json --out out/my-lattice --width 640 --height 360
+
+Preview small first (640x360), then raise the size for the final. The command prints JSON with the film path, the flash result and the stills. Open `stills/sheet.png` and every strip before you describe the clip to anyone. A render you have not looked at is not done.
+
+Every render burns a small `agentvfx` credit into a corner of the frame (switch it off with `"credit": { "overlay": false }` in the score), writes `CREDIT.txt` and puts the credit line in the MP4 metadata. Crediting agentvfx is a condition of its licence for anything published: while the on-screen credit stays in the frame nothing more is needed; if the overlay is off, or the user hands the clip on without it, the text credit must go in the post, description or credits. When you report a finished clip, give the user the line to paste:
+
+    Made with agentvfx by Woojin Go - https://github.com/wjgoarxiv/agentvfx
+
+The licence is the agentvfx licence: Additional Terms plus the PolyForm Noncommercial License 1.0.0 (see LICENSE). An individual (sole proprietors and a band of individuals included) may use the clips they render in their own work, also commercially: their own channel, sponsored content on it, music videos, their own VJ or live set. Employers, companies, client work, output made for someone else to publish, paid rendering services, selling clips or templates on their own, and AI training on the code or templates are not covered and need a commercial licence (or are not allowed). A changed copy shared with others (a fork) must carry a name without "agentvfx" and say it is changed from agentvfx. If the user's request is clearly one of those, say so before rendering. When you hand a clip over to be published, tell the user to keep the on-screen credit or pass the credit line along.
+
+## 5. Flash safety
+
+Every render carries a flash audit (general and red flashes per second, WCAG 2.3.1 style). Default mode `stage` keeps full intensity and writes `SAFETY.txt` when limits are exceeded. `"safety": { "mode": "broadcast-safe" }` enforces the limits; `"safeVariant": true` adds `film.safe.mp4` beside the full version. Tell the user plainly when a clip exceeds the limits.
+
+## 6. Background plates (optional, Blender)
+
+    node scripts/plate.mjs --scene terminalcore --shot gallery --out out/plate --width 640 --height 360 --seconds 4
+
+Procedural scenes, no downloaded assets. Use the plate's `film.mp4` as `input.video`. `--quality final` is slow (about 2 minutes per 1080p frame); ask before starting one. See `references/plates.md`.
+
+## 7. Silent loops
+
+    node scripts/loop.mjs out/my-lattice/film.mp4 reels/my-lattice.mp4 --preview reels/preview/my-lattice.webp --audit out/my-lattice/loop-flash.json
+
+Plays the clip forward then backward (no seam, no audio track) and flash-audits the loop played twice. Exit code 3 means the loop exceeds the flash limits. Reversing can double the flashes around a turn; `--hold 6` pauses six frames at each turn, which often brings such a loop back inside the limit. A red change that becomes a red flash when reversed cannot be fixed this way — say so and let the user decide.
+
+## 8. Live on a web page
+
+    node scripts/export-web.mjs lattice collage --out out/web
+
+Writes a self-contained runtime, the chosen templates and a demo page. Respects `prefers-reduced-motion`. See `references/web.md`.
+
+## Rules
+
+- Never ship or commit music you do not have the rights to redistribute. A render's motion may come from a track while the published loop stays silent.
+- References inspire; they are not copied. Do not reproduce a frame, logo, mark or font file from someone else's work.
+- Do not bundle font files. Name installed fonts; they fall back when absent.
+
+## More
+
+- `references/template-format.md` — how a template is built (`fx.json`, passes, presets, text layer).
+- `references/plates.md` — Blender plates.
+- `references/web.md` — web runtime API.

package/skills/agentvfx/engine/core/constants.mjs

@@ -0,0 +1,84 @@
+// agentvfx (agentvfx licence, see LICENSE). Adapted from lit-typographic-motion 1.0.45 engine/core/constants.mjs.
+// Every number the agentvfx engine and its gate use, in one place.
+
+export const ENGINE_COMMIT = "ca251e3dddda422b364385eb484b5a3593a0990d";
+export const ENGINE_CREDIT = `mexicat/pdoom-video ${ENGINE_COMMIT} (MIT)`;
+export const CREDIT_LINE = "Capture engine adapted from lit-typographic-motion 1.0.45, itself adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.";
+
+// ---- frame geometry ----
+export const FRAME = Object.freeze({ width: 1920, height: 1080, maxScale: 4 });
+
+// ---- exit codes (numbers kept from the source family; never renumbered) ----
+export const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  BLOCKED_NO_CHROME: 10,
+  BLOCKED_NO_WEBGL2: 11,
+  BLOCKED_NO_FFMPEG_FOR_VIDEO: 12,
+  GATE_FAIL_QA: 13,
+  SCORE_INVALID: 16,
+  STAGE_CONTRACT_ERROR: 17,
+  STAGE_NONDETERMINISTIC: 18,
+  STAGE_NETWORK_REQUEST: 19,
+  BLOCKED_ASSET_MISSING: 22,
+});
+export const EXIT_NAME = Object.freeze(Object.fromEntries(Object.entries(EXIT).map(([name, code]) => [code, name])));
+
+export const TIMELINE = Object.freeze({ defaultFps: 30, defaultSeed: 20260926, minDurationSec: 3, maxDurationSec: 5 });
+
+/** Software-rasterizer match list (case-insensitive substrings). */
+export const SOFTWARE_RENDERERS = Object.freeze([
+  "swiftshader", "llvmpipe", "softpipe", "lavapipe", "apple software renderer", "microsoft basic render driver",
+]);
+export const UNKNOWN_RENDERER = "unknown (debug-info extension unavailable)";
+
+// ---- Chrome launch ladder ----
+export const CHROME_ALWAYS = Object.freeze([
+  "--disable-background-timer-throttling", "--disable-renderer-backgrounding", "--disable-backgrounding-occluded-windows",
+]);
+export const CHROME_RUNGS = Object.freeze({
+  darwin: [["--use-angle=metal", "--enable-gpu-rasterization", "--ignore-gpu-blocklist"]],
+  linux: [["--use-angle=gl", "--enable-gpu-rasterization", "--ignore-gpu-blocklist"]],
+  win32: [["--use-angle=d3d11", "--enable-gpu-rasterization"]],
+  software: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"],
+});
+
+// ---- gate: flash audit grid and thresholds (WCAG 2.2 excursion method) ----
+export const GATE = Object.freeze({
+  flashGrid: [320, 180],
+  flashCellPx: 6,
+  flashDelta: 0.1,
+  flashDarkCeiling: 0.8,
+  flashWindowCells: [107, 60],
+  flashWindowArea: 0.25,
+  flashEdgeFrames: 3,
+  redRatio: 0.8,
+  redScale: 320,
+  redDelta: 20,
+  maxFlashesPerSecond: 3,
+  maxRedFlashesPerSecond: 3,
+  nearBlackPercentile: 0.995,
+});
+
+// ---- preview ladder ----
+export const PREVIEW = Object.freeze({
+  rungs: [
+    { width: 960, fps: 30 },
+    { width: 720, fps: 24 },
+    { width: 540, fps: 20 },
+  ],
+  minWidth: 540,
+  webpQuality: 60,
+});
+
+// ---- encode: H.264 master, BT.709 matrix and tags, tv range ----
+export const ENCODE_ARGS = Object.freeze([
+  // setparams tags the frames themselves: without it libx264 writes the matrix but leaves the
+  // primaries and transfer unspecified, whatever -color_primaries / -color_trc say.
+  "-vf", "scale=out_color_matrix=bt709:out_range=tv,format=yuv420p,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv",
+  "-c:v", "libx264", "-preset", "slow", "-crf", "16", "-tune", "grain", "-x264-params", "aq-mode=3",
+  "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-color_range", "tv",
+  "-movflags", "+faststart",
+]);
+
+export const MAX_ROUNDS = 3;

package/skills/agentvfx/engine/core/flash-constants.mjs

@@ -0,0 +1,23 @@
+// Flash audit thresholds (WCAG 2.2 general/red flash, ITU-R BT.1702-3, IRIS-style extended rule).
+export const FLASH = Object.freeze({
+  grid: [320, 180],
+  windowCells: [107, 60], // 1/3 x 1/3 of the grid
+  windowArea: 0.25,
+  edgeFrames: 1, // a window transition is judged on the single frame whose cells registered it
+  delta: 0.1,
+  darkCeiling: 0.8,
+  redRatio: 0.8,
+  redScale: 320,
+  redDelta: 20,
+  maxFlashesPerSecond: 3,
+  maxTransitionsPerSecond: 6, // BT.1702-3: more than 6 transitions (3 flashes) in any 1 s
+  extendedMinTransitions: 4,
+  extendedMaxTransitions: 6,
+  extendedSeconds: 4,
+});
+
+/** 8-bit sRGB code value to linear light. */
+export const LINEAR_LUT = Float32Array.from({ length: 256 }, (_, v) => {
+  const s = v / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+});

package/skills/agentvfx/engine/core/flash.mjs

@@ -0,0 +1,240 @@
+// Flash audit for agentvfx, adapted from lit-typographic-motion 1.0.45 engine/core/flash.mjs (MIT).
+// Pure report: frames are read, never modified (spec Amendment A1: stage mode keeps full intensity).
+//
+// Method: each RGBA frame is area-averaged onto a 320x180 linear-light grid. A flash is a pair of
+// OPPOSING luminance changes of the SAME area (WCAG 2.2 / BT.1702-3), so the test is per cell first:
+// a cell registers a transition when its luminance moves at least 0.1 from the extreme it reached
+// since its last transition, in the direction opposite to that last transition, while the darker of
+// the two is below 0.8. Continued motion the same way is not a new transition. A frame-level
+// transition exists when, on that one frame, the cells that registered a transition in one
+// direction cover more than 25% of some 1/3 x 1/3 window of the grid. Cells that brighten and
+// cells that darken in the same frame (a moving edge) never combine into a transition pair; a
+// frame where both directions fill a window counts as a single alternating transition. Red uses
+// the same method on (R-G-B)x320 over saturated-red cells (R/(R+G+B) >= 0.8). Verdicts: BT.1702-3
+// (more than 6 transitions in any 1 s), any red flash, and the IRIS-style extended rule (at least 4
+// transitions in each of 4 consecutive seconds, at any frame offset; reported alone, not folded
+// into `exceeds`).
+import { FLASH, LINEAR_LUT } from "./flash-constants.mjs";
+
+export { LINEAR_LUT };
+
+/**
+ * The audit grid for a frame: 6x6 px cells and the 640x360 window, transposed for a portrait
+ * frame (180x320 cells, a 60x107 window) so the 10-degree field keeps its size in either format.
+ */
+export function gridFor(width = 1920, height = 1080) {
+  const [gw, gh] = FLASH.grid;
+  const [ww, wh] = FLASH.windowCells;
+  return width >= height ? { gw, gh, ww, wh } : { gw: gh, gh: gw, ww: wh, wh: ww };
+}
+
+/**
+ * Per-cell hysteresis. `hi`/`lo` are the extremes since the cell's last counted transition, `last`
+ * is that transition's direction (0 = none yet). A transition counts only against `last`.
+ */
+class CellTracker {
+  constructor(cells, delta, ceiling) {
+    this.delta = delta;
+    this.ceiling = ceiling;
+    this.hi = new Float32Array(cells);
+    this.lo = new Float32Array(cells);
+    this.last = new Int8Array(cells);
+  }
+
+  start(values) {
+    this.hi.set(values);
+    this.lo.set(values);
+  }
+
+  /** Feed cell i's value; returns +1 / -1 when it counts a transition, else 0. */
+  update(i, v) {
+    const { hi, lo, last, delta, ceiling } = this;
+    let dir = 0;
+    if (last[i] !== 1 && v - lo[i] >= delta && Math.min(v, lo[i]) < ceiling) dir = 1;
+    else if (last[i] !== -1 && hi[i] - v >= delta && Math.min(v, hi[i]) < ceiling) dir = -1;
+    if (dir) {
+      hi[i] = v; lo[i] = v; last[i] = dir;
+    } else {
+      if (v > hi[i]) hi[i] = v;
+      if (v < lo[i]) lo[i] = v;
+    }
+    return dir;
+  }
+}
+
+/** Streaming detector. Each frame is { R, G, B }: linear 0..1 cell averages on the grid. */
+export class FlashDetector {
+  constructor(grid = gridFor()) {
+    const { gw, gh, ww, wh } = grid;
+    this.grid = grid;
+    this.cells = gw * gh;
+    this.windowLimit = FLASH.windowArea * ww * wh;
+    this.frames = 0;
+    this.lum = new CellTracker(this.cells, FLASH.delta, FLASH.darkCeiling);
+    this.red = new CellTracker(this.cells, FLASH.redDelta, Infinity);
+    this.prevL = new Float32Array(this.cells);
+    this.sat = new Int32Array((gw + 1) * (gh + 1));
+  }
+
+  /**
+   * Feed one frame; returns { up, down, redUp, redDown, stepArea, edge }. The four flags say that,
+   * on this frame, the cells registering a transition that way cover a window; `edge` says this
+   * frame moved any cell that way.
+   */
+  push({ R, G, B }) {
+    const CELLS = this.cells;
+    const L = new Float32Array(CELLS);
+    const V = new Float32Array(CELLS);
+    for (let i = 0; i < CELLS; i++) {
+      L[i] = 0.2126 * R[i] + 0.7152 * G[i] + 0.0722 * B[i];
+      const sum = R[i] + G[i] + B[i];
+      V[i] = sum > 0 && R[i] / sum >= FLASH.redRatio ? Math.max(0, R[i] - G[i] - B[i]) * FLASH.redScale : 0;
+    }
+    const maps = { up: new Uint8Array(CELLS), down: new Uint8Array(CELLS), redUp: new Uint8Array(CELLS), redDown: new Uint8Array(CELLS) };
+    const edge = { up: false, down: false, redUp: false, redDown: false };
+    let stepCells = 0;
+    if (this.frames === 0) {
+      this.lum.start(L);
+      this.red.start(V);
+    } else {
+      for (let i = 0; i < CELLS; i++) {
+        if (Math.abs(L[i] - this.prevL[i]) >= FLASH.delta) stepCells += 1;
+        const l = this.lum.update(i, L[i]);
+        if (l) { maps[l > 0 ? "up" : "down"][i] = 1; edge[l > 0 ? "up" : "down"] = true; }
+        const r = this.red.update(i, V[i]);
+        if (r) { maps[r > 0 ? "redUp" : "redDown"][i] = 1; edge[r > 0 ? "redUp" : "redDown"] = true; }
+      }
+    }
+    this.prevL = L;
+    this.frames += 1;
+    const result = { stepArea: +(stepCells / CELLS).toFixed(4), edge };
+    for (const dir of ["up", "down", "redUp", "redDown"]) result[dir] = edge[dir] && this.windowHit(maps[dir]);
+    return result;
+  }
+
+  // Largest window count of this frame's transition map via a summed-area table.
+  windowHit(map) {
+    const { gw: GW, gh: GH, ww: WW, wh: WH } = this.grid;
+    const sat = this.sat;
+    const stride = GW + 1;
+    for (let y = 0; y < GH; y++) {
+      let row = 0;
+      for (let x = 0; x < GW; x++) {
+        row += map[y * GW + x];
+        sat[(y + 1) * stride + x + 1] = sat[y * stride + x + 1] + row;
+      }
+    }
+    if (sat[GH * stride + GW] <= this.windowLimit) return false;
+    for (let y = 0; y + WH <= GH; y++) {
+      for (let x = 0; x + WW <= GW; x++) {
+        const count = sat[(y + WH) * stride + x + WW] - sat[y * stride + x + WW] - sat[(y + WH) * stride + x] + sat[y * stride + x];
+        if (count > this.windowLimit) return true;
+      }
+    }
+    return false;
+  }
+}
+
+/** Area-average an RGBA8 frame of any size onto its audit grid in linear light. */
+export function cellsFromRgba(bytes, width, height, lut = LINEAR_LUT, { gw: GW, gh: GH } = gridFor(width, height)) {
+  const CELLS = GW * GH;
+  const R = new Float32Array(CELLS);
+  const G = new Float32Array(CELLS);
+  const B = new Float32Array(CELLS);
+  const count = new Float32Array(CELLS);
+  for (let y = 0; y < height; y++) {
+    const cy = Math.min(GH - 1, Math.floor((y * GH) / height)) * GW;
+    for (let x = 0; x < width; x++) {
+      const c = cy + Math.min(GW - 1, Math.floor((x * GW) / width));
+      const o = (y * width + x) * 4;
+      R[c] += lut[bytes[o]];
+      G[c] += lut[bytes[o + 1]];
+      B[c] += lut[bytes[o + 2]];
+      count[c] += 1;
+    }
+  }
+  for (let i = 0; i < CELLS; i++) {
+    const n = count[i] || 1;
+    R[i] /= n; G[i] /= n; B[i] /= n;
+  }
+  return { R, G, B };
+}
+
+// Consecutive same-direction transitions collapse into one edge; an edge is one "transition".
+function edgesIn(events, start, span) {
+  let edges = 0;
+  let last = 0;
+  for (const t of events) {
+    if (t.frame < start || t.frame >= start + span || t.dir === last) continue;
+    edges += 1;
+    last = t.dir;
+  }
+  return edges;
+}
+
+function summarize(general, red, count, fps) {
+  const span = Math.round(fps);
+  let worst = { startFrame: 0, transitions: 0 };
+  for (const { frame } of general) {
+    const transitions = edgesIn(general, frame, span);
+    if (transitions > worst.transitions) worst = { startFrame: frame, transitions };
+  }
+  const perSecond = [];
+  for (let s = 0; s * span < count; s++) {
+    perSecond.push({ second: s, transitions: edgesIn(general, s * span, span), redTransitions: edgesIn(red, s * span, span) });
+  }
+  let extendedFlashing = false;
+  for (let s0 = 0; !extendedFlashing && s0 + FLASH.extendedSeconds * span <= count; s0++) {
+    extendedFlashing = Array.from({ length: FLASH.extendedSeconds }, (_, k) => edgesIn(general, s0 + k * span, span))
+      .every((n) => n >= FLASH.extendedMinTransitions);
+  }
+  const redFlashes = Math.floor(edgesIn(red, 0, count) / 2);
+  return {
+    exceeds: worst.transitions > FLASH.maxTransitionsPerSecond || redFlashes > 0,
+    worstWindow: { ...worst, startSec: +(worst.startFrame / fps).toFixed(3) },
+    flashesPerSecondMax: Math.floor(worst.transitions / 2),
+    redFlashes,
+    extendedFlashing,
+    perSecond,
+    limits: { ...FLASH, fps, frames: count },
+  };
+}
+
+// One event per frame: a lone direction is that direction; both directions filling windows on the
+// same frame (opposite areas moving against each other) is one transition, alternating with the last.
+function frameDir(up, down, last) {
+  if (up && down) return last === 1 ? -1 : 1;
+  return up ? 1 : down ? -1 : 0;
+}
+
+/**
+ * Streaming auditor: push RGBA frames one at a time (only transition events are kept, never the
+ * frames), then finish() for the report. Reports only; the pushed bytes are not modified.
+ */
+export function createFlashAuditor({ fps, width, height }) {
+  if (!(Number.isFinite(fps) && fps > 0)) throw new TypeError("createFlashAuditor: fps must be a positive number");
+  const grid = gridFor(width, height);
+  const detector = new FlashDetector(grid);
+  const general = [];
+  const red = [];
+  return {
+    push(frame) {
+      const frameIndex = detector.frames;
+      const r = detector.push(cellsFromRgba(frame.data, frame.width, frame.height, LINEAR_LUT, grid));
+      const dir = frameDir(r.up, r.down, general.at(-1)?.dir ?? 0);
+      if (dir) general.push({ frame: frameIndex, dir });
+      const redDir = frameDir(r.redUp, r.redDown, red.at(-1)?.dir ?? 0);
+      if (redDir) red.push({ frame: frameIndex, dir: redDir });
+    },
+    finish: () => summarize(general, red, detector.frames, fps),
+  };
+}
+
+/** Audit a whole frame sequence ({ width, height, data } RGBA sRGB) at `fps`. */
+export function auditFlash(frames, { fps }) {
+  if (!(Number.isFinite(fps) && fps > 0)) throw new TypeError("auditFlash: fps must be a positive number");
+  const first = frames[0] ?? { width: 1920, height: 1080 };
+  const auditor = createFlashAuditor({ fps, width: first.width, height: first.height });
+  for (const frame of frames) auditor.push(frame);
+  return auditor.finish();
+}