@litfamily/litopencode 1.0.7 → 1.0.9

package/skills/lit-typographic-motion/engine/constants.mjs

@@ -0,0 +1,177 @@
+// Every number the motion engine and its gate use lives here. Rows marked [NEW] come from the
+// family spec's own proposed defaults; no user sign-off is recorded for them yet, so they are
+// PROVISIONAL. They are implemented exactly as written and must not be tuned in this wave.
+
+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,
+  BLOCKED_TREATMENT_INVALID: 16,
+  STAGE_CONTRACT_ERROR: 17,
+  STAGE_NONDETERMINISTIC: 18,
+  STAGE_NETWORK_REQUEST: 19,
+  SOUND_INVALID: 20
+});
+
+export const FRAME = Object.freeze({ width: 1920, height: 1080, fps: 60 });
+
+export const limits = Object.freeze({
+  defaultBpm: 100, // MO-A-14
+  generatorMargin: 1.25, // MO-A-09/10: Tier-1 pace = 1.25 x the reading floor
+  minSceneBeats: 2, // MO-A-16
+  beatSnapFrames: 1, // MO-A-15: <= 1 frame at 60 fps
+  masterSamples: 4, masterShutter: 0.5, // MO-A-26
+  previewSamples: 1, // MO-A-27
+  titleSafeX: 96, titleSafeY: 54, // MO-C-04
+  actionSafeX: 48, actionSafeY: 27, // MO-C-05 [NEW] provisional
+  bodyContrast: 4.5, largeContrast: 3, // MO-C-06
+  largeFontPx: 32, largeBoldFontPx: 25, largeBoldWeight: 700, // MO-C-06 [NEW] provisional
+  lineFloorLatin: 0.9, lineFloorHangul: 1.0, wordFloor: 0.5, revealFloor: 0.35, // MO-C-07/08 [NEW] provisional
+  secondsPerHangulSyllable: 0.2, latinWordsPerSecond: 3.3, latinCharsPerSecond: 17, // MO-C-07/08 [NEW] provisional
+  minFps: 30, minDurationSec: 3, warnDurationSec: 90, // MO-C-10..12 (30 fps floor and 3 s floor [NEW] provisional)
+  previewMaxBytes: 3 * 1000 * 1000, posterMaxBytes: 1000 * 1000, // MO-C-13 [NEW] provisional
+  mp4WarnBytesPer10s: 100 * 1000 * 1000, // MO-C-13 [NEW] provisional
+  stillInkRatio: 0.9, // MO-C-14 [NEW] provisional
+  displayTrackingFloorEm: -0.04, // MO-C-25 [NEW] provisional
+  lineHeightLatin: 1.5, lineHeightCjk: 1.6, lineHeightThreePlus: 1.4, // MO-C-26
+  measureMinCh: 60, measureMaxCh: 75, cjkMeasureMinCh: 30, cjkMeasureMaxCh: 45, // MO-C-27
+  clusterHueDeg: 15, clusterSaturation: 0.5, clusterMinSidePx: 24, // MO-C-29 [NEW] provisional
+  accentMaxEntries: 1, accentMaxFrameFraction: 0.1, // MO-C-29 [NEW] provisional
+  realGpuP95Ms: 40, softwareGpuP95Ms: 250, perfFrames: 120, // MO-D-02 [NEW] provisional
+  nearBlackLuminance: 0.05, nearBlackQuantile: 0.995, nearBlackFloorMultiple: 2, nearBlackFadeSec: 1, // MO-D-03 [NEW] provisional
+  missingGlyphsAllowed: 0, // MO-D-04 [NEW] provisional
+  flashLimitGeneral: 3, flashLimitRed: 3, // MO-C-03
+  eventsPerSecondPerShot: 2, // MO-SH-03
+  glitchHitRateCap: 2.0, glitchAreaCapPct: 20, // MO-SH-05
+  surgeRateCap: 2, surgeEdgeFloorSec: 0.1, // MO-SH-06
+  crtFlickerCap: 0.06, // MO-SH-07
+  maxTerminalLayers: 2, // MO-SH-11
+  fullFrameStepDelta: 0.1, fullFrameStepArea: 0.25 // MO-SH-04a
+});
+
+// Rules whose threshold is a [NEW] spec default; the report labels each one provisional.
+export const provisionalRules = 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"
+]);
+
+// MO-C-03 flash audit geometry (logical px at 1920x1080).
+export const flashGeometry = Object.freeze({
+  gridW: 320, gridH: 180, cellPx: 6,
+  windowCellsW: 107, windowCellsH: 60, // 640x360 logical px, a 10-degree field
+  areaFraction: 0.25, // more than 25% of one window (> 57,600 px)
+  deltaL: 0.1, darkerBelow: 0.8,
+  redRatio: 0.8, redScale: 320, redDelta: 20,
+  historyFrames: 3 // cells registered in frames [f-2, f]
+});
+
+// MO-SH-09: the one canonical software-rasterizer list.
+export const softwareRendererNames = Object.freeze([
+  "swiftshader", "llvmpipe", "softpipe", "lavapipe", "apple software renderer", "microsoft basic render driver"
+]);
+export const unknownRenderer = "unknown (debug-info extension unavailable)";
+export function isSoftwareRenderer(name) {
+  const lower = String(name ?? "").toLowerCase();
+  return softwareRendererNames.some((part) => lower.includes(part));
+}
+
+// MO-A-51: per-platform GPU rung, then the SwiftShader rung; anti-throttling flags always appended.
+export const alwaysChromeFlags = Object.freeze([
+  "--disable-background-timer-throttling", "--disable-renderer-backgrounding", "--disable-backgrounding-occluded-windows"
+]);
+// Every launch also carries these two, so headless Chrome under a custom profile or an isolated HOME
+// never asks the macOS keychain for its safe-storage item (that request raises a dialog on the
+// user's screen). The engine stores no credentials, so a mock keychain loses nothing.
+export const keychainChromeFlags = Object.freeze(["--use-mock-keychain", "--password-store=basic"]);
+export function chromeFlagRungs(platform = process.platform) {
+  const native = 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 [
+    { name: "gpu", flags: [...native, ...alwaysChromeFlags, ...keychainChromeFlags] },
+    { name: "swiftshader", flags: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", ...alwaysChromeFlags, ...keychainChromeFlags] }
+  ];
+}
+
+// MO-A-58: override vocabulary with a fixed type, range and neutral value per field.
+export const postOverrideTable = Object.freeze({
+  exposure: { kind: "number", min: 0, exclusiveMin: true, max: Infinity, neutral: 1 },
+  bloom: { kind: "number", min: 0, max: 1, neutral: 0 },
+  bloomThreshold: { kind: "number", min: 0, max: 1, neutral: 0.85 },
+  bloomKnee: { kind: "number", min: 0, max: 1, neutral: 0 },
+  bloomRadius: { kind: "number", min: 0, max: 1, neutral: 0 },
+  halation: { kind: "number", min: 0, max: 1, neutral: 0 },
+  ca: { kind: "number", min: 0, max: Infinity, neutral: 0 },
+  grain: { kind: "number", min: 0, max: 1, neutral: 0 },
+  vignette: { kind: "number", min: 0, max: 1, neutral: 0 },
+  fade: { kind: "number", min: 0, max: 1, neutral: 1 },
+  flash: { kind: "number", min: 0, max: 1, neutral: 0 },
+  shake: { kind: "pair", neutral: [0, 0] },
+  zoom: { kind: "number", min: 0, exclusiveMin: true, max: Infinity, neutral: 1 },
+  invert: { kind: "boolean", neutral: false }
+});
+export const flashEventThreshold = 0.1; // each rise of `flash` above 0.1 is one MO-SH-03 event
+
+export const passIds = Object.freeze(["glitch", "tidal-gradient", "crt", "dither", "swiss-grid", "terminal-ui"]);
+
+// MO-B-00: whole-word keyword table, first match wins; an explicit style always wins.
+export const presetKeywordTable = Object.freeze([
+  { preset: "terminalcore", words: ["터미널", "crt", "해커", "terminal", "hacker"], reason: "terminal cue" },
+  { preset: "tidal", words: ["물결", "파도", "잔잔한", "흐름", "gradient", "wave", "tide", "calm"], reason: "flow cue" }
+]);
+
+// MO-B-01..03 style bibles, as data the engine reads. Colours are sRGB hex; the engine
+// linearizes them once. The prose version lives in references/style-bibles.md.
+export const presets = Object.freeze({
+  "swiss-signal": {
+    palette: { background: "#0C0E13", text: "#E9EBE4", signal: "#0F7A82", accent: "#D9A441", secondary: "#4B5058" },
+    passes: ["swiss-grid", "dither"],
+    voices: { display: "display", machine: "machine", body: "body" },
+    motion: { entrance: "slam", entranceSec: 0.18, hold: "hold", cut: "snap-cut" },
+    post: { exposure: 1, bloom: 0.18, bloomThreshold: 0.85, bloomKnee: 0.4, bloomRadius: 0.6, halation: 0.08, ca: 0.8, grain: 0.035, vignette: 0.22, fade: 1, flash: 0, shake: [0, 0], zoom: 1, invert: false },
+    params: {
+      "swiss-grid": { columns: 12, gutterPx: 24, marginPx: 96, baselinePx: 8, moduleSnap: true, showGuides: false, hairlineWidthPx: 1 },
+      dither: { mode: 1, paletteSize: 0, pixelScale: 1, ditherStrength: 0.3 }
+    }
+  },
+  terminalcore: {
+    palette: { background: "#05070A", panel: "#0C1116", text: "#39FF6A", signal: "#39FF6A", alternate: "#2FB6FF", secondary: "#7C8B93" },
+    passes: ["terminal-ui", "crt", "dither", "glitch"],
+    voices: { display: "pixel", machine: "machine", body: "pixel" },
+    motion: { entrance: "type-in", entranceSec: 0, hold: "hold", cut: "hard-cut", bootFlickerSec: 0.25 },
+    post: { exposure: 1, bloom: 0.22, bloomThreshold: 0.8, bloomKnee: 0.4, bloomRadius: 0.55, halation: 0.05, ca: 1.0, grain: 0.03, vignette: 0.3, fade: 1, flash: 0, shake: [0, 0], zoom: 1, invert: false },
+    params: {
+      "terminal-ui": { charGridPx: [14, 24], windowChromeWidthPx: 1.5, meterCount: 2, logLineRateCharsPerSec: 22, caretBlinkHz: 1.2, wordTimingSource: "reading-time" },
+      crt: { scanlineFreqPerFrame: 540, scanlineDepth: 0.22, phosphorPersistence: 0.15, bloomAmount: 0.15, curvature: 0.04, vignette: 0.3, triadMaskAmount: 0.12, flickerAmp: 0.03, flickerFreqHz: 8 },
+      dither: { mode: 1, paletteSize: 0, pixelScale: 2, ditherStrength: 0.35 },
+      glitch: { intensity: 0.35, sliceCount: 6, maxOffsetPx: 24, blockCorruptSize: [32, 18], rgbSplitPx: 3, holdFrames: 2, hitRatePerSec: 1.0, areaCapPct: 12 }
+    }
+  },
+  tidal: {
+    palette: { background: "#0E1420", text: "#E8ECEF", signal: "#124559", stopB: "#4C3B6E", accent: "#E07856" },
+    passes: ["tidal-gradient", "swiss-grid", "glitch"],
+    voices: { display: "display", machine: "machine", body: "body" },
+    motion: { entrance: "drift", entranceSec: 2.4, hold: "flow", cut: "hard-cut", punchSec: 0.3 },
+    post: { exposure: 1, bloom: 0.12, bloomThreshold: 0.85, bloomKnee: 0.4, bloomRadius: 0.7, halation: 0.04, ca: 0.6, grain: 0.03, vignette: 0.18, fade: 1, flash: 0, shake: [0, 0], zoom: 1, invert: false },
+    params: {
+      "tidal-gradient": { flowSpeed: 0.06, warpAmount: 0.35, curlStrength: 0.4, octaves: 4, surgeOnHit: 0.5, surgeAttackSec: 0.15, surgeDecaySec: 0.25, surgeCapPerSec: 2, bandingSteps: 0, ditherAmount: 0.02 },
+      "swiss-grid": { columns: 12, gutterPx: 24, marginPx: 96, baselinePx: 8, moduleSnap: true, showGuides: false, hairlineWidthPx: 1 },
+      glitch: { intensity: 0.3, sliceCount: 5, maxOffsetPx: 18, blockCorruptSize: [32, 18], rgbSplitPx: 2, holdFrames: 2, hitRatePerSec: 0.5, areaCapPct: 10 }
+    }
+  }
+});
+
+// Named easing tokens (MO-A-08, MO-B-01..03). Scenes use these names only.
+export const easeTokens = Object.freeze({
+  slam: [0.16, 1, 0.3, 1],
+  "surge-punch": [0.16, 1, 0.3, 1],
+  drift: [0.37, 0, 0.63, 1],
+  exit: [0.7, 0, 0.84, 0]
+});
+
+export const engineCredit = "mexicat/pdoom-video ca251e3dddda422b364385eb484b5a3593a0990d (MIT)";
+export const engineCreditLine = "Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.";

package/skills/lit-typographic-motion/engine/contrast.mjs

@@ -0,0 +1,101 @@
+// MO-C-06 type contrast measured on rendered frames with the glyph-coverage mask (CF-204's method
+// on a video frame), and MO-C-29's saturated-hue cluster count.
+import { linearLut } from "./flash.mjs";
+import { limits } from "./constants.mjs";
+
+const relative = (a, b) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+function percentile(values, q) {
+  if (values.length === 0) return NaN;
+  const sorted = Float64Array.from(values).sort();
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.round(q * (sorted.length - 1))))];
+}
+
+// CRT barrel: output pixel (u, v) shows the source at (u, v) + d * |d|^2 * k, d = (u, v) - 0.5.
+export function warpMask(mask, width, height, curvature) {
+  if (!curvature) return mask;
+  const out = new Uint8Array(mask.length);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const u = (x + 0.5) / width - 0.5, v = (y + 0.5) / height - 0.5;
+    const r2 = u * u + v * v;
+    const sx = Math.floor((u + u * r2 * curvature + 0.5) * width), sy = Math.floor((v + v * r2 * curvature + 0.5) * height);
+    if (sx >= 0 && sy >= 0 && sx < width && sy < height) out[y * width + x] = mask[sy * width + sx];
+  }
+  return out;
+}
+
+function morph(mask, width, height, x0, y0, x1, y1, radius, erode) {
+  const out = new Uint8Array((x1 - x0) * (y1 - y0));
+  for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+    let value = erode ? 1 : 0;
+    for (let dy = -radius; dy <= radius && (erode ? value : !value); dy++) for (let dx = -radius; dx <= radius; dx++) {
+      const sx = x + dx, sy = y + dy;
+      const on = sx >= 0 && sy >= 0 && sx < width && sy < height && mask[sy * width + sx] > 127;
+      if (erode && !on) { value = 0; break; }
+      if (!erode && on) { value = 1; break; }
+    }
+    out[(y - y0) * (x1 - x0) + (x - x0)] = value;
+  }
+  return out;
+}
+
+const lum = (rgba, i) => 0.2126 * linearLut[rgba[i]] + 0.7152 * linearLut[rgba[i + 1]] + 0.0722 * linearLut[rgba[i + 2]];
+
+// One textBoxes entry: foreground = median linear luminance under the mask eroded by 1 px (5th and
+// 95th percentiles for a gradient fill); background = 5th/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.
+// `large` overrides the type engine's size rule (the stage judges large as 3 % of the short side).
+export function boxContrast(rgba, mask, width, height, box, scale = 1, large = undefined) {
+  const [bx0, by0, bx1, by1] = box.bbox.map((v) => v * scale);
+  const grow = 0.25 * box.capHeightPx * scale;
+  const clampX = (v) => Math.max(0, Math.min(width, Math.round(v))), clampY = (v) => Math.max(0, Math.min(height, Math.round(v)));
+  const ix0 = clampX(bx0), iy0 = clampY(by0), ix1 = clampX(bx1), iy1 = clampY(by1);
+  const ox0 = clampX(bx0 - grow), oy0 = clampY(by0 - grow), ox1 = clampX(bx1 + grow), oy1 = clampY(by1 + grow);
+  if (ix1 <= ix0 || iy1 <= iy0) return null;
+  const eroded = morph(mask, width, height, ix0, iy0, ix1, iy1, Math.max(1, Math.round(scale)), true);
+  const fg = [];
+  for (let y = iy0; y < iy1; y++) for (let x = ix0; x < ix1; x++) if (eroded[(y - iy0) * (ix1 - ix0) + (x - ix0)]) fg.push(lum(rgba, (y * width + x) * 4));
+  const dilated = morph(mask, width, height, ox0, oy0, ox1, oy1, Math.max(2, Math.round(2 * scale)), false);
+  const bg = [];
+  for (let y = oy0; y < oy1; y++) for (let x = ox0; x < ox1; x++) if (!dilated[(y - oy0) * (ox1 - ox0) + (x - ox0)]) bg.push(lum(rgba, (y * width + x) * 4));
+  if (fg.length < 4 || bg.length < 4) return null;
+  const fgValues = box.fill === "gradient" ? [percentile(fg, 0.05), percentile(fg, 0.95)] : [percentile(fg, 0.5)];
+  const bgValues = [percentile(bg, 0.05), percentile(bg, 0.95)];
+  let worst = Infinity;
+  for (const f of fgValues) for (const b of bgValues) worst = Math.min(worst, relative(f, b));
+  const isLarge = large ?? (box.fontSizePx >= limits.largeFontPx || (box.fontSizePx >= limits.largeBoldFontPx && box.weight >= limits.largeBoldWeight));
+  return { ratio: worst, floor: isLarge ? limits.largeContrast : limits.bodyContrast, large: isLarge, fgPixels: fg.length, bgPixels: bg.length };
+}
+
+export function hexToHsl(hex) {
+  const n = parseInt(hex.replace("#", ""), 16);
+  const r = ((n >> 16) & 255) / 255, g = ((n >> 8) & 255) / 255, b = (n & 255) / 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  const h = max === r ? ((g - b) / d + (g < b ? 6 : 0)) * 60 : max === g ? ((b - r) / d + 2) * 60 : ((r - g) / d + 4) * 60;
+  return { h, s, l };
+}
+
+const hueDistance = (a, b) => { const d = Math.abs(a - b) % 360; return d > 180 ? 360 - d : d; };
+
+// MO-C-29: saturated fills (HSL S >= 50%, region >= 24x24 logical px) grouped into +-15 degree hue
+// clusters. Each observation is { color, frame, entryId }.
+export function hueClusters(observations) {
+  const clusters = [];
+  for (const obs of observations) {
+    const { h, s } = hexToHsl(obs.color);
+    if (s < limits.clusterSaturation) continue;
+    let cluster = clusters.find((c) => hueDistance(c.hue, h) <= limits.clusterHueDeg);
+    if (!cluster) { cluster = { hue: h, colors: new Set(), frames: new Set(), entries: new Set() }; clusters.push(cluster); }
+    cluster.colors.add(obs.color.toUpperCase());
+    cluster.frames.add(obs.frame);
+    cluster.entries.add(obs.entryId);
+  }
+  return clusters.map((c) => ({ hue: Math.round(c.hue), colors: [...c.colors], frames: c.frames.size, entries: [...c.entries] }));
+}
+
+export function bigEnough(bbox) {
+  return bbox && bbox[2] - bbox[0] >= limits.clusterMinSidePx && bbox[3] - bbox[1] >= limits.clusterMinSidePx;
+}

