@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/skills/lit-typographic-motion/engine/core/constants.mjs

@@ -0,0 +1,211 @@
+// Every number the lit-typographic-motion engine and its QA gate use, in one place.
+//
+// Rule ids refer to the LitFamily motion spec (MO-A engine/runtime, MO-SH shader passes,
+// MO-B presets, MO-FT fonts, MO-C gate/routing, MO-D addenda). Numbers marked PROVISIONAL
+// are the spec's [NEW] defaults: the spec asked for a user nod that has not been recorded,
+// so they are implemented exactly as written and reported as provisional. Do not tune them
+// here to make a render pass; fix the render.
+
+/** Ids whose numbers are [NEW] defaults awaiting sign-off. The report labels them. */
+export const PROVISIONAL_RULES = Object.freeze([
+  "MO-C-05", "MO-C-06", "MO-C-07", "MO-C-08", "MO-C-13", "MO-C-14", "MO-C-25", "MO-C-29",
+  "MO-D-02", "MO-D-03", "MO-D-04",
+]);
+
+export const ENGINE_COMMIT = "ca251e3dddda422b364385eb484b5a3593a0990d";
+export const ENGINE_CREDIT = `mexicat/pdoom-video ${ENGINE_COMMIT} (MIT)`;
+export const CREDIT_LINE = "Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.";
+
+// ---- frame geometry (logical 1080p; --scale N multiplies the physical size) ----
+export const FRAME = Object.freeze({ width: 1920, height: 1080, maxScale: 4 });
+
+// ---- exit codes (MO-A-45, plus 16-20 for the treatment, the stage path and sound) ----
+export const EXIT = Object.freeze({
+  OK: 0,
+  BLOCKED_NO_CHROME: 10,
+  BLOCKED_NO_WEBGL2: 11,
+  BLOCKED_NO_FFMPEG_FOR_VIDEO: 12,
+  GATE_FAIL_QA: 13,
+  BLOCKED_DEPS_NOT_PREWARMED: 14,
+  BLOCKED_FONT_FETCH: 15,
+  // Director wave (family-wide numbers; never renumbered).
+  BLOCKED_TREATMENT_INVALID: 16,
+  STAGE_CONTRACT_ERROR: 17,
+  STAGE_NONDETERMINISTIC: 18,
+  STAGE_NETWORK_REQUEST: 19,
+  SOUND_INVALID: 20,
+  USAGE: 2,
+});
+export const EXIT_NAME = Object.freeze(Object.fromEntries(Object.entries(EXIT).map(([name, code]) => [code, name])));
+
+// ---- timeline (MO-A-09..16, MO-C-07/08) ----
+export const TIMELINE = Object.freeze({
+  generatorMargin: 1.25, // MO-A-09/10: Tier-1 hold = 1.25 x floor(unit)
+  defaultBpm: 100, // MO-A-14
+  snapToleranceFrames: 1, // MO-A-15 (<= 1 frame at 60 fps)
+  minSceneBeats: 2, // MO-A-16
+  defaultFps: 60,
+  defaultSeed: 20260926,
+});
+
+// One reading-floor function (MO-C-07/08, MO-A-11/12, MO-FT-06). PROVISIONAL.
+export const READING = Object.freeze({
+  secondsPerHangulSyllable: 0.2, // MO-C-08
+  wordsPerSecond: 3.3, // MO-C-07
+  lineFloorLatin: 0.9, // MO-A-11
+  lineFloorHangul: 1.0, // MO-A-11
+  wordFloor: 0.5, // MO-FT-06
+  revealFloor: 0.35, // MO-A-12
+  maxCharsPerSecond: 17, // MO-C-07 cross-check, line/scene only
+});
+
+// ---- sampling (MO-A-26..28) ----
+export const SAMPLING = Object.freeze({
+  masterSamples: 4,
+  masterShutter: 0.5,
+  previewSamples: 1,
+  stillSamples: 1,
+});
+
+// ---- post chain override contract (MO-A-58): range and neutral value per field ----
+export const POST_FIELDS = Object.freeze({
+  exposure: { min: 0, max: Infinity, neutral: 1, exclusiveMin: true },
+  bloom: { min: 0, max: 1, neutral: 0 },
+  bloomThreshold: { min: 0, max: 1, neutral: 0.85 },
+  bloomKnee: { min: 0, max: 1, neutral: 0 },
+  bloomRadius: { min: 0, max: 1, neutral: 0 },
+  halation: { min: 0, max: 1, neutral: 0 },
+  ca: { min: 0, max: Infinity, neutral: 0 },
+  grain: { min: 0, max: 1, neutral: 0 },
+  vignette: { min: 0, max: 1, neutral: 0 },
+  fade: { min: 0, max: 1, neutral: 1 },
+  flash: { min: 0, max: 1, neutral: 0 },
+  shake: { pair: true, neutral: [0, 0] },
+  zoom: { min: 0, max: Infinity, neutral: 1, exclusiveMin: true },
+  invert: { boolean: true, neutral: false },
+});
+export const POST_ORDER = Object.freeze(["bloom+halation", "ca", "tone-shoulder", "grain", "vignette", "flash", "shake/zoom", "invert"]);
+export const FLASH_EVENT_THRESHOLD = 0.1; // MO-A-58: each rise of `flash` above 0.1 is one event
+
+// ---- shader passes (MO-SH) ----
+export const PASS_IDS = Object.freeze(["glitch", "tidal-gradient", "crt", "dither", "swiss-grid", "terminal-ui"]);
+export const SHADER = Object.freeze({
+  eventsPerSecondPerShot: 2, // MO-SH-03: <= 2 events in any 1 s window per shot, all sources
+  fullFrameStepDelta: 0.1, // MO-SH-04a
+  fullFrameStepArea: 0.25,
+  glitchHitRateCap: 2.0, // MO-SH-05
+  glitchAreaCapPct: 20,
+  surgeRateCap: 2, // MO-SH-06
+  surgeAttackFloor: 0.1,
+  surgeDecayFloor: 0.1,
+  crtFlickerCap: 0.06, // MO-SH-07
+  terminalLayerCap: 2, // MO-SH-11
+  softwareOctaves: (octaves) => Math.max(3, Math.floor(octaves / 2)), // MO-SH-09
+});
+
+/** MO-SH-09: the one canonical 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 (MO-A-51) ----
+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"],
+});
+
+// ---- QA gate (MO-C, MO-D) ----
+export const GATE = Object.freeze({
+  // MO-C-03 flash audit (excursion method)
+  flashGrid: [320, 180], // 6x6 logical px cells
+  flashCellPx: 6,
+  flashDelta: 0.1,
+  flashDarkCeiling: 0.8,
+  flashWindowCells: [107, 60], // 640x360 logical px, the 10-degree field
+  flashWindowArea: 0.25, // more than 25% of the window
+  flashEdgeFrames: 3, // cells transitioning in [f-2, f]
+  redRatio: 0.8,
+  redScale: 320,
+  redDelta: 20,
+  maxFlashesPerSecond: 3,
+  maxRedFlashesPerSecond: 3,
+  // MO-C-04 title-safe (inner 90%)
+  titleSafe: [96, 54, 1824, 1026],
+  // MO-C-05 action-safe (inner 95%) PROVISIONAL
+  actionSafe: [48, 27, 1872, 1053],
+  // MO-C-06 contrast PROVISIONAL (size translation)
+  contrastBody: 4.5,
+  contrastLarge: 3.0,
+  largeFontPx: 32,
+  largeBoldFontPx: 25,
+  largeBoldWeight: 700,
+  // MO-C-10..12 floors
+  minResolution: [1920, 1080],
+  minFps: 30,
+  minDurationSec: 3,
+  warnDurationSec: 90,
+  // MO-C-13 caps PROVISIONAL
+  previewCapBytes: 3 * 1000 * 1000,
+  posterCapBytes: 1 * 1000 * 1000,
+  mp4WarnBytesPer10s: 100 * 1000 * 1000,
+  // MO-C-14 reduced-motion ink floor PROVISIONAL
+  stillInkRatio: 0.9,
+  // MO-C-25 tracking PROVISIONAL
+  displayTrackingFloorEm: -0.04,
+  // MO-C-26 line height
+  lineHeightLatin: 1.5,
+  lineHeightCjk: 1.6,
+  lineHeightThreePlus: 1.4,
+  // MO-C-27 measure
+  measureLatin: [60, 75],
+  measureCjkAdvisory: [30, 45],
+  // MO-C-29 accent PROVISIONAL (saturation floor + accent limits)
+  clusterHueTolerance: 15,
+  clusterSaturation: 0.5,
+  clusterMinFillPx: 24,
+  accentMaxFrameShare: 0.1,
+  accentMaxEntries: 1,
+  // MO-D-02 perf PROVISIONAL
+  perfMinFrames: 120,
+  perfP95HardwareMs: 40,
+  perfP95SoftwareMs: 250,
+  // MO-D-03 near-black runs PROVISIONAL
+  nearBlackLuminance: 0.05,
+  nearBlackPercentile: 0.995,
+  nearBlackHoldFactor: 2,
+  nearBlackEdgeAllowanceSec: 1,
+});
+
+// ---- preview ladder (MO-A-38) ----
+export const PREVIEW = Object.freeze({
+  rungs: [
+    { width: 960, fps: 30 },
+    { width: 720, fps: 24 },
+    { width: 540, fps: 20 },
+  ],
+  minWidth: 540,
+  minGlyphPx: 10,
+  webpQuality: 60,
+});
+
+// ---- encode (MO-A-03) ----
+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",
+]);
+
+// ---- fonts (MO-A-46) ----
+export const FONT_BUDGET = Object.freeze({ perFileBytes: 1_000_000, totalBytes: 4_000_000 });
+
+// ---- craft loop (MO-C-15/16) ----
+export const MAX_ROUNDS = 3;

package/plugins/litclaude/skills/lit-typographic-motion/engine/core/contrast.mjs

@@ -0,0 +1,90 @@
+// MO-C-06 contrast measurement on a rendered frame (CF-204's method for type over a rendered
+// background). Foreground: the median linear luminance under the glyph mask eroded by 1 px (the
+// 5th and 95th percentiles for a gradient fill). Background: the 5th and 95th percentiles inside
+// the bbox grown by 0.25 x cap height, outside the mask dilated by 2 px. The ratio is the worst
+// pairing. Coordinates are logical px; `scale` maps them onto the frame's physical pixels (the type
+// path's 1920-wide logical frame by default; the stage path passes 1, its boxes are already pixels).
+import { LINEAR_LUT } from "./flash.mjs";
+
+const lum = (rgba, i) => 0.2126 * LINEAR_LUT[rgba[i]] + 0.7152 * LINEAR_LUT[rgba[i + 1]] + 0.0722 * LINEAR_LUT[rgba[i + 2]];
+const ratio = (a, b) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+function percentile(sorted, p) {
+  if (!sorted.length) return null;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.round(p * (sorted.length - 1))))];
+}
+
+/**
+ * Where a logical box lands on screen after the crt pass. The pass shows, at screen uv s, the content
+ * at barrel(s) = s + d|d|^2 * 2k (d = s - 0.5), so a box is carried by the inverse of that map: each
+ * point of its outline is solved by fixed-point iteration and the result is their bounding box.
+ * Without this the frame line of a curved window lands inside a corner label's background ring.
+ */
+export function screenBox(bbox, curvature, width = 1920, height = 1080) {
+  if (!curvature) return bbox;
+  const toScreen = (x, y) => {
+    const c = [x / width, y / height];
+    let s = [...c];
+    for (let i = 0; i < 12; i++) {
+      const dx = s[0] - 0.5;
+      const dy = s[1] - 0.5;
+      const r2 = dx * dx + dy * dy;
+      s = [c[0] - dx * r2 * curvature * 2, c[1] - dy * r2 * curvature * 2];
+    }
+    return [s[0] * width, s[1] * height];
+  };
+  const [x0, y0, x1, y1] = bbox;
+  const pts = [];
+  for (let i = 0; i <= 8; i++) {
+    const u = i / 8;
+    pts.push(toScreen(x0 + (x1 - x0) * u, y0), toScreen(x0 + (x1 - x0) * u, y1), toScreen(x0, y0 + (y1 - y0) * u), toScreen(x1, y0 + (y1 - y0) * u));
+  }
+  return [Math.min(...pts.map((p) => p[0])), Math.min(...pts.map((p) => p[1])), Math.max(...pts.map((p) => p[0])), Math.max(...pts.map((p) => p[1]))];
+}
+
+/** Returns { ratio, fg, bg: [p5, p95], fgPixels, bgPixels } or null when nothing is measurable. */
+export function measureContrast({ rgba, mask, width, height, bbox, capHeightPx, gradient = false, scale = width / 1920 }) {
+  const grow = 0.25 * capHeightPx;
+  const x0 = Math.max(0, Math.floor((bbox[0] - grow) * scale));
+  const y0 = Math.max(0, Math.floor((bbox[1] - grow) * scale));
+  const x1 = Math.min(width - 1, Math.ceil((bbox[2] + grow) * scale));
+  const y1 = Math.min(height - 1, Math.ceil((bbox[3] + grow) * scale));
+  const bx0 = Math.max(0, Math.floor(bbox[0] * scale));
+  const by0 = Math.max(0, Math.floor(bbox[1] * scale));
+  const bx1 = Math.min(width - 1, Math.ceil(bbox[2] * scale));
+  const by1 = Math.min(height - 1, Math.ceil(bbox[3] * scale));
+  const erode = Math.max(1, Math.round(scale));
+  const dilate = Math.max(2, Math.round(2 * scale));
+  const on = (x, y) => x >= 0 && y >= 0 && x < width && y < height && mask[y * width + x] >= 128;
+  const allOn = (x, y, d) => {
+    for (let dy = -d; dy <= d; dy++) for (let dx = -d; dx <= d; dx++) if (!on(x + dx, y + dy)) return false;
+    return true;
+  };
+  const anyOn = (x, y, d) => {
+    for (let dy = -d; dy <= d; dy++) for (let dx = -d; dx <= d; dx++) if (on(x + dx, y + dy)) return true;
+    return false;
+  };
+  let fg = [];
+  const fgLoose = [];
+  for (let y = by0; y <= by1; y++) {
+    for (let x = bx0; x <= bx1; x++) {
+      if (!on(x, y)) continue;
+      const l = lum(rgba, (y * width + x) * 4);
+      fgLoose.push(l);
+      if (allOn(x, y, erode)) fg.push(l);
+    }
+  }
+  // Thin strokes (pixel fonts, small machine text) can vanish under erosion; fall back to the mask.
+  if (fg.length < 12) fg = fgLoose;
+  const bg = [];
+  for (let y = y0; y <= y1; y++) for (let x = x0; x <= x1; x++) if (!anyOn(x, y, dilate)) bg.push(lum(rgba, (y * width + x) * 4));
+  if (!fg.length || !bg.length) return null;
+  fg.sort((a, b) => a - b);
+  bg.sort((a, b) => a - b);
+  const bgLo = percentile(bg, 0.05);
+  const bgHi = percentile(bg, 0.95);
+  const fgValues = gradient ? [percentile(fg, 0.05), percentile(fg, 0.95)] : [percentile(fg, 0.5)];
+  let worst = Infinity;
+  for (const f of fgValues) for (const b of [bgLo, bgHi]) worst = Math.min(worst, ratio(f, b));
+  return { ratio: worst, fg: fgValues, bg: [bgLo, bgHi], fgPixels: fg.length, bgPixels: bg.length };
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/core/events.mjs

@@ -0,0 +1,46 @@
+// Per-shot event budget (MO-SH-03): glitch hits, tidal surges, flash pulses, invert changes and
+// boot-flicker bursts together stay at or under 2 events in any 1 s window of a shot. Sources ask
+// for candidate times in priority order; a candidate is accepted only if the window rule still
+// holds. The schedule is built once per shot from the seed, never rolled per frame.
+import { SHADER } from "./constants.mjs";
+import { mulberry32 } from "./util.mjs";
+
+export class ShotEvents {
+  constructor(start, end, limit = SHADER.eventsPerSecondPerShot) {
+    this.start = start;
+    this.end = end;
+    this.limit = limit;
+    this.events = [];
+  }
+  fits(t) {
+    const times = [...this.events.map((e) => e.t), t].sort((a, b) => a - b);
+    for (let i = 0; i < times.length; i++) {
+      let n = 0;
+      for (let j = i; j < times.length && times[j] < times[i] + 1; j++) n += 1;
+      if (n > this.limit) return false;
+    }
+    return true;
+  }
+  add(t, source) {
+    if (t < this.start || t >= this.end || !this.fits(t)) return false;
+    this.events.push({ t, source });
+    this.events.sort((a, b) => a.t - b.t);
+    return true;
+  }
+  of(source) {
+    return this.events.filter((e) => e.source === source).map((e) => e.t);
+  }
+}
+
+/**
+ * Candidate glitch hit times for a shot at `rate` per second, jittered by the pass seed. Hits keep
+ * clear of the first `guard` seconds so a cut and a hit never share a frame.
+ */
+export function glitchCandidates({ start, end, rate, seed, guard = 0.3 }) {
+  if (rate <= 0) return [];
+  const rnd = mulberry32(seed);
+  const spacing = 1 / Math.min(rate, SHADER.glitchHitRateCap);
+  const out = [];
+  for (let t = start + guard + spacing * (0.3 + 0.4 * rnd()); t < end - guard; t += spacing * (0.8 + 0.4 * rnd())) out.push(t);
+  return out;
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/core/flash.mjs

@@ -0,0 +1,211 @@
+// WCAG 2.3.1 flash audit, excursion method (MO-C-03, MO-SH-04). Pure: it takes per-cell linear
+// colour averages on the 320x180 grid (6x6 logical px at 1080p) frame by frame, and never decodes
+// a video itself. The renderer feeds it the exact bytes it hands to ffmpeg (master) and to the
+// preview encoder (preview), and logs each frame's transitions; the gate counts flashes from that
+// log.
+//
+// A cell registers a transition when its luminance moves at least 0.1 from the extreme it reached
+// since its last transition while the darker of the two is below 0.8; the extremes then reset. A
+// frame-level transition in a direction exists when the cells that moved that way in frames
+// [f-2, f] cover more than 25% of some 640x360 logical-px window (107x60 cells). Red uses the same
+// method on (R-G-B)x320 over saturated-red cells. A flash is a pair of opposing frame-level
+// transitions inside one second.
+import { GATE } from "./constants.mjs";
+
+/**
+ * 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] = GATE.flashGrid;
+  const [ww, wh] = GATE.flashWindowCells;
+  return width >= height ? { gw, gh, ww, wh } : { gw: gh, gh: gw, ww: wh, wh: ww };
+}
+
+/** 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 = GATE.flashWindowArea * ww * wh;
+    const CELLS = this.cells;
+    this.frames = 0;
+    this.hi = new Float32Array(CELLS);
+    this.lo = new Float32Array(CELLS);
+    this.rhi = new Float32Array(CELLS);
+    this.rlo = new Float32Array(CELLS);
+    this.prevL = new Float32Array(CELLS);
+    this.history = []; // last GATE.flashEdgeFrames maps of { up, down, redUp, redDown } (Uint8Array)
+    this.sat = new Int32Array((gw + 1) * (gh + 1));
+  }
+
+  /** Feed one frame; returns { up, down, redUp, redDown, stepArea } for the log. */
+  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 >= GATE.redRatio ? Math.max(0, R[i] - G[i] - B[i]) * GATE.redScale : 0;
+    }
+    const maps = { up: new Uint8Array(CELLS), down: new Uint8Array(CELLS), redUp: new Uint8Array(CELLS), redDown: new Uint8Array(CELLS) };
+    let stepCells = 0;
+    if (this.frames === 0) {
+      this.hi.set(L); this.lo.set(L); this.rhi.set(V); this.rlo.set(V);
+    } else {
+      for (let i = 0; i < CELLS; i++) {
+        const l = L[i];
+        if (Math.abs(l - this.prevL[i]) >= GATE.flashDelta) stepCells += 1;
+        if (l - this.lo[i] >= GATE.flashDelta && Math.min(l, this.lo[i]) < GATE.flashDarkCeiling) {
+          maps.up[i] = 1; this.hi[i] = l; this.lo[i] = l;
+        } else if (this.hi[i] - l >= GATE.flashDelta && Math.min(l, this.hi[i]) < GATE.flashDarkCeiling) {
+          maps.down[i] = 1; this.hi[i] = l; this.lo[i] = l;
+        } else {
+          if (l > this.hi[i]) this.hi[i] = l;
+          if (l < this.lo[i]) this.lo[i] = l;
+        }
+        const v = V[i];
+        if (v - this.rlo[i] > GATE.redDelta) {
+          maps.redUp[i] = 1; this.rhi[i] = v; this.rlo[i] = v;
+        } else if (this.rhi[i] - v > GATE.redDelta) {
+          maps.redDown[i] = 1; this.rhi[i] = v; this.rlo[i] = v;
+        } else {
+          if (v > this.rhi[i]) this.rhi[i] = v;
+          if (v < this.rlo[i]) this.rlo[i] = v;
+        }
+      }
+    }
+    this.prevL = L;
+    this.frames += 1;
+    this.history.push(maps);
+    if (this.history.length > GATE.flashEdgeFrames) this.history.shift();
+    const result = { stepArea: +(stepCells / CELLS).toFixed(4) };
+    for (const dir of ["up", "down", "redUp", "redDown"]) result[dir] = this.windowHit(dir);
+    return result;
+  }
+
+  // Union of the direction's maps over the last frames, then the largest window count via a
+  // summed-area table.
+  windowHit(dir) {
+    const { gw: GW, gh: GH, ww: WW, wh: WH } = this.grid;
+    const CELLS = this.cells;
+    const WINDOW_LIMIT = this.windowLimit;
+    const union = new Uint8Array(CELLS);
+    let any = 0;
+    for (const maps of this.history) {
+      const m = maps[dir];
+      for (let i = 0; i < CELLS; i++) if (m[i]) { union[i] = 1; any += 1; }
+    }
+    if (any <= WINDOW_LIMIT) return false;
+    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 += union[y * GW + x];
+        sat[(y + 1) * stride + x + 1] = sat[y * stride + x + 1] + row;
+      }
+    }
+    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 > WINDOW_LIMIT) return true;
+      }
+    }
+    return false;
+  }
+}
+
+/** Frame-level transitions (from logged per-frame records) as an ordered list for one channel. */
+export function transitionsOf(records, general = true) {
+  const out = [];
+  records.forEach((r, frame) => {
+    if (general ? r.up : r.redUp) out.push({ frame, dir: 1 });
+    if (general ? r.down : r.redDown) out.push({ frame, dir: -1 });
+  });
+  return out;
+}
+
+// Flashes in an ordered run of transitions: consecutive same-direction transitions collapse into
+// one edge, and every two opposing edges make one flash.
+function flashesIn(ordered) {
+  let edges = 0;
+  let last = 0;
+  for (const t of ordered) {
+    if (t.dir !== last) {
+      edges += 1;
+      last = t.dir;
+    }
+  }
+  return Math.floor(edges / 2);
+}
+
+/**
+ * Worst 1 s window. `loop: false` (the master) never wraps: windows start in [0, count - fps] and
+ * a clip shorter than a second is one window. `loop: true` (the preview) wraps across the seam.
+ */
+export function worstWindow(transitions, count, fps, { loop }) {
+  const span = Math.round(fps);
+  let worst = { startFrame: 0, flashes: 0, transitions: [] };
+  const starts = loop ? count : Math.max(1, count - span + 1);
+  for (let s = 0; s < starts; s++) {
+    const inside = [];
+    for (const t of transitions) {
+      const k = loop ? (t.frame - s + count) % count : t.frame - s;
+      if (k >= 0 && k < span && (loop || t.frame < count)) inside.push({ ...t, k });
+    }
+    inside.sort((a, b) => a.k - b.k || a.dir - b.dir);
+    const flashes = flashesIn(inside);
+    if (flashes > worst.flashes) worst = { startFrame: s, flashes, transitions: inside.map((t) => `${t.frame}:${t.dir > 0 ? "up" : "down"}`) };
+  }
+  return { ...worst, startSec: +(worst.startFrame / fps).toFixed(3) };
+}
+
+/** Audit a logged sequence: { general, red } worst windows and the pass/fail against 3/3. */
+export function auditRecords(records, fps, { loop }) {
+  const general = worstWindow(transitionsOf(records, true), records.length, fps, { loop });
+  const red = worstWindow(transitionsOf(records, false), records.length, fps, { loop });
+  return {
+    general, red,
+    pass: general.flashes <= GATE.maxFlashesPerSecond && red.flashes <= GATE.maxRedFlashesPerSecond,
+  };
+}
+
+/** Run the detector over frames and return the per-frame records (looping runs two passes). */
+export function detectSequence(cellFrames, { loop, grid = gridFor() }) {
+  const detector = new FlashDetector(grid);
+  if (loop) for (const frame of cellFrames) detector.push(frame);
+  return cellFrames.map((frame) => detector.push(frame));
+}
+
+/** 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 };
+}
+
+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;
+});