@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/embedded-captions/scripts/make-cinematic.cjs

@@ -0,0 +1,1205 @@
+#!/usr/bin/env node
+/*
+ * make-cinematic.cjs — compile cinematic.json → plan.json (then make-composition.cjs).
+ * CINEMATIC MODE, raised to BLOCK level. The agent authors thought-BLOCKS — lines of
+ * words, which plane each block stacks in, at most one promoted HERO word — and the
+ * compiler lowers that into the classic plan.json with everything deterministic
+ * generated, so the Cinematic failure modes seen in the wild become impossible:
+ *   - READING ORDER by construction: lines stack in declaration order inside a flex
+ *     plane (spoken order = visual order; a hero can never sit below later words)
+ *   - timings from the transcript BY SEQUENCE (no hand-copied times; duplicates by position)
+ *   - accumulate-within-block / page-flip-between-blocks rhythm generated:
+ *     lines of a block share the block's out (they accumulate, then clear together
+ *     when the next block's first word lands); the NEXT block enters fresh
+ *   - hero hand-off: the promoted word is lifted OUT of its line, enters as the hero
+ *     (its own plane, BIG) when spoken, holds to the END of its block, exits cleanly
+ *   - fg fallback: safe-zones verdict "fg" → caption_layer:"fg" automatically
+ *
+ *   node make-cinematic.cjs <project-dir>
+ *
+ * cinematic.json schema:
+ * {
+ *   "template": "cinematic-cream",
+ *   "width": 1920, "height": 1080, "fps": 30,
+ *   "planes": {                       // layout REGIONS — place them using safe-zones.json
+ *     "narr": "top: 14%; left: 4%; width: 26%;",            // string or {css}
+ *     "hero": null                    // null/absent → auto from safe-zones heroAnchor
+ *   },
+ *   "blocks": [
+ *     { "plane": "narr", "lines": [
+ *         { "words": ["You","need","to"],        "css": "font-size: calc(0.05*var(--h)); font-weight:600;" },
+ *         { "words": ["judge","us","by","the"],  "css": "font-size: calc(0.062*var(--h)); font-weight:700;" },
+ *         { "words": ["actions"],                "hero": true,
+ *           "text": "ACTIONS", "css": "font-size: calc(0.24*var(--h)); font-weight:900; text-transform:uppercase;" },
+ *         { "words": ["that","we","take."],      "css": "font-size: calc(0.05*var(--h));" },
+ *         // per-line escape hatch: "layer":"fg" lifts a line ABOVE the subject matte
+ *         // (use when the occlusion gate reports a context line eaten by the subject)
+ *         { "words": ["over","the","subject"],     "layer": "fg" }
+ *       ] },
+ *     { "plane": "narr", "lines": [ ... next thought ... ] }
+ *   ],
+ *   "tones": { "default": "soft", "hero": "present" }       // optional
+ * }
+ * Rules: words must match the transcript verbatim in spoken order across all blocks.
+ * Mark at most ONE line "hero": true per clip (scarcity); its words form the hero
+ * (usually a single word; "text" overrides the display form).
+ */
+const path = require("path");
+const fs = require("fs");
+
+const norm = (s) =>
+  String(s == null ? "" : s)
+    .toLowerCase()
+    .replace(/[^a-z0-9']/g, "");
+const LOOKAHEAD = 40;
+
+// Authored css WITHOUT a font-size renders at browser-default ~16px (an
+// invisible ribbon) and every gate still passes — observed in the cold-start
+// E2E. Guarantee the default is present whenever the author omitted it.
+function ensureFontSize(css, defaultDecl) {
+  if (!css) return defaultDecl;
+  return /font-size\s*:/.test(css) ? css : defaultDecl + " " + css;
+}
+
+function die(m) {
+  console.error(`[make-cinematic] ${m}`);
+  process.exit(1);
+}
+
+function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) die("usage: make-cinematic.cjs <project-dir>");
+  const cj = path.join(project, "cinematic.json");
+  const tj = path.join(project, "transcript.json");
+  if (!fs.existsSync(cj)) die(`missing ${cj} — author it first (schema in this header)`);
+  if (!fs.existsSync(tj)) die(`missing ${tj} — run prepare.sh first`);
+  const C = JSON.parse(fs.readFileSync(cj, "utf8"));
+  const tr = (JSON.parse(fs.readFileSync(tj, "utf8")).words || []).filter(
+    (w) => w && "start" in w && "end" in w,
+  );
+  if (!tr.length) die("transcript has no word timings");
+
+  // safe-zones: fg verdict + heroAnchor default
+  let sz = null;
+  try {
+    sz = JSON.parse(fs.readFileSync(path.join(project, "safe-zones.json"), "utf8"));
+  } catch {}
+  // author override first (borderline scenes: coverage near the line, agitated subject),
+  // else the safe-zones verdict.
+  // narration legibility follows the verdict; the HERO is judged separately — it WANTS
+  // occlusion (~30–55% is the product). fg for the hero is the LAST resort: only when no
+  // height band achieves ≤62% predicted occlusion (safe-zones heroBands). An explicit
+  // author caption_layer:"fg" still forces everything front.
+  const authorFg = C.caption_layer === "fg";
+  const narrFg = authorFg || (sz && sz.recommendation === "fg");
+  const hb = sz && sz.heroBands;
+  const heroFeasible = authorFg ? false : hb ? hb.feasible : !narrFg;
+  const globalFg = narrFg; // narration layer (name kept for the lowering below)
+
+  const W = C.width || 1920,
+    H = C.height || 1080,
+    FPS = C.fps || 24;
+  const blocks = C.blocks || [];
+  if (!blocks.length) die("blocks is empty");
+
+  // ── sequence-match every word across blocks/lines ──────────────────────────
+  let p = 0;
+  const missing = [];
+  for (const b of blocks)
+    for (const ln of b.lines || []) {
+      ln._w = (ln.words || []).map((text) => {
+        const t = norm(text);
+        let f = -1;
+        for (let j = p; j < Math.min(tr.length, p + LOOKAHEAD); j++)
+          if (norm(tr[j].text) === t) {
+            f = j;
+            break;
+          }
+        if (f < 0) {
+          missing.push(text);
+          return { text, start: null, end: null };
+        }
+        p = f + 1;
+        return { text, start: tr[f].start, end: tr[f].end, ti: f };
+      });
+    }
+  if (missing.length)
+    die(
+      `words not in transcript (in order): ${missing.join(" ")} — lines must match the transcript verbatim`,
+    );
+
+  // COMPLETENESS GATE — verbatim is a hard rule, so enforce it at compile time: the
+  // sequence matcher's lookahead can silently SKIP transcript words the author forgot
+  // (a real case shipped missing "in our newly released model."). Every transcript word
+  // must be consumed; the only legitimate drops are filler (um/uh/stutters), declared in
+  // cinematic.json "drops": ["um", ...].
+  {
+    const consumed = new Set();
+    for (const b of blocks)
+      for (const ln of b.lines || []) for (const w of ln._w) if (w.ti != null) consumed.add(w.ti);
+    const dropOk = new Set((C.drops || []).map(norm));
+    const FILLER = new Set(["um", "uh", "er", "ah", "hmm", "mm"]);
+    const skipped = tr
+      .map((w, i) => ({ w, i }))
+      .filter(
+        ({ w, i }) => !consumed.has(i) && !dropOk.has(norm(w.text)) && !FILLER.has(norm(w.text)),
+      );
+    if (skipped.length)
+      die(
+        `VERBATIM VIOLATION — ${skipped.length} transcript word(s) never authored (the matcher skipped them): ` +
+          `${skipped.map(({ w }) => `"${w.text}"`).join(" ")} — add them to a line, or declare true filler in "drops": []`,
+      );
+  }
+
+  // text override + multiple words double-renders (override replaces word 1, words
+  // 2..n still draw) — caught cold by a clean-room agent; illegal for ANY hero line.
+  for (const b of blocks)
+    for (const ln of b.lines || []) {
+      if (ln.hero && ln.text && (ln.words || []).length > 1)
+        die(
+          `hero line ["${(ln.words || []).join('" "')}"] has BOTH multiple words and a "text" override — drop "text" (words render verbatim; DNA case applies) or promote a single word.`,
+        );
+    }
+
+  // ── block windows: in = first word −lead; out = page-flip = next block's first word −0.28 (or +1.2 hold) ──
+  const LEAD = 0.18;
+  const bw = blocks.map((b) => {
+    const ws = (b.lines || []).flatMap((l) => l._w);
+    return { first: Math.min(...ws.map((w) => w.start)), last: Math.max(...ws.map((w) => w.end)) };
+  });
+  let srcDur = null;
+  try {
+    const cp = require("child_process");
+    for (const f of ["source.mp4"].concat(
+      fs.readdirSync(project).filter((x) => /\.(mp4|mov|webm)$/i.test(x)),
+    )) {
+      const fp = path.join(project, f);
+      if (!fs.existsSync(fp)) continue;
+      const d = parseFloat(
+        cp.execFileSync(
+          "ffprobe",
+          [
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration",
+            "-of",
+            "default=nokey=1:noprint_wrappers=1",
+            fp,
+          ],
+          { encoding: "utf8" },
+        ),
+      );
+      if (d > 0) {
+        srcDur = d;
+        break;
+      }
+    }
+  } catch {}
+  const DUR = +(srcDur || bw[bw.length - 1].last + 0.6).toFixed(3);
+  // ── SLOT layout + paging. Lines get FIXED absolute positions (no flex reflow — the
+  // "lower line jumps up when the upper one clears" bug is impossible by construction).
+  // Lines accumulate down the plane like a poem; the plane PAGE-FLIPS (all visible lines
+  // clear together, the next line restarts at the top) only when (a) the plane is full,
+  // (b) a block sets "flip": true, or (c) a block boundary coincides with a real speech
+  // pause (≥0.6s). Block windows (bw) are kept only for the hero's hold.
+  for (let i = 0; i < bw.length; i++) {
+    bw[i].in = Math.max(0, bw[i].first - LEAD);
+    bw[i].out = Math.min(DUR - 0.05, Math.min(bw[i].last, DUR - 0.05) + 0.9);
+    // a block's hold (incl. a LOCKUP's) yields to the NEXT block's entrance — the same
+    // page-flip semantics columns already have; floor: its own words must finish
+    if (i + 1 < bw.length)
+      bw[i].out = Math.max(
+        Math.min(bw[i].last, DUR - 0.05) + 0.15,
+        Math.min(bw[i].out, bw[i + 1].first - 0.28),
+      );
+  }
+  const fracOfLine = (css) => {
+    const m = (css || "").match(/font-size\s*:\s*calc\(\s*([\d.]+)\s*\*\s*var\(--h\)/);
+    return m ? +m[1] : 0.05;
+  };
+  const planeBudgetPx = (pk) => {
+    const css =
+      (C.planes &&
+        C.planes[pk] &&
+        (typeof C.planes[pk] === "string" ? C.planes[pk] : C.planes[pk].css)) ||
+      "";
+    const m = css.match(/height\s*:\s*([\d.]+)%/);
+    return (m ? +m[1] / 100 : 0.3) * H;
+  };
+
+  // ── planes: agent's + auto LOCKUP planes (one per hero block) ───────────────
+  // The LOCKUP is the layout answer to "the sentence reads broken around the hero":
+  // a hero block's lines do NOT scatter into the narration column — kicker, HERO and
+  // tail compose as ONE bonded ORBIT (context anchored at the hero's edges, diagonal
+  // read). DEPTH: context EMBEDS (bg) with the hero — one shared depth; per-line
+  // `layer:"fg"` is the escape hatch when the matte eats a context line (gate tells you).
+  const planes = {};
+  for (const [k, v] of Object.entries(C.planes || {})) {
+    if (v == null) continue;
+    let css = typeof v === "string" ? v : v.css || "";
+    if (!/text-align\s*:/.test(css)) css += " text-align:center;"; // slot children are absolute; only alignment carries
+    planes[k] = { css };
+  }
+  // multiple heroes allowed — scarcity is per BLOCK (≤1 per thought), not per clip.
+  // The LARGEST authored hero is the APEX: it gets the full lockup embed (centered on
+  // the subject, matte showcase). Smaller heroes are MINOR peaks: they stay IN their
+  // column's flow as oversized emphasis lines (fg, hero motion at reduced amplitude) —
+  // not every beat needs the matte showcase; that's what keeps the apex an event.
+  const allHeroBlocks = [];
+  blocks.forEach((b, bi) => {
+    const hs = (b.lines || []).filter((l) => l.hero === true);
+    if (hs.length > 1)
+      die(
+        `block ${bi} has ${hs.length} hero lines — at most ONE hero per block (scarcity = per beat)`,
+      );
+    if (hs.length === 1)
+      allHeroBlocks.push({ b, bi, ln: hs[0], frac: fracOfLine(hs[0].css) || 0.24 });
+  });
+  const apexFracAll = Math.max(...allHeroBlocks.map((h) => h.frac), 0);
+  // placement: "column" keeps even an APEX in its column's flow (the hero bursts the
+  // column instead of crossing the subject) — the sanctioned alternative to the
+  // subject-anchored lockup. Author it per hero line: { "hero": true, "placement": "column" }.
+  const heroBlocks = allHeroBlocks.filter(
+    (h) => h.frac >= apexFracAll - 1e-6 && (h.ln.placement || "subject") !== "column",
+  );
+  const minorHeroBis = new Set(
+    allHeroBlocks
+      .filter((h) => h.frac < apexFracAll - 1e-6 || (h.ln.placement || "subject") === "column")
+      .map((h) => h.bi),
+  );
+  const columnApexBis = new Set(
+    allHeroBlocks
+      .filter((h) => h.frac >= apexFracAll - 1e-6 && (h.ln.placement || "subject") === "column")
+      .map((h) => h.bi),
+  );
+  if (minorHeroBis.size)
+    console.log(
+      `[make-cinematic] ${minorHeroBis.size} minor hero(es) stay in the column flow (apex gets the lockup embed)`,
+    );
+  const lockupName = (bi) => `lockup-b${bi}`;
+  const lockupTemplate =
+    C.planes && C.planes.lockup
+      ? typeof C.planes.lockup === "string"
+        ? C.planes.lockup
+        : C.planes.lockup.css
+      : null;
+  delete planes.lockup; // template only — not a real plane
+  for (const hRef of heroBlocks) {
+    const a = sz && sz.heroAnchor && sz.heroAnchor.plane;
+    // band pick: target ~40% occlusion AND a band the DNA's text can survive on
+    // (skip bright bands when luma data exists) — heroAnchor.yPct is the fallback
+    let heroTop = a ? a.yPct : 30;
+    if (hb && hb.profile && hb.profile.length) {
+      const ok = hb.profile.filter(
+        (b2) => b2.occPct >= 12 && b2.occPct <= 62 && (b2.bgLuma == null || b2.bgLuma <= 165),
+      );
+      const pool = ok.length ? ok : hb.profile;
+      const best = pool.reduce((x, y) =>
+        Math.abs(y.occPct - 40) < Math.abs(x.occPct - 40) ? y : x,
+      );
+      heroTop = +(best.topPct + 6.5).toFixed(1);
+    }
+    const heroFrac = (hRef.ln.css || "").match(/calc\(\s*([\d.]+)\s*\*\s*var\(--h\)/);
+    // the lockup is taller than the hero alone (context above+below) — anchor so the
+    // HERO band (not the plane top) lands on the target, then clamp so the WHOLE
+    // lockup (pre + hero + post) stays on frame
+    const heroIdx2 = (hRef.b.lines || []).indexOf(hRef.ln);
+    const preH = (hRef.b.lines || [])
+      .filter((l, i) => l !== hRef.ln && i < heroIdx2)
+      .reduce(
+        (s, l) =>
+          s + (fracOfLine(l.css) * 100 * 1.32 + Math.max(1.6, fracOfLine(l.css) * 100 * 0.38)),
+        0,
+      );
+    const postH = (hRef.b.lines || [])
+      .filter((l, i) => l !== hRef.ln && i > heroIdx2)
+      .reduce(
+        (s, l) =>
+          s + (fracOfLine(l.css) * 100 * 1.32 + Math.max(1.6, fracOfLine(l.css) * 100 * 0.38)),
+        0,
+      );
+    const heroHpct = (heroFrac ? +heroFrac[1] : 0.24) * 100 * 1.12;
+    const totalH = preH + heroHpct + postH;
+    let top = +Math.max(2, Math.min(96 - totalH, heroTop - heroHpct / 2 - preH)).toFixed(1);
+    const css = lockupTemplate
+      ? lockupTemplate.replace(/top:\s*[\d.]+%/, `top: ${top}%`)
+      : a
+        ? `top: ${top}%; left: ${a.xPct}%; width: ${a.wPct}%; text-align: center;`
+        : `top: ${top}%; left: 6%; width: 88%; text-align: center;`;
+    planes[lockupName(hRef.bi)] = { css };
+    hRef.plane = lockupName(hRef.bi);
+  }
+  // legacy alias: an author-defined "hero" plane positions the FIRST lockup
+  if (planes.hero) {
+    if (heroBlocks.length) {
+      planes[lockupName(heroBlocks[0].bi)] = planes.hero;
+    }
+    delete planes.hero;
+  }
+
+  // ── PER-PLANE LEGIBILITY COMPENSATION ────────────────────────────────────
+  // The DNA fixes hue + blend; the SCENE decides whether that survives. Match each
+  // plane to its best-overlapping measured zone and ladder the treatment:
+  //   luma > 150 → opaque (blend:normal) + strong tight scrim — screen/blend washes out
+  //   luma 95–150 → keep the DNA blend, strengthen the glyph scrim
+  const planeComp = {};
+  if (sz && sz.zones) {
+    const zlist = Object.entries(sz.zones).filter(([, z]) => z && z.meanLuma != null);
+    for (const [pk, pv] of Object.entries(C.planes || {})) {
+      const css0 = typeof pv === "string" ? pv : (pv || {}).css || "";
+      const lm = css0.match(/left:\s*([\d.]+)%/),
+        wm = css0.match(/width:\s*([\d.]+)%/);
+      if (!lm || !wm) continue;
+      const a0 = +lm[1],
+        a1 = a0 + +wm[1];
+      let best = null,
+        bestOv = 0;
+      for (const [, z] of zlist) {
+        const ov = Math.min(a1, z.xPct + z.wPct) - Math.max(a0, z.xPct);
+        if (ov > bestOv) {
+          bestOv = ov;
+          best = z;
+        }
+      }
+      if (!best) continue;
+      // gate on the time PEAK too — a dark wall swept by a bright moving object
+      // (handheld drift, screens) averages "clean" but peaks hot, and text there
+      // washes out exactly when the bright thing passes (real cold-start case)
+      const pkL = best.peakLuma != null ? best.peakLuma : best.meanLuma;
+      if (best.meanLuma > 150 || pkL > 175)
+        planeComp[pk] =
+          " mix-blend-mode: normal; text-shadow: 0 1px 6px rgba(0,0,0,.65), 0 2px 16px rgba(0,0,0,.4);";
+      else if (best.meanLuma > 95 || pkL > 135)
+        planeComp[pk] = " text-shadow: 0 1px 5px rgba(0,0,0,.6), 0 2px 14px rgba(0,0,0,.35);";
+      if (planeComp[pk])
+        console.log(
+          `[make-cinematic] plane "${pk}" zone luma ${best.meanLuma} (peak ${pkL}) → legibility compensation (${best.meanLuma > 150 || pkL > 175 ? "opaque+scrim" : "scrim"})`,
+        );
+    }
+  }
+  // lockup context shares the hero band's luma
+  const bandLuma = sz && sz.heroAnchor && sz.heroAnchor.bandLuma;
+  const lockupComp =
+    bandLuma != null && bandLuma > 150
+      ? " mix-blend-mode: normal; text-shadow: 0 1px 6px rgba(0,0,0,.65), 0 2px 16px rgba(0,0,0,.4);"
+      : bandLuma != null && bandLuma > 95
+        ? " text-shadow: 0 1px 5px rgba(0,0,0,.6), 0 2px 14px rgba(0,0,0,.35);"
+        : "";
+
+  // ── lower to classic plan.json groups (slot layout + per-plane paging) ─────
+  const tones = C.tones || {};
+  let dnaBodyLayer = null;
+  try {
+    const dnaLib0 = require("./lib-dna.cjs");
+    const dn0 = C.dna || (C.template ? dnaLib0.LEGACY[C.template] : "cream");
+    if (dn0) {
+      const d0 = dnaLib0.load(dn0);
+      dnaBodyLayer = d0.bodyLayer || null;
+      // category lock (symmetric): column is every classic DNA's home today,
+      // so this only fires if a future DNA declares a different home.
+      if (d0.deliveries && d0.deliveries.home && d0.deliveries.home !== "column")
+        console.warn(
+          `[make-cinematic] WARN: DNA "${dn0}" declares home="${d0.deliveries.home}" — cinematic use is cross-category and unvalidated.`,
+        );
+    }
+  } catch (e) {
+    if (e.message && e.message.includes("does not support")) throw e;
+  }
+  const groups = [];
+  const heroRefs = heroBlocks; // [{b, bi, ln, plane}]
+  const isHeroBlock = new Set(heroBlocks.map((h) => h.bi));
+  const flat = [];
+  blocks.forEach((b, bi) => {
+    const heroIdx = isHeroBlock.has(bi) ? (b.lines || []).findIndex((l) => l.hero === true) : -1;
+    (b.lines || []).forEach((ln, li) => {
+      if (ln.hero === true && isHeroBlock.has(bi)) return; // APEX heroes slot into their lockup below
+      flat.push({
+        b,
+        bi,
+        ln,
+        plane: heroIdx >= 0 ? lockupName(bi) : b.plane,
+        lockupPos: heroIdx >= 0 ? (li < heroIdx ? "pre" : "post") : null,
+        isMinorHero: ln.hero === true && minorHeroBis.has(bi), // minor peak rides its column
+        first: Math.min(...ln._w.map((w) => w.start)),
+        lastEnd: Math.min(Math.max(...ln._w.map((w) => w.end)), DUR - 0.05),
+        frac: fracOfLine(ln.css),
+      });
+    });
+  });
+  // size sanity: narration below 0.05·h is whisper-tier (36px at 720p) — warn loudly
+  {
+    const tiny = flat.filter((l) => !l.isMinorHero && l.frac > 0 && l.frac < 0.05);
+    if (tiny.length)
+      console.log(
+        `[make-cinematic] ⚠ ${tiny.length} narration line(s) authored below 0.05·h (whisper tier) — body narration wants 0.055–0.07·h: ${tiny
+          .slice(0, 3)
+          .map((l) => `"${l.ln.words.slice(0, 3).join(" ")}…"`)
+          .join(" ")}`,
+      );
+  }
+  // RATIO LOCK — poster lockup typography: context is sized FROM the hero, the way a
+  // title system locks its eyebrow/tagline (kicker & tail ≈ 0.26× the hero height,
+  // clamped to [0.05, 0.085]·h). Hero dominance is structural (~4× height + weight
+  // contrast), so the old mass-rule downscale is gone — whisper-small context was the
+  // disease, not the cure. Too MUCH context is a line-count problem, never a size one.
+  for (const hRef of heroRefs) {
+    const ctx = flat.filter((l) => l.bi === hRef.bi);
+    if (!ctx.length) continue;
+    const heroFracV = fracOfLine(hRef.ln.css || "") || 0.24;
+    const ratioFrac = +Math.min(0.085, Math.max(0.05, heroFracV * 0.26)).toFixed(4);
+    if (ctx.length > 3)
+      console.log(
+        `[make-cinematic] ⚠ lockup-b${hRef.bi} has ${ctx.length} context lines — a lockup wants kicker + hero + tail; move narration to the column (a leading clause can be its own block)`,
+      );
+    const moved = ctx.filter((l) => Math.abs(l.frac - ratioFrac) > 0.002).length;
+    ctx.forEach((l) => {
+      l.ln.css = (l.ln.css || "").replace(
+        /font-size\s*:\s*[^;]+/,
+        `font-size: calc(${ratioFrac} * var(--h))`,
+      );
+      l.frac = ratioFrac;
+    });
+    if (moved)
+      console.log(
+        `[make-cinematic] lockup-b${hRef.bi}: context RATIO-LOCKED to 0.26×hero → ${ratioFrac}·h (${moved} line(s) re-sized)`,
+      );
+  }
+  const byPlane = {};
+  flat.forEach((l) => {
+    (byPlane[l.plane] = byPlane[l.plane] || []).push(l);
+  });
+  // make sure a lockup whose block has NO context lines still exists in the loop
+  for (const hRef of heroRefs) if (!byPlane[hRef.plane]) byPlane[hRef.plane] = [];
+  for (const [pk, ls] of Object.entries(byPlane)) {
+    const isLockup = /^lockup-b/.test(pk);
+    const budget = isLockup ? H : planeBudgetPx(pk); // a lockup is ONE composition — never paginate inside it
+    const hRef = isLockup ? heroRefs.find((h) => h.plane === pk) : null;
+    const heroH = hRef ? (fracOfLine(hRef.ln.css || "") || 0.24) * H * 1.12 + 12 : 0;
+    // ORBIT estimate: where do the hero's left/right edges land inside the (frame-wide,
+    // centered) lockup plane — kicker hangs off the left edge, tail off the right
+    let orbit = null;
+    if (hRef) {
+      const disp = String(hRef.ln.text || (hRef.ln.words || []).join(" "));
+      const fpx = (fracOfLine(hRef.ln.css || "") || 0.24) * H;
+      const estW = Math.min(
+        W * 0.94,
+        Math.max(fpx * 1.2, disp.replace(/\s/g, "").length * fpx * 0.6),
+      );
+      const planeCss0 = (planes[pk] && planes[pk].css) || "";
+      const _pl = ((planeCss0.match(/left:\s*([\d.]+)%/) || [0, 0])[1] * W) / 100;
+      const pw = ((planeCss0.match(/width:\s*([\d.]+)%/) || [0, 100])[1] * W) / 100;
+      const heroLeft = Math.max(0, (pw - estW) / 2);
+      // side-aware: anchor context to the CLEANER side of THIS hero's window — the
+      // kicker/tail must land on scene, not on a large/moving subject
+      let side = (sz && sz.subject && sz.subject.clearerSide) || "left";
+      try {
+        const hin = Math.min(...hRef.ln._w.map((w) => w.start));
+        const win = (sz.windows || []).find((w2) => hin >= w2.in - 0.3 && hin <= w2.out + 0.3);
+        if (win && win.clearerSide) side = win.clearerSide;
+      } catch {}
+      orbit = {
+        left: Math.round(heroLeft),
+        right: Math.round(Math.max(0, pw - heroLeft - estW)),
+        maxW: Math.round(Math.min(estW * 0.75, pw * 0.55)),
+        side,
+      };
+    }
+    const pages = [];
+    let page = [],
+      slot = 0;
+    for (const l of ls) {
+      // the HERO occupies its slot between pre- and post-context, in spoken order
+      if (hRef && hRef.slotPx == null && l.lockupPos === "post") {
+        hRef.slotPx = Math.round(slot);
+        slot += heroH;
+      }
+      const lineH = l.frac * H * 1.32 + Math.max(12, Math.round(l.frac * H * 0.38)); // ink overflows the 1.0 line-box (+shadows) — breathe in proportion to the type
+      const prev = page[page.length - 1];
+      const pauseGap = prev ? l.first - prev.lastEnd : 0;
+      const boundary = prev && l.bi !== prev.bi;
+      // a block carrying a COLUMN-PLACED apex is one composition — never split it on
+      // budget (the oversized hero legitimately exceeds the column's page height)
+      const unbreakable = columnApexBis.has(l.bi) && prev && prev.bi === l.bi;
+      if (
+        page.length &&
+        !unbreakable &&
+        (slot + lineH > budget || (boundary && l.b.flip === true) || (boundary && pauseGap >= 0.6))
+      ) {
+        pages.push(page);
+        page = [];
+        slot = 0;
+      }
+      l.slotPx = Math.round(slot);
+      if (isLockup) l._orbit = orbit;
+      slot += lineH;
+      page.push(l);
+    }
+    if (hRef && hRef.slotPx == null) {
+      hRef.slotPx = Math.round(slot);
+    } // hero is the block's last line
+    if (page.length) pages.push(page);
+    pages.forEach((pg, pi) => {
+      const nextFirst = pi + 1 < pages.length ? pages[pi + 1][0].first : null;
+      const maxEnd = Math.max(...pg.map((l) => l.lastEnd));
+      let out =
+        nextFirst != null
+          ? Math.max(maxEnd + 0.01, Math.min(DUR - 0.05, nextFirst - 0.28))
+          : Math.min(DUR - 0.05, maxEnd + 1.2);
+      // THE LOCKUP OWNS THE FRAME: a sidebar page must not linger into an apex
+      // lockup's window (its kicker/tail can land in the same zone → text-on-text)
+      if (!isLockup)
+        for (const hRef2 of heroRefs) {
+          const lkIn = bw[hRef2.bi].first - 0.18;
+          if (lkIn > maxEnd - 0.2 && lkIn < out)
+            out = Math.max(maxEnd + 0.01, Math.min(out, lkIn - 0.28));
+        }
+      pg.forEach((l, li) => {
+        l.pageIdx = pi;
+        if (!isLockup)
+          for (const hRef2 of heroRefs) {
+            const lkOut = bw[hRef2.bi].out;
+            const lkIn2 = bw[hRef2.bi].first - 0.18;
+            const enter0 = Math.max(0, l.first - LEAD);
+            if (enter0 > lkIn2 && enter0 < lkOut)
+              l._delayIn = +Math.min(l.first, Math.max(enter0, lkOut - 0.2)).toFixed(3);
+          }
+        // a LOCKUP fades as ONE unit: context lines exit with the hero (block window),
+        // never linger on page timing after the hero has left
+        l.out = l.lockupPos ? +Math.min(out, bw[l.bi].out).toFixed(3) : +out.toFixed(3);
+        l.in = l._delayIn != null ? l._delayIn : +Math.max(0, l.first - LEAD).toFixed(3);
+        // first line of a NEW page: don't enter before the old page has begun clearing
+        if (li === 0 && pi > 0)
+          l.in = +Math.min(l.first, Math.max(l.first - LEAD, pages[pi - 1][0].out - 0.02)).toFixed(
+            3,
+          );
+      });
+    });
+  }
+  let gid = 0;
+  for (const l of flat) {
+    l.gid = l.isMinorHero ? `h-${l.bi}` : `b${l.bi}-l${gid++}`;
+    // depth model: lockup CONTEXT embeds (bg) WITH the hero — the orbit anchors it
+    // beside the head/shoulder so it reads on the scene, one shared depth; narration
+    // columns embed too unless the DNA declares bodyLayer:"fg" (loud's announce-style).
+    // Minor heroes ride their column in FRONT. Per-line layer overrides any default.
+    // ORBIT depth: lockup context lands BESIDE the subject (kicker/tail at the hero's
+    // edges) — so it EMBEDS (bg) like the hero; the whole composition shares one depth.
+    // fg remains for: minor heroes (column emphasis), a DNA's bodyLayer (loud announces),
+    // scene verdict FG (globalFg), and explicit per-line "layer" overrides.
+    const defLayer = l.isMinorHero ? "fg" : dnaBodyLayer || "bg";
+    groups.push({
+      id: l.gid,
+      plane: l.plane,
+      layer: globalFg ? "fg" : l.ln.layer || l.b.layer || defLayer,
+      ...(l.isMinorHero ? { hero: true, ...(columnApexBis.has(l.bi) ? {} : { minor: true }) } : {}),
+      tone: l.isMinorHero ? tones.hero || "present" : l.ln.tone || tones.default || "soft",
+      allow_overlap: true,
+      // a MINOR hero holds only to the end of ITS thought (+a breath) — lingering with
+      // the page through a long pause leaves it co-visible with the next apex
+      in: l.in,
+      out: l.isMinorHero ? +Math.min(l.out, bw[l.bi].out + 0.3).toFixed(3) : l.out,
+      // carry the PLANE's text-align onto each slotted line (absolute children don't
+      // reliably inherit through the template's .cap centering — authored "right edge
+      // hugs the silhouette" was silently centered)
+      css:
+        (l.lockupPos && l._orbit
+          ? (l.ln.anchor || (l.lockupPos === "pre" ? l._orbit.side : l._orbit.side)) === "left"
+            ? `position:absolute;top:${l.slotPx}px;left:${l._orbit.left}px;right:auto;max-width:${l._orbit.maxW}px;text-align:left; `
+            : `position:absolute;top:${l.slotPx}px;right:${l._orbit.right}px;left:auto;max-width:${l._orbit.maxW}px;text-align:right; `
+          : `position:absolute;left:0;right:0;top:${l.slotPx}px; ` +
+            (() => {
+              const pc =
+                (C.planes &&
+                  C.planes[l.plane] &&
+                  (typeof C.planes[l.plane] === "string"
+                    ? C.planes[l.plane]
+                    : C.planes[l.plane].css)) ||
+                "";
+              const ta = pc.match(/text-align\s*:\s*(left|right|center)/);
+              return ta ? `text-align:${ta[1]}; ` : "";
+            })()) +
+        ensureFontSize(l.ln.css, "font-size: calc(0.05 * var(--h)); font-weight: 600;") +
+        (l.lockupPos ? lockupComp : planeComp[l.plane] || ""),
+      words: l.ln._w.map((w, wi2) => ({
+        // minor/column heroes honor the display-form override too (single-word lines)
+        text: l.isMinorHero && l.ln.text && wi2 === 0 && l.ln._w.length === 1 ? l.ln.text : w.text,
+        start: w.start,
+        end: Math.min(w.end, DUR - 0.05),
+        ti: w.ti,
+      })),
+    });
+  }
+  for (const hRef of heroRefs) {
+    const { bi, ln } = hRef;
+    const w0 = ln._w[0];
+    groups.push({
+      id: `h-${bi}`,
+      hero: true,
+      plane: hRef.plane,
+      layer: ln.layer || (heroFeasible ? "bg" : "fg"),
+      tone: tones.hero || "present",
+      allow_overlap: true,
+      in: +Math.max(0, w0.start - 0.02).toFixed(3),
+      out: +bw[bi].out.toFixed(3),
+      css:
+        `position:absolute;left:0;right:0;top:${hRef.slotPx || 0}px; text-align:center; ` +
+        ensureFontSize(
+          ln.css,
+          "font-size: calc(0.24 * var(--h)); font-weight: 900; white-space: nowrap;",
+        ), // case/tracking come from the DNA's hero treatment
+      words: ln._w.map((w, i) => ({
+        text: i === 0 && ln.text ? ln.text : w.text,
+        start: w.start,
+        end: Math.min(w.end, DUR - 0.05),
+        ti: w.ti,
+      })),
+    });
+    if (!heroFeasible)
+      console.log(
+        "[make-cinematic] no hero band ≤62% predicted occlusion → hero rendered in FRONT (last resort)",
+      );
+  }
+  // scarcity spacing: heroes must breathe apart (≥ a beat between windows)
+  const heroGs = groups.filter((g) => g.hero === true).sort((a, b) => a.in - b.in);
+  for (let i = 1; i < heroGs.length; i++) {
+    const gap = heroGs[i].in - heroGs[i - 1].out;
+    if (gap < 0.6)
+      console.log(
+        `[make-cinematic] ⚠ heroes "${heroGs[i - 1].words[0].text}" and "${heroGs[i].words[0].text}" are only ${gap.toFixed(2)}s apart — peaks need a beat of air between them (consider demoting one to an emphasis line)`,
+      );
+  }
+  // proximity: narration planes should HUG the silhouette (the embed reads as in-scene
+  // only when typography interacts with the subject) — warn on far-parked planes.
+  if (sz && sz.subject) {
+    for (const [pk2, pv] of Object.entries(C.planes || {})) {
+      if (/^lockup/.test(pk2) || pk2 === "hero" || pv == null) continue;
+      const css2 = typeof pv === "string" ? pv : pv.css || "";
+      const lm = css2.match(/left\s*:\s*([\d.]+)%/),
+        wm = css2.match(/width\s*:\s*([\d.]+)%/);
+      if (!lm || !wm) continue;
+      const pl = +lm[1],
+        pr = +lm[1] + +wm[1];
+      const gap =
+        pr <= sz.subject.colMinPct
+          ? sz.subject.colMinPct - pr
+          : pl >= sz.subject.colMaxPct
+            ? pl - sz.subject.colMaxPct
+            : 0;
+      if (gap > 12)
+        console.log(
+          `[make-cinematic] ⚠ plane "${pk2}" sits ${gap.toFixed(0)}% away from the silhouette — embeds read in-scene when text HUGS the subject (use safe-zones zones.hugLeft/hugRight, gap 2–6%)`,
+        );
+    }
+  }
+  const plan = {
+    mode: "template",
+    dna: C.dna || (C.template ? undefined : "cream"), // canonical: name a DNA; default cream
+    template: C.template || "cinematic-cream",
+    compiled_by: "make-cinematic.cjs",
+    width: W,
+    height: H,
+    fps: FPS,
+    duration: DUR,
+    ...(globalFg && (!heroRefs.length || !heroFeasible) ? { caption_layer: "fg" } : {}), // mixed narration-fg + hero-bg → per-group layers (hybrid render)
+    planes: Object.fromEntries(Object.entries(planes).map(([k, v]) => [k, { css: v.css }])),
+    groups,
+  };
+  fs.writeFileSync(path.join(project, "plan.json"), JSON.stringify(plan, null, 2));
+  console.log(
+    `[make-cinematic] ${blocks.length} block(s) → ${groups.length} group(s)` +
+      `${heroRefs.length ? `, ${heroRefs.length} hero(es): ${heroRefs.map((h) => `"${h.ln.text || h.ln.words[0]}"`).join(" · ")} (each holds to its block end, lockup-composed)` : ""}` +
+      `${globalFg ? ", caption_layer=fg (safe-zones verdict)" : ""}, canvas ${DUR}s`,
+  );
+  // straight into the existing template compiler
+  const cp2 = require("child_process");
+  let r = cp2.spawnSync("node", [path.join(__dirname, "make-composition.cjs"), project], {
+    stdio: "inherit",
+  });
+  if ((r.status || 0) !== 0) process.exit(r.status);
+
+  // ── RE-SLOT pass (real measurement). Compile-time slots assume each line renders as
+  // ONE visual line; a narrow plane WRAPS long lines and the next slot overlaps the
+  // wrapped tail. Measure every page's REAL text heights in Chromium and re-stack.
+  {
+    const textBoxH = (c) => {
+      const ws = (c.words || []).filter((w) => (w.opacity ?? 1) > 0.05 && w.w > 0);
+      if (!ws.length) return c.cap_bbox ? c.cap_bbox.h : 0;
+      return Math.max(...ws.map((w) => w.y + w.h)) - Math.min(...ws.map((w) => w.y));
+    };
+    const pagesByKey = {};
+    for (const l of flat) {
+      const key = l.plane + "|" + (l.pageIdx || 0);
+      (pagesByKey[key] = pagesByKey[key] || { t: +(l.out - 0.1).toFixed(2), lines: [] }).lines.push(
+        l,
+      );
+    }
+    // the HERO is a real member of its lockup's stack — re-slot must move it (and the
+    // post-context below it) from MEASURED heights, or a wrapped pre-line / raised hero
+    // font reopens the very overlap this pass exists to prevent
+    for (const hRef of heroRefs) {
+      const key = hRef.plane + "|0";
+      const hg2 = groups.find((g2) => g2.id === `h-${hRef.bi}`);
+      if (!hg2) continue;
+      (pagesByKey[key] = pagesByKey[key] || {
+        t: +(hg2.out - 0.1).toFixed(2),
+        lines: [],
+      }).lines.push({
+        gid: hg2.id,
+        slotPx: hRef.slotPx || 0,
+        frac: fracOfLine(hg2.css) || 0.24,
+        _hero: true,
+      });
+    }
+    const times = [...new Set(Object.values(pagesByKey).map((pg) => pg.t))];
+    if (times.length) {
+      cp2.spawnSync(
+        "node",
+        [path.join(__dirname, "measure-layout.cjs"), project, ...times.map(String)],
+        { stdio: "ignore", timeout: 120000 },
+      );
+      let lay = null;
+      try {
+        lay = JSON.parse(fs.readFileSync(path.join(project, "_layout.json"), "utf8"));
+      } catch {}
+      if (lay && lay.samples) {
+        let changes = 0;
+        for (const pg of Object.values(pagesByKey)) {
+          const sample = lay.samples.reduce((a, b) =>
+            Math.abs(b.t - pg.t) < Math.abs(a.t - pg.t) ? b : a,
+          );
+          if (!sample || Math.abs(sample.t - pg.t) > 0.3) continue;
+          const ordered = [...pg.lines].sort((a, b) => a.slotPx - b.slotPx);
+          let top = 0;
+          for (const l of ordered) {
+            const cap = (sample.caps || []).find((c) => c.id === l.gid);
+            const realH = cap
+              ? (cap.cap_bbox && cap.cap_bbox.h) || textBoxH(cap)
+              : l.frac * H * 1.25;
+            if (Math.abs(top - l.slotPx) > 3) {
+              const g = groups.find((g2) => g2.id === l.gid);
+              g.css = g.css.replace(/top:\s*-?[\d.]+px/, "top:" + Math.round(top) + "px");
+              if (l._hero) {
+                const hr = heroRefs.find((h) => `h-${h.bi}` === l.gid);
+                if (hr) hr.slotPx = Math.round(top);
+              }
+              l.slotPx = Math.round(top);
+              changes++;
+            }
+            top +=
+              (realH || l.frac * H * 1.25) + Math.max(12, Math.round((l.frac || 0.05) * H * 0.38)); // box is lh1.12 — contains its own ink
+          }
+        }
+        if (changes) {
+          console.log(
+            `[make-cinematic] re-slot: ${changes} line(s) re-stacked from MEASURED heights (wrapped lines accounted)`,
+          );
+          fs.writeFileSync(path.join(project, "plan.json"), JSON.stringify(plan, null, 2));
+          cp2.spawnSync("node", [path.join(__dirname, "make-composition.cjs"), project], {
+            stdio: "ignore",
+          });
+          try {
+            fs.unlinkSync(path.join(project, "_layout.json"));
+          } catch {}
+        }
+      }
+    }
+  }
+
+  // ── HERO post-pass (real measurement, up to 2 re-emits) — runs PER HERO ─────
+  // (a) SIZE: a timid hero is the #1 quality kill. If the authored font leaves >25%
+  //     of the usable width unused, raise it to the width-fit maximum (DNA sizeRange cap).
+  // (b) CLEARANCE vs OTHER planes: the hero band must not overlap caps outside its own
+  //     lockup (its own context is composed around it by the slot layout). On a hit,
+  //     shift the whole LOCKUP plane vertically.
+  // (c) LOCKUP RE-STACK: a size change moves the hero's height — restack the lockup's
+  //     slots from measured heights so post-context stays bonded BELOW the hero.
+  // HERO words never wrap — a mid-word break ("Watermelo|n") is wrong in every case,
+  // and author css REPLACES the default (which silently lost white-space:nowrap).
+  // Forced here so no authoring path can drop it; centered nowrap text overflows a
+  // narrow plane SYMMETRICALLY, which also keeps width-fit honest (it measures the
+  // true single-line width instead of a wrapped row).
+  // narration lines whipped away by a mid-sentence page-flip are the same disease
+  // in mild form — warn (a deliberate quick beat is legal, so no die)
+  for (const g of groups)
+    if (!g.hero && g.words && g.words.length && g.out - g.in < 0.6) {
+      console.log(
+        `[make-cinematic] ⚠ line "${g.words
+          .map((w) => w.text)
+          .join(" ")
+          .slice(
+            0,
+            28,
+          )}" visible only ${(g.out - g.in).toFixed(2)}s (page-flip) — merge micro-lines or give the plane more height so the page holds`,
+      );
+    }
+  // MIN DWELL — a peak on screen <0.5s is unreadable ("stars" shipped at 0.47s and
+  // the user couldn't read it). Merge the block with the next (one thought), promote
+  // a word with room, or demote to an emphasized line. <0.8s gets a loud warning.
+  for (const g of groups)
+    if (g.hero) {
+      const dwell = g.out - g.in;
+      if (dwell < 0.5)
+        die(
+          `hero "${(g.words[0] || {}).text}" is on screen only ${dwell.toFixed(2)}s (<0.5s readability floor) — merge its block with the next, promote a word with more room, or demote it to an emphasized (non-hero) line.`,
+        );
+      if (dwell < 0.8)
+        console.log(
+          `[make-cinematic] ⚠ hero "${(g.words[0] || {}).text}" dwell ${dwell.toFixed(2)}s is tight (<0.8s) — consider merging blocks so the peak can breathe`,
+        );
+    }
+  {
+    let nwChanged = false;
+    for (const g of groups)
+      if (g.hero && !/white-space\s*:\s*nowrap/.test(g.css || "")) {
+        g.css = (g.css || "") + " white-space: nowrap;";
+        nwChanged = true;
+      }
+    if (nwChanged) {
+      fs.writeFileSync(path.join(project, "plan.json"), JSON.stringify(plan, null, 2));
+      require("child_process").spawnSync(
+        "node",
+        [path.join(__dirname, "make-composition.cjs"), project],
+        { stdio: "ignore" },
+      );
+    }
+  }
+  const fracOf = (css) => {
+    const m = (css || "").match(/font-size\s*:\s*calc\(\s*([\d.]+)\s*\*\s*var\(--h\)/);
+    return m ? +m[1] : null;
+  };
+  const setFrac = (css, f) =>
+    (css || "").replace(
+      /font-size\s*:\s*[^;]+/,
+      "font-size: calc(" + f.toFixed(3) + " * var(--h))",
+    );
+  const textBox = (c) => {
+    const ws = (c.words || []).filter((w) => (w.opacity ?? 1) > 0.05 && w.w > 0);
+    if (!ws.length) return c.cap_bbox;
+    const x0 = Math.min(...ws.map((w) => w.x)),
+      x1 = Math.max(...ws.map((w) => w.x + w.w));
+    const y0 = Math.min(...ws.map((w) => w.y)),
+      y1 = Math.max(...ws.map((w) => w.y + w.h));
+    return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+  };
+  let dnaSizeCap = 0.34,
+    dnaHeroCase = "none";
+  try {
+    const dnaLib2 = require("./lib-dna.cjs");
+    const dn = plan.dna || dnaLib2.LEGACY[plan.template];
+    if (dn) {
+      const dj = dnaLib2.load(dn);
+      if (dj.hero && dj.hero.sizeRange) dnaSizeCap = dj.hero.sizeRange[1];
+      if (dj.hero) dnaHeroCase = dj.hero.case || "none";
+    }
+  } catch {}
+  // the APEX (largest authored hero) gets the width-fit raise; minor heroes keep their
+  // authored size — inter-hero hierarchy is a deliberate choice, not timidity
+  const apexFrac = Math.max(
+    ...heroRefs.map((h) => fracOf((groups.find((g) => g.id === `h-${h.bi}`) || {}).css) || 0),
+    0,
+  );
+  for (const hRef of heroRefs) {
+    const heroG = groups.find((g) => g.id === `h-${hRef.bi}`);
+    if (!heroG) continue;
+    const isApex = (fracOf(heroG.css) || 0) >= apexFrac - 1e-6;
+    const lockupMates = groups.filter((g) => g.plane === hRef.plane && g.id !== heroG.id);
+    // hero size changed → context follows the 0.26 poster ratio, and its orbit
+    // max-width scales WITH the font (a stale max-width wraps re-locked context
+    // into multi-row towers that blow the stack past the frame)
+    const relockMates = (hf) => {
+      const rf = +Math.min(0.085, Math.max(0.05, hf * 0.26)).toFixed(4);
+      for (const m of lockupMates) {
+        const mf = fracOf(m.css);
+        if (!mf || Math.abs(mf - rf) <= 0.002) continue;
+        const scale = rf / mf;
+        m.css = setFrac(m.css, rf).replace(
+          /max-width:\s*([\d.]+)px/,
+          (s2, px) => "max-width:" + Math.round(+px * scale) + "px",
+        );
+      }
+    };
+    const measure = () => {
+      const midT = ((heroG.in + Math.min(heroG.out, heroG.in + 1.0)) / 2).toFixed(2);
+      const endT = Math.max(+midT + 0.05, heroG.out - 0.12).toFixed(2);
+      cp2.spawnSync(
+        "node",
+        [path.join(__dirname, "measure-layout.cjs"), project, String(midT), String(endT)],
+        { stdio: "ignore", timeout: 90000 },
+      );
+      try {
+        const ss = JSON.parse(fs.readFileSync(path.join(project, "_layout.json"), "utf8")).samples;
+        const near = (t) =>
+          ss.reduce((a, b) => (Math.abs(b.t - t) < Math.abs((a ? a.t : 1e9) - t) ? b : a), null);
+        return { caps: (near(+midT) || {}).caps || [], capsEnd: (near(+endT) || {}).caps || [] };
+      } catch {
+        return null;
+      }
+    };
+    let didRaise = false;
+    for (let pass = 0; pass < 5; pass++) {
+      const m0 = measure();
+      if (!m0) break;
+      const caps = m0.caps,
+        capsEnd = m0.capsEnd && m0.capsEnd.length ? m0.capsEnd : m0.caps;
+      const hc0 = caps.find((c) => c.id === heroG.id);
+      if (!hc0 || !hc0.cap_bbox) break;
+      const hc = { ...hc0, cap_bbox: textBox(hc0) };
+      const mateIds = new Set(lockupMates.map((m) => m.id));
+      const others = caps
+        .filter(
+          (c) =>
+            c.id !== heroG.id &&
+            !mateIds.has(c.id) &&
+            !/-glow$/.test(c.id || "") &&
+            c.cap_bbox &&
+            c.opacity > 0.05,
+        )
+        .map((c) => ({ ...c, cap_bbox: textBox(c) }));
+      const maxW = W * 0.94;
+      const f0 = fracOf(heroG.css);
+      let changed = false;
+      if (f0 && hc.cap_bbox.w > 0) {
+        if (hc.cap_bbox.w > maxW) {
+          const nf = Math.max(0.06, (f0 * maxW) / hc.cap_bbox.w);
+          console.log(
+            `[make-cinematic] hero "${heroG.words[0].text}" too WIDE ${Math.round(hc.cap_bbox.w)}px → ${f0}h→${nf.toFixed(3)}h`,
+          );
+          heroG.css = setFrac(heroG.css, nf);
+          changed = true;
+        } else if (hc.cap_bbox.w >= maxW * 0.88) {
+          if (pass === 0)
+            console.log(
+              `[make-cinematic] hero "${heroG.words[0].text}" at width CEILING (${Math.round(hc.cap_bbox.w)}/${Math.round(maxW)}px) — cannot enlarge.`,
+            );
+        } else if (!didRaise && hc.cap_bbox.w < maxW * 0.88 && isApex) {
+          // NO DEAD ZONE: anything under 88% of usable width is raised toward a 93%
+          // fill (the old <75% trigger let 75–88%-wide heroes stay merely "decent")
+          const fit = (f0 * (maxW * 0.93)) / hc.cap_bbox.w;
+          const nf = Math.min(dnaSizeCap, fit);
+          if (nf > f0 * 1.05 || fit > dnaSizeCap * 1.02) {
+            if (nf > f0 * 1.001)
+              console.log(
+                `[make-cinematic] hero "${heroG.words[0].text}" TIMID (${Math.round(hc.cap_bbox.w)}px of ${Math.round(maxW)}px usable) → ${f0}h→${nf.toFixed(3)}h (width-fit max)`,
+              );
+            // SHORT-WORD FILL: height cap bound before the width target → fill with
+            // TRACKING (film-title craft — HER, DUNE), ≤0.32em so it stays a word.
+            const wAtCap = (hc.cap_bbox.w * nf) / f0;
+            const dispT = String(heroG.text || (heroG.words || []).map((w) => w.text).join(" "));
+            // never letterspace lowercase (tracked lowercase falls apart — caps only)
+            const capsy = dnaHeroCase === "uppercase" || dispT === dispT.toUpperCase();
+            if (fit > dnaSizeCap && wAtCap < maxW * 0.85 && capsy) {
+              const disp = dispT;
+              // letter-spacing adds a gap after EVERY char (N gaps) and the centering
+              // text-indent adds one more — budget N+1 gaps or the word leaves the frame
+              const gaps = disp.length + 1;
+              const tr = +Math.min(0.32, (maxW * 0.88 - wAtCap) / (gaps * nf * H)).toFixed(3);
+              if (tr >= 0.04) {
+                heroG.css =
+                  heroG.css
+                    .replace(/letter-spacing\s*:[^;]+;?\s*/g, "")
+                    .replace(/text-indent\s*:[^;]+;?\s*/g, "") +
+                  (heroG.css.trim().endsWith(";") || !heroG.css.trim() ? "" : ";") +
+                  ` letter-spacing:${tr}em; text-indent:${tr}em;`;
+                console.log(
+                  `[make-cinematic] hero "${disp}" short word at height cap (${Math.round(wAtCap)}px of ${Math.round(maxW)}px) → tracked +${tr}em to fill`,
+                );
+              }
+            }
+            heroG.css = setFrac(heroG.css, nf);
+            changed = true;
+            didRaise = true;
+            relockMates(nf);
+          }
+        }
+      }
+      const hbx = hc.cap_bbox;
+      // colliders OUTSIDE the lockup only — the lockup composes around the hero by design
+      const hits = others.filter((o) => {
+        const b = o.cap_bbox;
+        const ix = Math.min(hbx.x + hbx.w, b.x + b.w) - Math.max(hbx.x, b.x);
+        const iy = Math.min(hbx.y + hbx.h, b.y + b.h) - Math.max(hbx.y, b.y);
+        return ix > 8 && iy > 8;
+      });
+      if (hits.length) {
+        const maxBottom = Math.max(...hits.map((o) => o.cap_bbox.y + o.cap_bbox.h));
+        const minTop = Math.min(...hits.map((o) => o.cap_bbox.y));
+        const downTo = ((maxBottom + 14) / H) * 100;
+        const upTo = Math.max(2, ((minTop - hbx.h - 14) / H) * 100);
+        const planeCss = plan.planes[hRef.plane].css;
+        const curTop = +(planeCss.match(/top:\s*([\d.]+)%/) || [0, 30])[1];
+        const newTop = downTo + (hbx.h / H) * 100 < 96 ? downTo : upTo;
+        plan.planes[hRef.plane].css = planeCss.replace(
+          /top:\s*[\d.]+%/,
+          "top: " + newTop.toFixed(1) + "%",
+        );
+        console.log(
+          `[make-cinematic] hero "${heroG.words[0].text}" OVERLAPS ${hits.map((o) => o.id).join(",")} — lockup top ${curTop}% → ${newTop.toFixed(1)}%`,
+        );
+        changed = true;
+      }
+      // ORBIT REFINE: anchor kicker/tail to the MEASURED hero edges (estimate → real)
+      if (lockupMates.length && hc.cap_bbox && hc.cap_bbox.w > 0) {
+        const planeCss2 = (plan.planes[hRef.plane] && plan.planes[hRef.plane].css) || "";
+        const pl2 = ((planeCss2.match(/left:\s*([\d.]+)%/) || [0, 0])[1] * W) / 100;
+        const relL = Math.max(0, Math.round(hc.cap_bbox.x - pl2));
+        const pw2 = ((planeCss2.match(/width:\s*([\d.]+)%/) || [0, 100])[1] * W) / 100;
+        const relR = Math.max(0, Math.round(pw2 - (hc.cap_bbox.x - pl2) - hc.cap_bbox.w));
+        for (const m of lockupMates) {
+          if (/left:\s*\d+px;right:auto/.test(m.css)) {
+            const nc = m.css.replace(/left:\s*\d+px/, "left:" + relL + "px");
+            if (nc !== m.css) {
+              m.css = nc;
+              changed = true;
+            }
+          } else if (/right:\s*\d+px;left:auto/.test(m.css)) {
+            const nc = m.css.replace(/right:\s*\d+px/, "right:" + relR + "px");
+            if (nc !== m.css) {
+              m.css = nc;
+              changed = true;
+            }
+          }
+        }
+      }
+      // LOCKUP RE-STACK from measured heights — runs EVERY pass for lockups (orbit
+      // max-widths wrap context lines, so the re-slot's estimates can leave the tail
+      // displaced or the whole composition off frame)
+      if (lockupMates.length) {
+        const caps2 = capsEnd; // lockup-END sample: every context line is revealed there
+        // TOWER CHECK — a context line wrapped to 3+ rows means its orbit max-width is
+        // too narrow for the (re-locked) font; widen toward the plane before stacking,
+        // or the tower blows the stack past the frame and the walk-back eats the hero
+        for (const m of lockupMates) {
+          const cm = caps2.find((x) => x.id === m.id);
+          const frm = fracOf(m.css) || 0.05;
+          const mwM = m.css.match(/max-width:\s*([\d.]+)px/);
+          if (!cm || !cm.cap_bbox || !mwM) continue;
+          const rows = Math.round(cm.cap_bbox.h / (frm * H * 1.12));
+          if (rows >= 3) {
+            const planeCssW2 = (plan.planes[hRef.plane] && plan.planes[hRef.plane].css) || "";
+            const pwX = W * (+(planeCssW2.match(/width:\s*([\d.]+)%/) || [0, 92])[1] / 100);
+            const nw = Math.round(pwX * 0.62);
+            if (nw > +mwM[1] + 10) {
+              m.css = m.css.replace(/max-width:\s*[\d.]+px/, "max-width:" + nw + "px");
+              console.log(
+                `[make-cinematic] context "${((m.words || [])[0] || {}).text}…" wrapped to ${rows} rows — orbit max-width ${Math.round(+mwM[1])}→${nw}px (towers break the stack)`,
+              );
+              changed = true;
+            }
+          }
+        }
+        const entries = [heroG, ...lockupMates]
+          .map((g) => {
+            const c = caps2.find((x) => x.id === g.id);
+            const curTop = +(g.css.match(/top:\s*(-?[\d.]+)px/) || [0, 0])[1];
+            const fr = fracOf(g.css) || 0.05;
+            // SLOT HEIGHT = the LAYOUT box (cap_bbox), not the glyph box: words reveal
+            // over time, so at the hero-mid sample a context line's later words are
+            // still opacity-0 — glyph-box measured a wrapped line one row short and the
+            // next line slotted INTO its wrap band (real text-on-text shipped).
+            const measuredH = c && c.cap_bbox ? c.cap_bbox.h : null;
+            const h2 = g.id === heroG.id && didRaise ? fr * H * 1.12 : measuredH || fr * H * 1.25;
+            return { g, curTop, h: h2 };
+          })
+          .sort((a, b) => a.curTop - b.curTop);
+        let top = 0;
+        for (const e of entries) {
+          if (Math.abs(top - e.curTop) > 3) {
+            e.g.css = e.g.css.replace(/top:\s*-?[\d.]+px/, "top:" + Math.round(top) + "px");
+            changed = true;
+          }
+          top += e.h + Math.max(12, Math.round((fracOf(e.g.css) || 0.05) * H * 0.38)); // box is lh1.12 — contains its own ink
+        }
+        // RE-CLAMP the plane after MEASURED growth — keep the whole composition on frame
+        const planeCss3 = plan.planes[hRef.plane].css;
+        const curTopPct = +(planeCss3.match(/top:\s*([\d.]+)%/) || [0, 30])[1];
+        const maxTopPct = Math.max(2, ((H * 0.97 - top) / H) * 100);
+        if (curTopPct > maxTopPct + 0.3) {
+          plan.planes[hRef.plane].css = planeCss3.replace(
+            /top:\s*[\d.]+%/,
+            "top: " + maxTopPct.toFixed(1) + "%",
+          );
+          console.log(
+            `[make-cinematic] lockup measured ${Math.round(top)}px tall — plane top ${curTopPct}% → ${maxTopPct.toFixed(1)}% (kept on frame)`,
+          );
+          changed = true;
+        }
+        // even at the 2% ceiling the stack can exceed the frame (TIMID raise + ratio
+        // context on a tall lockup) — walk the hero back 8% and re-lock until it fits
+        if (top > H * 0.95 && maxTopPct <= 2.01) {
+          const f0c = fracOf(heroG.css);
+          if (f0c && f0c > 0.14) {
+            // decisive step: stack height scales ~linearly with the hero (context is
+            // ratio-locked to it), so aim straight at a 93% fill instead of nibbling
+            const nf2 = +Math.max(0.14, Math.min(f0c * 0.92, (f0c * (H * 0.93)) / top)).toFixed(3);
+            console.log(
+              `[make-cinematic] lockup stack ${Math.round(top)}px exceeds the frame even at top 2% — hero ${f0c}h → ${nf2}h (fit)`,
+            );
+            heroG.css = setFrac(heroG.css, nf2);
+            relockMates(nf2);
+            didRaise = true;
+            changed = true;
+          }
+        }
+      }
+      if (!changed) break;
+      fs.writeFileSync(path.join(project, "plan.json"), JSON.stringify(plan, null, 2));
+      r = cp2.spawnSync("node", [path.join(__dirname, "make-composition.cjs"), project], {
+        stdio: "ignore",
+      });
+      try {
+        fs.unlinkSync(path.join(project, "_layout.json"));
+      } catch {}
+    }
+  }
+  // MINOR HERO measure pass — minors keep their authored size (hierarchy is a choice)
+  // but never ship broken: wider than the frame's usable width shrinks to fit, and a
+  // column overflow gets a loud note (centered spill is legal on a clear side only).
+  {
+    const minors = groups.filter((g) => g.hero && !heroRefs.some((h) => `h-${h.bi}` === g.id));
+    let minorChanged = false;
+    for (const mg of minors) {
+      const midT = ((mg.in + Math.min(mg.out, mg.in + 1.0)) / 2).toFixed(2);
+      cp2.spawnSync("node", [path.join(__dirname, "measure-layout.cjs"), project, String(midT)], {
+        stdio: "ignore",
+        timeout: 60000,
+      });
+      let mc = null;
+      try {
+        mc = (
+          JSON.parse(fs.readFileSync(path.join(project, "_layout.json"), "utf8")).samples[0].caps ||
+          []
+        ).find((c) => c.id === mg.id);
+      } catch {}
+      if (!mc || !mc.cap_bbox) continue;
+      const bb = textBox(mc),
+        f0 = fracOf(mg.css);
+      if (f0 && bb.w > W * 0.94) {
+        const nf = Math.max(0.06, +((f0 * (W * 0.94)) / bb.w).toFixed(3));
+        console.log(
+          `[make-cinematic] minor hero "${(mg.words[0] || {}).text}" too WIDE ${Math.round(bb.w)}px → ${f0}h→${nf.toFixed(3)}h (shrink-to-fit)`,
+        );
+        mg.css = setFrac(mg.css, nf);
+        minorChanged = true;
+      } else {
+        const planeCssM = (plan.planes[mg.plane] && plan.planes[mg.plane].css) || "";
+        const pwPx = W * (+(planeCssM.match(/width:\s*([\d.]+)%/) || [0, 100])[1] / 100);
+        if (bb.w > pwPx * 1.05)
+          console.log(
+            `[make-cinematic] note: minor hero "${(mg.words[0] || {}).text}" (${Math.round(bb.w)}px) spills its ${Math.round(pwPx)}px column — fine on a clear side; reduce size if it crosses the subject`,
+          );
+      }
+      try {
+        fs.unlinkSync(path.join(project, "_layout.json"));
+      } catch {}
+    }
+    if (minorChanged) {
+      fs.writeFileSync(path.join(project, "plan.json"), JSON.stringify(plan, null, 2));
+      cp2.spawnSync("node", [path.join(__dirname, "make-composition.cjs"), project], {
+        stdio: "ignore",
+      });
+    }
+  }
+  process.exit(0);
+}
+main();