@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/chrome.mjs

@@ -0,0 +1,330 @@
+// Headless Chrome over the DevTools pipe transport (fd 3/4, NUL-delimited JSON), so no control
+// port ever listens. Re-expresses the driver mechanism of mexicat/pdoom-video app/scripts/render.ts
+// (MIT, see ../NOTICE) without a driver package. Launch walks the MO-A-51 flag ladder and a rung
+// only counts when a real page gets a WebGL2 context; the page is served from disk through CDP
+// Fetch interception, so nothing listens for it either.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { CHROME_ALWAYS, CHROME_RUNGS, EXIT, UNKNOWN_RENDERER } from "../core/constants.mjs";
+
+export class BlockedError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const CANDIDATES = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    path.join(homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+  ],
+  linux: ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+function onPath(name) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8" });
+  return probe.status === 0 ? probe.stdout.trim().split("\n")[0] : null;
+}
+
+/** Resolve Chrome: $CHROME_PATH, then the platform's usual locations. Returns null when absent. */
+export function findChrome(env = process.env) {
+  if (env.CHROME_PATH) return existsSync(env.CHROME_PATH) ? env.CHROME_PATH : null;
+  for (const candidate of CANDIDATES[process.platform] ?? []) {
+    if (path.isAbsolute(candidate)) {
+      if (existsSync(candidate)) return candidate;
+    } else {
+      const found = onPath(candidate);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function chromeVersion(chrome) {
+  const probe = spawnSync(chrome, ["--version"], { encoding: "utf8", timeout: 15000 });
+  return probe.status === 0 ? probe.stdout.trim() : `unknown (${(probe.stderr || probe.error?.message || "").trim().split("\n")[0]})`;
+}
+
+/**
+ * The stage path's flag set (director brief 6d): the software rung only (SwiftShader, CPU raster),
+ * the compositor and animation flags that keep a captured frame a function of the page's state,
+ * sRGB at scale 1, the window at the format's size, no background networking, and a resolver rule
+ * that leaves only the synthetic stage origin resolvable.
+ */
+export function stageFlags({ width, height }) {
+  return [
+    ...CHROME_RUNGS.software, "--disable-gpu-rasterization", "--disable-partial-raster",
+    "--run-all-compositor-stages-before-draw", "--disable-checker-imaging", "--disable-new-content-rendering-timeout",
+    "--disable-threaded-animation", "--disable-threaded-scrolling", "--disable-image-animation-resync", "--disable-lcd-text",
+    "--force-color-profile=srgb", "--hide-scrollbars", "--mute-audio", "--force-device-scale-factor=1", `--window-size=${width},${height}`,
+    "--disable-background-networking", "--disable-component-update", "--disable-sync", "--no-pings", "--metrics-recording-only",
+    "--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE lit.stage",
+    ...CHROME_ALWAYS,
+  ];
+}
+
+/** The ladder for this platform: GPU rung(s) first, SwiftShader last (MO-A-51). */
+export function flagLadder({ softwareOnly = false } = {}) {
+  const gpu = CHROME_RUNGS[process.platform] ?? [];
+  const rungs = softwareOnly ? [CHROME_RUNGS.software] : [...gpu, CHROME_RUNGS.software];
+  return rungs.map((rung) => [...rung, ...CHROME_ALWAYS]);
+}
+
+// Messages arrive as raw bytes: each chunk is scanned once for the NUL terminator and kept as a
+// Buffer until its message is complete, so a large screenshot never rescans what came before and a
+// multi-byte character split across two chunks is decoded whole.
+export class Pipe {
+  constructor(child) {
+    this.child = child;
+    this.id = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.parts = [];
+    this.closed = false;
+    child.stdio[4].on("data", (chunk) => this.receive(chunk));
+    child.stdio[4].on("error", () => {});
+    child.stdio[3].on("error", () => {});
+    child.on("exit", () => {
+      this.closed = true;
+      for (const { reject } of this.pending.values()) reject(new Error("Chrome exited"));
+      this.pending.clear();
+    });
+  }
+  receive(chunk) {
+    let start = 0;
+    for (;;) {
+      const end = chunk.indexOf(0, start);
+      if (end < 0) {
+        if (start < chunk.length) this.parts.push(chunk.subarray(start));
+        return;
+      }
+      this.parts.push(chunk.subarray(start, end));
+      start = end + 1;
+      const message = JSON.parse(Buffer.concat(this.parts).toString("utf8"));
+      this.parts = [];
+      if (message.id !== undefined && this.pending.has(message.id)) {
+        const { resolve, reject } = this.pending.get(message.id);
+        this.pending.delete(message.id);
+        if (message.error) reject(new Error(`${message.error.message}${message.error.data ? `: ${message.error.data}` : ""}`));
+        else resolve(message.result);
+      } else if (message.method) {
+        for (const fn of this.listeners.get(message.method) ?? []) fn(message.params, message.sessionId);
+      }
+    }
+  }
+  send(method, params = {}, sessionId) {
+    if (this.closed) return Promise.reject(new Error("Chrome pipe closed"));
+    const id = ++this.id;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.child.stdio[3].write(`${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`);
+    });
+  }
+  on(method, fn) {
+    if (!this.listeners.has(method)) this.listeners.set(method, []);
+    this.listeners.get(method).push(fn);
+  }
+}
+
+const withTimeout = (promise, ms, message) => Promise.race([
+  promise,
+  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref()),
+]);
+
+const CONTENT_TYPES = { ".html": "text/html", ".mjs": "text/javascript", ".js": "text/javascript", ".json": "application/json", ".ttf": "font/ttf", ".otf": "font/otf", ".svg": "image/svg+xml" };
+
+// A loopback origin: the page may then open its WebSocket to 127.0.0.1 without tripping Chrome's
+// private-network rules. Every request to it is fulfilled by Fetch interception, so nothing is
+// ever sent to a real localhost server.
+export const APP_ORIGIN = "http://localhost";
+
+/**
+ * One headless Chrome with one page. `routes(pathname)` returns a file path or { body, type } for a
+ * request under APP_ORIGIN, or null for 404.
+ */
+/**
+ * The full argument list for one headless launch. `--use-mock-keychain` and `--password-store=basic`
+ * keep Chrome away from the OS keychain: with a fresh profile (or an isolated HOME) it would
+ * otherwise look for its safe-storage item and macOS would put a keychain dialog on screen.
+ */
+export function launchArgs(profileDir, flags) {
+  return [
+    "--headless", `--user-data-dir=${profileDir}`, "--remote-debugging-pipe", "--no-first-run", "--no-default-browser-check",
+    "--use-mock-keychain", "--password-store=basic",
+    "--disable-extensions", "--hide-scrollbars", "--mute-audio", ...flags, "about:blank",
+  ];
+}
+
+export class ChromeSession {
+  static async launch({ chrome, flags, profileDir, routes, timeoutMs = 30000 }) {
+    mkdirSync(profileDir, { recursive: true });
+    const args = launchArgs(profileDir, flags);
+    let child;
+    try {
+      child = spawn(chrome, args, { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"] });
+    } catch (error) {
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch: ${error.message}`);
+    }
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    const spawnError = new Promise((_, reject) => child.on("error", (error) => reject(error)));
+    const session = new ChromeSession(child, profileDir, routes, flags);
+    try {
+      await withTimeout(Promise.race([session.pipe.send("Browser.getVersion"), spawnError]), timeoutMs, "Chrome did not answer on the DevTools pipe");
+    } catch (error) {
+      session.kill();
+      const first = stderr.split("\n").map((l) => l.trim()).find(Boolean) ?? error.message;
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch headless: ${first}`);
+    }
+    session.stderr = () => stderr;
+    return session;
+  }
+
+  constructor(child, profileDir, routes, flags) {
+    this.child = child;
+    this.profileDir = profileDir;
+    this.routes = routes;
+    this.flags = flags;
+    this.pipe = new Pipe(child);
+    this.logs = [];
+  }
+
+  async openPage() {
+    const { targetId } = await this.pipe.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await this.pipe.send("Target.attachToTarget", { targetId, flatten: true });
+    this.sessionId = sessionId;
+    this.pipe.on("Runtime.exceptionThrown", (p) => this.logs.push(`[exception] ${p.exceptionDetails?.exception?.description ?? p.exceptionDetails?.text}`));
+    this.pipe.on("Runtime.consoleAPICalled", (p) => {
+      if (p.type === "error" || p.type === "warning") this.logs.push(`[${p.type}] ${p.args.map((a) => a.value ?? a.description).join(" ")}`);
+    });
+    this.pipe.on("Fetch.requestPaused", (p, sid) => this.serve(p, sid));
+    // Chrome gates a page's connections to 127.0.0.1 behind a loopback-network permission; grant
+    // it for the app origin only (older builds do not know the name, which is fine).
+    await this.pipe.send("Browser.grantPermissions", { permissions: ["loopbackNetwork"], origin: APP_ORIGIN }).catch(() => {});
+    await this.send("Runtime.enable");
+    await this.send("Fetch.enable", { patterns: [{ urlPattern: `${APP_ORIGIN}/*`, requestStage: "Request" }] });
+    await this.send("Emulation.setDeviceMetricsOverride", { width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false });
+  }
+
+  async serve(params, sid) {
+    const url = new URL(params.request.url);
+    let resolved = null;
+    try {
+      resolved = this.routes(decodeURIComponent(url.pathname));
+    } catch {
+      resolved = null;
+    }
+    try {
+      if (!resolved) {
+        await this.pipe.send("Fetch.fulfillRequest", { requestId: params.requestId, responseCode: 404, body: "" }, sid);
+        return;
+      }
+      const body = typeof resolved === "string" ? readFileSync(resolved) : Buffer.from(resolved.body);
+      const type = typeof resolved === "string" ? CONTENT_TYPES[path.extname(resolved)] ?? "application/octet-stream" : resolved.type;
+      await this.pipe.send("Fetch.fulfillRequest", {
+        requestId: params.requestId, responseCode: 200,
+        responseHeaders: [{ name: "Content-Type", value: type }, { name: "Cache-Control", value: "no-store" }],
+        body: body.toString("base64"),
+      }, sid);
+    } catch (error) {
+      this.logs.push(`[serve] ${url.pathname}: ${error.message}`);
+    }
+  }
+
+  send(method, params = {}) {
+    return this.pipe.send(method, params, this.sessionId);
+  }
+
+  /** Evaluate an expression in the page; resolves promises and returns the JSON value. */
+  async evaluate(expression, { timeoutMs = 600000 } = {}) {
+    const result = await withTimeout(this.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }), timeoutMs, `page evaluation timed out: ${expression.slice(0, 80)}`);
+    if (result.exceptionDetails) throw new Error(`page error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+    return result.result.value;
+  }
+
+  /** WebGL2 in a blank page: { webgl2, renderer } (MO-A-51 rung check). */
+  async probeWebgl2() {
+    return this.evaluate(`(() => {
+      const gl = document.createElement('canvas').getContext('webgl2');
+      if (!gl) return { webgl2: false, renderer: null };
+      const ext = gl.getExtension('WEBGL_debug_renderer_info');
+      return { webgl2: true, renderer: ext ? String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)) : ${JSON.stringify(UNKNOWN_RENDERER)} };
+    })()`);
+  }
+
+  async navigate(url) {
+    await this.send("Page.enable");
+    await this.send("Page.navigate", { url });
+  }
+
+  kill() {
+    try {
+      this.child.kill("SIGKILL");
+    } catch {
+      // already gone
+    }
+  }
+
+  async close() {
+    try {
+      await withTimeout(this.pipe.send("Browser.close"), 5000, "close timed out");
+    } catch {
+      this.kill();
+    }
+    const exited = (ms) => new Promise((resolve) => {
+      if (this.child.exitCode !== null || this.child.signalCode) resolve();
+      else this.child.once("exit", resolve);
+      setTimeout(resolve, ms).unref();
+    });
+    await exited(5000);
+    // A browser that acknowledged Browser.close but is still alive would keep this process open.
+    if (this.child.exitCode === null && !this.child.signalCode) {
+      this.kill();
+      await exited(2000);
+    }
+    rmSync(this.profileDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Walk the ladder: launch, check WebGL2 in a real page, keep the first rung that has it. Throws
+ * BlockedError 10 when Chrome itself cannot run, 11 when Chrome runs on every rung but no WebGL2.
+ */
+export async function launchWithLadder({ chrome, profileRoot, routes, softwareOnly = false, log = () => {} }) {
+  if (!chrome) throw new BlockedError(EXIT.BLOCKED_NO_CHROME, "BLOCKED_NO_CHROME: Chrome/Chromium not found (set CHROME_PATH or install Google Chrome)");
+  const failures = [];
+  let index = 0;
+  for (const flags of flagLadder({ softwareOnly })) {
+    const profileDir = path.join(profileRoot, `c${process.pid % 100000}-${index++}`);
+    let session;
+    try {
+      session = await ChromeSession.launch({ chrome, flags, profileDir, routes });
+    } catch (error) {
+      rmSync(profileDir, { recursive: true, force: true });
+      if (error instanceof BlockedError) throw error;
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: ${error.message}`);
+    }
+    try {
+      await session.openPage();
+      const probe = await session.probeWebgl2();
+      if (probe.webgl2) {
+        log(`chrome rung ok: ${flags.join(" ")} -> ${probe.renderer}`);
+        return { session, flags, renderer: probe.renderer };
+      }
+      failures.push(`${flags[0]}: getContext('webgl2') returned null`);
+    } catch (error) {
+      failures.push(`${flags[0]}: ${error.message}`);
+    }
+    await session.close();
+  }
+  throw new BlockedError(EXIT.BLOCKED_NO_WEBGL2, `BLOCKED_NO_WEBGL2: Chrome ran but no rung produced a WebGL2 context (${failures.join("; ")})`);
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/coverage.mjs

