@litfamily/lithermes 1.0.8 → 1.0.9

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/constants.mjs

@@ -0,0 +1,162 @@
+// Every number the LitHermes motion engine and its gate use, in one place.
+// Source: the family motion spec (FINAL + Delta 1). Rows the spec marks [NEW]
+// are PROVISIONAL: implemented exactly as written, pending a user decision, and
+// labelled "provisional" here and in every gate report.
+
+export const PROVISIONAL = Object.freeze(new Set([
+  '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 FRAME = Object.freeze({ width: 1920, height: 1080, fps: 60, maxScale: 4 });
+
+export const SAMPLING = Object.freeze({
+  masterSamples: 4, // MO-A-26
+  masterShutter: 0.5,
+  previewSamples: 1, // MO-A-27 (stills, sheet, perf)
+});
+
+export const TIMING = Object.freeze({
+  defaultBpm: 100, // MO-A-14
+  paceMargin: 1.25, // MO-A-09/10: generator pace = 1.25 x floor
+  minSceneBeats: 2, // MO-A-16
+  cutToleranceFrames: 1, // MO-A-15
+  minBpm: 40,
+  maxBpm: 220,
+});
+
+// MO-C-07 / MO-C-08: the one reading-floor function (provisional numbers).
+export const READING = Object.freeze({
+  hangulSecPerSyllable: 0.2,
+  englishWordsPerSec: 3.3,
+  englishCps: 17,
+  lineFloorLatin: 0.9, // MO-A-11
+  lineFloorHangul: 1.0,
+  wordFloor: 0.5,
+  revealFloor: 0.35, // MO-A-12
+});
+
+export const SAFE = Object.freeze({
+  titleX: 96, titleY: 54, // MO-C-04
+  actionX: 48, actionY: 27, // MO-C-05 provisional
+});
+
+export const CONTRAST = Object.freeze({
+  body: 4.5, large: 3.0, // MO-C-06 floors
+  largePx: 32, largeBoldPx: 25, largeBoldWeight: 700, // MO-C-06 provisional "large"
+  maskErodePx: 1, maskDilatePx: 2, bboxExpandCap: 0.25,
+});
+
+export const TYPE = Object.freeze({
+  displayTrackingMinEm: -0.04, // MO-C-25 provisional
+  machineTrackingMinEm: 0,
+  lineHeightLatin: 1.5, lineHeightCjk: 1.6, lineHeightThreePlus: 1.4, // MO-C-26
+  paragraphChMin: 60, paragraphChMax: 75, // MO-C-27 (Latin FAIL; CJK 30-45 advisory)
+  cjkChAdvisoryMin: 30, cjkChAdvisoryMax: 45,
+  entranceScaleFloor: 0.95, // CF-503 via MO-A-08
+});
+
+export const FLASH = Object.freeze({
+  gridX: 320, gridY: 180, cellLogicalPx: 6, // MO-C-03
+  cellDelta: 0.1, cellCeiling: 0.8,
+  windowLogicalW: 640, windowLogicalH: 360, windowFraction: 0.25,
+  redShare: 0.8, redScale: 320, redDelta: 20,
+  lookbackFrames: 2,
+  maxFlashes: 3, maxRedFlashes: 3,
+  fullFrameFraction: 0.25, // MO-SH-04a
+});
+
+export const EVENTS = Object.freeze({
+  perShotWindowSec: 1, maxPerShotWindow: 2, // MO-SH-03
+  flashRiseThreshold: 0.1, // MO-A-58
+});
+
+export const PASS_CAPS = Object.freeze({
+  glitchHitsPerSec: 2.0, glitchAreaPct: 20, // MO-SH-05
+  surgePerSec: 2, surgeAttackSec: 0.1, surgeDecaySec: 0.1, // MO-SH-06
+  crtFlickerPeakToPeak: 0.06, // MO-SH-07
+  terminalLayersMax: 2, // MO-SH-11
+});
+
+export const OUTPUT = Object.freeze({
+  minWidth: 1920, minHeight: 1080, minFps: 30, minDurationSec: 3, warnDurationSec: 90, // MO-C-10..12
+  previewMaxBytes: 3 * 1000 * 1000, posterMaxBytes: 1000 * 1000, // MO-C-13 provisional
+  mp4WarnBytesPer10s: 100 * 1000 * 1000,
+  previewLadder: Object.freeze([[960, 30], [720, 24], [540, 20]]), // MO-A-38
+  previewMinWidth: 540, previewMinGlyphPx: 10,
+  reducedInkFraction: 0.9, // MO-C-14 provisional
+  crf: 16,
+});
+
+export const PERF = Object.freeze({
+  frames: 120, hardwareP95Ms: 40, softwareP95Ms: 250, // MO-D-02 provisional
+});
+
+export const EMPTY = Object.freeze({
+  sceneHoldMultiplier: 2, fadeAllowanceSec: 1, p995Ceiling: 0.05, // MO-D-03 provisional
+});
+
+export const ACCENT = Object.freeze({
+  maxFrameFraction: 0.1, maxEntries: 1, saturationFloor: 0.5, hueTolerance: 15, minFillPx: 24, // MO-C-29 provisional
+  maxClusters: 2,
+});
+
+// MO-SH-09: the one canonical software-rasterizer 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)';
+
+export function isSoftwareRenderer(renderer) {
+  const value = String(renderer || '').toLowerCase();
+  return SOFTWARE_RENDERERS.some((entry) => value.includes(entry));
+}
+
+// MO-A-51: per-platform ladder, then the SwiftShader rung; anti-throttling flags always appended,
+// plus the two that keep Chrome off the OS keychain (a custom profile dir otherwise makes
+// macOS ask the user where to store Chrome's safe-storage key).
+export const ALWAYS_FLAGS = Object.freeze([
+  '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows',
+  '--use-mock-keychain', '--password-store=basic',
+]);
+export function chromeFlagLadder(platform = process.platform) {
+  const gpu = platform === 'darwin'
+    ? ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist']
+    : platform === 'win32'
+      ? ['--use-angle=d3d11', '--enable-gpu-rasterization']
+      : ['--use-angle=gl', '--enable-gpu-rasterization', '--ignore-gpu-blocklist'];
+  return [[...gpu, ...ALWAYS_FLAGS], ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', ...ALWAYS_FLAGS]];
+}
+
+// MO-A-45 exit codes.
+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.
+  BLOCKED_TREATMENT_INVALID: 16,
+  STAGE_CONTRACT_ERROR: 17,
+  STAGE_NONDETERMINISTIC: 18,
+  STAGE_NETWORK_REQUEST: 19,
+  SOUND_INVALID: 20,
+});
+
+// MO-A-58 post-chain override vocabulary: [min, max, neutral]. null max = no ceiling.
+export const OVERRIDES = Object.freeze({
+  exposure: [0, null, 1], bloom: [0, 1, 0], bloomThreshold: [0, 1, 0.85], bloomKnee: [0, 1, 0],
+  bloomRadius: [0, 1, 0], halation: [0, 1, 0], ca: [0, null, 0], grain: [0, 1, 0], vignette: [0, 1, 0],
+  fade: [0, 1, 1], flash: [0, 1, 0], zoom: [0, null, 1],
+});
+
+export const POST_ORDER = Object.freeze([
+  'bloom+halation', 'chromatic-aberration', 'tone-shoulder', 'film-grain', 'vignette', 'flash', 'shake/zoom', 'invert',
+]);
+
+export const LOOK_PASSES = Object.freeze(['glitch', 'tidal-gradient', 'crt', 'dither', 'swiss-grid', 'terminal-ui']);
+
+export const ENGINE_CREDIT = 'mexicat/pdoom-video ca251e3dddda422b364385eb484b5a3593a0990d (MIT)';
+export const CREDIT_LINE = 'Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.';

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/director.mjs

@@ -0,0 +1,33 @@
+// Director-wave state shared by both render paths: the first valid treatment
+// (the done-check compares against it) and the run-state file every command
+// leaves behind.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const writeJson = (file, value) => writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+
+export function recordFirstTreatment(out, treatment) {
+  const dir = join(out, '.run');
+  const first = join(dir, 'treatment-first.json');
+  if (existsSync(first)) return first;
+  mkdirSync(dir, { recursive: true });
+  if (existsSync(join(out, 'treatment.json'))) copyFileSync(join(out, 'treatment.json'), first);
+  else writeJson(first, treatment);
+  return first;
+}
+
+export function writeRunState(out, state) {
+  mkdirSync(out, { recursive: true });
+  writeJson(join(out, 'run-state.json'), { ...state, finishedAt: new Date().toISOString() });
+}
+
+// Every stills file look.json lists as viewed, across rounds. Read fresh on
+// each report, so a gate rerun never resets the count.
+export function viewedFiles(out) {
+  const file = join(out, 'look.json');
+  if (!existsSync(file)) return [];
+  try {
+    const look = JSON.parse(readFileSync(file, 'utf8'));
+    return [...new Set((look.rounds || []).flatMap((r) => (r.frames || []).map((f) => f.file)))];
+  } catch { return []; }
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/encode.mjs

@@ -0,0 +1,191 @@
+// Output side: PNG helpers, contact sheet, the pinned master encode (MO-A-03)
+// and the preview encoder + size ladders (MO-A-38). ffmpeg is always the last
+// stage; Chrome never writes a video.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { OUTPUT } from './constants.mjs';
+import { FlashDetector } from './flash.mjs';
+
+// Video only: sound is muxed afterwards by sound.mjs (padded or trimmed to the
+// film, never -shortest), so a track can never shorten or silently drop out.
+export function masterArgs({ width, height, fps, output }) {
+  const args = ['-hide_banner', '-loglevel', 'error', '-y',
+    '-f', 'rawvideo', '-pix_fmt', 'rgba', '-s', `${width}x${height}`, '-r', String(fps), '-i', 'pipe:0'];
+  // setparams: ffmpeg 8.1 leaves primaries/transfer "unknown" from the output flags alone.
+  args.push('-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', String(OUTPUT.crf), '-tune', 'grain', '-x264-params', 'aq-mode=3',
+    '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-color_range', 'tv', '-movflags', '+faststart');
+  args.push(output);
+  return args;
+}
+
+export function hasFfmpeg(env = process.env) {
+  return spawnSync('ffmpeg', ['-hide_banner', '-version'], { stdio: 'ignore', env }).status === 0;
+}
+
+export function startMaster(options) {
+  const child = spawn('ffmpeg', masterArgs(options), { stdio: ['pipe', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (chunk) => { stderr = (stderr + chunk.toString()).slice(-4000); });
+  const done = new Promise((resolve) => child.on('close', (code) => resolve({ code, stderr })));
+  return {
+    async write(bytes) {
+      if (!child.stdin.write(bytes)) await new Promise((resolve) => child.stdin.once('drain', resolve));
+    },
+    async finish() { child.stdin.end(); return done; },
+  };
+}
+
+export function ffprobe(file) {
+  const out = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries',
+    'stream=codec_name,width,height,r_frame_rate,avg_frame_rate,pix_fmt,color_space,color_primaries,color_transfer,color_range,nb_frames:format=duration',
+    '-of', 'json', file], { encoding: 'utf8' });
+  if (out.status !== 0) return null;
+  const parsed = JSON.parse(out.stdout);
+  const stream = parsed.streams?.[0] || {};
+  const [num, den] = String(stream.r_frame_rate || '0/1').split('/').map(Number);
+  return { ...stream, fps: den ? num / den : 0, duration: Number(parsed.format?.duration || 0) };
+}
+
+// Delivered PNGs use deflateStrategy 1 (filtered): pngjs's default RLE made a
+// lossless 1080p poster 4.5x larger for the same pixels. Scratch frames that
+// only feed an encoder keep the much faster RLE (`scratch: true`).
+export function pngEncode(PNG, rgba, width, height, { gray = false, level = 6, scratch = false } = {}) {
+  const options = { width, height, colorType: gray ? 0 : 2, inputColorType: gray ? 0 : 6, inputHasAlpha: !gray, deflateLevel: level, deflateStrategy: scratch ? 3 : 1, filterType: -1 };
+  const png = new PNG(options);
+  png.data = Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength);
+  return PNG.sync.write(png, options);
+}
+
+export function pngDecode(PNG, file) {
+  const png = PNG.sync.read(readFileSync(file));
+  return { data: png.data, width: png.width, height: png.height };
+}
+
+// Box-filter downscale (area average), which also averages grain away.
+export function areaResize(src, width, height, targetWidth) {
+  const targetHeight = Math.round((height * targetWidth) / width);
+  const out = Buffer.alloc(targetWidth * targetHeight * 4);
+  const xs = Array.from({ length: targetWidth + 1 }, (_, i) => Math.round((i * width) / targetWidth));
+  const ys = Array.from({ length: targetHeight + 1 }, (_, i) => Math.round((i * height) / targetHeight));
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      let r = 0, g = 0, b = 0, n = 0;
+      for (let sy = ys[y]; sy < Math.max(ys[y] + 1, ys[y + 1]); sy++) {
+        let at = (sy * width + xs[x]) * 4;
+        for (let sx = xs[x]; sx < Math.max(xs[x] + 1, xs[x + 1]); sx++, at += 4) { r += src[at]; g += src[at + 1]; b += src[at + 2]; n++; }
+      }
+      const o = (y * targetWidth + x) * 4;
+      out[o] = Math.round(r / n); out[o + 1] = Math.round(g / n); out[o + 2] = Math.round(b / n); out[o + 3] = 255;
+    }
+  }
+  return { data: out, width: targetWidth, height: targetHeight };
+}
+
+// 3x5 digits for frame labels on the contact sheet.
+const DIGITS = ['111101101101111', '010110010010111', '111001111100111', '111001111001111', '101101111001001', '111100111001111', '111100111101111', '111001001001001', '111101111101111', '111101111001111'];
+function stamp(buf, width, x, y, text, scale = 3) {
+  let cx = x;
+  for (const ch of String(text)) {
+    const glyph = DIGITS[Number(ch)];
+    if (glyph) for (let i = 0; i < 15; i++) if (glyph[i] === '1') {
+      for (let dy = 0; dy < scale; dy++) for (let dx = 0; dx < scale; dx++) {
+        const o = ((y + Math.floor(i / 3) * scale + dy) * width + cx + (i % 3) * scale + dx) * 4;
+        buf[o] = 255; buf[o + 1] = 255; buf[o + 2] = 255; buf[o + 3] = 255;
+      }
+    }
+    cx += 4 * scale;
+  }
+}
+
+export function contactSheet(PNG, tiles, file, { columns, cellWidth } = {}) {
+  const portrait = tiles[0] && tiles[0].height > tiles[0].width;
+  columns ??= portrait ? 6 : 4;
+  cellWidth ??= portrait ? 270 : 480;
+  const cellHeight = Math.round((cellWidth * (tiles[0]?.height || 9)) / (tiles[0]?.width || 16)), label = 22, pad = 6;
+  const rows = Math.ceil(tiles.length / columns);
+  const width = columns * (cellWidth + pad) + pad, height = rows * (cellHeight + label + pad) + pad;
+  const sheet = Buffer.alloc(width * height * 4);
+  for (let i = 0; i < sheet.length; i += 4) { sheet[i] = 30; sheet[i + 1] = 32; sheet[i + 2] = 36; sheet[i + 3] = 255; }
+  tiles.forEach((tile, index) => {
+    const small = areaResize(tile.data, tile.width, tile.height, cellWidth);
+    const left = pad + (index % columns) * (cellWidth + pad);
+    const top = pad + Math.floor(index / columns) * (cellHeight + label + pad);
+    stamp(sheet, width, left + 2, top + 3, tile.frame, 3);
+    for (let y = 0; y < Math.min(cellHeight, small.height); y++) {
+      small.data.copy(sheet, ((top + label + y) * width + left) * 4, y * cellWidth * 4, (y + 1) * cellWidth * 4);
+    }
+  });
+  writeFileSync(file, pngEncode(PNG, sheet, width, height));
+  return { width, height, tiles: tiles.length };
+}
+
+function encoderLadder(env = process.env) {
+  const encoders = spawnSync('ffmpeg', ['-hide_banner', '-encoders'], { encoding: 'utf8', env }).stdout || '';
+  const rungs = [];
+  if (/libwebp_anim/.test(encoders)) rungs.push('libwebp_anim');
+  if (spawnSync('img2webp', ['-version'], { stdio: 'ignore', env }).status === 0) rungs.push('img2webp');
+  rungs.push('gif');
+  return rungs;
+}
+
+// Preview: the first encoder rung that works, then the first size rung <= 3 MB.
+// Every frame handed to the encoder goes through the looping flash audit first.
+// Rungs are keyed on the long edge (960, 720, 540), so a 9:16 source gets
+// 540x960, 405x720 and 304x540 previews.
+export function encodePreview({ PNG, sourceFrames, masterFps, durationSec, workDir, minGlyphPx = 32, env = process.env, sourceWidth = 1920, sourceHeight = 1080 }) {
+  const rungs = encoderLadder(env);
+  const attempts = [];
+  const longEdge = Math.max(sourceWidth, sourceHeight);
+  for (const [long, fps] of OUTPUT.previewLadder) {
+    const scale = long / longEdge;
+    const width = Math.round(sourceWidth * scale);
+    if (long < OUTPUT.previewMinWidth || minGlyphPx * scale < OUTPUT.previewMinGlyphPx) { attempts.push({ width, fps, skipped: 'smallest glyph under 10 px' }); continue; }
+    const dir = join(workDir, `preview-${width}`);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const count = Math.max(1, Math.round(durationSec * fps));
+    const detector = new FlashDetector(width, Math.round(sourceHeight * scale));
+    const records = [];
+    const files = [];
+    for (let i = 0; i < count; i++) {
+      const want = Math.min(Math.round((i * masterFps) / fps), sourceFrames.length - 1);
+      let index = want;
+      while (index > 0 && !sourceFrames[index]) index--;
+      const source = pngDecode(PNG, sourceFrames[index]);
+      const frame = source.width === width ? source : areaResize(source.data, source.width, source.height, width);
+      const flash = detector.push(frame.data);
+      records.push({ frame: i, general: flash.general, generalBoth: flash.generalBoth, red: flash.red, redBoth: flash.redBoth });
+      const file = join(dir, `p${String(i).padStart(5, '0')}.png`);
+      writeFileSync(file, pngEncode(PNG, frame.data, frame.width, frame.height, { level: 1, scratch: true }));
+      files.push(file);
+    }
+    for (const encoder of rungs) {
+      const output = join(workDir, encoder === 'gif' ? 'preview.gif' : 'preview.webp');
+      rmSync(output, { force: true });
+      let result;
+      if (encoder === 'img2webp') {
+        const args = ['-loop', '0', '-lossy', '-q', '72', '-m', '4'];
+        for (const file of files) args.push('-d', String(Math.round(1000 / fps)), file);
+        args.push('-o', output);
+        result = spawnSync('img2webp', args, { encoding: 'utf8', env, timeout: 900000 });
+      } else if (encoder === 'libwebp_anim') {
+        result = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-framerate', String(fps), '-i', join(dir, 'p%05d.png'), '-c:v', 'libwebp_anim', '-lossless', '0', '-q:v', '72', '-loop', '0', output], { encoding: 'utf8', env, timeout: 900000 });
+      } else {
+        result = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-framerate', String(fps), '-i', join(dir, 'p%05d.png'), '-vf', 'split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=4', '-loop', '0', output], { encoding: 'utf8', env, timeout: 900000 });
+      }
+      const ok = result.status === 0 && existsSync(output);
+      const bytes = ok ? statSync(output).size : null;
+      attempts.push({ width, fps, encoder, ok, bytes, error: ok ? null : (result.stderr || result.error?.message || '').split('\n')[0] });
+      if (!ok) continue;
+      rmSync(dir, { recursive: true, force: true });
+      if (bytes <= OUTPUT.previewMaxBytes || long === OUTPUT.previewLadder.at(-1)[0]) {
+        return { file: output, encoder, width, fps, bytes, records, attempts };
+      }
+      break;
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+  return { file: null, encoder: null, attempts, records: [] };
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/flash.mjs

@@ -0,0 +1,163 @@
+// WCAG 2.3.1 flash audit, excursion method (MO-C-03, MO-SH-04). It runs on the
+// exact RGBA bytes handed to ffmpeg or to the preview encoder, one frame at a
+// time, and emits a per-frame record { general, red } in {-1, 0, 1} for the
+// render log. flashesFromRecords() counts flashes from those records; the gate
+// never re-derives them from a decoded MP4 or WebP.
+import { FLASH, FRAME } from './constants.mjs';
+
+const LIN = Float64Array.from({ length: 256 }, (_, v) => {
+  const s = v / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+});
+
+export class FlashDetector {
+  // The grid is always 320x180 cells of 6x6 logical px, so a 960-wide preview
+  // frame gets 3x3-pixel cells and a --scale 2 master gets 12x12. A portrait
+  // frame transposes it: 180x320 cells and a 60x107-cell window.
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    const portrait = height > width;
+    this.gx = portrait ? FLASH.gridY : FLASH.gridX;
+    this.gy = portrait ? FLASH.gridX : FLASH.gridY;
+    const n = this.gx * this.gy;
+    this.lo = new Float64Array(n); this.hi = new Float64Array(n);
+    this.rlo = new Float64Array(n); this.rhi = new Float64Array(n);
+    this.started = false;
+    this.history = [];
+    // The 10-degree window in cells, scaled with the grid (640x360 of 1920x1080).
+    const ww = Math.round(FLASH.gridX * FLASH.windowLogicalW / FRAME.width);
+    const wh = Math.round(FLASH.gridY * FLASH.windowLogicalH / FRAME.height);
+    this.ww = portrait ? wh : ww;
+    this.wh = portrait ? ww : wh;
+    this.xEdges = Array.from({ length: this.gx + 1 }, (_, i) => Math.round((i * width) / this.gx));
+    this.yEdges = Array.from({ length: this.gy + 1 }, (_, i) => Math.round((i * height) / this.gy));
+    this.lastL = null;
+  }
+
+  cells(rgba) {
+    const { gx, gy, width } = this;
+    const L = new Float64Array(gx * gy), red = new Float64Array(gx * gy);
+    for (let cy = 0; cy < gy; cy++) {
+      const y0 = this.yEdges[cy], y1 = Math.max(y0 + 1, this.yEdges[cy + 1]);
+      for (let cx = 0; cx < gx; cx++) {
+        const x0 = this.xEdges[cx], x1 = Math.max(x0 + 1, this.xEdges[cx + 1]);
+        let r = 0, g = 0, b = 0, count = 0;
+        for (let y = y0; y < y1; y++) {
+          let at = (y * width + x0) * 4;
+          for (let x = x0; x < x1; x++, at += 4) { r += LIN[rgba[at]]; g += LIN[rgba[at + 1]]; b += LIN[rgba[at + 2]]; count++; }
+        }
+        r /= count; g /= count; b /= count;
+        const i = cy * gx + cx;
+        L[i] = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        const sum = r + g + b;
+        red[i] = sum > 0 && r / sum >= FLASH.redShare ? Math.max(0, r - g - b) * FLASH.redScale : 0;
+      }
+    }
+    return { L, red };
+  }
+
+  // Returns this frame's transition directions plus the whole-frame step used by MO-SH-04a.
+  push(rgba) {
+    const { L, red } = this.cells(rgba);
+    const n = L.length;
+    const gen = new Int8Array(n), rd = new Int8Array(n);
+    if (!this.started) {
+      this.lo.set(L); this.hi.set(L); this.rlo.set(red); this.rhi.set(red);
+      this.started = true;
+    } else {
+      for (let i = 0; i < n; i++) {
+        const v = L[i];
+        if (v - this.lo[i] >= FLASH.cellDelta && this.lo[i] < FLASH.cellCeiling) { gen[i] = 1; this.lo[i] = v; this.hi[i] = v; }
+        else if (this.hi[i] - v >= FLASH.cellDelta && v < FLASH.cellCeiling) { gen[i] = -1; this.lo[i] = v; this.hi[i] = v; }
+        else { if (v < this.lo[i]) this.lo[i] = v; if (v > this.hi[i]) this.hi[i] = v; }
+        const q = red[i];
+        if (q - this.rlo[i] > FLASH.redDelta) { rd[i] = 1; this.rlo[i] = q; this.rhi[i] = q; }
+        else if (this.rhi[i] - q > FLASH.redDelta) { rd[i] = -1; this.rlo[i] = q; this.rhi[i] = q; }
+        else { if (q < this.rlo[i]) this.rlo[i] = q; if (q > this.rhi[i]) this.rhi[i] = q; }
+      }
+    }
+    let stepCells = 0;
+    if (this.lastL) for (let i = 0; i < n; i++) {
+      const a = this.lastL[i], b = L[i];
+      if (Math.abs(b - a) >= FLASH.cellDelta && Math.min(a, b) < FLASH.cellCeiling) stepCells++;
+    }
+    this.lastL = L;
+    this.history.push({ gen, rd });
+    if (this.history.length > FLASH.lookbackFrames + 1) this.history.shift();
+    const general = this.direction('gen', 1) ? 1 : 0, generalDown = this.direction('gen', -1) ? -1 : 0;
+    const redUp = this.direction('rd', 1) ? 1 : 0, redDown = this.direction('rd', -1) ? -1 : 0;
+    return {
+      general: general || generalDown, generalBoth: Boolean(general && generalDown),
+      red: redUp || redDown, redBoth: Boolean(redUp && redDown),
+      fullFrameStep: stepCells / n,
+    };
+  }
+
+  // Same-direction cells in [f-2, f] covering more than 25% of some window.
+  direction(key, dir) {
+    const { gx, gy, ww, wh } = this;
+    const sat = new Int32Array((gx + 1) * (gy + 1));
+    for (let y = 0; y < gy; y++) {
+      let row = 0;
+      for (let x = 0; x < gx; x++) {
+        const i = y * gx + x;
+        let hit = 0;
+        for (const h of this.history) if (h[key][i] === dir) { hit = 1; break; }
+        row += hit;
+        sat[(y + 1) * (gx + 1) + x + 1] = sat[y * (gx + 1) + x + 1] + row;
+      }
+    }
+    const need = FLASH.windowFraction * ww * wh;
+    for (let y = 0; y + wh <= gy; y++) for (let x = 0; x + ww <= gx; x++) {
+      const area = sat[(y + wh) * (gx + 1) + x + ww] - sat[y * (gx + 1) + x + ww] - sat[(y + wh) * (gx + 1) + x] + sat[y * (gx + 1) + x];
+      if (area > need) return true;
+    }
+    return false;
+  }
+}
+
+// Frame records -> transition events. A frame-level transition persists for up
+// to three frames because of the [f-2, f] lookback, so a run of consecutive
+// same-direction frames is one event; a frame with both directions is two.
+function events(records, key) {
+  const out = [];
+  let prev = 0;
+  for (const r of records) {
+    const both = key === 'general' ? r.generalBoth : r.redBoth;
+    const dir = r[key] || 0;
+    if (both) { out.push({ frame: r.frame, dir: 1 }, { frame: r.frame, dir: -1 }); prev = 0; continue; }
+    if (dir && dir !== prev) out.push({ frame: r.frame, dir });
+    prev = dir;
+  }
+  return out;
+}
+
+function countPairs(ordered) {
+  let flashes = 0;
+  for (let i = 0; i + 1 < ordered.length; i++) if (ordered[i].dir !== ordered[i + 1].dir) { flashes++; i++; }
+  return flashes;
+}
+
+// Master: non-looping; window starts in [0, count - fps], never wrapping, and
+// the final second forms one window (fixes (a) and (b)). Preview: looping; a
+// window may run across the seam.
+export function flashesFromRecords(records, fps, { loop = false } = {}) {
+  const count = records.length;
+  const result = { general: 0, red: 0, worstGeneral: null, worstRed: null };
+  for (const key of ['general', 'red']) {
+    const ev = events(records, key);
+    let worst = 0, worstStart = 0, worstList = [];
+    const starts = loop ? count : Math.max(1, count - fps + 1);
+    for (let s = 0; s < starts; s++) {
+      const inside = loop
+        ? ev.map((e) => ({ ...e, k: (e.frame - s + count) % count })).filter((e) => e.k < fps).sort((a, b) => a.k - b.k || a.dir - b.dir)
+        : ev.filter((e) => e.frame >= s && e.frame < Math.min(s + fps, count)).map((e) => ({ ...e, k: e.frame - s }));
+      const n = countPairs(inside);
+      if (n > worst) { worst = n; worstStart = s; worstList = inside.map((e) => `${e.frame}:${e.dir > 0 ? 'up' : 'down'}`); }
+    }
+    result[key] = worst;
+    result[key === 'general' ? 'worstGeneral' : 'worstRed'] = { startFrame: worstStart, startSec: Number((worstStart / fps).toFixed(3)), transitions: worstList };
+  }
+  return result;
+}