From 619836227820a1eebd27d749490fbd3051216ab5 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Tue, 30 Jun 2026 09:58:55 +0800
Subject: [PATCH 1/2] =?UTF-8?q?fix(skills):=20storyboard=20review=20?=
 =?UTF-8?q?=E2=80=94=20bg-on-clip=20rule,=20slideshow=20output,=20parser?=
 =?UTF-8?q?=20parity=20guard?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the storyboard-angle review (jrusso1020):

- M1 (invisible text): frame-worker.md (x3) + SKILL.md Step 5 (x3) now require a
  frame's full-bleed background on a class=clip layer, never the #root /
  data-composition-id element (the root is clip-gated to its scene window, so a
  background on it is not a dependable ground and dark text can land on the black
  host body). The assembler already paints frame.md's canvas onto index #root as
  the base ground; the per-frame clip rides on top.
- B3 (slideshow truncates to slide 1): slideshow/SKILL.md gains an Output section
  (decks render via 'present'; 'render index.html' captures only the first
  composition; linear main-line MP4 export is deferred).
- Parser drift: vendoredParity.test.ts guards the three vendored storyboard.mjs
  copies (byte-identical + parse-parity with @hyperframes/core).
- skills-manifest.json regenerated for the edited SKILL.md files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/storyboard/vendoredParity.test.ts     | 71 +++++++++++++++++++
 skills-manifest.json                          |  8 +--
 skills/faceless-explainer/SKILL.md            |  2 +
 .../sub-agents/frame-worker.md                |  1 +
 skills/pr-to-video/SKILL.md                   |  2 +
 skills/pr-to-video/sub-agents/frame-worker.md |  1 +
 skills/product-launch-video/SKILL.md          |  2 +
 .../sub-agents/frame-worker.md                |  1 +
 skills/slideshow/SKILL.md                     |  6 ++
 9 files changed, 90 insertions(+), 4 deletions(-)
 create mode 100644 packages/core/src/storyboard/vendoredParity.test.ts

