dsh-hyperframes 0.9.1 → 0.9.2

package/skills/embedded-captions/references/typographic-moves.md

@@ -1,266 +0,0 @@
-# Typographic moves — a palette, not a cage
-
-`cinematic-cream` template locks DNA only (font-family, motion, color
-palette defaults). It does NOT enforce slot structure. The agent writes
-each caption group's typography from scratch via the plan.json `css`
-field.
-
-This doc is a **palette** of tried combinations — pick what fits the
-scene, invent new ones, skip these if the content demands. These are
-recommendations, not rules.
-
-## Size vs text length — DO THIS BEFORE PICKING SIZE
-
-Bigger is NOT better if the word doesn't fit the frame width. Every time
-you pick a font-size, sanity-check against word length:
-
-**Rough rule for Inter 900 uppercase at -0.03em tracking:**
-`max_font_px ≈ frame_width / (longest_word_chars × 0.72)`
-
-The 0.72 multiplier is intentionally conservative — it targets the text
-filling ~90% of the frame width so there's a small side margin. If you
-want edge-to-edge, drop to 0.65, but you lose a bit of safety margin.
-
-720px portrait:
-
-- 3-char word (15%): max ~330px (a single big number like "15%")
-- 5-char word (TAKE): max ~200px
-- 7-char word (AUGMENT / QUANTUM / MATTERS): max ~143px
-- 10-char word (CREATIVITY): max ~100px
-- 13-char word (UNPRECEDENTED): max ~77px
-
-1920px landscape:
-
-- 7-char word: max ~380px
-- 10-char word: max ~267px
-
-For italic/upright 500-700 it's slightly narrower — increase max by ~10%.
-
-**If you want the word bigger than it fits:**
-
-- Split into multiple words per group (natural wrap), OR
-- Add explicit `<br>` between syllables, OR
-- Drop letter-spacing to -0.05em, OR
-- Accept that the matte will cut part of it (Vogue-cover embed effect —
-  only works when the cut area is exactly where the subject is)
-
-Never let the text OVERFLOW the frame edge — that's not cinematic, that's
-just broken. Use the heuristic.
-
-## Sizing discipline (frame-height-relative)
-
-Portrait 9:16 (720×1290) and landscape 16:9 (1920×1080) have very
-different comfort ranges. Use `calc(<pct> * var(--h))` for responsive:
-
-| Feel                   | % of frame height | Example calc            |
-| ---------------------- | ----------------- | ----------------------- |
-| Whisper / label        | 4-6%              | `calc(0.05 * var(--h))` |
-| Soft opener            | 6-9%              | `calc(0.07 * var(--h))` |
-| Narrative body         | 9-14%             | `calc(0.11 * var(--h))` |
-| Emphasis               | 14-22%            | `calc(0.18 * var(--h))` |
-| Climax / monumental    | 22-35%            | `calc(0.28 * var(--h))` |
-| Title-bigger-than-face | 40%+              | `calc(0.48 * var(--h))` |
-
-Use absolute px only when a specific scale needs to look identical
-across frame sizes (rare). Prefer `calc` + `var(--h)`.
-
-## Named moves — pick per group
-
-**Italic contemplative opener** (memory-wall cap-1 lineage):
-
-```css
-font-weight: 600;
-font-style: italic;
-letter-spacing: -0.01em;
-font-size: calc(0.075 * var(--h));
-```
-
-**Italic continuation / dreamier continuation** (cap-2 lineage):
-
-```css
-font-weight: 500;
-font-style: italic;
-letter-spacing: -0.005em;
-font-size: calc(0.065 * var(--h));
-```
-
-**Upright pivot / statement** (cap-3 lineage — "but suddenly"):
-
-```css
-font-weight: 700;
-letter-spacing: -0.015em;
-font-size: calc(0.07 * var(--h));
-```
-
-**Uppercase climax / monumental** (cap-4 lineage — "EVERYTHING IS SHARP AGAIN"):
-
-```css
-font-weight: 900;
-text-transform: uppercase;
-letter-spacing: -0.03em;
-line-height: 0.95;
-font-size: calc(0.18 * var(--h));
-```
-
-**Chapter card / full-frame Adam Curtis manifesto**:
-
-```css
-font-weight: 700;
-text-transform: uppercase;
-letter-spacing: -0.015em;
-line-height: 0.9;
-font-size: calc(0.14 * var(--h));
-```
-
-**News chyron / broadcast label** (small, locked):
-
-```css
-font-weight: 500;
-letter-spacing: 0.02em;
-font-size: calc(0.038 * var(--h));
-```
-
-**Tiny side note / caption-on-surface**:
-
-```css
-font-weight: 400;
-font-style: italic;
-font-size: calc(0.045 * var(--h));
-```
-
-**Vogue-masthead monumental**:
-
-```css
-font-weight: 900;
-text-transform: uppercase;
-letter-spacing: -0.04em;
-line-height: 0.85;
-font-size: calc(0.32 * var(--h));
-```
-
-## Narrative arcs (suggestions, not required)
-
-**Poem arc** — memory-wall canonical: italic opener → italic continuation
-→ upright pivot → uppercase climax. Four steps.
-
-**Question-answer arc**: italic question small → uppercase answer big.
-Two steps.
-
-**List-of-three arc**: three equal-weight narration segments, one
-climactic uppercase. Four steps.
-
-**Single-statement arc**: one monumental uppercase held long. One step.
-
-**Whisper-hook arc** (short-form): tiny italic hook → massive uppercase
-reveal. Two steps.
-
-The **number** of groups comes from the **content**. A 25s Pausch talk
-has ~8 beats. A 7s TikTok hook has 2-3 beats. Don't force 4 or 5 or 7 —
-read the transcript and mark breath-groups.
-
-## Position + layer vocabulary
-
-**Position** is where the caption lives in frame. Use:
-
-- `top / left / right / bottom` (percentages or px) for anchor
-- `transform: translateX/Y` for fine offsets
-- `text-align: center / left / right` for alignment
-
-**Layer** per group:
-
-- `bg` (default) — behind subject. Matte occludes. Cinematic embed. Works
-  on clean zones (sky, walls) OR intentionally crosses subject for the
-  Vogue-masthead effect.
-- `fg` — on top of subject. Announcement. Use for climax breakthroughs or
-  when bg would be 100% occluded by body.
-
-**Tone** per group:
-
-- `soft` — gentle per-word opacity+y drift (0.45s power2.out). Use for
-  introspective, dreamy, or narrative content.
-- `present` — snappy per-word opacity+y+scale pop (0.22s power3.out). Use
-  for emphatic or declarative beats.
-
-## Anti-patterns the DNA protects against
-
-The DNA defaults prevent most ugly outcomes. But avoid in per-group CSS:
-
-- Multiple different `font-family` within one video (DNA is one family)
-- Multiple saturated colors (one accent at most; DNA defaults cream or
-  deep warm)
-- `letter-spacing` above ±0.05em unless there's a specific reason
-- `font-weight` 300 or below — too light for screen
-- `font-style: italic` on emphasis — italic is for lyricism, not stress
-
-## When cinematic-cream is wrong
-
-This DNA assumes mid-to-dark backgrounds (luminance 60-180). For:
-
-- Bright white studios → cinematic-cream's cream + `screen` washes out, and the DNA is
-  **locked** (you cannot recolour it) → use **Standard mode** (opaque rail) instead
-- Documentary formal → Standard mode (documentary-dignified direction; see references/direction-catalog.md §1)
-- Energetic vlog hooks → future `kinetic-vlog` DNA (not yet shipped)
-
-## Example: memory-wall original, expressed in freeform
-
-Same output as the canonical memory-wall.html, but using slot-free plan:
-
-```json
-{
-  "template": "cinematic-cream",
-  "caption_layer": "bg",
-  "groups": [
-    {
-      "id": "cg-0",
-      "tone": "soft",
-      "in": 0.2,
-      "out": 4.85,
-      "css": "top: 14%; right: 6%; left: auto; text-align: right; font-size: calc(0.09 * var(--h)); font-weight: 600; font-style: italic; letter-spacing: -0.01em;",
-      "words": [
-        { "text": "Some", "start": 0.24, "end": 0.44 },
-        { "text": "memories", "start": 0.48, "end": 0.82 },
-        { "text": "feel", "start": 0.92, "end": 1.14 },
-        { "text": "soft", "start": 1.2, "end": 1.64 }
-      ]
-    },
-    {
-      "id": "cg-1",
-      "tone": "soft",
-      "in": 2.55,
-      "out": 4.85,
-      "css": "top: 26%; right: 10%; left: auto; text-align: right; font-size: calc(0.075 * var(--h)); font-weight: 500; font-style: italic;",
-      "words": [
-        { "text": "like", "start": 2.66, "end": 2.78 },
-        { "text": "old", "start": 2.88, "end": 3.02 },
-        { "text": "film", "start": 3.16, "end": 3.46 }
-      ]
-    },
-    {
-      "id": "cg-2",
-      "tone": "present",
-      "in": 4.9,
-      "out": 8.04,
-      "css": "top: 18%; right: 6%; left: auto; text-align: right; font-size: calc(0.085 * var(--h)); font-weight: 700;",
-      "words": [
-        { "text": "but", "start": 5.04, "end": 5.18 },
-        { "text": "suddenly", "start": 5.24, "end": 5.76 }
-      ]
-    },
-    {
-      "id": "cg-3",
-      "tone": "present",
-      "in": 6.7,
-      "out": 8.04,
-      "css": "top: 32%; right: 6%; left: auto; text-align: right; font-size: calc(0.11 * var(--h)); font-weight: 900; text-transform: uppercase; letter-spacing: -0.03em; line-height: 0.95;",
-      "words": [
-        { "text": "everything", "start": 6.82, "end": 7.14 },
-        { "text": "is", "start": 7.18, "end": 7.28 },
-        { "text": "sharp", "start": 7.32, "end": 7.52 },
-        { "text": "again", "start": 7.58, "end": 7.92 }
-      ]
-    }
-  ]
-}
-```
-
-Same visual, no slot constraint. Each group owns its typography.

