luckiest-co 1.0.32 → 1.0.33

package/skills/luckiest-video-studio/references/storyboard.md

@@ -14,6 +14,7 @@ this file and re-renders only what it touched. Schema:
   "mode": "demo",
   "tone": "polished",
   "format": { "width": 1920, "height": 1080, "fps": 30 },
+  "formats": ["landscape", "vertical", "square"],
   "hyperframes": "0.8.84",
   "music": { "file": "audio/bed.mp3", "volume": 0.3, "license": "user supplied" },
   "scenes": [
@@ -27,16 +28,23 @@ this file and re-renders only what it touched. Schema:
 
 | Field | Meaning |
 |---|---|
-| `format` | Output size and frame rate. Landscape 1920x1080, vertical 1080x1920, square 1080x1080. |
+| `format` | Master size and frame rate. Landscape 1920x1080, vertical 1080x1920, square 1080x1080. Scenes are designed and reviewed at this size. |
+| `formats` | Optional. Render the same scenes once per listed format: `landscape` 1920x1080, `vertical` 1080x1920, `square` 1080x1080, all at `format.fps`. Motion and logo scenes re-lay out for each size (see "Build once, render every format" in `step-3-compose.md`); they are never cropped. Only demo footage is cropped, around `scenes[].focus`. Omit it to render `format` alone. |
 | `hyperframes` | Pinned HyperFrames version so a re-render months later looks the same. |
-| `music` | Optional bed mixed under the joined video, looped and faded out. Licensed files only. |
+| `music` | Optional bed mixed under the joined video, looped and faded out. Licensed files only. `offset` skips into the track and `at` starts it in the video, so a chosen kick lands on a chosen moment: a kick 10.4s into the track on a cut at 3.0s is `"offset": 7.4, "at": 0` or `"offset": 10.4, "at": 3`. |
+| `facts` | Every number, price, and id the video shows, as short phrases: `["3 unpaid invoices, $4,792.44 total", "Tom Becker INV-0039, 5 days late"]`. Write them in Step 2 from the project's real data. `qa.mjs facts` fails any on-screen number with two or more digits, a currency sign, a percent, or an id that no fact contains, and any em dash on screen. Add decorative numbers (a timecode, a year) here too. |
+| `loudness` | Integrated loudness of `final.mp4` in LUFS, default `-14` (the streaming norm), two-pass with a -1.2 dBTP ceiling. `false` skips it. |
+| `sfx` | Optional `{ "file": "audio/sfx.wav", "volume": 1 }` from `scripts/sfx-cues.mjs`, mixed under the joined video at 0 s. Cue times are global, so re-run the mixer after a scene's length changes. |
 | `scenes[].id` | Lowercase and hyphens. Stable: edits refer to scenes by id. |
 | `scenes[].kind` | `motion` (HyperFrames scene), `logo` (HyperFrames logo recipe), `demo` (footage). |
 | `scenes[].composition` | For motion and logo, the sub-composition under `composition/`. Default `compositions/<id>.html`. |
 | `scenes[].source`, `sourceStart` | For demo, the footage file and where to start in it. |
+| `scenes[].focus` | For demo, `{ "x": 0.5, "y": 0.5 }` as fractions of the source frame: the point kept in view when the footage is cropped to a different shape (a 16:9 screen recording in a vertical cut). Set it on the cursor, the face, or the UI the line talks about. |
 | `scenes[].variables` | Copy, colors, and file paths the composition reads. Keep editable values here, not hardcoded in HTML. |
 | `scenes[].assets` | Other files the scene depends on (logo SVG, shared CSS). Changing one re-renders the scene. |
+| `scenes[].states` | For a one-shape morph scene, the state list: `{ t, label, shape, cursor? }` per state, local times. See "One shape, never cut" in `step-2-plan.md`. |
 | `scenes[].line` | One line on what the scene says or shows. Goes into `TIMING.md`. |
+| `scenes[].hold` | Optional. Seconds into the scene where `--stills` captures its hold frame. Default 0.5s before the cut. |
 
 ## Rendering
 
@@ -45,6 +53,7 @@ node <skill-dir>/scripts/render-scenes.mjs <run-dir>                    # render
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --scene stat       # force one scene
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --quality draft    # fast pass while iterating
 node <skill-dir>/scripts/render-scenes.mjs <run-dir> --no-join          # clips only
+node <skill-dir>/scripts/render-scenes.mjs <run-dir> --stills           # hold-frame PNGs per format, no render
 ```
 
 The script hashes each scene's JSON, its composition or footage, and its `assets`.
@@ -53,6 +62,16 @@ scenes and leaves the rest as they are. Every clip is normalized to the same siz
 frame rate, and a stereo audio track, so the join is a lossless concat. It writes
 `clips/NN-id.mp4`, `final.mp4`, and `TIMING.md`.
 
+With `formats`, each format gets its own folder and file: `clips/<format>/NN-id.mp4`
+and `final-<format>.mp4`, each with its own cache, so adding a format renders only
+that format. A landscape format reuses the clips of a finished single-format 16:9
+render at the same `--quality`, so adding formats after the master is done renders
+only the new sizes (demo footage re-crops, which is ffmpeg only). For motion and logo scenes it writes a stamped copy of the composition
+next to the original (`compositions/<id>.<format>.html`, root `data-width`,
+`data-height`, and `data-format` set, plus `:root{--w;--h;--u}`), renders it, and
+deletes the copy. A scene that sizes itself with those tokens re-lays out; one
+hardcoded to 1920x1080 px gets clipped, which `qa.mjs` catches.
+
 It runs `hyperframes` when it is on the PATH, otherwise `npx hyperframes@<pinned
 version>`. Before the first `npx` run in a session, tell the user it downloads
 HyperFrames from npm and ask.
@@ -75,4 +94,6 @@ HyperFrames from npm and ask.
 | "Make the demo part shorter" | `duration` or `sourceStart` of that demo scene |
 | "Swap scenes 2 and 4" | Reorder `scenes`; clips are reused and renamed, nothing re-renders |
 | "Different logo in the outro" | Replace the file listed in that scene's `assets` |
-| "Vertical version" | Change `format`; every scene re-renders |
+| "Vertical version" | Add `"vertical"` to `formats`; existing formats keep their clips and only the new one renders |
+| "Square too" | Add `"square"` to `formats` |
+| "The crop cuts off the button" | Move that demo scene's `focus` toward the button, then `--scene <id>` |

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

@@ -12,6 +12,10 @@
 //   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 avsync      <video> [--expect 1.5,4.2] [--duration 20] audio present, length right, hits within one frame
+//   node qa.mjs loop        <video> [--max 6]                          last frame must match the first, so the piece loops
+//   node qa.mjs facts       <run-dir>                                  on-screen numbers not in storyboard facts, em dashes on screen
+//   node qa.mjs safe        <run-dir> [--max 0.004] [--stills]         text or logo edges in the margins each format's platforms cover
 //   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
 //
@@ -22,6 +26,7 @@ import { readFileSync, readdirSync, existsSync, statSync, mkdirSync, writeFileSy
 import { join, resolve, extname } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { FORMATS, SAFE } from "./stamp-format.mjs";
 
 // ---------- shared ----------
 
@@ -68,12 +73,15 @@ export function scanTokens(html, tokens = DEFAULT_TOKENS) {
 
 // ---------- cross-fade ----------
 
-// Selectors whose CSS makes them cover the whole frame.
+// Selectors whose CSS makes them cover the whole frame: 100%, the size tokens, or the root's own data-width/data-height in px.
 export function fullFrameSelectors(html) {
+  const root = html.match(/<div\b[^>]*\bdata-composition-id\b[^>]*>/i)?.[0] ?? "";
+  const [w, h] = ["width", "height"].map((d, i) => root.match(new RegExp(`data-${d}\\s*=\\s*["']?(\\d+)`))?.[1] ?? [1920, 1080][i]);
+  const fullW = new RegExp(`width:(100%|var\\(--w\\)|${w}px)`), fullH = new RegExp(`height:(100%|var\\(--h\\)|${h}px)`);
   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));