diff --git a/packages/core/src/storyboard/vendoredParity.test.ts b/packages/core/src/storyboard/vendoredParity.test.ts
new file mode 100644
index 0000000000..15413042b2
--- /dev/null
+++ b/packages/core/src/storyboard/vendoredParity.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseStoryboard as coreParse } from "./parseStoryboard.js";
+
+// Sync guard for the hand-vendored parser.
+//
+// Each standalone skill ships a plain-JS copy of this parser at
+// scripts/lib/storyboard.mjs — skills install via `npx skills add`, where a
+// script can't reach @hyperframes/core (and the core export is .ts that node
+// can't load). The copies MUST stay in lockstep with core. This test fails the
+// moment they drift, so a parser change can't silently leave the skills behind:
+//   1. every vendored copy is byte-identical to the others, and
+//   2. a vendored copy parses a representative storyboard identically to core.
+// If you change the parser, update every path below in the same commit.
+const VENDORED_RELATIVE = [
+  "../../../../skills/faceless-explainer/scripts/lib/storyboard.mjs",
+  "../../../../skills/pr-to-video/scripts/lib/storyboard.mjs",
+  "../../../../skills/product-launch-video/scripts/lib/storyboard.mjs",
+];
+
+const vendoredUrls = VENDORED_RELATIVE.map((rel) => new URL(rel, import.meta.url));
+
+// Exercises frontmatter (known keys + an unknown global), H2/H3 frame headings,
+// every recognized meta key + an alias (transition / vo / description), an unknown
+// status (warning + stash under extra), an unparseable duration (warning), unknown
+// extra keys, and free-form narrative — the surfaces most likely to drift.
+const SAMPLE = `---
+format: 1080x1920
+message: "Ship it"
+arc: Hook → Proof → CTA
+audience: builders
+campaign: spring
+---
+
+## Frame 1 — Hook
+- duration: 3s
+- status: animated
+- transition: cut
+- vo: "Open cold."
+- src: compositions/frames/01-hook.html
+- poster: 2s
+- effect: shimmer
+
+Open on the promise.
+
+### Beat 2 — Detail
+- duration: four
+- status: glowing
+- description: a quiet hold
+- voiceover: "The payoff."
+
+Land it.
+`;
+
+describe("vendored storyboard parser parity", () => {
+  it("every vendored copy is byte-identical", () => {
+    const bodies = vendoredUrls.map((u) => readFileSync(fileURLToPath(u), "utf8"));
+    for (let i = 1; i < bodies.length; i++) {
+      expect(
+        bodies[i],
+        `${VENDORED_RELATIVE[i]} drifted from ${VENDORED_RELATIVE[0]} — re-vendor it`,
+      ).toBe(bodies[0]);
+    }
+  });
+
+  it("a vendored copy parses identically to core", async () => {
+    const vendored = await import(vendoredUrls[0].href);
+    expect(vendored.parseStoryboard(SAMPLE)).toEqual(coreParse(SAMPLE));
+  });
+});
diff --git a/skills-manifest.json b/skills-manifest.json
index acb94dd4a1..12e5474423 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,7 +6,7 @@
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "b94e52c77d04c1ea",
+      "hash": "edbe47dd738d14d8",
       "files": 17
     },
     "general-video": {
@@ -54,11 +54,11 @@
       "files": 132
     },
     "pr-to-video": {
-      "hash": "85a7577aee41bb82",
+      "hash": "ef4a3aa5a943aeec",
       "files": 21
     },
     "product-launch-video": {
-      "hash": "5341508d185c091d",
+      "hash": "b7bee220096f2ae2",
       "files": 18
     },
     "remotion-to-hyperframes": {
@@ -66,7 +66,7 @@
       "files": 70
     },
     "slideshow": {
-      "hash": "ae8d8f3093ef0c04",
+      "hash": "2f006c93745fcc32",
       "files": 2
     },
     "talking-head-recut": {
diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md
index 30667133a6..6a80d44e9e 100644
--- a/skills/faceless-explainer/SKILL.md
+++ b/skills/faceless-explainer/SKILL.md
@@ -128,6 +128,8 @@ Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/refe
 
 Each worker context must include `PROJECT_DIR`, `frame_id`, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
 
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
+
 As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
 
 After audio timings exist, build captions in the background and assemble the index:
diff --git a/skills/faceless-explainer/sub-agents/frame-worker.md b/skills/faceless-explainer/sub-agents/frame-worker.md
index ac7fa0bb93..1528410b67 100644
--- a/skills/faceless-explainer/sub-agents/frame-worker.md
+++ b/skills/faceless-explainer/sub-agents/frame-worker.md
@@ -62,6 +62,7 @@ You **can't** meaningfully run `hyperframes lint` / `validate` / `inspect` here:
 - `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
 - **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
 - `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
+- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
 - `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
 - `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
 - `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
diff --git a/skills/pr-to-video/SKILL.md b/skills/pr-to-video/SKILL.md
index e3e4a955e7..f2a8b7c525 100644
--- a/skills/pr-to-video/SKILL.md
+++ b/skills/pr-to-video/SKILL.md
@@ -159,6 +159,8 @@ Duration sync is mechanical: real voice duration wins; silent frames keep estima
 
 Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame. Each worker's context must include `PROJECT_DIR`, `frame_id`, canvas size, caption status and keep-out band if captions are enabled, `RULES_DIR` (absolute path to this skill's `../hyperframes-animation/rules/`), and the absolute path to `references/code-vocabulary.md`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`), and — for a code beat — `code-vocabulary.md` for the named block's inputs. Each worker writes only `compositions/frames/NN-*.html`; workers never edit `STORYBOARD.md`.
 
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
+
 As each worker returns, mark that frame `animated` in `STORYBOARD.md`.
 
 After audio timings exist, build captions in the background and assemble the index:
diff --git a/skills/pr-to-video/sub-agents/frame-worker.md b/skills/pr-to-video/sub-agents/frame-worker.md
index 25ca6ad2fc..ea674c8578 100644
--- a/skills/pr-to-video/sub-agents/frame-worker.md
+++ b/skills/pr-to-video/sub-agents/frame-worker.md
@@ -81,6 +81,7 @@ You **can't** meaningfully run `hyperframes lint` / `validate` / `inspect` here:
 - `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
 - **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
 - `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
+- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
 - `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
 - `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
 - `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md
index b1038c7900..4b54f2199a 100644
--- a/skills/product-launch-video/SKILL.md
+++ b/skills/product-launch-video/SKILL.md
@@ -131,6 +131,8 @@ Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/refe
 
 Each worker context must include `PROJECT_DIR`, `frame_id`, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
 
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
+
 As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
 
 After audio timings exist, build captions in the background and assemble the index:
diff --git a/skills/product-launch-video/sub-agents/frame-worker.md b/skills/product-launch-video/sub-agents/frame-worker.md
index 88c59bd30e..6dad8fb66d 100644
--- a/skills/product-launch-video/sub-agents/frame-worker.md
+++ b/skills/product-launch-video/sub-agents/frame-worker.md
@@ -62,6 +62,7 @@ You **can't** meaningfully run `hyperframes lint` / `validate` / `inspect` here:
 - `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
 - **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
 - `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
+- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
 - `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
 - `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
 - `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
diff --git a/skills/slideshow/SKILL.md b/skills/slideshow/SKILL.md
index 1e4726114c..0088bbe9d8 100644
--- a/skills/slideshow/SKILL.md
+++ b/skills/slideshow/SKILL.md
@@ -15,6 +15,12 @@ A HyperFrames slideshow is a normal HyperFrames composition — scenes, clips, G
 
 **Read `/hyperframes-core` first** for the base composition contract (clips, tracks, `data-*` attributes, determinism rules). This skill covers only what is new: the island schema, slide writing rules, fragments, branching, validation, and the wrapping component.
 
+## Output — a navigable deck, not a linear MP4
+
+A slideshow's output is the **running deck**: serve it with `hyperframes present <project-dir>` (or Studio present mode) — the player's `SlideshowController` reads the island and drives navigation, fragments, branching, and presenter mode. See **Presenting and handoff** below.
+
+**Do not `hyperframes render` a slideshow into a single MP4.** A deck is authored as several top-level scene compositions (one `data-composition-id` per slide) with **no master-root composition** wrapping them, so `render` resolves only the **first** composition and emits a **silently truncated** MP4 (e.g. 6s of a 40-second deck). A linear main-line export (main slides only, branch sequences excluded) is **deferred** — until it ships, the supported outputs are the live `present` deck and per-slide `snapshot` stills. If a user needs a linear MP4 today, surface this limitation rather than pointing `render` at the deck.
+
 ## Intent confirmation
 
 If the user explicitly asks for a slideshow, slide show, or HyperFrames slideshow, proceed with this skill.

From 83ee705ad2864033654a8545e5fd692d449bbffb Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Tue, 30 Jun 2026 09:59:43 +0800
Subject: [PATCH 2/2] =?UTF-8?q?fix(cli):=20storyboard=20review=20=E2=80=94?=
 =?UTF-8?q?=20lint,=20validate=20help,=20snapshot,=20inspect,=20capture,?=
 =?UTF-8?q?=20render?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the CLI findings from the storyboard-angle review (jrusso1020):

- lint (@hyperframes/lint): accept vendor-prefixed system-font keywords
  -apple-system / BlinkMacSystemFont so a system stack with a generic fallback no
  longer trips font_family_without_font_face (+ test).
- help: list 'validate' under Project in 'hyperframes --help' (was runnable but
  undocumented).
- snapshot: honor -o/--output (the flag did not exist; output was hardcoded to
  snapshots/). The dir is resolved once and threaded through capture + contact
  sheet + Gemini.
- snapshot: split font status into loaded / error / unused with a one-line
  summary; only a real 'error' is reported as FAILED (an unrequested @font-face
  is 'unused', not a contradiction with 'loaded').
- inspect: suppress text_occluded across a scene-to-scene crossfade (occluder in
  a different data-composition-id mount while a scene is mid-fade); a same-scene
  or two-settled-scenes overlap still flags.
- inspect: suppress content_overlap between in-flow siblings governed by the same
  flex/grid container (tight stacks / number lockups are layout slop).
- capture: record source resolution (videoWidth/Height) in video-manifest.json
  alongside the DOM display box; consumers size off the source dims.