package/skills/lit-typographic-motion/engine/encode.mjs

@@ -0,0 +1,46 @@
+// The pinned encodes both render paths share: the H.264 master from raw RGBA frames (MO-A-03 args at
+// the frame's own size and rate) and the looping preview's encoder ladder (MO-A-38).
+import { spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { rmSync } from "node:fs";
+import path from "node:path";
+
+export function encodeMaster(file, width, height, fps) {
+  const args = ["-y", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${width}x${height}`, "-r", String(fps), "-i", "pipe:0",
+    "-vf", "scale=out_color_matrix=bt709:out_range=tv,format=yuv420p", "-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", file];
+  const child = spawn("ffmpeg", args, { stdio: ["pipe", "ignore", "pipe"] });
+  const chunks = [];
+  child.stderr.on("data", (chunk) => chunks.push(chunk));
+  return { child, stderr: () => Buffer.concat(chunks).toString("utf8") };
+}
+
+export async function write(child, bytes) {
+  if (!child.stdin.write(bytes)) await once(child.stdin, "drain");
+}
+
+// Preview size rungs: [long edge in px, fps]. The long edge is the width at 16:9 and the height at 9:16.
+export function previewRungs() {
+  return [[960, 30], [720, 24], [540, 20]];
+}
+
+export function previewSize(longEdge, width, height) {
+  return width >= height
+    ? { width: longEdge, height: Math.round((longEdge * height) / width / 2) * 2 }
+    : { width: Math.round((longEdge * width) / height / 2) * 2, height: longEdge };
+}
+
+export async function encodePreview(runDir, frameDir, fps, count, encoder) {
+  const pattern = path.join(frameDir, "p%05d.png");
+  const target = path.join(runDir, encoder === "gif" ? "preview.gif" : "preview.webp");
+  rmSync(path.join(runDir, "preview.webp"), { force: true });
+  rmSync(path.join(runDir, "preview.gif"), { force: true });
+  let result;
+  if (encoder === "libwebp_anim") result = spawnSync("ffmpeg", ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", pattern, "-c:v", "libwebp_anim", "-lossless", "0", "-q:v", "78", "-loop", "0", target], { encoding: "utf8", timeout: 600000 });
+  else if (encoder === "img2webp") {
+    const files = Array.from({ length: count }, (_, k) => path.join(frameDir, `p${String(k).padStart(5, "0")}.png`));
+    result = spawnSync("img2webp", ["-loop", "0", "-lossy", "-q", "78", "-m", "4", "-d", String(Math.round(1000 / fps)), ...files, "-o", target], { encoding: "utf8", timeout: 600000, maxBuffer: 16_000_000 });
+  } else result = spawnSync("ffmpeg", ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", pattern, "-filter_complex", "[0:v]split[a][b];[a]palettegen=stats_mode=full[p];[b][p]paletteuse=dither=bayer:bayer_scale=4", "-loop", "0", target], { encoding: "utf8", timeout: 600000 });
+  if (result.status !== 0) throw new Error(`preview encode (${encoder}) failed: ${(result.stderr || result.error?.message || "").trim().split("\n").slice(-2).join(" ")}`);
+  return target;
+}

package/skills/lit-typographic-motion/engine/flash.mjs

@@ -0,0 +1,216 @@
+// MO-C-03 / MO-SH-04 / MO-SH-04a: the WCAG 2.3.1 excursion-method flash audit, written for this
+// engine's own 8-bit output frames. The render feeds it the exact bytes it hands to ffmpeg and to the
+// preview encoder and logs each frame's transitions; the gate counts flashes from those records.
+import { flashGeometry as G, limits } from "./constants.mjs";
+
+const toLinear = new Float64Array(256);
+for (let i = 0; i < 256; i++) {
+  const c = i / 255;
+  toLinear[i] = c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+export const linearLut = toLinear;
+
+// The audit geometry for a frame: the 320x180 grid and 107x60-cell window at 16:9, transposed to
+// 180x320 cells and a 60x107-cell window for a 9:16 frame.
+export function flashGeometryFor(width, height) {
+  if (width >= height) return G;
+  return Object.freeze({ ...G, gridW: G.gridH, gridH: G.gridW, windowCellsW: G.windowCellsH, windowCellsH: G.windowCellsW });
+}
+
+// Area-average an RGBA frame of any size onto the audit grid (linear R, G, B and luminance).
+// Integer block sizes take a fast path; other sizes use exact fractional area weights.
+export function auditCells(rgba, width, height, geometry = flashGeometryFor(width, height)) {
+  const G = geometry;
+  const cells = G.gridW * G.gridH;
+  const R = new Float64Array(cells), Gc = new Float64Array(cells), B = new Float64Array(cells), L = new Float64Array(cells);
+  const bw = width / G.gridW, bh = height / G.gridH;
+  if (Number.isInteger(bw) && Number.isInteger(bh)) {
+    const area = bw * bh;
+    for (let cy = 0; cy < G.gridH; cy++) for (let cx = 0; cx < G.gridW; cx++) {
+      let r = 0, g = 0, b = 0;
+      for (let y = cy * bh; y < (cy + 1) * bh; y++) {
+        let at = (y * width + cx * bw) * 4;
+        for (let x = 0; x < bw; x++, at += 4) { r += toLinear[rgba[at]]; g += toLinear[rgba[at + 1]]; b += toLinear[rgba[at + 2]]; }
+      }
+      const i = cy * G.gridW + cx;
+      R[i] = r / area; Gc[i] = g / area; B[i] = b / area;
+      L[i] = 0.2126 * R[i] + 0.7152 * Gc[i] + 0.0722 * B[i];
+    }
+    return { R, G: Gc, B, L };
+  }
+  const xw = spans(width, G.gridW), yw = spans(height, G.gridH);
+  for (let cy = 0; cy < G.gridH; cy++) for (let cx = 0; cx < G.gridW; cx++) {
+    let r = 0, g = 0, b = 0, total = 0;
+    for (const [y, wy] of yw[cy]) for (const [x, wx] of xw[cx]) {
+      const w = wx * wy, at = (y * width + x) * 4;
+      r += toLinear[rgba[at]] * w; g += toLinear[rgba[at + 1]] * w; b += toLinear[rgba[at + 2]] * w; total += w;
+    }
+    const i = cy * G.gridW + cx;
+    R[i] = r / total; Gc[i] = g / total; B[i] = b / total;
+    L[i] = 0.2126 * R[i] + 0.7152 * Gc[i] + 0.0722 * B[i];
+  }
+  return { R, G: Gc, B, L };
+}
+
+function spans(size, count) {
+  const step = size / count;
+  return Array.from({ length: count }, (_, c) => {
+    const a = c * step, b = (c + 1) * step, out = [];
+    for (let p = Math.floor(a); p < Math.ceil(b); p++) {
+      const w = Math.min(b, p + 1) - Math.max(a, p);
+      if (w > 1e-9) out.push([p, w]);
+    }
+    return out;
+  });
+}
+
+function redValue(r, g, b) {
+  const sum = r + g + b;
+  if (sum <= 0 || r / sum < G.redRatio) return 0;
+  return Math.max(0, r - g - b) * G.redScale;
+}
+
+function windowHit(mask, G) {
+  const W = G.gridW, H = G.gridH, ww = G.windowCellsW, wh = G.windowCellsH;
+  const sat = new Uint32Array((W + 1) * (H + 1));
+  let any = false;
+  for (let y = 1; y <= H; y++) {
+    let row = 0;
+    for (let x = 1; x <= W; x++) {
+      row += mask[(y - 1) * W + x - 1];
+      sat[y * (W + 1) + x] = sat[(y - 1) * (W + 1) + x] + row;
+    }
+    if (row) any = true;
+  }
+  if (!any) return false;
+  const threshold = ww * wh * G.areaFraction;
+  for (let y = 0; y + wh <= H; y++) for (let x = 0; x + ww <= W; x++) {
+    const area = sat[(y + wh) * (W + 1) + x + ww] - sat[y * (W + 1) + x + ww] - sat[(y + wh) * (W + 1) + x] + sat[y * (W + 1) + x];
+    if (area > threshold) return true;
+  }
+  return false;
+}
+
+// Streaming excursion detector. push() takes one frame's audit cells and returns that frame's
+// frame-level transitions: an up/down general transition and an up/down red transition, each
+// reported once at its onset frame, plus MO-SH-04a's full-frame luminance step flag.
+export class ExcursionDetector {
+  constructor(geometry = G) {
+    this.G = geometry;
+    const n = geometry.gridW * geometry.gridH;
+    this.lo = new Float64Array(n); this.hi = new Float64Array(n);
+    this.rlo = new Float64Array(n); this.rhi = new Float64Array(n);
+    this.prevL = new Float64Array(n);
+    this.history = [];
+    this.active = { up: false, down: false, redUp: false, redDown: false };
+    this.frames = 0;
+  }
+
+  push(cells) {
+    const G = this.G;
+    const n = G.gridW * G.gridH;
+    const up = new Uint8Array(n), down = new Uint8Array(n), redUp = new Uint8Array(n), redDown = new Uint8Array(n);
+    let stepped = 0;
+    for (let i = 0; i < n; i++) {
+      const l = cells.L[i];
+      const v = redValue(cells.R[i], cells.G[i], cells.B[i]);
+      if (this.frames === 0) {
+        this.lo[i] = this.hi[i] = l; this.rlo[i] = this.rhi[i] = v; this.prevL[i] = l;
+        continue;
+      }
+      if (Math.abs(l - this.prevL[i]) >= limits.fullFrameStepDelta) stepped++;
+      this.prevL[i] = l;
+      if (l - this.lo[i] >= G.deltaL && Math.min(l, this.lo[i]) < G.darkerBelow) { up[i] = 1; this.lo[i] = this.hi[i] = l; }
+      else if (this.hi[i] - l >= G.deltaL && Math.min(l, this.hi[i]) < G.darkerBelow) { down[i] = 1; this.lo[i] = this.hi[i] = l; }
+      else { if (l < this.lo[i]) this.lo[i] = l; if (l > this.hi[i]) this.hi[i] = l; }
+      if (v - this.rlo[i] > G.redDelta) { redUp[i] = 1; this.rlo[i] = this.rhi[i] = v; }
+      else if (this.rhi[i] - v > G.redDelta) { redDown[i] = 1; this.rlo[i] = this.rhi[i] = v; }
+      else { if (v < this.rlo[i]) this.rlo[i] = v; if (v > this.rhi[i]) this.rhi[i] = v; }
+    }
+    const first = this.frames === 0;
+    this.frames++;
+    this.history.push({ up, down, redUp, redDown });
+    if (this.history.length > G.historyFrames) this.history.shift();
+    const union = (key) => {
+      const mask = new Uint8Array(n);
+      for (const frame of this.history) { const m = frame[key]; for (let i = 0; i < n; i++) mask[i] |= m[i]; }
+      return mask;
+    };
+    const result = { fullStep: !first && stepped > n * limits.fullFrameStepArea };
+    for (const key of ["up", "down", "redUp", "redDown"]) {
+      const hit = !first && windowHit(union(key), G);
+      result[key] = hit && !this.active[key];
+      this.active[key] = hit;
+    }
+    return result;
+  }
+}
+
+// Pair opposing transitions inside one window; a flash is one opposing pair.
+function pairsIn(list) {
+  let pairs = 0, waiting = 0;
+  for (const direction of list) {
+    if (waiting === 0) waiting = direction;
+    else if (direction !== waiting) { pairs++; waiting = 0; }
+  }
+  return pairs;
+}
+
+// Count flashes from per-frame transition records. `records[f]` = { up, down, redUp, redDown }.
+// Master (looping=false): windows [s, s+fps) with s in [0, count-fps] and no wrap (MO-C-03 fixes a/b).
+// Preview (looping=true): every start s, and the window wraps across the loop seam (MO-SH-04).
+export function countFlashes(records, fps, looping) {
+  const count = records.length;
+  const events = { general: [], red: [] };
+  records.forEach((record, frame) => {
+    if (record.up) events.general.push([frame, 1]);
+    if (record.down) events.general.push([frame, -1]);
+    if (record.redUp) events.red.push([frame, 1]);
+    if (record.redDown) events.red.push([frame, -1]);
+  });
+  const worst = {};
+  for (const kind of ["general", "red"]) {
+    const list = events[kind];
+    let best = { flashes: 0, start: 0, transitions: [] };
+    const starts = looping ? count : Math.max(1, count - fps + 1);
+    for (let s = 0; s < starts; s++) {
+      let inWindow;
+      if (looping) {
+        inWindow = list.filter(([frame]) => ((frame - s + count) % count) < fps)
+          .sort((a, b) => ((a[0] - s + count) % count) - ((b[0] - s + count) % count));
+      } else {
+        const end = Math.min(s + fps, count);
+        inWindow = list.filter(([frame]) => frame >= s && frame < end);
+      }
+      const flashes = pairsIn(inWindow.map(([, direction]) => direction));
+      if (flashes > best.flashes) best = { flashes, start: s, transitions: inWindow.map(([frame, direction]) => `${frame}${direction > 0 ? "+" : "-"}`) };
+    }
+    worst[kind] = best;
+  }
+  return {
+    general: worst.general.flashes, red: worst.red.flashes,
+    worstWindow: { general: worst.general, red: worst.red },
+    pass: worst.general.flashes <= limits.flashLimitGeneral && worst.red.flashes <= limits.flashLimitRed
+  };
+}
+
+// Run the detector over a whole in-memory sequence (fixtures, preview frames).
+// A looping sequence runs one extra second past the seam so transitions at the wrap are seen.
+export function auditSequence(frames, width, height, fps, looping) {
+  const geometry = flashGeometryFor(width, height);
+  const detector = new ExcursionDetector(geometry);
+  const records = [];
+  const steps = [];
+  const total = looping ? frames.length + fps : frames.length;
+  for (let i = 0; i < total; i++) {
+    const frame = frames[i % frames.length];
+    const record = detector.push(auditCells(frame, width, height, geometry));
+    if (i < frames.length) { records.push(record); steps.push(record.fullStep); }
+    else {
+      const target = records[i % frames.length];
+      for (const key of ["up", "down", "redUp", "redDown"]) target[key] = target[key] || record[key];
+      if (record.fullStep) steps[i % frames.length] = true;
+    }
+  }
+  return { records, ...countFlashes(records, fps, looping), fullStep: steps.some(Boolean) };
+}