@@ -0,0 +1,83 @@
+// MO-D-04 glyph coverage, run before the first frame: every codepoint of every string a shot shows
+// must resolve in the cmap of the font its script run uses (the same run-to-font mapping the page
+// type kit uses). A missing glyph is a pre-flight FAIL naming the font and the character, never a
+// blank glyph found later in a still.
+import { readFileSync } from "node:fs";
+import { scriptRuns } from "../core/text.mjs";
+import { runFontKey } from "../core/voices.mjs";
+import { loadFontManifest, fontLocation, opentypeModule } from "./runtime.mjs";
+
+/** The strings each shot shows, with the voice they are set in. */
+export function shotStrings(plan) {
+  const out = [];
+  const add = (shot, voice, text) => {
+    if (text) out.push({ shot: shot.id ?? shot.scene, voice, text });
+  };
+  for (const shot of plan.shots) {
+    if (shot.scene === "signature") {
+      out.push({ shot: shot.id ?? shot.scene, voice: "signature", text: shot.text, strokeFont: shot.font ?? "ems-readability" });
+      continue;
+    }
+    add(shot, "display", shot.text);
+    add(shot, "display", shot.heading);
+    add(shot, "machine", shot.sub);
+    add(shot, "body", shot.label);
+    add(shot, "machine", shot.display);
+    for (const item of shot.items ?? []) add(shot, "body", item);
+  }
+  if (plan.preset.passes.includes("terminal-ui")) {
+    out.push({ shot: "terminal-ui", voice: "chrome", text: plan.label });
+    out.push({ shot: "terminal-ui", voice: "machine", text: "T+0123456789." });
+  }
+  return out;
+}
+
+/** Font keys a plan needs: every run font plus any stroke font. */
+export function planFontKeys(plan) {
+  const keys = new Set();
+  for (const s of shotStrings(plan)) {
+    if (s.strokeFont) {
+      keys.add(s.strokeFont);
+      continue;
+    }
+    for (const run of scriptRuns(s.text)) {
+      keys.add(runFontKey(plan.preset.voices, s.voice, run.script));
+      const v = plan.preset.voices[s.voice];
+      if (run.script === "latin" && v.latin.startsWith("archivo-")) for (const w of v.latinWidths ?? [100]) keys.add(runFontKey(plan.preset.voices, s.voice, "latin", { widthPct: w }));
+      if (run.script === "hangul" && v.weightSteps) v.weightSteps.forEach((k) => keys.add(k));
+    }
+  }
+  return [...keys];
+}
+
+export async function checkCoverage(plan, env = process.env) {
+  const manifest = loadFontManifest();
+  const { parse } = await import(opentypeModule(env));
+  const cache = new Map();
+  const cmap = (key) => {
+    if (!cache.has(key)) {
+      const font = manifest.fonts[key];
+      const bytes = readFileSync(fontLocation(key, font, env));
+      if (font.format === "svg") {
+        const chars = new Set([...bytes.toString("utf8").matchAll(/<glyph[^>]*\sunicode="([^"]*)"/gu)].map((m) => m[1].replace(/&#x([0-9a-f]+);/giu, (_, h) => String.fromCodePoint(Number.parseInt(h, 16))).replace(/&quot;/gu, '"').replace(/&amp;/gu, "&").replace(/&lt;/gu, "<").replace(/&gt;/gu, ">").replace(/&apos;/gu, "'")));
+        cache.set(key, (ch) => chars.has(ch) || ch === " ");
+      } else {
+        const ot = parse(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.length));
+        cache.set(key, (ch) => ot.charToGlyphIndex(ch) > 0);
+      }
+    }
+    return cache.get(key);
+  };
+  const missing = [];
+  for (const s of shotStrings(plan)) {
+    const runs = s.strokeFont ? [{ script: "latin", text: s.text, key: s.strokeFont }] : scriptRuns(s.text).map((run) => ({ ...run, key: runFontKey(plan.preset.voices, s.voice, run.script) }));
+    for (const run of runs) {
+      const has = cmap(run.key);
+      for (const ch of new Set(Array.from(run.text))) {
+        if (/\s/u.test(ch)) continue;
+        if (!has(ch)) missing.push(`${run.key} lacks "${ch}" (U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}) in ${s.shot}/${s.voice}`);
+      }
+    }
+  }
+  return { ok: missing.length === 0, missing };
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/done.mjs

@@ -0,0 +1,104 @@
+// The done-check (director brief section 9), shared by the Stop hook. A film is done only with a
+// valid treatment, gate PASS on the final full render, at least two look rounds (the first a stills
+// round with a change, the last stamped with the final render's stills manifest), and the last
+// round's viewed list covering the poster, the sheet, every beat still and every strip, each opened
+// with the host's image tool when the host exposes its tool events. It also compares the final
+// treatment with the first valid one and records any downgrade.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { readLook } from "./look.mjs";
+import { readStills } from "./stills.mjs";
+import { validateTreatment } from "./treatment.mjs";
+
+const SILENCE_ASKED = /무음|소리\s?없|음악\s?없|\bsilent\b|\bsilence\b|\bno\s+(?:sound|music|audio)\b|\bwithout\s+(?:sound|music|audio)\b|\bmuted?\b/iu;
+
+export const treatmentSha = (out) => createHash("sha256").update(readFileSync(path.join(out, "treatment.json"))).digest("hex");
+
+/** Beats covered by the subject devices (the count the downgrade rule compares). */
+const subjectBeats = (t) => new Set((t.visualDevices ?? []).filter((d) => d.role === "subject").flatMap((d) => d.beats ?? [])).size;
+
+/** Downgrades from the first valid treatment to the final one. */
+export function downgrades(first, final) {
+  if (!first) return [];
+  const items = [];
+  if (final.durationSec < first.durationSec * 0.8) items.push(`the film was shortened from ${first.durationSec} s to ${final.durationSec} s`);
+  if (subjectBeats(final) < subjectBeats(first)) items.push(`the subject is on screen in fewer beats (${subjectBeats(first)} -> ${subjectBeats(final)})`);
+  if (final.sound?.mode === "none" && first.sound?.mode !== "none" && !SILENCE_ASKED.test(final.request)) items.push("the sound was switched to none without a user request");
+  if (first.path === "stage" && final.path === "type") items.push("the path moved from stage to type");
+  return items;
+}
+
+/**
+ * Evaluate done for an output directory. `viewedFiles` is a Set of absolute paths the host's image
+ * tool opened (null when the host exposes no tool events). Returns
+ * { status: "DONE" | "DONE_UNVIEWED" | "NOT_DONE", reasons, downgraded, openItems }.
+ */
+export function evaluateDone({ out, viewedFiles = null }) {
+  const reasons = [];
+  const notDone = (reason) => ({ status: "NOT_DONE", reasons: [reason], downgraded: [], openItems: [] });
+  if (!out) return notDone("the render's output directory is unknown");
+  const tFile = path.join(out, "treatment.json");
+  if (!existsSync(tFile)) return notDone(`treatment.json is missing in ${out}`);
+  let treatment;
+  try {
+    treatment = validateTreatment(JSON.parse(readFileSync(tFile, "utf8")));
+  } catch (error) {
+    return notDone(`treatment.json is not valid: ${error.message}`);
+  }
+  const manifestFile = path.join(out, "manifest.json");
+  const reportFile = path.join(out, "gate-report.txt");
+  if (!existsSync(manifestFile) || !existsSync(reportFile)) return notDone("no full render has finished (manifest.json or gate-report.txt is missing)");
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+  } catch {
+    return notDone("manifest.json is unreadable");
+  }
+  if (manifest.treatmentSha256 && manifest.treatmentSha256 !== treatmentSha(out)) reasons.push("treatment.json changed after the last full render; render again");
+  if (!/^QA gate: PASS$/mu.test(readFileSync(reportFile, "utf8"))) reasons.push("the gate did not pass on the last full render (gate-report.txt)");
+  const stills = readStills(out);
+  if (!stills) reasons.push("the stills set is missing");
+  else if (stills.index.stillsOnly) reasons.push("the latest stills set is from a stills-only render; the final full render has not run since");
+  let look;
+  try {
+    look = readLook(out);
+  } catch {
+    return notDone("look.json is unreadable");
+  }
+  const rounds = look.rounds;
+  if (!existsSync(path.join(out, "look.json"))) reasons.push("look.json is missing: no look round was recorded");
+  const openItems = [];
+  let unviewed = false;
+  if (rounds.length) {
+    const first = rounds[0];
+    const last = rounds[rounds.length - 1];
+    if (rounds.length < 2) reasons.push("only one look round is recorded; look at the final render and record the last round");
+    if (!first.blocked && (first.round !== 1 || !first.stillsOnly || !first.change)) reasons.push("round 1 must be a stills round that names the change made");
+    if (stills && last.stillsSha256 !== stills.sha256) reasons.push("the last look round was recorded before the final render (its stills manifest differs); look again and record it");
+    if (last.blocked === "no-vision-tool") unviewed = true;
+    else if (stills) {
+      const required = stills.index.files.filter((f) => ["poster", "sheet", "beat", "strip"].includes(f.kind)).map((f) => f.file);
+      const missing = required.filter((f) => !last.viewed?.includes(f));
+      if (missing.length) reasons.push(`the last look round did not view ${missing.slice(0, 4).join(", ")}${missing.length > 4 ? ` (+${missing.length - 4})` : ""}`);
+      if (viewedFiles) {
+        const unopened = (last.viewed ?? []).filter((f) => !viewedFiles.has(path.resolve(out, f)));
+        if (unopened.length) reasons.push(`these frames are listed as viewed but were never opened with the image tool: ${unopened.slice(0, 4).join(", ")}${unopened.length > 4 ? ` (+${unopened.length - 4})` : ""}`);
+      }
+      if (last.revise?.length) {
+        if (last.round >= 3) openItems.push(...last.revise.map((q) => `look question ${q}`));
+        else reasons.push(`look questions ${last.revise.join(", ")} ask for another round`);
+      }
+    }
+  }
+  let first = null;
+  try {
+    const firstFile = path.join(out, ".run", "treatment.first.json");
+    if (existsSync(firstFile)) first = JSON.parse(readFileSync(firstFile, "utf8"));
+  } catch {
+    first = null;
+  }
+  const downgraded = downgrades(first, treatment);
+  if (reasons.length) return { status: "NOT_DONE", reasons, downgraded, openItems };
+  return { status: unviewed ? "DONE_UNVIEWED" : "DONE", reasons: [], downgraded, openItems };
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/encode.mjs

@@ -0,0 +1,104 @@
+// ffmpeg is always the last stage and always a separately installed host binary (MO-A-03): the
+// master is one pinned encode (BT.709 matrix and tags, tv range, CRF 16, tune grain). The preview
+// walks the MO-A-38 encoder ladder (ffmpeg libwebp_anim, then img2webp, then GIF) over PNG frames
+// the renderer wrote and audited itself.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { ENCODE_ARGS, PREVIEW } from "../core/constants.mjs";
+
+function which(name, env = process.env) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8", env });
+  return probe.status === 0 ? probe.stdout.trim().split("\n")[0] : null;
+}
+
+export const findFfmpeg = (env = process.env) => (env.FFMPEG_PATH && existsSync(env.FFMPEG_PATH) ? env.FFMPEG_PATH : which("ffmpeg", env));
+export const findFfprobe = (env = process.env) => (env.FFPROBE_PATH && existsSync(env.FFPROBE_PATH) ? env.FFPROBE_PATH : which("ffprobe", env));
+export const findImg2webp = (env = process.env) => which("img2webp", env);
+
+export function ffmpegVersion(ffmpeg) {
+  const probe = spawnSync(ffmpeg, ["-version"], { encoding: "utf8" });
+  return probe.status === 0 ? probe.stdout.split("\n")[0].trim() : null;
+}
+
+/** The preview-encoder rungs available on this host, in ladder order. */
+export function previewRungs(ffmpeg, env = process.env) {
+  const rungs = [];
+  if (ffmpeg) {
+    const list = spawnSync(ffmpeg, ["-hide_banner", "-encoders"], { encoding: "utf8" }).stdout ?? "";
+    if (/\blibwebp_anim\b/u.test(list)) rungs.push("libwebp_anim");
+  }
+  if (findImg2webp(env)) rungs.push("img2webp");
+  if (ffmpeg) rungs.push("gif");
+  return rungs;
+}
+
+/** Start the master encode; returns { write(bytes), finish() }. Writes respect stdin backpressure. */
+export function startMaster({ ffmpeg, width, height, fps, out, audio = null }) {
+  const args = ["-y", "-hide_banner", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${width}x${height}`, "-r", String(fps), "-i", "pipe:0"];
+  if (audio) args.push("-i", audio);
+  args.push(...ENCODE_ARGS);
+  // The track is prepared to the film's exact sample count, so nothing is cut to the shorter stream.
+  if (audio) args.push("-map", "0:v:0", "-map", "1:a:0", "-c:a", "aac", "-b:a", "256k");
+  args.push(out);
+  const child = spawn(ffmpeg, args, { stdio: ["pipe", "ignore", "pipe"] });
+  let stderr = "";
+  child.stderr.on("data", (d) => { stderr += d.toString(); });
+  const exited = new Promise((resolve) => child.on("close", (code) => resolve(code)));
+  child.stdin.on("error", () => {});
+  return {
+    args,
+    async write(bytes) {
+      if (!child.stdin.write(bytes)) await new Promise((resolve) => child.stdin.once("drain", resolve));
+    },
+    async finish() {
+      child.stdin.end();
+      const code = await exited;
+      return { code, stderr: stderr.trim() };
+    },
+  };
+}
+
+function run(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return { code: r.status, stderr: (r.stderr || r.error?.message || "").trim() };
+}
+
+/** Encode one preview rung from numbered PNGs (00000.png ...) with one encoder. */
+export function encodePreview({ encoder, ffmpeg, img2webp, dir, fps, out }) {
+  const frames = readdirSync(dir).filter((f) => /^\d{5}\.png$/u.test(f)).sort();
+  if (encoder === "libwebp_anim") {
+    return run(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "%05d.png"), "-c:v", "libwebp_anim", "-lossless", "0", "-q:v", String(PREVIEW.webpQuality), "-loop", "0", out]);
+  }
+  if (encoder === "img2webp") {
+    const args = ["-loop", "0", "-lossy", "-q", String(PREVIEW.webpQuality), "-m", "4"];
+    let elapsed = 0;
+    frames.forEach((f, i) => {
+      const next = Math.round(((i + 1) * 1000) / fps);
+      args.push("-d", String(next - elapsed), path.join(dir, f));
+      elapsed = next;
+    });
+    args.push("-o", out);
+    return run(img2webp, args);
+  }
+  return run(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "%05d.png"),
+    "-vf", "split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=4", "-loop", "0", out]);
+}
+
+/** ffprobe the first video stream. Returns null when ffprobe is missing or fails. */
+export function probeVideo(file, env = process.env) {
+  const ffprobe = findFfprobe(env);
+  if (!ffprobe || !existsSync(file)) return null;
+  const r = spawnSync(ffprobe, ["-v", "error", "-select_streams", "v:0", "-count_frames", "-show_entries",
+    "stream=width,height,r_frame_rate,pix_fmt,color_space,color_range,color_transfer,color_primaries,nb_read_frames,codec_name:format=duration,size",
+    "-of", "json", file], { encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const j = JSON.parse(r.stdout);
+  const s = j.streams?.[0] ?? {};
+  const [num, den] = String(s.r_frame_rate ?? "0/1").split("/").map(Number);
+  return {
+    codec: s.codec_name, width: s.width, height: s.height, fps: den ? num / den : 0, pixFmt: s.pix_fmt, colorSpace: s.color_space,
+    colorRange: s.color_range, colorTransfer: s.color_transfer, colorPrimaries: s.color_primaries, frames: Number(s.nb_read_frames ?? 0),
+    duration: Number(j.format?.duration ?? 0), bytes: statSync(file).size,
+  };
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/frame-worker.mjs

@@ -0,0 +1,36 @@
+// One frame-analysis worker: decode a captured PNG to RGBA and analyse it off the capture thread
+// (the SHA-256 of the decoded RGBA, the flash-audit cells on the frame's own grid, the 99.5th
+// percentile luminance). The capture loop steps the next frame while a pool of these decodes.
+import { parentPort } from "node:worker_threads";
+import { analyzeFrame } from "./analysis.mjs";
+import { decodePng } from "./png.mjs";
+
+parentPort.on("message", ({ id, png, width, height }) => {
+  try {
+    const image = decodePng(Buffer.from(png));
+    if (image.width !== width || image.height !== height) {
+      parentPort.postMessage({ id, error: `captured ${image.width}x${image.height}, expected ${width}x${height}` });
+      return;
+    }
+    const rgba = image.channels === 4 ? image.pixels : toRgba(image.pixels, image.channels);
+    // A stage frame is opaque: analyzeFrame's alpha-as-ink count is meaningless here and is dropped.
+    const { cells, luminanceP995, rgbaSha256 } = analyzeFrame(rgba, width, height);
+    const buffer = rgba.buffer.slice(rgba.byteOffset, rgba.byteOffset + rgba.byteLength);
+    parentPort.postMessage({ id, rgba: buffer, cells, luminanceP995, rgbaSha256 }, [buffer, cells.R.buffer, cells.G.buffer, cells.B.buffer]);
+  } catch (error) {
+    parentPort.postMessage({ id, error: error.message });
+  }
+});
+
+function toRgba(pixels, channels) {
+  const n = pixels.length / channels;
+  const out = Buffer.alloc(n * 4);
+  for (let i = 0; i < n; i++) {
+    const s = i * channels;
+    out[i * 4] = pixels[s];
+    out[i * 4 + 1] = pixels[channels >= 3 ? s + 1 : s];
+    out[i * 4 + 2] = pixels[channels >= 3 ? s + 2 : s];
+    out[i * 4 + 3] = 255;
+  }
+  return out;
+}