luckiest-co 1.0.19 → 1.0.21

package/skills/luckiest-video-studio/scripts/qa.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+// QA gates for a luckiest-video-studio run. Each gate prints JSON and exits 1 on a fail.
+// Needs Node 22+ and ffmpeg/ffprobe; nothing else is installed or downloaded.
+//
+//   node qa.mjs tokens      <composition-dir> [--tokens tokens.json]   off-system stroke, type, radius
+//   node qa.mjs crossfade   <composition-dir>                          full-frame layers tweening opacity
+//   node qa.mjs legibility  <video> [--every 1] [--min 180]            frames with nothing bright enough to read
+//   node qa.mjs pops        <video> [--seams 5.2,9.8]                  one-frame pops and jumps (seams reported apart)
+//   node qa.mjs deadframes  <video> [--freeze 3]                       black frames and long freezes
+//   node qa.mjs presence    <run-dir> [--min 0]                        share of time the speaker is on screen
+//   node qa.mjs beatsync    <talk-dir>                                 plan anchors against the transcript words
+//   node qa.mjs beatgrid    <video> --bpm 128 [--phase 0] [--tol 0.035] cuts on the beat or half beat
+//   node qa.mjs face        <run-dir> [--max 18]                       cards covering the speaker's face (scene faceRect)
+//   node qa.mjs judge       <new.mp4> <old.mp4> [--out dir] [--cmd "claude -p --model sonnet"] [--verdicts A,B]
+//                           new vs old, asked twice with the order swapped; the new one is kept only if it wins both
+//
+// A gate that has never failed proves nothing: qa.test.mjs runs each one on a control
+// built to fail it.
+
+import { readFileSync, readdirSync, existsSync, statSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, extname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// ---------- shared ----------
+
+const ff = (args) => spawnSync("ffmpeg", ["-hide_banner", "-nostats", ...args], { maxBuffer: 1 << 30 });
+
+export function probe(video) {
+  const r = spawnSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries",
+    "stream=r_frame_rate:format=duration", "-of", "json", video], { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffprobe failed on ${video}: ${r.stderr}`);
+  const j = JSON.parse(r.stdout), [n, d] = j.streams[0].r_frame_rate.split("/").map(Number);
+  return { fps: n / d, duration: Number(j.format.duration) };
+}
+
+// Every frame as a small grayscale buffer (w x h bytes).
+export function grayFrames(video, w = 64, h = 36, { start = 0, duration } = {}) {
+  const r = ff(["-v", "error", "-ss", String(start), ...(duration ? ["-t", String(duration)] : []), "-i", video,
+    "-vf", `scale=${w}:${h}:flags=area,format=gray`, "-f", "rawvideo", "-"]);
+  if (r.status !== 0) throw new Error(`ffmpeg failed on ${video}: ${r.stderr}`);
+  const size = w * h, frames = [];
+  for (let o = 0; o + size <= r.stdout.length; o += size) frames.push(r.stdout.subarray(o, o + size));
+  return frames;
+}
+
+export const meanDiff = (a, b) => { let s = 0; for (let i = 0; i < a.length; i++) s += Math.abs(a[i] - b[i]); return s / a.length; };
+
+const htmlFiles = (dir) => readdirSync(dir, { recursive: true }).map(String)
+  .filter((f) => extname(f) === ".html").map((f) => join(dir, f));
+
+// ---------- tokens ----------
+
+export const DEFAULT_TOKENS = { stroke: [1.5, 2.5, 4, 7], type: [22, 30, 42, 60, 84], radius: [10, 22, 40] };
+
+export function scanTokens(html, tokens = DEFAULT_TOKENS) {
+  const out = [];
+  const check = (kind, prop, raw) => {
+    const v = Number(raw);
+    if (Number.isFinite(v) && v > 0 && !tokens[kind].includes(v)) out.push({ kind, prop, value: v });
+  };
+  for (const m of html.matchAll(/stroke-width\s*[:=]\s*"?([\d.]+)/g)) check("stroke", "stroke-width", m[1]);
+  for (const m of html.matchAll(/font-size\s*:\s*([\d.]+)px/g)) check("type", "font-size", m[1]);
+  for (const m of html.matchAll(/border-radius\s*:\s*([\d.]+)px/g)) check("radius", "border-radius", m[1]);
+  return out;
+}
+
+// ---------- cross-fade ----------
+
+// Selectors whose CSS makes them cover the whole frame.
+export function fullFrameSelectors(html) {
+  const sels = new Set();
+  for (const m of html.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    const body = m[2].replace(/\s/g, "");
+    const full = /inset:0(;|$)/.test(body) || (/width:(100%|1920px)/.test(body) && /height:(100%|1080px)/.test(body));
+    if (full) for (const s of m[1].split(",")) { const t = s.trim().split(/[\s>]+/).pop(); if (/^[.#][\w-]+$/.test(t)) sels.add(t); }
+  }
+  return sels;
+}
+
+// Tweens (not instant sets) that change opacity on a full-frame layer.
+export function scanCrossfades(html) {
+  const full = fullFrameSelectors(html), out = [];
+  for (const m of html.matchAll(/\.(to|from|fromTo)\(\s*["'`]([^"'`]+)["'`]\s*,([^;]*?)\)\s*[;,]/gs)) {
+    const targets = m[2].split(",").map((s) => s.trim()).filter((s) => full.has(s));
+    if (targets.length && /opacity\s*:/.test(m[3]) && !/duration\s*:\s*0\s*[,}]/.test(m[3])) out.push({ tween: m[1], targets });
+  }
+  return out;
+}
+
+// ---------- legibility ----------
+
+// Brightest luma per sampled frame (0-255). A frame whose brightest pixel is dim has nothing lit to read.
+export function legibility(video, { every = 1, min = 180 } = {}) {
+  const { duration } = probe(video);
+  const rows = [];
+  for (let t = 0; t < duration; t += every) {
+    // Read at 960x540, the size the storytelling rules judge legibility at.
+    const [f] = grayFrames(video, 960, 540, { start: t, duration: 0.05 });
+    if (!f) continue;
+    let max = 0; for (const v of f) if (v > max) max = v;
+    rows.push({ t: Number(t.toFixed(2)), brightest: max });
+  }
+  const dim = rows.filter((r) => r.brightest < min);
+  return { ok: dim.length === 0, min, dim, sampled: rows.length };
+}
+
+// ---------- pops ----------
+
+// A pop is one frame unlike both neighbours while the neighbours match each other.
+export function findPops(frames, fps, { ratio = 3, floor = 6 } = {}) {
+  const pops = [];
+  for (let i = 1; i < frames.length - 1; i++) {
+    const a = meanDiff(frames[i - 1], frames[i]), b = meanDiff(frames[i], frames[i + 1]), c = meanDiff(frames[i - 1], frames[i + 1]);
+    if (a > floor && b > floor && Math.min(a, b) > ratio * Math.max(c, 1)) pops.push({ frame: i, t: Number((i / fps).toFixed(3)), jump: Number(Math.min(a, b).toFixed(1)) });
+  }
+  return pops;
+}
+
+// ---------- dead frames ----------
+
+export function deadFrames(video, { freeze = 3, blackMin = 0.06 } = {}) {
+  const r = ff(["-i", video, "-vf", `blackdetect=d=${blackMin}:pix_th=0.02:pic_th=0.995,freezedetect=n=0.001:d=${freeze}`, "-an", "-f", "null", "-"]);
+  const log = r.stderr.toString();
+  const black = [...log.matchAll(/black_start:([\d.]+) black_end:([\d.]+)/g)].map((m) => ({ start: +m[1], end: +m[2] }));
+  const freezes = [...log.matchAll(/freeze_start: ([\d.]+)/g)].map((m) => ({ start: +m[1] }));
+  return { ok: black.length === 0 && freezes.length === 0, black, freezes };
+}
+
+// ---------- presence ----------
+
+// Compare each second of final.mp4 with the clip frame the storyboard says should be under it.
+export function presence(runDir, { threshold = 12 } = {}) {
+  const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
+  const final = join(runDir, "final.mp4");
+  let t0 = 0, onScreen = 0, total = 0;
+  const cache = new Map();
+  for (const s of sb.scenes) {
+    const src = s.source ?? (s.assets ?? []).find((a) => a.endsWith(".mp4"));
+    for (let t = 0; t < s.duration; t += 1) {
+      total++;
+      if (!src || !existsSync(join(runDir, src))) continue;
+      const [f] = grayFrames(final, 64, 36, { start: t0 + t, duration: 0.05 });
+      const key = `${src}@${((s.sourceStart ?? 0) + t).toFixed(2)}`;
+      if (!cache.has(key)) cache.set(key, grayFrames(join(runDir, src), 64, 36, { start: (s.sourceStart ?? 0) + t, duration: 0.05 })[0]);
+      const g = cache.get(key);
+      if (f && g && meanDiff(f, g) < threshold) onScreen++;
+    }
+    t0 += s.duration;
+  }
+  return { share: total ? Number((onScreen / total).toFixed(3)) : 0, sampled: total };
+}
+
+// ---------- beat sync ----------
+
+const norm = (s) => String(s).toLowerCase().replace(/[^a-z0-9' ]/g, "").trim();
+
+// Start time of the first occurrence of an anchor phrase in the word list.
+export function findAnchor(words, phrase) {
+  const want = norm(phrase).split(/\s+/).filter(Boolean);
+  const ws = words.map((w) => norm(w.text));
+  for (let i = 0; i + want.length <= ws.length; i++) if (want.every((x, k) => ws[i + k] === x)) return words[i].start;
+  return null;
+}
+
+// Every scene and event with an anchor must enter between 0.2 s after and 1.8 s before its word.
+export function beatSync(plan, transcript, { lead = [-0.2, 1.8] } = {}) {
+  const words = (Array.isArray(transcript) ? transcript : transcript.words).filter((w) => w.type !== "spacing");
+  const rows = [];
+  for (const item of [...(plan.scenes ?? []).map((s) => ({ id: s.id, time: s.start, anchor: s.anchor })),
+    ...(plan.events ?? []).map((e, i) => ({ id: `${e.visual}#${i}`, time: e.time, anchor: e.anchor }))]) {
+    if (!item.anchor) continue;
+    const at = findAnchor(words, item.anchor);
+    const diff = at === null ? null : Number((at - item.time).toFixed(3));
+    rows.push({ ...item, word: at, lead: diff, ok: diff !== null && diff >= lead[0] && diff <= lead[1] });
+  }
+  return { ok: rows.every((r) => r.ok), fails: rows.filter((r) => !r.ok), checked: rows.length };
+}
+
+// ---------- beat grid ----------
+
+// Hard cuts are frames far from the previous one; each must sit near a beat or half beat.
+export function cutTimes(frames, fps, { floor = 30 } = {}) {
+  const cuts = [];
+  for (let i = 1; i < frames.length; i++) if (meanDiff(frames[i - 1], frames[i]) > floor) cuts.push(i / fps);
+  return cuts;
+}
+
+export function beatGrid(cuts, { bpm, phase = 0, tol = 0.035 }) {
+  const half = 60 / bpm / 2;
+  const rows = cuts.map((t) => {
+    const k = Math.round((t - phase) / half), off = t - phase - k * half;
+    return { t: Number(t.toFixed(3)), offset: Number(off.toFixed(3)), ok: Math.abs(off) <= tol };
+  });
+  return { ok: rows.every((r) => r.ok), off: rows.filter((r) => !r.ok), cuts: rows.length };
+}
+
+// ---------- face ----------
+
+// Crop a 0-1 rect [x, y, w, h] out of a w x h gray frame.
+export const crop = (f, w, h, [x, y, cw, ch]) => {
+  const x0 = Math.floor(x * w), y0 = Math.floor(y * h), x1 = Math.ceil((x + cw) * w), y1 = Math.ceil((y + ch) * h), out = [];
+  for (let r = y0; r < y1; r++) for (let c = x0; c < x1; c++) out.push(f[r * w + c]);
+  return out;
+};
+
+// For scenes with faceRect, the face area in final.mp4 must still match the clip under it.
+// A card over the face changes those pixels; the clip alone does not.
+export function faceCover(runDir, { max = 18, w = 160, h = 90 } = {}) {
+  const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
+  const final = join(runDir, "final.mp4"), covered = [];
+  let t0 = 0, checked = 0;
+  for (const s of sb.scenes) {
+    if (s.faceRect && s.source && existsSync(join(runDir, s.source))) {
+      for (let t = 0; t < s.duration; t += 0.5) {
+        const [f] = grayFrames(final, w, h, { start: t0 + t, duration: 0.05 });
+        const [g] = grayFrames(join(runDir, s.source), w, h, { start: (s.sourceStart ?? 0) + t, duration: 0.05 });
+        if (!f || !g) continue;
+        checked++;
+        const d = meanDiff(crop(f, w, h, s.faceRect), crop(g, w, h, s.faceRect));
+        if (d > max) covered.push({ scene: s.id, t: Number((t0 + t).toFixed(2)), diff: Number(d.toFixed(1)) });
+      }
+    }
+    t0 += s.duration;
+  }
+  return { ok: covered.length === 0, covered, checked };
+}
+
+// ---------- judge ----------
+
+// Pass 1 shows new as A, old as B. Pass 2 swaps them. Keep new only if it wins both,
+// so a judge that just prefers whatever comes first can never promote a version.
+export function pairVerdict(first, second) {
+  const keep = first === "A" && second === "B";
+  return { keep, winner: keep ? "new" : "old", passes: [first, second], consistent: (first === "A") === (second === "B") };
+}
+
+export const parseWinner = (text) => (String(text).match(/WINNER:\s*([AB])\b/gi) ?? []).pop()?.slice(-1).toUpperCase() ?? null;
+
+// One tiled contact sheet per video, 2 frames a second, 6 across.
+export function contactSheet(video, out, { rate = 2, cols = 6 } = {}) {
+  const { duration } = probe(video), rows = Math.max(1, Math.ceil((duration * rate) / cols));
+  const r = ff(["-v", "error", "-y", "-i", video, "-vf", `fps=${rate},scale=320:-2,tile=${cols}x${rows}`, "-frames:v", "1", out]);
+  if (r.status !== 0) throw new Error(`contact sheet failed on ${video}: ${r.stderr}`);
+  return out;
+}
+
+export const judgePrompt = (a, b) => `You are judging two versions of the same short video. Each image is a contact sheet: frames left to right, top to bottom, two per second.
+A: ${a}
+B: ${b}
+Open both images. Judge which reads better to a viewer: every card legible, the speaker's face never covered, visuals change with what is said, no empty or cluttered stretches, real evidence instead of filler.
+Name the two biggest differences, then end with exactly one line: WINNER: A or WINNER: B`;
+
+// ---------- CLI ----------
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [gate, target, ...rest] = process.argv.slice(2);
+  if (gate === "judge" && rest[0] && !rest[0].startsWith("--")) rest.unshift("--old", rest.shift());
+  const opt = (n, d) => { const i = rest.indexOf(n); return i >= 0 ? rest[i + 1] : d; };
+  const num = (n, d) => Number(opt(n, d));
+  if (!gate || !target) { console.error("Usage: qa.mjs <tokens|crossfade|legibility|pops|deadframes|presence|beatsync|beatgrid|face|judge> <path> [options]"); process.exit(1); }
+  let result;
+  if (gate === "tokens") {
+    const tokens = opt("--tokens") ? JSON.parse(readFileSync(opt("--tokens"), "utf8")) : DEFAULT_TOKENS;
+    const files = statSync(target).isDirectory() ? htmlFiles(target) : [target];
+    const off = files.flatMap((f) => scanTokens(readFileSync(f, "utf8"), tokens).map((v) => ({ file: f, ...v })));
+    result = { ok: off.length === 0, off };
+  } else if (gate === "crossfade") {
+    const files = statSync(target).isDirectory() ? htmlFiles(target) : [target];
+    const found = files.flatMap((f) => scanCrossfades(readFileSync(f, "utf8")).map((v) => ({ file: f, ...v })));
+    result = { ok: found.length === 0, found };
+  } else if (gate === "legibility") result = legibility(target, { every: num("--every", 1), min: num("--min", 180) });
+  else if (gate === "pops") {
+    const { fps } = probe(target), pops = findPops(grayFrames(target), fps);
+    const seams = (opt("--seams", "") || "").split(",").filter(Boolean).map(Number);
+    const atSeam = (p) => seams.some((s) => Math.abs(p.t - s) < 2 / fps);
+    result = { ok: pops.length === 0, pops: pops.map((p) => ({ ...p, seam: atSeam(p) })) };
+  } else if (gate === "deadframes") result = deadFrames(target, { freeze: num("--freeze", 3) });
+  else if (gate === "presence") { result = presence(target); result.ok = result.share >= num("--min", 0); }
+  else if (gate === "beatsync") {
+    const read = (n) => JSON.parse(readFileSync(join(target, "assets", n), "utf8"));
+    result = beatSync(read("plan.json"), read("transcript.json"));
+  } else if (gate === "beatgrid") {
+    if (!opt("--bpm")) { console.error("--bpm is required"); process.exit(1); }
+    const { fps } = probe(target);
+    result = beatGrid(cutTimes(grayFrames(target), fps), { bpm: num("--bpm"), phase: num("--phase", 0), tol: num("--tol", 0.035) });
+  } else if (gate === "face") result = faceCover(target, { max: num("--max", 18) });
+  else if (gate === "judge") {
+    const old = opt("--old"), out = opt("--out", "qa-judge");
+    if (!old) { console.error("judge needs <new.mp4> <old.mp4>"); process.exit(1); }
+    mkdirSync(out, { recursive: true });
+    const a = contactSheet(target, resolve(out, "new.png")), b = contactSheet(old, resolve(out, "old.png"));
+    const prompts = [judgePrompt(a, b), judgePrompt(b, a)];
+    let passes = opt("--verdicts")?.split(",").map((v) => v.trim().toUpperCase());
+    if (!passes && opt("--cmd")) {
+      passes = prompts.map((p, i) => {
+        const r = spawnSync(opt("--cmd"), { shell: true, input: p, encoding: "utf8", maxBuffer: 1 << 26 });
+        writeFileSync(join(out, `pass${i + 1}.txt`), (r.stdout ?? "") + (r.stderr ?? ""));
+        return parseWinner(r.stdout);
+      });
+    }
+    if (!passes) {
+      // No command: the agent that built the video judges. Answer each prompt, then rerun with --verdicts.
+      prompts.forEach((p, i) => writeFileSync(join(out, `prompt${i + 1}.md`), p));
+      console.log(JSON.stringify({ ok: false, pending: true, prompts: [join(out, "prompt1.md"), join(out, "prompt2.md")] }, null, 2));
+      process.exit(2);
+    }
+    if (passes.some((p) => p !== "A" && p !== "B")) { console.log(JSON.stringify({ ok: false, invalid: true, passes }, null, 2)); process.exit(2); }
+    result = { ...pairVerdict(...passes), ok: pairVerdict(...passes).keep };
+  } else { console.error(`unknown gate: ${gate}`); process.exit(1); }
+  console.log(JSON.stringify(result, null, 2));
+  process.exitCode = result.ok ? 0 : 1;
+}

package/skills/luckiest-video-studio/scripts/qa.test.mjs

@@ -0,0 +1,135 @@
+// Every gate runs on a control built to fail it and one built to pass it.
+// Fixtures are tiny ffmpeg lavfi videos in a temp folder; nothing is downloaded.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  scanTokens, scanCrossfades, legibility, findPops, deadFrames, presence,
+  beatSync, findAnchor, cutTimes, beatGrid, grayFrames, probe,
+  faceCover, pairVerdict, parseWinner,
+} from "./qa.mjs";
+
+const dir = mkdtempSync(join(tmpdir(), "qa-gates-"));
+const QA = join(import.meta.dirname, "qa.mjs");
+
+// Concatenate solid-color segments ([color, seconds]) or lavfi sources into one mp4.
+function video(name, parts, { fps = 30, size = "160x90" } = {}) {
+  const out = join(dir, name);
+  const ins = parts.map(([src, d], i) => (src.startsWith("testsrc") ? `${src}=size=${size}:rate=${fps}:duration=${d}` : `color=c=${src}:size=${size}:rate=${fps}:duration=${d}`) + `[v${i}]`);
+  const graph = `${ins.join(";")};${parts.map((_, i) => `[v${i}]`).join("")}concat=n=${parts.length}:v=1:a=0,format=yuv420p[out]`;
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", "nullsrc=size=16x16:duration=0.01", "-filter_complex", graph, "-map", "[out]", "-c:v", "libx264", "-crf", "12", "-g", "1", out]);
+  assert.equal(r.status, 0, r.stderr?.toString());
+  return out;
+}
+const cli = (...a) => spawnSync(process.execPath, [QA, ...a], { encoding: "utf8" });
+
+test("tokens: off-system values fail, system values pass", () => {
+  const bad = `<style>.a{font-size:31px;border-radius:12px}</style><path stroke-width="3"/>`;
+  const good = `<style>.a{font-size:30px;border-radius:22px}</style><path stroke-width="2.5"/>`;
+  assert.deepEqual(scanTokens(bad).map((v) => v.kind), ["stroke", "type", "radius"]);
+  assert.deepEqual(scanTokens(good), []);
+  assert.deepEqual(scanTokens(`<style>.a{font-size:31px}</style>`, { stroke: [], type: [31], radius: [] }), []);
+});
+
+test("crossfade: tweening a full-frame layer's opacity fails, a cut or a small element passes", () => {
+  const css = `<style>.layer{position:absolute;inset:0}.chip{width:200px;height:40px}</style>`;
+  assert.equal(scanCrossfades(`${css}<script>tl.to(".layer",{opacity:0,duration:0.5},2);</script>`).length, 1);
+  assert.equal(scanCrossfades(`${css}<script>tl.fromTo(".layer",{opacity:0},{opacity:1,duration:0.4},1);</script>`).length, 1);
+  assert.equal(scanCrossfades(`${css}<script>tl.set(".layer",{opacity:0},2);</script>`).length, 0);
+  assert.equal(scanCrossfades(`${css}<script>tl.to(".chip",{opacity:0,duration:0.5},2);</script>`).length, 0);
+});
+
+test("crossfade: the shipped reel and talk templates pass", () => {
+  for (const f of ["../../luckiest-video-studio-reel/templates/reel.html", "../../luckiest-video-studio-talk/templates/talk-overlay.html"]) {
+    assert.deepEqual(scanCrossfades(readFileSync(join(import.meta.dirname, f), "utf8")), [], f);
+  }
+});
+
+test("legibility: an all-dim video fails, a bright test pattern passes", () => {
+  assert.equal(legibility(video("dim.mp4", [["0x202020", 2]])).ok, false);
+  assert.equal(legibility(video("bright.mp4", [["testsrc2", 2]])).ok, true);
+});
+
+test("pops: a one-frame flash is found, a clean hard cut is not", () => {
+  const flash = video("flash.mp4", [["gray", 1], ["white", 1 / 30], ["gray", 1]]);
+  const pops = findPops(grayFrames(flash), 30);
+  assert.equal(pops.length, 1);
+  assert.ok(Math.abs(pops[0].t - 1) < 0.07);
+  assert.equal(findPops(grayFrames(video("cut.mp4", [["gray", 1], ["white", 1]])), 30).length, 0);
+  assert.equal(cli("pops", flash).status, 1);
+});
+
+test("deadframes: black and long freezes fail, moving footage passes", () => {
+  const r = deadFrames(video("black.mp4", [["testsrc2", 1], ["black", 0.5], ["testsrc2", 1]]));
+  assert.equal(r.black.length, 1);
+  assert.equal(deadFrames(video("frozen.mp4", [["0x808080", 4]]), { freeze: 3 }).freezes.length, 1);
+  assert.equal(deadFrames(video("moving.mp4", [["testsrc2", 3]])).ok, true);
+});
+
+test("presence: the clip itself reads as on screen, a black final does not", () => {
+  const run = join(dir, "run");
+  mkdirSync(join(run, "footage"), { recursive: true });
+  const clip = video("clip.mp4", [["testsrc2", 4]]);
+  copyFileSync(clip, join(run, "footage/clean.mp4"));
+  writeFileSync(join(run, "storyboard.json"), JSON.stringify({ scenes: [{ id: "talk", kind: "demo", duration: 4, source: "footage/clean.mp4", sourceStart: 0 }] }));
+  copyFileSync(clip, join(run, "final.mp4"));
+  assert.ok(presence(run).share > 0.9);
+  copyFileSync(video("allblack.mp4", [["black", 4]]), join(run, "final.mp4"));
+  assert.equal(presence(run).share, 0);
+});
+
+test("beatsync: anchors on their words pass, a late overlay and a missing phrase fail", () => {
+  const words = [{ text: "Grow", start: 0.1, end: 0.4 }, { text: "something.", start: 0.4, end: 1 }, { text: "Start", start: 2.1, end: 2.4 }];
+  assert.equal(findAnchor(words, "grow something"), 0.1);
+  const plan = (t) => ({ scenes: [{ id: "s00", start: 0, anchor: "Grow something" }], events: [{ time: t, visual: "s00", anchor: "Start" }] });
+  assert.equal(beatSync(plan(1.9), words).ok, true);
+  assert.equal(beatSync(plan(2.6), words).ok, false);
+  assert.equal(beatSync({ scenes: [{ id: "x", start: 0, anchor: "never said" }] }, words).ok, false);
+});
+
+test("beatgrid: cuts on the beat pass, cuts 0.1 s late fail", () => {
+  const beat = 60 / 120; // 15 frames at 30 fps, so the fixture has no rounding drift
+  const onGrid = video("grid.mp4", [["red", beat], ["blue", beat], ["red", beat], ["blue", beat]]);
+  const { fps } = probe(onGrid);
+  assert.equal(beatGrid(cutTimes(grayFrames(onGrid), fps), { bpm: 120 }).ok, true);
+  const late = video("late.mp4", [["red", beat + 0.1], ["blue", beat], ["red", beat]]);
+  assert.equal(beatGrid(cutTimes(grayFrames(late), fps), { bpm: 120 }).ok, false);
+  assert.equal(cli("beatgrid", late, "--bpm", "120").status, 1);
+});
+
+test("face: the clip alone passes, a box over the face fails", () => {
+  const run = join(dir, "facerun");
+  mkdirSync(join(run, "footage"), { recursive: true });
+  const clip = video("face-clip.mp4", [["testsrc2", 2]]);
+  copyFileSync(clip, join(run, "footage/clean.mp4"));
+  writeFileSync(join(run, "storyboard.json"), JSON.stringify({ scenes: [{ id: "talk", kind: "demo", duration: 2, source: "footage/clean.mp4", faceRect: [0.3, 0.2, 0.4, 0.5] }] }));
+  copyFileSync(clip, join(run, "final.mp4"));
+  assert.equal(faceCover(run).ok, true);
+  const boxed = join(dir, "face-boxed.mp4");
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-i", clip, "-vf", "drawbox=x=iw*0.3:y=ih*0.2:w=iw*0.4:h=ih*0.5:color=white:t=fill", "-c:v", "libx264", "-crf", "12", boxed]);
+  assert.equal(r.status, 0, r.stderr?.toString());
+  copyFileSync(boxed, join(run, "final.mp4"));
+  assert.equal(faceCover(run).ok, false);
+  assert.equal(cli("face", run).status, 1);
+});
+
+test("judge: new is kept only when it wins with the order swapped", () => {
+  assert.equal(pairVerdict("A", "B").keep, true);
+  assert.equal(pairVerdict("A", "A").keep, false); // always picks the first shown
+  assert.equal(pairVerdict("B", "B").keep, false); // always picks the second shown
+  assert.equal(pairVerdict("B", "A").keep, false);
+  assert.equal(pairVerdict("A", "A").consistent, false);
+  assert.equal(parseWinner("A is cleaner.\nWINNER: b"), "B");
+  assert.equal(parseWinner("no verdict"), null);
+});
+
+test("judge CLI: pending without a verdict, keeps or rejects with verdicts, fake judge command", () => {
+  const n = video("j-new.mp4", [["testsrc2", 1]]), o = video("j-old.mp4", [["gray", 1]]), out = join(dir, "judge");
+  assert.equal(cli("judge", n, o, "--out", out).status, 2);
+  assert.equal(cli("judge", n, o, "--out", out, "--verdicts", "A,B").status, 0);
+  assert.equal(cli("judge", n, o, "--out", out, "--verdicts", "A,A").status, 1);
+  assert.equal(cli("judge", n, o, "--out", out, "--cmd", "echo WINNER: A").status, 1); // first-position bias
+});