- render: warn when the target carries a slideshow island (render captures only
  the first scene, so the MP4 is truncated to slide 1; use 'present').

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/cli/src/capture/contentExtractor.ts  |  6 +-
 packages/cli/src/capture/mediaCapture.ts      | 14 ++++
 packages/cli/src/commands/capture/video.ts    | 11 ++-
 .../cli/src/commands/layout-audit.browser.js  | 47 ++++++++++++-
 packages/cli/src/commands/render.ts           | 24 +++++++
 packages/cli/src/commands/snapshot.ts         | 68 +++++++++++++------
 packages/cli/src/help.ts                      |  4 ++
 packages/lint/src/rules/fonts.test.ts         | 10 +++
 packages/lint/src/rules/fonts.ts              |  6 ++
 9 files changed, 162 insertions(+), 28 deletions(-)

diff --git a/packages/cli/src/capture/contentExtractor.ts b/packages/cli/src/capture/contentExtractor.ts
index 55f5715bb7..2caee86e48 100644
--- a/packages/cli/src/capture/contentExtractor.ts
+++ b/packages/cli/src/capture/contentExtractor.ts
@@ -511,6 +511,8 @@ export function generateAssetDescriptions(
       heading?: string;
       width?: number;
       height?: number;
+      sourceWidth?: number;
+      sourceHeight?: number;
     }>;
     for (const v of manifest) {
       if (!v.localPath) continue; // only describe clips that actually downloaded
@@ -518,7 +520,9 @@ export function generateAssetDescriptions(
       if (!base) continue;
       const desc =
         (v.caption || v.heading || "").trim().replace(/\s+/g, " ").slice(0, 140) || "motion clip";
-      const dims = v.width && v.height ? `, ~${v.width}×${v.height}` : "";
+      const dimW = v.sourceWidth || v.width;
+      const dimH = v.sourceHeight || v.height;
+      const dims = dimW && dimH ? `, ~${dimW}×${dimH}` : "";
       videoLines.push(`${base} — [video] ${desc}${dims}`);
     }
   } catch {
diff --git a/packages/cli/src/capture/mediaCapture.ts b/packages/cli/src/capture/mediaCapture.ts
index efed312764..fff270ed28 100644
--- a/packages/cli/src/capture/mediaCapture.ts
+++ b/packages/cli/src/capture/mediaCapture.ts
@@ -277,6 +277,8 @@ interface VideoDescriptor {
   src: string;
   width: number;
   height: number;
+  sourceWidth: number;
+  sourceHeight: number;
   top: number;
   left: number;
   heading: string;
@@ -315,8 +317,14 @@ const VIDEO_SCAN_EXPR = `(() => {
     if (!ariaLabel && wrapper) ariaLabel = wrapper.getAttribute('aria-label') || '';
     return {
       src: src,
+      // width/height are the DOM display box (what the page laid the element out
+      // at); sourceWidth/Height are the clip's intrinsic resolution. Size planners
+      // off the source dims, not the display box (a 1920x1080 clip can display at
+      // 904x613). 0 when metadata has not loaded yet.
       width: Math.round(rect.width),
       height: Math.round(rect.height),
+      sourceWidth: v.videoWidth || 0,
+      sourceHeight: v.videoHeight || 0,
       top: Math.round(rect.top),
       left: Math.round(rect.left),
       heading: heading,
@@ -418,6 +426,8 @@ export async function captureVideoManifest(
         filename: k,
         width: 0,
         height: 0,
+        sourceWidth: 0,
+        sourceHeight: 0,
         top: 0,
         left: 0,
         heading: "",
@@ -441,6 +451,8 @@ export async function captureVideoManifest(
     filename: string;
     width: number;
     height: number;
+    sourceWidth: number;
+    sourceHeight: number;
     heading: string;
     caption: string;
     ariaLabel: string;
@@ -508,6 +520,8 @@ export async function captureVideoManifest(
       filename: v.filename,
       width: v.width,
       height: v.height,
+      sourceWidth: v.sourceWidth,
+      sourceHeight: v.sourceHeight,
       heading: v.heading,
       caption: v.caption,
       ariaLabel: v.ariaLabel,
diff --git a/packages/cli/src/commands/capture/video.ts b/packages/cli/src/commands/capture/video.ts
index 8aa612eb1d..7dd621903d 100644
--- a/packages/cli/src/commands/capture/video.ts
+++ b/packages/cli/src/commands/capture/video.ts
@@ -104,6 +104,11 @@ export interface ManifestEntry {
   filename: string;
   width: number;
   height: number;
+  /** Intrinsic clip resolution (videoWidth/Height). Optional — absent in
+   * manifests written before source dims were recorded. Size off these, not
+   * the display box (width/height). */
+  sourceWidth?: number;
+  sourceHeight?: number;
   heading: string;
   caption: string;
   ariaLabel: string;
@@ -213,7 +218,7 @@ export async function runVideoMode(args: VideoModeArgs): Promise<void> {
     );
     for (const e of manifest) {
       console.log(
-        `  ${c.bold(`[${e.index}]`)} ${e.filename} — ${e.width}×${e.height}` +
+        `  ${c.bold(`[${e.index}]`)} ${e.filename} — ${e.sourceWidth || e.width}×${e.sourceHeight || e.height}` +
           (e.heading ? `\n      heading: "${e.heading}"` : "") +
           `\n      url: ${e.url}`,
       );
@@ -253,7 +258,7 @@ export async function runVideoMode(args: VideoModeArgs): Promise<void> {
   const relPath = isW2hLayout ? `capture/assets/videos/${fname}` : `assets/videos/${fname}`;
 
   console.log(
-    `${c.accent("▸")} downloading [${entry.index}] ${entry.filename} (${entry.width}×${entry.height})`,
+    `${c.accent("▸")} downloading [${entry.index}] ${entry.filename} (${entry.sourceWidth || entry.width}×${entry.sourceHeight || entry.height})`,
   );
   console.log(`     from: ${entry.url}`);
   try {
@@ -264,7 +269,7 @@ export async function runVideoMode(args: VideoModeArgs): Promise<void> {
     const snippetId = `video-${entry.index}`;
     console.log(
       `     Reference it from a beat composition as:\n` +
-        `       <video id="${snippetId}" src="${relPath}" data-start="0" data-duration="${entry.width === entry.height ? 5 : 4}" data-track-index="0" autoplay muted loop></video>`,
+        `       <video id="${snippetId}" src="${relPath}" data-start="0" data-duration="${(entry.sourceWidth || entry.width) === (entry.sourceHeight || entry.height) ? 5 : 4}" data-track-index="0" autoplay muted loop></video>`,
     );
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === "EEXIST") {
diff --git a/packages/cli/src/commands/layout-audit.browser.js b/packages/cli/src/commands/layout-audit.browser.js
index b3722ecb37..510a55c96e 100644
--- a/packages/cli/src/commands/layout-audit.browser.js
+++ b/packages/cli/src/commands/layout-audit.browser.js
@@ -473,11 +473,37 @@
     return a.contains(b) || b.contains(a);
   }
 
+  function isInFlow(element) {
+    const position = getComputedStyle(element).position;
+    return position === "static" || position === "relative" || position === "sticky";
+  }
+
+  function nearestFlexGridAncestor(element) {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+      const display = getComputedStyle(parent).display;
+      if (display.includes("flex") || display.includes("grid")) return parent;
+    }
+    return null;
+  }
+
+  // Two in-flow text blocks governed by the same flex/grid container are placed
+  // by the layout engine, which reserves space for each — they cannot visually
+  // collide. Any measured text-rect overlap between them is line-box / leading
+  // slop (tight stacks, number lockups, super/subscript units), not a collision.
+  // A real overlap bug needs free positioning (absolute/fixed), which keeps a
+  // different formatting context and is still flagged.
+  function isManagedFlowOverlap(a, b) {
+    if (!isInFlow(a) || !isInFlow(b)) return false;
+    const container = nearestFlexGridAncestor(a);
+    return !!container && container === nearestFlexGridAncestor(b);
+  }
+
   // Two solid text blocks whose boxes overlap by more than a fifth of the
   // smaller block read as a collision — unreadable, and invisible to the
   // overflow checks, which only compare an element against its container.
   function overlapIssue(a, b, time) {
     if (isNested(a.element, b.element)) return null;
+    if (isManagedFlowOverlap(a.element, b.element)) return null;
     const area = intersectionArea(a.rect, b.rect);
     if (area <= Math.min(rectArea(a.rect), rectArea(b.rect)) * 0.2) return null;
     return {
@@ -537,13 +563,30 @@
     return !!hit && hit !== element && !element.contains(hit) && !hit.contains(element);
   }
 
+  // During a scene-to-scene crossfade the incoming scene paints over the
+  // outgoing scene's still-visible text at >= 0.6 opacity — and `--at-transitions`
+  // samples exactly that midpoint. That overlap is the transition doing its job,
+  // not an occlusion bug. Detect it: the occluder lives in a DIFFERENT composition
+  // mount ([data-composition-id]) than the text, and at least one of the two scenes
+  // is mid-fade (effective opacity < 1). Two fully-settled scenes overlapping
+  // (both opacity 1) is NOT suppressed — that is a real layering bug.
+  function isCrossSceneTransitionOverlap(textEl, occluder) {
+    const textScene = textEl.closest("[data-composition-id]");
+    const occluderScene = occluder.closest("[data-composition-id]");
+    if (!textScene || !occluderScene || textScene === occluderScene) return false;
+    return Math.min(opacityChain(textScene), opacityChain(occluderScene)) < 0.999;
+  }
+
   // The opaque element painted over (x, y), or null when the topmost element
-  // there is related to the text or non-opaque.
+  // there is related to the text, non-opaque, or a transient crossfade overlap.
+  // fallow-ignore-next-line complexity
   function occluderAt(element, x, y) {
     if (typeof document.elementFromPoint !== "function") return null;
     const hit = document.elementFromPoint(x, y);
     if (!isForeignElement(element, hit)) return null;
-    return isOpaqueOccluder(hit) ? hit : null;
+    if (!isOpaqueOccluder(hit)) return null;
+    if (isCrossSceneTransitionOverlap(element, hit)) return null;
+    return hit;
   }
 
   // Sweep a grid across the text box (three rows, not just the mid-line, so
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index 65f12f67d2..6c20afb046 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -661,6 +661,30 @@ export default defineCommand({
       }
     }
 
+    // ── Slideshow guard ───────────────────────────────────────────────────
+    // A slideshow deck is several top-level scene compositions with no master
+    // root. `render` captures only the FIRST composition, so a deck renders as a
+    // silently truncated MP4 (e.g. slide 1 of a 40s deck). Warn and point at the
+    // deck-native path. Best-effort — never block a render on this probe.
+    if (!quiet) {
+      try {
+        const renderTarget = entryFile ? resolve(project.dir, entryFile) : project.indexPath;
+        const { slideshowIslandRegex } = await import("@hyperframes/core/slideshow");
+        if (slideshowIslandRegex("i").test(readFileSync(renderTarget, "utf8"))) {
+          console.log(
+            c.warn("⚠") +
+              "  This composition carries a slideshow island — `render` captures only the first" +
+              " scene, so the MP4 will be truncated to slide 1. Use " +
+              c.accent("hyperframes present") +
+              " for the deck; a linear main-line MP4 export is not yet available.",
+          );
+          console.log("");
+        }
+      } catch {
+        /* best-effort — a missing/unreadable target surfaces later in the real flow */
+      }
+    }
+
     // ── Print render plan ─────────────────────────────────────────────────
     if (!quiet && !batchPath) {
       const workerLabel =
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index 81b947d5af..3b9606bdb3 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { defineCommand } from "citty";
 import { existsSync, mkdtempSync, readFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { resolve, join, relative, isAbsolute } from "node:path";
+import { resolve, join, relative, isAbsolute, basename } from "node:path";
 import { resolveProject } from "../utils/project.js";
 import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
 import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
@@ -94,7 +94,7 @@ export const examples: Example[] = [
  */
 async function captureSnapshots(
   projectDir: string,
-  opts: { frames?: number; timeout?: number; at?: number[] },
+  opts: { frames?: number; timeout?: number; at?: number[]; outputDir?: string },
 ): Promise<string[]> {
   const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
   const { ensureBrowser } = await import("../browser/manager.js");
@@ -176,26 +176,37 @@ async function captureSnapshots(
       // Extra settle time for media and animations to initialize
       await new Promise((r) => setTimeout(r, 1500));
 
-      // Font verification — report which fonts loaded vs fell back
+      // Font verification — split into loaded / errored / unused. Only status
+      // "error" is a real failure; a face still "unloaded"/"loading" after
+      // document.fonts.ready + the settle wait was simply never requested by any
+      // rendered text (an unused @font-face), so it is reported as "unused", not
+      // FAILED — printing it as FAILED alongside "loaded" read as a contradiction.
       const fontReport = await page
         .evaluate(() => {
           const loaded: string[] = [];
-          const failed: string[] = [];
+          const errored: string[] = [];
+          const unused: string[] = [];
           (document as any).fonts.forEach((f: any) => {
             const entry = `${f.family} (${f.weight} ${f.style})`;
             if (f.status === "loaded") loaded.push(entry);
-            else failed.push(entry + ` [${f.status}]`);
+            else if (f.status === "error") errored.push(entry);
+            else unused.push(entry);
           });
-          return { loaded, failed };
+          return { loaded, errored, unused };
         })
-        .catch(() => ({ loaded: [] as string[], failed: [] as string[] }));
-
-      if (fontReport.loaded.length > 0 || fontReport.failed.length > 0) {
-        console.log(
-          `\n   ${c.dim("Fonts loaded:")} ${fontReport.loaded.length > 0 ? fontReport.loaded.join(", ") : "none"}`,
-        );
-        if (fontReport.failed.length > 0) {
-          console.log(`   ${c.error("Fonts FAILED:")} ${fontReport.failed.join(", ")}`);
+        .catch(() => ({ loaded: [] as string[], errored: [] as string[], unused: [] as string[] }));
+
+      if (
+        fontReport.loaded.length > 0 ||
+        fontReport.errored.length > 0 ||
+        fontReport.unused.length > 0
+      ) {
+        const parts = [`${fontReport.loaded.length} loaded`];
+        if (fontReport.errored.length > 0) parts.push(`${fontReport.errored.length} failed`);
+        if (fontReport.unused.length > 0) parts.push(`${fontReport.unused.length} unused`);
+        console.log(`\n   ${c.dim("Fonts:")} ${parts.join(", ")}`);
+        if (fontReport.errored.length > 0) {
+          console.log(`   ${c.error("Fonts FAILED:")} ${fontReport.errored.join(", ")}`);
         }
       }
 
@@ -221,7 +232,7 @@ async function captureSnapshots(
           ? [duration / 2]
           : Array.from({ length: numFrames }, (_, i) => (i / (numFrames - 1)) * duration);
 
-      const snapshotDir = join(projectDir, "snapshots");
+      const snapshotDir = opts.outputDir ?? join(projectDir, "snapshots");
       mkdirSync(snapshotDir, { recursive: true });
       try {
         const { readdirSync } = await import("node:fs");
@@ -387,7 +398,8 @@ async function captureSnapshots(
         const framePath = join(snapshotDir, filename);
 
         await page.screenshot({ path: framePath, type: "png" });
-        savedPaths.push(`snapshots/${filename}`);
+        const rel = relative(projectDir, framePath);
+        savedPaths.push(rel.startsWith("..") || isAbsolute(rel) ? framePath : rel);
       }
     } finally {
       await chromeBrowser.close();
@@ -410,6 +422,11 @@ export default defineCommand({
       description: "Project directory",
       required: false,
     },
+    output: {
+      type: "string",
+      alias: "o",
+      description: "Directory to write snapshots into (default: <project>/snapshots)",
+    },
     frames: {
       type: "string",
       description: "Number of evenly-spaced frames to capture (default: 5)",
@@ -457,7 +474,15 @@ export default defineCommand({
     console.log(`${c.accent("◆")}  Capturing ${label} from ${c.accent(project.name)}`);
 
     try {
-      const paths = await captureSnapshots(project.dir, { frames, timeout, at: atTimestamps });
+      const snapshotDir = args.output
+        ? resolve(String(args.output))
+        : join(project.dir, "snapshots");
+      const paths = await captureSnapshots(project.dir, {
+        frames,
+        timeout,
+        at: atTimestamps,
+        outputDir: snapshotDir,
+      });
 
       if (paths.length === 0) {
         console.log(
@@ -466,7 +491,9 @@ export default defineCommand({
         process.exit(1);
       }
 
-      console.log(`\n${c.success("◇")}  ${paths.length} snapshots saved to snapshots/`);
+      console.log(
+        `\n${c.success("◇")}  ${paths.length} snapshots saved to ${args.output ? snapshotDir : "snapshots/"}`,
+      );
       for (const p of paths) {
         console.log(`   ${p}`);
       }
@@ -474,7 +501,6 @@ export default defineCommand({
       // Generate contact sheet for quick AI review
       try {
         const { createSnapshotContactSheet } = await import("../capture/contactSheet.js");
-        const snapshotDir = join(project.dir, "snapshots");
         const sheets = await createSnapshotContactSheet(
           snapshotDir,
           join(snapshotDir, "contact-sheet.jpg"),
@@ -501,8 +527,6 @@ export default defineCommand({
             const { GoogleGenAI } = await import("@google/genai");
             const ai = new GoogleGenAI({ apiKey: geminiKey });
             const model = process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";
-            const snapshotDir = join(project.dir, "snapshots");
-
             const customQuestion =
               describeArg === "true"
                 ? "Describe this video composition frame in 1-2 sentences. Be specific and factual: what elements are visible, what text appears, is the frame blank/black/loading, what is the composition. Flag any obvious problems."
@@ -533,7 +557,7 @@ export default defineCommand({
 
             const results = await Promise.allSettled(
               paths.map(async (p) => {
-                const filename = p.replace("snapshots/", "");
+                const filename = basename(p);
                 const filePath = join(snapshotDir, filename);
                 if (!existsSync(filePath)) return { filename, desc: "file not found" };
                 const raw = readFileSync(filePath);
diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.ts
index 28d589a0c8..a44796da07 100644
--- a/packages/cli/src/help.ts
+++ b/packages/cli/src/help.ts
@@ -33,6 +33,10 @@ const GROUPS: Group[] = [
     title: "Project",
     commands: [
       ["lint", "Validate a composition for common mistakes"],
+      [
+        "validate",
+        "Runtime-validate a composition in headless Chrome (JS errors, missing assets, contrast)",
+      ],
       ["beats", "Detect beats in the music track and write beats/<audio>.json"],
       ["inspect", "Inspect rendered visual layout across the timeline"],
       ["snapshot", "Capture key frames as PNG screenshots for visual verification"],
diff --git a/packages/lint/src/rules/fonts.test.ts b/packages/lint/src/rules/fonts.test.ts
index 853781bd74..964cecbf56 100644
--- a/packages/lint/src/rules/fonts.test.ts
+++ b/packages/lint/src/rules/fonts.test.ts
@@ -261,6 +261,16 @@ describe("font rules", () => {
       expect(findings).toHaveLength(0);
     });
 
+    it("does not flag vendor-prefixed system-font keywords (-apple-system, BlinkMacSystemFont)", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          body { font-family: -apple-system, BlinkMacSystemFont, system-ui, sans-serif; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
     it("does not flag installed registry blocks that declare fonts via Google Fonts", async () => {
       const html =
         `<!-- hyperframes-registry-item: my-block -->\n` +
diff --git a/packages/lint/src/rules/fonts.ts b/packages/lint/src/rules/fonts.ts
index a942704e6d..5ffdd22d7b 100644
--- a/packages/lint/src/rules/fonts.ts
+++ b/packages/lint/src/rules/fonts.ts
@@ -16,6 +16,12 @@ const GENERIC_FAMILIES = new Set([
   "math",
   "emoji",
   "fangsong",
+  // Vendor-prefixed system-font keywords. Like `system-ui`, the engine resolves
+  // these to the OS UI font — they are never installable files and must not be
+  // flagged as a missing @font-face, even when a generic fallback follows them
+  // (e.g. `-apple-system, system-ui, sans-serif`).
+  "-apple-system",
+  "blinkmacsystemfont",
   "inherit",
   "initial",
   "unset",