+    const full = /inset:0(;|$)/.test(body) || (fullW.test(body) && fullH.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;
@@ -237,6 +245,79 @@ export function beatGrid(cuts, { bpm, phase = 0, tol = 0.035 }) {
   return { ok: rows.every((r) => r.ok), off: rows.filter((r) => !r.ok), cuts: rows.length };
 }
 
+// ---------- avsync ----------
+
+// Times where the audio's short-window energy jumps (a hit, a click, a whoosh's attack).
+export function audioOnsets(video, { rate = 8000, win = 0.005, rise = 4, floor = 0.02 } = {}) {
+  const r = ff(["-v", "error", "-i", video, "-vn", "-ac", "1", "-ar", String(rate), "-f", "s16le", "-"]);
+  if (r.status !== 0) throw new Error(`ffmpeg failed on ${video}: ${r.stderr}`);
+  const pcm = new Int16Array(r.stdout.buffer, r.stdout.byteOffset, r.stdout.length >> 1);
+  const n = Math.round(rate * win), e = [];
+  for (let o = 0; o + n <= pcm.length; o += n) { let s = 0; for (let i = o; i < o + n; i++) s += (pcm[i] / 32768) ** 2; e.push(Math.sqrt(s / n)); }
+  const back = Math.round(0.05 / win), onsets = [];
+  for (let i = 1; i < e.length; i++) {
+    let prev = 0; for (let j = Math.max(0, i - back); j < i; j++) prev += e[j];
+    prev /= Math.max(1, Math.min(back, i));
+    // ponytail: energy-rise onsets, good for hits on a quiet-ish bed; under a dense mix pass the SFX stem instead.
+    if (e[i] > floor && e[i] > rise * prev && !(onsets.length && i * win - onsets.at(-1) < 0.1)) onsets.push(Number((i * win).toFixed(3)));
+  }
+  return onsets;
+}
+
+// The final MP4 has an audio stream, the expected length, and each expected hit lands within one frame.
+export function avSync(video, { expect = [], duration } = {}) {
+  const { fps, duration: vdur } = probe(video), tol = 1 / fps;
+  const r = spawnSync("ffprobe", ["-v", "error", "-select_streams", "a:0", "-show_entries", "stream=duration", "-of", "json", video], { encoding: "utf8" });
+  const a = JSON.parse(r.stdout || "{}").streams?.[0];
+  if (!a) return { ok: false, audio: false, hits: [] };
+  const problems = [], adur = Number(a.duration);
+  // ponytail: two frames of slack for the encoder's audio padding.
+  if (Number.isFinite(adur) && Math.abs(adur - vdur) > 2 * tol) problems.push(`audio ${adur.toFixed(3)}s vs video ${vdur.toFixed(3)}s`);
+  if (duration != null && Math.abs(vdur - duration) > tol) problems.push(`video ${vdur.toFixed(3)}s, expected ${duration}s`);
+  const on = expect.length ? audioOnsets(video) : [];
+  const hits = expect.map((t) => {
+    const near = on.reduce((b, o) => (b == null || Math.abs(o - t) < Math.abs(b - t) ? o : b), null);
+    const offset = near == null ? null : Number((near - t).toFixed(3));
+    return { t, onset: near, offset, ok: offset != null && Math.abs(offset) <= tol };
+  });
+  return { ok: problems.length === 0 && hits.every((h) => h.ok), audio: true, problems, hits, tolerance: Number(tol.toFixed(3)) };
+}
+
+// ---------- loop ----------
+
+// A looping piece (a state-list morph) must end on its first frame, or the repeat shows a jump.
+export function loopCheck(video, { max = 6 } = {}) {
+  const frames = grayFrames(video);
+  const diff = meanDiff(frames[0], frames.at(-1));
+  return { ok: diff <= max, diff: Number(diff.toFixed(2)), frames: frames.length };
+}
+
+// ---------- facts ----------
+
+const ENTITIES = { amp: "&", nbsp: " ", mdash: "\u2014", ndash: "\u2013", lt: "<", gt: ">", quot: '"', "#39": "'", "#8212": "\u2014" };
+
+// What a viewer can read: markup, scripts, styles, and comments removed. Template contents stay (sub-compositions).
+export const visibleText = (html) => html
+  .replace(/<!--[\s\S]*?-->/g, " ").replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, " ")
+  .replace(/<[^>]+>/g, " ").replace(/&(#?\w+);/g, (m, e) => ENTITIES[e] ?? m);
+
+// ponytail: single digits pass unchecked (step numbers, "1 click"); currency, percents, ids, and 2+ digit numbers are checked.
+const NUMBERS = /[A-Z]{2,}-\d+|[$€£]\s?\d[\d,]*(?:\.\d+)?|\d[\d,]*(?:\.\d+)?\s?%|\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d{2,}(?:\.\d+)?|\d\.\d+/g;
+
+// texts: [{ where, text }]. A number passes when it appears inside one of the story facts.
+export function scanFacts(texts, facts = []) {
+  const norm = (x) => x.replace(/\s/g, "");
+  const known = facts.map(norm);
+  const found = [];
+  for (const { where, text } of texts) {
+    for (const token of text.match(NUMBERS) ?? []) {
+      if (!known.some((f) => f.includes(norm(token)))) found.push({ where, rule: "not-a-fact", token: token.trim() });
+    }
+    if (text.includes("\u2014")) found.push({ where, rule: "em-dash", token: "\u2014" });
+  }
+  return found;
+}
+
 // ---------- face ----------
 
 // Crop a 0-1 rect [x, y, w, h] out of a w x h gray frame.
@@ -250,7 +331,8 @@ export const crop = (f, w, h, [x, y, cw, ch]) => {
 // 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 = [];
+  // With formats, faceRect matches the landscape cut (16:9 footage is not cropped there).
+  const final = join(runDir, existsSync(join(runDir, "final.mp4")) ? "final.mp4" : "final-landscape.mp4"), covered = [];
   let t0 = 0, checked = 0;
   for (const s of sb.scenes) {
     if (s.faceRect && s.source && existsSync(join(runDir, s.source))) {
@@ -268,6 +350,71 @@ export function faceCover(runDir, { max = 18, w = 160, h = 90 } = {}) {
   return { ok: covered.length === 0, covered, checked };
 }
 
+// ---------- safe ----------
+
+// Share of sharp-edge pixels in each margin the format's platforms cover (SAFE in stamp-format.mjs).
+// Text and logos are sharp edges; a solid or gradient background has none.
+// ponytail: pixels, not DOM boxes; a full-bleed photo or texture in a motion scene also trips it, so check a hit by eye.
+export function marginInk(frame, w, h, [t, b, l, r], { edge = 48 } = {}) {
+  // Each band stops one row short of the safe edge, so a line drawn exactly on the edge (a HUD corner) is not counted.
+  const bands = { top: [0, 0, w, Math.round(t * h) - 1], bottom: [0, h - Math.round(b * h) + 1, w, h], left: [0, 0, Math.round(l * w) - 1, h], right: [w - Math.round(r * w) + 1, 0, w, h] };
+  const out = {};
+  for (const [side, [x0, y0, x1, y1]] of Object.entries(bands)) {
+    let hits = 0, n = 0;
+    for (let y = y0; y < Math.min(y1, h - 1); y++) for (let x = x0; x < Math.min(x1, w - 1); x++) {
+      const i = y * w + x;
+      if (Math.abs(frame[i] - frame[i + 1]) + Math.abs(frame[i] - frame[i + w]) > edge) hits++;
+      n++;
+    }
+    out[side] = n ? hits / n : 0;
+  }
+  return out;
+}
+
+// Samples every motion and logo scene of each format's final, twice a second. Demo footage is skipped:
+// a screen recording fills the frame by design. With stills, reads the hold-frame PNGs that
+// `render-scenes.mjs --stills` wrote instead, so the check needs no render.
+export function safeAreas(runDir, { max = 0.004, every = 0.5, stills = false } = {}) {
+  const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
+  const named = Object.keys(FORMATS).find((k) => FORMATS[k][0] === sb.format.width && FORMATS[k][1] === sb.format.height);
+  const runs = Array.isArray(sb.formats) ? sb.formats.map((f) => [f, `final-${f}.mp4`]) : named ? [[named, "final.mp4"]] : [];
+  const hits = [];
+  let checked = 0;
+  if (stills) {
+    for (const [fmt] of runs) {
+      const [W, H] = FORMATS[fmt], w = W / 4, h = H / 4;
+      sb.scenes.forEach((s, i) => {
+        if (s.kind === "demo") return;
+        const png = join(runDir, "stills", Array.isArray(sb.formats) ? fmt : "", `${String(i + 1).padStart(2, "0")}-${s.id}.png`);
+        if (!existsSync(png)) { hits.push({ format: fmt, scene: s.id, missing: png }); return; }
+        const [f] = grayFrames(png, w, h);
+        checked++;
+        for (const [side, ink] of Object.entries(marginInk(f, w, h, SAFE[fmt]))) {
+          if (ink > max) hits.push({ format: fmt, scene: s.id, side, ink: Number(ink.toFixed(4)) });
+        }
+      });
+    }
+    return { ok: hits.length === 0, hits, checked };
+  }
+  for (const [fmt, file] of runs) {
+    const video = join(runDir, file), [W, H] = FORMATS[fmt], w = W / 4, h = H / 4;
+    if (!existsSync(video)) { hits.push({ format: fmt, missing: file }); continue; }
+    let t0 = 0;
+    for (const s of sb.scenes) {
+      for (let t = 0.25; s.kind !== "demo" && t < s.duration; t += every) {
+        const [f] = grayFrames(video, w, h, { start: t0 + t, duration: 0.05 });
+        if (!f) continue;
+        checked++;
+        for (const [side, ink] of Object.entries(marginInk(f, w, h, SAFE[fmt]))) {
+          if (ink > max) hits.push({ format: fmt, scene: s.id, t: Number((t0 + t).toFixed(2)), side, ink: Number(ink.toFixed(4)) });
+        }
+      }
+      t0 += s.duration;
+    }
+  }
+  return { ok: hits.length === 0, hits, checked };
+}
+
 // ---------- judge ----------
 
 // Pass 1 shows new as A, old as B. Pass 2 swaps them. Keep new only if it wins both,
@@ -300,7 +447,7 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
   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|motion|legibility|pops|deadframes|presence|beatsync|beatgrid|face|judge> <path> [options]"); process.exit(1); }
+  if (!gate || !target) { console.error("Usage: qa.mjs <tokens|crossfade|motion|legibility|pops|deadframes|presence|beatsync|beatgrid|face|avsync|loop|facts|safe|judge> <path> [options]"); process.exit(1); }
   let result;
   if (gate === "tokens") {
     const tokens = opt("--tokens") ? JSON.parse(readFileSync(opt("--tokens"), "utf8")) : DEFAULT_TOKENS;
@@ -331,7 +478,22 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
     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") {
+  else if (gate === "avsync") {
+    const expect = (opt("--expect", "") || "").split(",").filter(Boolean).map(Number);
+    result = avSync(target, { expect, duration: opt("--duration") != null ? num("--duration") : undefined });
+  } else if (gate === "loop") result = loopCheck(target, { max: num("--max", 6) });
+  else if (gate === "safe") result = safeAreas(target, { max: num("--max", 0.004), stills: rest.includes("--stills") });
+  else if (gate === "facts") {
+    const sb = JSON.parse(readFileSync(join(target, "storyboard.json"), "utf8"));
+    const comp = join(target, "composition");
+    const texts = existsSync(comp) ? htmlFiles(comp).map((f) => ({ where: f, text: visibleText(readFileSync(f, "utf8")) })) : [];
+    for (const sc of sb.scenes ?? []) {
+      const vals = [sc.line, ...Object.values(sc.variables ?? {})].filter((v) => typeof v === "string");
+      texts.push({ where: `storyboard.json#${sc.id}`, text: vals.join("\n") });
+    }
+    const found = scanFacts(texts, sb.facts ?? []);
+    result = { ok: found.length === 0, found, facts: (sb.facts ?? []).length };
+  } 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 });

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

@@ -9,7 +9,8 @@ import { spawnSync } from "node:child_process";
 import {
   scanTokens, scanCrossfades, scanMotion, legibility, findPops, deadFrames, presence,
   beatSync, findAnchor, cutTimes, beatGrid, grayFrames, probe,
-  faceCover, pairVerdict, parseWinner,
+  faceCover, pairVerdict, parseWinner, audioOnsets, avSync, visibleText, scanFacts, loopCheck,
+  fullFrameSelectors, safeAreas,
 } from "./qa.mjs";
 
 const dir = mkdtempSync(join(tmpdir(), "qa-gates-"));
@@ -150,3 +151,100 @@ test("judge CLI: pending without a verdict, keeps or rejects with verdicts, fake
   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
 });
+
+// Gray video with a 50 ms tone burst starting at each time in `hits`.
+function withHits(name, hits, d = 2) {
+  const out = join(dir, name);
+  const expr = hits.length ? hits.map((h) => `between(t,${h},${h + 0.05})`).join("+") : "0";
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", `color=c=gray:size=160x90:rate=30:duration=${d}`,
+    "-f", "lavfi", "-i", `aevalsrc='0.8*(${expr})*sin(2*PI*1000*t)':s=48000:d=${d}`,
+    "-c:v", "libx264", "-crf", "12", "-c:a", "aac", "-shortest", out]);
+  assert.equal(r.status, 0, r.stderr?.toString());
+  return out;
+}
+
+test("avsync: hits on time pass; a hit 3 frames late, no audio, or the wrong length fail", () => {
+  const clip = withHits("hits.mp4", [0.5, 1.2]);
+  const on = audioOnsets(clip);
+  assert.ok(on.some((t) => Math.abs(t - 0.5) < 1 / 30) && on.some((t) => Math.abs(t - 1.2) < 1 / 30), JSON.stringify(on));
+  assert.equal(avSync(clip, { expect: [0.5, 1.2], duration: 2 }).ok, true);
+  const late = avSync(clip, { expect: [0.5, 1.1] });
+  assert.equal(late.ok, false);
+  assert.equal(late.hits.filter((h) => !h.ok).length, 1);
+  assert.equal(avSync(clip, { duration: 3 }).ok, false);
+  const silent = avSync(video("noaudio.mp4", [["gray", 1]]));
+  assert.equal(silent.ok, false);
+  assert.equal(silent.audio, false);
+  assert.equal(cli("avsync", clip, "--expect", "0.5,1.1").status, 1);
+  assert.equal(cli("avsync", clip, "--expect", "0.5,1.2", "--duration", "2").status, 0);
+});
+
+test("facts: on-screen numbers must be story facts; code numbers and single digits are ignored; em dashes fail", () => {
+  const html = `<style>.t{font-size:84px;letter-spacing:-0.02em}</style>
+    <template><div class="t" data-start="1.25">3 unpaid, $4,792.44 total</div><p>INV-0043 opened twice</p></template>
+    <script>tl.to(".t", { y: 120, duration: 0.35 }, 2.5);</script>`;
+  assert.equal(visibleText(html).replace(/\s+/g, " ").trim(), "3 unpaid, $4,792.44 total INV-0043 opened twice");
+  const facts = ["3 unpaid invoices, $4,792.44 total", "Maya Chen INV-0043 $781.94"];
+  assert.deepEqual(scanFacts([{ where: "a.html", text: visibleText(html) }], facts), []);
+  const drift = scanFacts([{ where: "b.html", text: "Total $4,792.40, up 12% since INV-0044" }], facts);
+  assert.deepEqual(drift.map((f) => f.token), ["$4,792.40", "12%", "INV-0044"]);
+  assert.deepEqual(scanFacts([{ where: "c.html", text: "Fast \u2014 and free" }], facts).map((f) => f.rule), ["em-dash"]);
+  assert.deepEqual(scanFacts([{ where: "d.html", text: visibleText("<p>Fast &mdash; free</p>") }], facts).map((f) => f.rule), ["em-dash"]);
+  const run = join(dir, "factsrun");
+  mkdirSync(join(run, "composition/compositions"), { recursive: true });
+  writeFileSync(join(run, "composition/compositions/hook.html"), "<p>Paid $2,860.50</p>");
+  writeFileSync(join(run, "storyboard.json"), JSON.stringify({ facts: ["Nair Dental $2,860.50"], scenes: [{ id: "hook", kind: "motion", duration: 2, line: "Paid $2,860.50", variables: { value: "3x" } }] }));
+  assert.equal(cli("facts", run).status, 0);
+  writeFileSync(join(run, "composition/compositions/hook.html"), "<p>Paid $2,680.50</p>");
+  const r = cli("facts", run);
+  assert.equal(r.status, 1);
+  assert.match(r.stdout, /2,680\.50/);
+});
+
+test("loop: last frame matching the first passes, a different end frame fails", () => {
+  const loops = video("loops.mp4", [["0x3050a0", 0.5], ["0xa05030", 0.5], ["0x3050a0", 0.5]]);
+  assert.equal(loopCheck(loops).ok, true);
+  const ends = video("ends.mp4", [["0x3050a0", 0.5], ["0xa05030", 1]]);
+  assert.equal(loopCheck(ends).ok, false);
+  assert.equal(cli("loop", ends).status, 1);
+});
+
+test("crossfade: a full-frame layer is found at the composition's own size, not only 1920x1080", () => {
+  const html = `<div data-composition-id="m" data-width="1080" data-height="1920"></div><style>.bg{width:1080px;height:1920px}.v{width:var(--w);height:var(--h)}.wide{width:1920px;height:1080px}</style>`;
+  assert.deepEqual([...fullFrameSelectors(html)], [".bg", ".v"]);
+});
+
+test("safe: sharp content in vertical's covered bottom fails, the same content in the safe area passes", () => {
+  // A 320x180 test pattern (sharp text and bars) on a plain vertical frame.
+  const place = (name, y) => {
+    const run = join(dir, name);
+    mkdirSync(run, { recursive: true });
+    const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", "color=c=0xf3efe6:size=1080x1920:rate=30:duration=1", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30:duration=1",
+      "-filter_complex", `[0][1]overlay=x=380:y=${y},format=yuv420p`, "-c:v", "libx264", "-crf", "12", join(run, "final-vertical.mp4")]);
+    assert.equal(r.status, 0, r.stderr?.toString());
+    writeFileSync(join(run, "storyboard.json"), JSON.stringify({ format: { width: 1920, height: 1080, fps: 30 }, formats: ["vertical"], scenes: [{ id: "end", kind: "motion", duration: 1 }] }));
+    return run;
+  };
+  const low = safeAreas(place("safe-low", 1500));
+  assert.equal(low.ok, false);
+  assert.ok(low.hits.every((h) => h.side === "bottom" && h.format === "vertical"), JSON.stringify(low.hits));
+  assert.equal(safeAreas(place("safe-mid", 700)).ok, true);
+  assert.equal(cli("safe", join(dir, "safe-low")).status, 1);
+});
+
+test("safe --stills reads the hold-frame PNGs from render-scenes --stills, no final needed", () => {
+  const place = (name, y) => {
+    const run = join(dir, name);
+    mkdirSync(join(run, "stills/vertical"), { recursive: true });
+    const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", "color=c=0xf3efe6:size=1080x1920", "-f", "lavfi", "-i", "testsrc2=size=320x180",
+      "-filter_complex", `[0][1]overlay=x=380:y=${y}`, "-frames:v", "1", join(run, "stills/vertical/01-end.png")]);
+    assert.equal(r.status, 0, r.stderr?.toString());
+    writeFileSync(join(run, "storyboard.json"), JSON.stringify({ format: { width: 1920, height: 1080, fps: 30 }, formats: ["vertical"], scenes: [{ id: "end", kind: "motion", duration: 1 }] }));
+    return run;
+  };
+  const low = safeAreas(place("stills-low", 1500), { stills: true });
+  assert.equal(low.ok, false);
+  assert.deepEqual(low.hits.map((h) => h.side), ["bottom"]);
+  assert.equal(safeAreas(place("stills-mid", 700), { stills: true }).ok, true);
+  assert.equal(cli("safe", join(dir, "stills-low"), "--stills").status, 1);
+});