package/skills/luckiest-video-studio/scripts/render-scenes.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Render each storyboard scene to clips/NN-id.mp4, skip unchanged scenes, then join final.mp4 and write TIMING.md.
+// Usage: node render-scenes.mjs <run-dir> [--scene <id>]... [--quality draft|looks|delivery] [--no-join]
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const runDir = resolve(args.find((a, i) => !a.startsWith("--") && !["--scene", "--quality"].includes(args[i - 1])) ?? ".");
+const forced = args.flatMap((a, i) => (a === "--scene" ? [args[i + 1]] : []));
+const quality = args.includes("--quality") ? args[args.indexOf("--quality") + 1] : "looks";
+const join_ = !args.includes("--no-join");
+
+const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
+const { width: W, height: H, fps } = sb.format;
+const clipsDir = join(runDir, "clips");
+const rawDir = join(clipsDir, ".raw");
+mkdirSync(rawDir, { recursive: true });
+const cachePath = join(clipsDir, ".cache.json");
+const cache = existsSync(cachePath) ? JSON.parse(readFileSync(cachePath, "utf8")) : {};
+
+const fail = (msg) => { console.error(`error: ${msg}`); process.exit(1); };
+const run = (cmd, argv, opts = {}) => {
+  const r = spawnSync(cmd, argv, { stdio: ["ignore", "inherit", "inherit"], ...opts });
+  if (r.error) fail(`${cmd} not found (${r.error.code})`);
+  if (r.status !== 0) fail(`${cmd} ${argv.slice(0, 3).join(" ")} exited ${r.status}`);
+};
+const hasBin = (b) => spawnSync("which", [b], { stdio: "ignore" }).status === 0;
+
+const ids = new Set();
+for (const s of sb.scenes) {
+  if (ids.has(s.id)) fail(`duplicate scene id "${s.id}"`);
+  ids.add(s.id);
+  if (!["motion", "logo", "demo"].includes(s.kind)) fail(`scene ${s.id}: unknown kind "${s.kind}"`);
+  if (!(s.duration > 0)) fail(`scene ${s.id}: duration must be > 0`);
+}
+for (const id of forced) if (!ids.has(id)) fail(`--scene ${id}: no such scene`);
+
+const inputsOf = (s) => {
+  const files = [...(s.assets ?? [])];
+  if (s.kind === "demo") {
+    if (!s.source) fail(`demo scene ${s.id} needs "source"`);
+    files.push(s.source);
+  } else files.push(join("composition", s.composition ?? `compositions/${s.id}.html`));
+  return files;
+};
+const hashOf = (s) => {
+  const h = createHash("sha256").update(JSON.stringify({ s, W, H, fps, quality }));
+  for (const f of inputsOf(s)) {
+    const p = join(runDir, f);
+    if (!existsSync(p)) fail(`scene ${s.id}: missing ${f}`);
+    h.update(f).update(readFileSync(p));
+  }
+  return h.digest("hex").slice(0, 16);
+};
+
+// Every clip gets the same codec, size, fps and a stereo audio track so the join is a lossless concat.
+const normalize = (input, out, s, seek = 0) => {
+  const probe = spawnSync("ffprobe", ["-v", "error", "-select_streams", "a", "-show_entries", "stream=index", "-of", "csv=p=0", input], { encoding: "utf8" });
+  const hasAudio = probe.stdout.trim().length > 0;
+  const vf = `scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,fps=${fps},format=yuv420p`;
+  const a = ["-y", "-v", "error", "-ss", String(seek), "-t", String(s.duration), "-i", input];
+  if (!hasAudio) a.push("-f", "lavfi", "-t", String(s.duration), "-i", "anullsrc=r=48000:cl=stereo");
+  a.push("-map", "0:v:0", "-map", hasAudio ? "0:a:0" : "1:a:0", "-vf", vf, "-c:v", "libx264", "-crf", "18", "-preset", "medium",
+    "-c:a", "aac", "-ar", "48000", "-ac", "2", "-shortest", "-movflags", "+faststart", out);
+  run("ffmpeg", a);
+};
+
+const hf = hasBin("hyperframes") ? ["hyperframes"] : ["npx", `hyperframes@${sb.hyperframes ?? "latest"}`];
+let rendered = 0;
+const clips = sb.scenes.map((s, i) => {
+  const name = `${String(i + 1).padStart(2, "0")}-${s.id}.mp4`;
+  const out = join(clipsDir, name);
+  const hash = hashOf(s);
+  const prev = cache[s.id];
+  const force = forced.includes(s.id);
+  if (!force && prev?.hash === hash && existsSync(join(clipsDir, prev.file))) {
+    if (prev.file !== name) renameSync(join(clipsDir, prev.file), out);
+    console.log(`skip   ${name} (unchanged)`);
+  } else if (forced.length && !force && prev && existsSync(join(clipsDir, prev.file))) {
+    if (prev.file !== name) renameSync(join(clipsDir, prev.file), out);
+    console.log(`keep   ${name} (not selected)`);
+    return { s, name, hash: prev.hash };
+  } else {
+    console.log(`render ${name}`);
+    if (s.kind === "demo") normalize(join(runDir, s.source), out, s, s.sourceStart ?? 0);
+    else {
+      const raw = join(rawDir, name);
+      const comp = s.composition ?? `compositions/${s.id}.html`;
+      run(hf[0], [...hf.slice(1), "render", "-c", comp, "-o", raw, "--fps", String(fps), "--quality", quality], { cwd: join(runDir, "composition") });
+      normalize(raw, out, s);
+    }
+    rendered++;
+  }
+  return { s, name, hash };
+});
+
+const nextCache = Object.fromEntries(clips.map((c) => [c.s.id, { hash: c.hash, file: c.name }]));
+writeFileSync(cachePath, JSON.stringify(nextCache, null, 2));
+
+let t = 0;
+const rows = clips.map(({ s, name }, i) => {
+  const row = `| ${i + 1} | ${s.id} | ${s.kind} | ${t.toFixed(2)} | ${(t + s.duration).toFixed(2)} | \`clips/${name}\` | ${(s.line ?? "").replace(/\|/g, "/")} |`;
+  t += s.duration;
+  return row;
+});
+writeFileSync(join(runDir, "TIMING.md"), `# Timing: ${sb.title}\n\nTotal ${t.toFixed(2)}s at ${W}x${H}, ${fps} fps.\n\n| # | Scene | Kind | In (s) | Out (s) | Clip | Line |\n|---|---|---|---|---|---|---|\n${rows.join("\n")}\n`);
+
+if (join_) {
+  const list = join(clipsDir, ".concat.txt");
+  writeFileSync(list, clips.map((c) => `file '${join(clipsDir, c.name).replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+  const joined = join(clipsDir, ".joined.mp4");
+  run("ffmpeg", ["-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", joined]);
+  const final = join(runDir, "final.mp4");
+  if (sb.music?.file) {
+    const vol = String(sb.music.volume ?? 0.35);
+    run("ffmpeg", ["-y", "-v", "error", "-i", joined, "-stream_loop", "-1", "-i", join(runDir, sb.music.file),
+      "-filter_complex", `[1:a]volume=${vol},afade=t=out:st=${Math.max(0, t - 1.5)}:d=1.5[m];[0:a][m]amix=inputs=2:duration=first:normalize=0[a]`,
+      "-map", "0:v", "-map", "[a]", "-c:v", "copy", "-c:a", "aac", "-t", String(t), "-movflags", "+faststart", final]);
+    rmSync(joined);
+  } else renameSync(joined, final);
+  console.log(`joined final.mp4 (${t.toFixed(2)}s)`);
+}
+console.log(`done: ${rendered} rendered, ${clips.length - rendered} reused`);

package/skills/luckiest-video-studio/scripts/storyboard.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "luckiest-video-studio storyboard",
+  "type": "object",
+  "required": ["version", "title", "mode", "format", "scenes"],
+  "properties": {
+    "version": { "const": 1 },
+    "title": { "type": "string", "minLength": 1 },
+    "mode": { "enum": ["launch", "demo", "logos"] },
+    "tone": { "type": "string" },
+    "format": {
+      "type": "object",
+      "required": ["width", "height", "fps"],
+      "properties": {
+        "width": { "type": "integer", "minimum": 16 },
+        "height": { "type": "integer", "minimum": 16 },
+        "fps": { "enum": [24, 30, 60] }
+      }
+    },
+    "hyperframes": { "type": "string", "description": "Pinned HyperFrames version for npx, for example 0.8.84" },
+    "music": {
+      "type": "object",
+      "required": ["file"],
+      "properties": {
+        "file": { "type": "string", "description": "Path relative to the run folder" },
+        "volume": { "type": "number", "minimum": 0, "maximum": 0.5, "default": 0.35 },
+        "license": { "type": "string" }
+      }
+    },
+    "scenes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "duration"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "kind": { "enum": ["motion", "logo", "demo"] },
+          "duration": { "type": "number", "exclusiveMinimum": 0 },
+          "line": { "type": "string", "description": "What this scene says or shows, one line, used in TIMING.md" },
+          "composition": { "type": "string", "description": "motion and logo: sub-composition path relative to composition/, default compositions/<id>.html" },
+          "recipe": { "type": "string", "description": "logo: recipe name from references/logo-recipes.md" },
+          "source": { "type": "string", "description": "demo: footage path relative to the run folder" },
+          "sourceStart": { "type": "number", "minimum": 0, "default": 0 },
+          "faceRect": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 4, "maxItems": 4, "description": "demo: speaker's face as [x, y, w, h] fractions of the frame, checked by the face gate" },
+          "variables": { "type": "object", "description": "Values the composition reads: copy, colors, logo path" },
+          "assets": { "type": "array", "items": { "type": "string" }, "description": "Extra files (relative to the run folder) whose change should trigger a re-render" }
+        }
+      }
+    }
+  }
+}