package/skills/embedded-captions/references/typography-presets.md

@@ -1,63 +0,0 @@
-# Typography Presets
-
-Five named styles corresponding to the `cap-*` CSS classes. Pick one per caption group in `plan.json` based on the line's semantic role.
-
-| style    | CSS                         | Use when                                                                                                                  |
-| -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `intro`  | 66px italic 500             | First line, filler ("You know…", "So…"), contemplative openings. Low visual weight.                                       |
-| `phrase` | 78px upright 600            | Main statement clauses. Default for most lines.                                                                           |
-| `emph`   | 92px upright 800            | Lines with emotional peak or key achievement ("I've achieved incredible things").                                         |
-| `dream`  | 82px italic 700             | Aspirational / "was dreaming of…" style lines. Italic signals memory/imagination.                                         |
-| `crown`  | 140px upright 900 uppercase | **Only for the climax line.** Used in center-stage `crown-plane`. Maximum one per composition — ideally the last caption. |
-
-## Tone field
-
-Independent of style, each group has `tone`: `soft` or `present`.
-
-- **soft** — gentle fade + 8px y-drift entrance, `power2.out` ease. Feels floaty, nostalgic. Use for memory, intro, dream.
-- **present** — snappy 6px y + 1.04 scale pop, `power3.out`, transformOrigin center. Feels assertive, in-the-moment. Use for emphasis and crown.
-
-## Picking automatically
-
-Scan each group's words:
-
-1. Does it contain superlatives (incredible, best, only, never, always) or brand/proper nouns? → `emph` + `present`
-2. Does it start with discourse markers (you know, so, well, look) or is it short (≤3 words)? → `intro` + `soft`
-3. Does it reference dreams, hopes, memory, past tense verbs like "was dreaming"? → `dream` + `soft`
-4. Is it the final sentence-clinching line and feels like a title/headline? → `crown` + `present` (only one per video)
-5. Otherwise → `phrase` + (match the group's neighbors' tone; default `soft`)
-
-## Font-size scales with column width
-
-The `.cap-*` defaults in each template are tuned for a **~560px column** (the original champion composition). When the caption plane is wider than that, the fonts feel underweight — too much negative space around text. Scale up accordingly.
-
-| Plane width         | intro | phrase | emph | dream | crown (centered, full-frame) | crown (clean-zone only) |
-| ------------------- | ----- | ------ | ---- | ----- | ---------------------------- | ----------------------- |
-| 460-580 px (tight)  | 66    | 78     | 92   | 82    | 140                          | n/a                     |
-| 600-760 px (medium) | 78    | 108    | 128  | 100   | 220                          | 118                     |
-| 780+ px (wide)      | 90    | 128    | 150  | 116   | 260                          | 140                     |
-
-Notes:
-
-- Crown sizes assume landscape (1920×1080). For portrait 1080×1920, divide all crown sizes by 1.5.
-- "full-frame crown" = centered, designed to span `0.8+ × frame_width` and cross the subject's body. Use only when [layout-heuristics.md § Crown placement](layout-heuristics.md) conditions pass.
-- "clean-zone only crown" = crown positioned inside one clean zone, smaller font, tail letters lightly touch subject. Fallback when centered crown would eat too much.
-
-Also: if a plane's `rotateY` is non-trivial (say > 8°), effective visible width shrinks. Scale fonts up ~10% to compensate.
-
-## What NOT to do
-
-- Don't use more than **one crown** per render. The whole point is that it's a singular payoff.
-- Don't use `emph` on more than ~30% of groups. Emphasis loses meaning when everything is emphasized.
-- Don't pick `intro` for the main content just because the words are short. "I won" (2 words) is `emph` or `crown`, not `intro`.
-- Don't mix `soft` and `present` alternately for no reason. Tone should follow the story arc: soft opening → present build → emph peak → (optional crown climax).
-
-## When scene luminance affects color choice
-
-The default color is warm bone-white (`#fff5df`). Adjust in the template CSS:
-
-- Wall is mostly warm wood / tan → keep default, or shift cooler `#e8f0ff`
-- Wall is cool blue / tech-lab → push warmer `#fff0c0`
-- Wall has strong primary color → desaturate default, luminance first
-
-These adjustments happen in the HTML template, not plan.json. If you repeatedly need different palettes, make new template variants.

