heygen-com--hyperframes/skills/embedded-captions/scripts/make-cinematic.cjs

#!/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();