package/skills/embedded-captions/scripts/audio-envelope.cjs

@@ -1,95 +0,0 @@
-#!/usr/bin/env node
-/*
- * audio-envelope.cjs — extract a per-50ms RMS loudness envelope from the source audio.
- *
- *   node audio-envelope.cjs <project-dir>     → <project>/envelope.json
- *
- * { hop: 0.05, rms: [linear 0..1 per hop] }
- *
- * Used by lib-dna.cjs to couple the hero's entrance amplitude to how hard the word was
- * actually SPOKEN (percentile of the hero window's loudness within the clip). ffmpeg
- * astats over fixed windows — deterministic, no network, no Python.
- */
-const path = require("path");
-const fs = require("fs");
-const cp = require("child_process");
-
-const HOP = 0.05;
-
-function findSource(project) {
-  for (const c of ["source.mp4"].concat(
-    fs
-      .readdirSync(project)
-      .filter(
-        (f) =>
-          /\.(mp4|mov|webm|mkv|m4v|wav|m4a|mp3)$/i.test(f) &&
-          !/^(final|bg_plus_caps|fg_caps|rail|index)/.test(f),
-      ),
-  )) {
-    const p = path.join(project, c);
-    if (fs.existsSync(p)) return p;
-  }
-  return null;
-}
-
-function main() {
-  const project = path.resolve(process.argv[2] || "");
-  if (!process.argv[2]) {
-    console.error("usage: audio-envelope.cjs <project-dir>");
-    process.exit(1);
-  }
-  const src = findSource(project);
-  if (!src) {
-    console.error("[envelope] no source media found");
-    process.exit(2);
-  }
-
-  // asetnsamples groups audio into fixed windows; astats prints RMS per window
-  const sr = 16000,
-    n = Math.round(sr * HOP);
-  let out;
-  try {
-    // resample INSIDE the filter chain — an output-option -ar applies after the
-    // filtergraph, which would make each window n/<input-rate> seconds instead of HOP
-    out = cp.execFileSync(
-      "ffmpeg",
-      [
-        "-v",
-        "info",
-        "-i",
-        src,
-        "-map",
-        "a:0",
-        "-af",
-        `aresample=${sr},aformat=channel_layouts=mono,asetnsamples=n=${n}:p=0,astats=metadata=1:reset=1,ametadata=mode=print:key=lavfi.astats.Overall.RMS_level:file=-`,
-        "-f",
-        "null",
-        "-",
-      ],
-      { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] },
-    );
-  } catch (e) {
-    // ffmpeg writes the metadata to stdout before exiting; some containers still exit 0 — re-throw only if nothing parsed
-    out = (e.stdout || "") + "";
-    if (!out.includes("RMS_level")) {
-      console.error(`[envelope] ffmpeg failed: ${e.message}`);
-      process.exit(2);
-    }
-  }
-  const rmsDb = [];
-  for (const line of String(out).split("\n")) {
-    const m = line.match(/lavfi\.astats\.Overall\.RMS_level=(-?[\d.]+|-inf)/);
-    if (m) rmsDb.push(m[1] === "-inf" ? -90 : Math.max(-90, parseFloat(m[1])));
-  }
-  if (!rmsDb.length) {
-    console.error("[envelope] no RMS windows parsed");
-    process.exit(2);
-  }
-  const rms = rmsDb.map((db) => +Math.pow(10, db / 20).toFixed(5)); // linear 0..1
-  fs.writeFileSync(path.join(project, "envelope.json"), JSON.stringify({ hop: HOP, rms }));
-  const peakAt = rms.indexOf(Math.max(...rms)) * HOP;
-  console.log(
-    `[envelope] ${rms.length} windows @ ${HOP}s → envelope.json (loudest beat ~${peakAt.toFixed(2)}s)`,
-  );
-}
-main();

package/skills/embedded-captions/scripts/check-occlusion.cjs

@@ -1,253 +0,0 @@
-#!/usr/bin/env node
-/* check-occlusion.cjs — pixel-perfect occlusion gate (Node port of check-occlusion-v2.py).
- * Runs measure-layout.cjs (real Chromium DOM rects), reads the subject-matte alpha via sharp,
- * computes per-word / per-cap occlusion. No Python.
- *   node check-occlusion.cjs <project-dir> [--strict] [--word-fail F] [--word-warn F] [--cap-fail F] [--remeasure]
- */
-const path = require("path");
-const fs = require("fs");
-const os = require("os");
-const cp = require("child_process");
-
-function hfResolve(pkg) {
-  const roots = [
-    process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
-    process.env.HYPERFRAMES_ROOT,
-    path.resolve(__dirname, "..", "..", ".."),
-    path.join(os.homedir(), "Downloads", "hyperframes"),
-  ].filter(Boolean);
-  for (const root of roots) {
-    const cands = [path.join(root, "node_modules", pkg)];
-    const bun = path.join(root, "node_modules", ".bun");
-    try {
-      if (fs.existsSync(bun))
-        for (const d of fs.readdirSync(bun))
-          if (d.startsWith(pkg + "@")) cands.push(path.join(bun, d, "node_modules", pkg));
-    } catch {}
-    for (const c of cands) {
-      try {
-        if (fs.existsSync(c)) return require(c);
-      } catch {}
-    }
-  }
-  console.error(
-    `[v2] cannot find ${pkg} — install project dependencies per embedded-captions SKILL.md Runtime prerequisites`,
-  );
-  process.exit(3);
-}
-const sharp = hfResolve("sharp");
-
-function ensureLayoutMeasured(project, force) {
-  const lp = path.join(project, "_layout.json"),
-    idx = path.join(project, "index.html");
-  let stale = force || !fs.existsSync(lp);
-  if (!stale && fs.existsSync(idx) && fs.statSync(idx).mtimeMs > fs.statSync(lp).mtimeMs)
-    stale = true;
-  if (stale)
-    cp.execFileSync("node", [path.join(__dirname, "measure-layout.cjs"), project], {
-      stdio: "inherit",
-    });
-  return JSON.parse(fs.readFileSync(lp, "utf8"));
-}
-async function loadAlphaMask(png) {
-  if (!fs.existsSync(png)) return null;
-  const { data, info } = await sharp(png)
-    .ensureAlpha()
-    .extractChannel(3)
-    .raw()
-    .toBuffer({ resolveWithObject: true });
-  return { data, W: info.width, H: info.height };
-}
-function occlusionForRect(m, x, y, w, h) {
-  if (!m) return 0;
-  const x0 = Math.max(0, Math.round(x)),
-    y0 = Math.max(0, Math.round(y));
-  const x1 = Math.min(m.W, Math.round(x + w)),
-    y1 = Math.min(m.H, Math.round(y + h));
-  if (x1 <= x0 || y1 <= y0) return 0;
-  let cnt = 0,
-    tot = 0;
-  for (let yy = y0; yy < y1; yy++) {
-    const row = yy * m.W;
-    for (let xx = x0; xx < x1; xx++) {
-      tot++;
-      if (m.data[row + xx] > 128) cnt++;
-    }
-  }
-  return tot ? cnt / tot : 0;
-}
-function argf(name, d) {
-  const i = process.argv.indexOf(name);
-  return i >= 0 ? parseFloat(process.argv[i + 1]) : d;
-}
-
-async function main() {
-  const project = path.resolve(process.argv[2] || "");
-  if (!process.argv[2]) {
-    console.error("usage: check-occlusion.cjs <project-dir> [--strict]");
-    process.exit(1);
-  }
-  const strict = process.argv.includes("--strict");
-  const wordFail = argf("--word-fail", 0.65),
-    wordWarn = argf("--word-warn", 0.35),
-    capFail = argf("--cap-fail", 0.5);
-  const layout = ensureLayoutMeasured(project, process.argv.includes("--remeasure"));
-  const framesDir = path.join(project, "frames_fg");
-  if (!fs.existsSync(framesDir)) {
-    console.error(`[v2] missing ${framesDir}`);
-    process.exit(2);
-  }
-  const planPath = path.join(project, "plan.json");
-  const plan = fs.existsSync(planPath) ? JSON.parse(fs.readFileSync(planPath, "utf8")) : {};
-  const planLayer = plan.caption_layer || "bg";
-  // Hero groups (the ONE big promoted word) are SUPPOSED to sit ON the subject — for them
-  // occlusion is a TARGET (~30–55%), not "minimize". Collect their ids for the advisory below.
-  const heroIds = new Set();
-  const heroIn = {};
-  for (const g of plan.groups || [])
-    if (g && (g.hero === true || /^(hero|crown)$/i.test(g.plane || ""))) {
-      heroIds.add(g.id);
-      heroIn[g.id] = g.in;
-    }
-  if (plan.crown_group && plan.crown_group.id) {
-    heroIds.add(plan.crown_group.id);
-    heroIn[plan.crown_group.id] = plan.crown_group.in;
-  }
-  const M = 2; // frame-edge tolerance (px) — matches check-overflow.cjs
-  const frameW = layout.width,
-    frameH = layout.height;
-
-  const capStats = {};
-  for (const sample of layout.samples) {
-    const png = path.join(framesDir, `f_${String(sample.frame_idx).padStart(4, "0")}.png`);
-    const mask = await loadAlphaMask(png);
-    if (!mask) continue;
-    for (const cap of sample.caps) {
-      const entry = (capStats[cap.id] ||= { layer: cap.layer || planLayer, samples: [] });
-      const wordsData = [];
-      for (const w of cap.words || []) {
-        if ((w.opacity ?? 1) < 0.3) continue;
-        wordsData.push({ text: w.text, occlusion: occlusionForRect(mask, w.x, w.y, w.w, w.h) });
-        // Frame-edge overflow — clipped SETTLED text is always wrong; a hero's first
-        // 0.5s is its entrance TRANSIENT (slam over-scale, streak fly-in pass through
-        // off-frame states by design) — judge overflow on the hold, not mid-flight.
-        if (heroIds.has(cap.id) && heroIn[cap.id] != null && sample.t < heroIn[cap.id] + 0.5)
-          continue;
-        const off = {
-          left: Math.max(0, Math.round(-w.x - M)),
-          right: Math.max(0, Math.round(w.x + w.w - frameW - M)),
-          top: Math.max(0, Math.round(-w.y - M)),
-          bottom: Math.max(0, Math.round(w.y + w.h - frameH - M)),
-        };
-        const score = off.left + off.right + off.top + off.bottom;
-        if (score > 0 && (!entry.overflow || score > entry.overflow.score))
-          entry.overflow = { text: w.text, off, score, t: sample.t };
-      }
-      const capOccl = occlusionForRect(
-        mask,
-        cap.cap_bbox.x,
-        cap.cap_bbox.y,
-        cap.cap_bbox.w,
-        cap.cap_bbox.h,
-      );
-      entry.samples.push({
-        t: sample.t,
-        cap_occl: capOccl,
-        cap_bbox: cap.cap_bbox,
-        words: wordsData,
-      });
-    }
-  }
-
-  const failures = [];
-  console.log(
-    `[v2] ${path.basename(project)}  word-fail≥${(wordFail * 100).toFixed(0)}%  cap-fail≥${(capFail * 100).toFixed(0)}%`,
-  );
-  for (const [gid, entry] of Object.entries(capStats)) {
-    // Frame-edge overflow applies to every layer (fg too). The skill allows the
-    // climax a few-px graze on the first/last letter, so only a clear glyph clip
-    // (>8px past an edge) is a hard FAIL; a sub-glyph graze is a WARN.
-    if (entry.overflow) {
-      const o = entry.overflow;
-      const maxOff = Math.max(o.off.left, o.off.right, o.off.top, o.off.bottom);
-      const sides = Object.entries(o.off)
-        .filter(([, v]) => v > 0)
-        .map(([s, v]) => `${s} ${v}px`)
-        .join(", ");
-      const hard = maxOff >= 8;
-      console.log(
-        `  ${gid}  [overflow${hard ? "" : "-warn"}] "${o.text}" off-frame: ${sides} (@${o.t}s)` +
-          (hard ? " — cropped text is always wrong" : " (graze — within climax tolerance)"),
-      );
-      if (hard && !failures.includes(gid)) failures.push(gid);
-    }
-    if (entry.layer === "fg") {
-      console.log(`  ${gid}  fg    (occlusion skipped — fg renders above matte)`);
-      continue;
-    }
-    const capOccls = entry.samples.map((s) => s.cap_occl);
-    const avgCap = capOccls.length ? capOccls.reduce((a, b) => a + b, 0) / capOccls.length : 0;
-    const peakCap = capOccls.length ? Math.max(...capOccls) : 0;
-    const wordPeaks = {};
-    for (const s of entry.samples)
-      for (const wd of s.words)
-        wordPeaks[wd.text] = Math.max(wordPeaks[wd.text] || 0, wd.occlusion);
-    const oblit = Object.entries(wordPeaks).filter(([, p]) => p >= wordFail);
-    const warn = Object.entries(wordPeaks).filter(([, p]) => p >= wordWarn && p < wordFail);
-    let status = "OK";
-    // HERO caps WANT occlusion (~30–55% is the embed); the generic cap threshold would
-    // fail a working hero. Heroes fail only past the feasibility ceiling (68%).
-    const capLimit = heroIds.has(gid) ? Math.max(capFail, 0.68) : capFail;
-    if (oblit.length || peakCap >= capLimit) {
-      status = "FAIL";
-      failures.push(gid);
-    } else if (warn.length) status = "WARN";
-    let s = "";
-    if (oblit.length)
-      s =
-        oblit
-          .slice(0, 5)
-          .map(([t, p]) => `${t}(${(p * 100).toFixed(0)}%)`)
-          .join(" ") + (oblit.length > 5 ? ` …+${oblit.length - 5}` : "");
-    else if (warn.length)
-      s =
-        "[warn] " +
-        warn
-          .slice(0, 3)
-          .map(([t, p]) => `${t}(${(p * 100).toFixed(0)}%)`)
-          .join(" ");
-    console.log(
-      `  ${gid}  ${entry.layer}  avg ${(avgCap * 100).toFixed(0)}%  peak ${(peakCap * 100).toFixed(0)}%  ${status}  ${s}`,
-    );
-    // HERO target-occlusion advisory (not a failure): a hero should sit ON the subject
-    // (~30–55%). If it barely grazes, it reads as a small floating word, not an embed.
-    if (heroIds.has(gid) && peakCap < 0.15) {
-      // METRIC HONESTY: this advisory uses CAP-AREA occlusion, which saturates ~15%
-      // for a width-filled hero over a narrow subject (the 30–55% figure elsewhere is
-      // the safe-zones BAND metric — different denominator). If the hero already owns
-      // the width, "center it + make it BIG" is unactionable — stay quiet.
-      const widest = Math.max(...entry.samples.map((sm) => (sm.cap_bbox && sm.cap_bbox.w) || 0), 0);
-      if (widest >= frameW * 0.8) {
-        console.log(
-          `  ${gid}  [hero-ok] peak ${(peakCap * 100).toFixed(0)}% cap-area — width-saturated hero over a narrow subject; cap-area can't reach the band target (this is the geometry, not a layout fault).`,
-        );
-      } else {
-        console.log(
-          `  ${gid}  [hero-weak] peak ${(peakCap * 100).toFixed(0)}% — hero barely crosses the subject; it should sit ON the subject (~30–55% by the safe-zones BAND metric = the embed effect). Center it (safe-zones heroAnchor) + make it BIG; don't park it in a clean margin.`,
-        );
-      }
-    }
-  }
-  if (failures.length) {
-    const uniq = [...new Set(failures)];
-    console.error(`\n[v2] ${uniq.length} cap(s) FAIL: ${uniq.join(", ")}`);
-    console.error(
-      "  → occlusion: set that cap's layer to fg, OR shrink/reposition;  overflow: shrink/reposition (fg won't help)",
-    );
-  }
-  process.exit(strict && failures.length ? 2 : 0);
-}
-main().catch((e) => {
-  console.error("[v2]", e.message);
-  process.exit(1);
-});