dsh-hyperframes 0.1.1 → 0.3.0

package/skills/embedded-captions/scripts/safe-zones.cjs

@@ -0,0 +1,813 @@
+#!/usr/bin/env node
+/*
+ * safe-zones.cjs — PRECOMPUTE where captions can safely go, from the subject matte.
+ *
+ *   node safe-zones.cjs <project-dir>            → safe-zones.json (global + per-sentence windows) + summary
+ *   node safe-zones.cjs <project-dir> <in> <out> → just that time window's zones (ad-hoc query)
+ *
+ * The inverse of check-occlusion: read the silhouette FIRST and hand the author the
+ * clean regions + an embed-vs-fg verdict, so layout is right the first time instead of
+ * after N occlusion-failure rounds.
+ *
+ * Uses the per-pixel ALPHA matte (not a bounding box): a cell counts as subject only
+ * where the silhouette actually is, so the empty pocket beside the head / above the
+ * shoulders stays FREE (a bbox would wrongly claim it). The subject MOVES, so zones are
+ * computed PER TIME WINDOW (the union over just that window's frames), not one global box.
+ */
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const THRESH = 30 / 255; // a cell is "subject" if ≥12% covered at any sampled frame in the window
+const SAMPLES = 48; // frames cached across the clip (windows aggregate the cached grids)
+
+const HF_ROOTS = [
+  process.env.HYPERFRAMES_ROOT,
+  path.resolve(__dirname, "../../.."),
+  path.join(os.homedir(), "Downloads", "hyperframes"),
+].filter(Boolean);
+let sharp = null;
+for (const root of HF_ROOTS) {
+  const cands = [path.join(root, "node_modules", "sharp")];
+  const bunDir = path.join(root, "node_modules", ".bun");
+  try {
+    if (fs.existsSync(bunDir))
+      for (const d of fs.readdirSync(bunDir))
+        if (d.startsWith("sharp@")) cands.push(path.join(bunDir, d, "node_modules", "sharp"));
+  } catch {}
+  for (const c of cands) {
+    try {
+      if (fs.existsSync(c)) {
+        sharp = require(c);
+        break;
+      }
+    } catch {}
+  }
+  if (sharp) break;
+}
+
+// largest all-clear (1) rectangle within [c0,c1)×[r0,r1), in CELL units
+function largestRect(safe, GW, c0, c1, r0, r1) {
+  const cols = c1 - c0;
+  const heights = new Array(cols).fill(0);
+  let best = { area: 0, x: 0, y: 0, w: 0, h: 0 };
+  for (let r = r0; r < r1; r++) {
+    for (let cc = 0; cc < cols; cc++) heights[cc] = safe[r * GW + (c0 + cc)] ? heights[cc] + 1 : 0;
+    const st = [];
+    for (let cc = 0; cc <= cols; cc++) {
+      const h = cc < cols ? heights[cc] : 0;
+      let start = cc;
+      while (st.length && st[st.length - 1].h >= h) {
+        const top = st.pop();
+        const area = top.h * (cc - top.i);
+        if (area > best.area)
+          best = { area, x: c0 + top.i, y: r - top.h + 1, w: cc - top.i, h: top.h };
+        start = top.i;
+      }
+      st.push({ i: start, h });
+    }
+  }
+  return best;
+}
+
+// turn a max-coverage grid into {coverage, subject, zones, recommendation}
+function analyze(occ, GW, GH, W, H, lum, lumSeries) {
+  const occCell = new Uint8Array(GW * GH);
+  for (let c = 0; c < GW * GH; c++) occCell[c] = occ[c] >= THRESH ? 1 : 0;
+  const safe = new Uint8Array(GW * GH); // 1-cell dilation margin around the silhouette
+  for (let y = 0; y < GH; y++)
+    for (let x = 0; x < GW; x++) {
+      let o = 0;
+      for (let dy = -1; dy <= 1 && !o; dy++)
+        for (let dx = -1; dx <= 1 && !o; dx++) {
+          const nx = x + dx,
+            ny = y + dy;
+          if (nx >= 0 && nx < GW && ny >= 0 && ny < GH && occCell[ny * GW + nx]) o = 1;
+        }
+      safe[y * GW + x] = o ? 0 : 1;
+    }
+  const occupied = occCell.reduce((a, b) => a + b, 0);
+  const coverage = occupied / (GW * GH);
+  let colMin = GW,
+    colMax = -1,
+    rowMin = GH,
+    rowMax = -1;
+  for (let x = 0; x < GW; x++)
+    for (let y = 0; y < GH; y++)
+      if (occCell[y * GW + x]) {
+        if (x < colMin) colMin = x;
+        if (x > colMax) colMax = x;
+        if (y < rowMin) rowMin = y;
+        if (y > rowMax) rowMax = y;
+      }
+  if (colMax < 0) {
+    colMin = 0;
+    colMax = -1;
+    rowMin = 0;
+    rowMax = -1;
+  }
+  const clearerSide = colMin >= GW - 1 - colMax ? "left" : "right";
+  const cellW = W / GW,
+    cellH = H / GH;
+  // HERO anchor — where the ONE big promoted word should sit: ON the subject (centered,
+  // crossing it so the head/torso occludes the middle). The OPPOSITE of the clean zones
+  // above (those are for narration). A wide band ≈ centered on the subject, vertically
+  // crossing the head/upper torso. Only meaningful when there IS a subject.
+  let heroAnchor = null;
+  if (colMax >= 0) {
+    const subjCx = ((colMin + colMax + 1) / 2 / GW) * 100;
+    const subjWpct = ((colMax - colMin + 1) / GW) * 100;
+    const yTop = (rowMin / GH) * 100,
+      yBot = ((rowMax + 1) / GH) * 100;
+    const wPct = Math.round(Math.min(92, Math.max(58, subjWpct + 26)));
+    const xPct = Math.round(Math.min(98 - wPct, Math.max(2, subjCx - wPct / 2)));
+    const yPct = Math.round(yTop + (yBot - yTop) * 0.12); // band crosses the head / upper torso
+    let bandLuma = null;
+    if (lum) {
+      const y0 = Math.round((yPct / 100) * GH),
+        y1 = Math.min(GH, y0 + Math.max(2, Math.round(GH * 0.14)));
+      const x0 = Math.round((xPct / 100) * GW),
+        x1 = Math.min(GW, Math.round(((xPct + wPct) / 100) * GW));
+      // luma of the BACKGROUND cells only — that's where the hero's glyphs are visible
+      // (the subject-occluded middle doesn't show text; averaging it in hides washout).
+      let s2 = 0,
+        n = 0;
+      for (let y = y0; y < y1; y++)
+        for (let x = x0; x < x1; x++) {
+          if (occCell[y * GW + x]) continue;
+          s2 += lum[y * GW + x];
+          n++;
+        }
+      bandLuma = n ? Math.round(s2 / n) : null;
+    }
+    heroAnchor = {
+      centerXPct: +subjCx.toFixed(1),
+      plane: { xPct, yPct, wPct, align: "center" },
+      ...(bandLuma != null ? { bandLuma, washoutRisk: bandLuma > 175 } : {}),
+      note:
+        "Place the ONE big hero here (centered on the subject); the head/torso occludes its middle (~30-55%) — that is the embed. Do NOT put the hero in a clean zone." +
+        (bandLuma != null && bandLuma > 175
+          ? " ⚠ BAND IS BRIGHT (luma " +
+            bandLuma +
+            "): cream/screen text will wash out — lower the hero onto the darker subject body, or use a template/mode with opaque text."
+          : ""),
+    };
+  }
+  const zoneLuma = (r) => {
+    if (!lum || r.area === 0) return null;
+    let s2 = 0,
+      n = 0;
+    for (let y = r.y; y < r.y + r.h; y++)
+      for (let x = r.x; x < r.x + r.w; x++) {
+        s2 += lum[y * GW + x];
+        n++;
+      }
+    return n ? Math.round(s2 / n) : null;
+  };
+  // a TIME-AVERAGED map walks a moving minefield: a dark wall swept by a bright
+  // moving object (handheld drift, screens) averages "clean" while peaking hot.
+  // peakLuma = p95 of the zone's per-sample mean over the window.
+  const zoneLumaPeak = (r) => {
+    if (!lumSeries || !lumSeries.length || r.area === 0) return null;
+    const means = lumSeries
+      .map((Lg) => {
+        let s2 = 0,
+          n = 0;
+        for (let y = r.y; y < r.y + r.h; y++)
+          for (let x = r.x; x < r.x + r.w; x++) {
+            s2 += Lg[y * GW + x];
+            n++;
+          }
+        return n ? s2 / n : 0;
+      })
+      .sort((a, b) => a - b);
+    return Math.round(means[Math.max(0, Math.ceil(means.length * 0.95) - 1)]);
+  };
+  const toZone = (r) =>
+    r.area === 0
+      ? null
+      : {
+          xPct: +((r.x / GW) * 100).toFixed(1),
+          yPct: +((r.y / GH) * 100).toFixed(1),
+          wPct: +((r.w / GW) * 100).toFixed(1),
+          hPct: +((r.h / GH) * 100).toFixed(1),
+          areaPct: +(((r.w * r.h) / (GW * GH)) * 100).toFixed(1),
+          px: {
+            x: Math.round(r.x * cellW),
+            y: Math.round(r.y * cellH),
+            w: Math.round(r.w * cellW),
+            h: Math.round(r.h * cellH),
+          },
+          ...(zoneLuma(r) != null
+            ? {
+                meanLuma: zoneLuma(r),
+                bright: zoneLuma(r) > 180,
+                ...(zoneLumaPeak(r) != null ? { peakLuma: zoneLumaPeak(r) } : {}),
+              }
+            : {}),
+        };
+  const zones = {
+    largest: toZone(largestRect(safe, GW, 0, GW, 0, GH)),
+    left: toZone(largestRect(safe, GW, 0, Math.round(GW / 2), 0, GH)),
+    right: toZone(largestRect(safe, GW, Math.round(GW / 2), GW, 0, GH)),
+    top: toZone(largestRect(safe, GW, 0, GW, 0, Math.max(2, Math.round(GH * 0.38)))),
+  };
+  // HUGGING zones — clean strips that ABUT the silhouette (the embed aesthetic wants
+  // text NEAR the subject, not parked in the farthest corner). Grown outward from the
+  // subject's edge at upper-body height; prefer these for narration.
+  const hug = (side) => {
+    if (colMax < 0) return null;
+    const pad = Math.max(1, Math.round(GW * 0.02));
+    const y0 = rowMin,
+      y1 = Math.min(GH, rowMin + Math.max(3, Math.round((rowMax - rowMin + 1) * 0.45)));
+    let x0, x1;
+    if (side === "right") {
+      x0 = Math.min(GW - 1, colMax + 1 + pad);
+      x1 = GW - pad;
+    } else {
+      x1 = Math.max(1, colMin - pad);
+      x0 = pad;
+    }
+    if (x1 - x0 < Math.round(GW * 0.1)) return null;
+    // shrink until actually clean (≤8% occupied cells)
+    let occN = 0,
+      tot = 0;
+    for (let y = y0; y < y1; y++)
+      for (let x = x0; x < x1; x++) {
+        tot++;
+        if (occCell[y * GW + x]) occN++;
+      }
+    if (tot === 0 || occN / tot > 0.08) return null;
+    const r = { x: x0, y: y0, w: x1 - x0, h: y1 - y0, area: (x1 - x0) * (y1 - y0) };
+    const z2 = toZone(r);
+    // GLYPHS must hug, not just the plane: in a wide column, text aligned to the far
+    // edge parks the words a third of the frame away from the subject. Align TOWARD
+    // the silhouette: right-side column → text-align:left (text starts beside the
+    // subject); left-side column → text-align:right.
+    if (z2) z2.align = side === "right" ? "left" : "right";
+    return z2;
+  };
+  zones.hugLeft = hug("left");
+  zones.hugRight = hug("right");
+  // HERO BAND PROFILE — per-height predicted occlusion of a centered hero band. The hero
+  // WANTS ~30–55% (occlusion IS the embed); fg is the LAST resort, only when no height
+  // achieves ≤62%. Even an 88%-coverage frame usually has a feasible band over the hairline.
+  let heroBands = null;
+  if (colMax >= 0) {
+    const bandH = Math.max(2, Math.round(GH * 0.13));
+    const hx0 = Math.round(((heroAnchor ? heroAnchor.plane.xPct : 8) / 100) * GW);
+    const hx1 = Math.min(
+      GW,
+      Math.round(((heroAnchor ? heroAnchor.plane.xPct + heroAnchor.plane.wPct : 92) / 100) * GW),
+    );
+    const profile = [];
+    for (let y0 = 0; y0 + bandH <= GH; y0 += Math.max(1, Math.round(GH * 0.02))) {
+      let n = 0,
+        occN = 0,
+        lsum = 0;
+      for (let y = y0; y < y0 + bandH; y++)
+        for (let x = hx0; x < hx1; x++) {
+          n++;
+          if (occCell[y * GW + x]) occN++;
+          if (lum) lsum += lum[y * GW + x];
+        }
+      profile.push({
+        topPct: +((y0 / GH) * 100).toFixed(1),
+        occPct: +((occN / n) * 100).toFixed(1),
+        ...(lum ? { bgLuma: Math.round(lsum / n) } : {}),
+      });
+    }
+    const ok = profile.filter((b) => b.occPct >= 12 && b.occPct <= 62);
+    const best = (ok.length ? ok : profile).reduce((a, b) =>
+      Math.abs(b.occPct - 40) < Math.abs(a.occPct - 40) ? b : a,
+    );
+    heroBands = { feasible: ok.length > 0, best, profile };
+  }
+  const big = zones.largest;
+  const embeddable = !!big && big.areaPct >= 8 && big.hPct >= 10 && big.wPct >= 18;
+  return {
+    coverage: +(coverage * 100).toFixed(1),
+    subject: {
+      colMinPct: +((colMin / GW) * 100).toFixed(1),
+      colMaxPct: +(((colMax + 1) / GW) * 100).toFixed(1),
+      clearerSide,
+    },
+    zones,
+    heroAnchor,
+    heroBands,
+    recommendation: embeddable ? "embed" : "fg",
+  };
+}
+
+// ── SCENE OPTICS + PALETTE (v2) ──────────────────────────────────────────────
+// Deterministic scene measurements that drive the DNA tokens, so "design that fits
+// the scene" is a pipeline product, not agent inspiration:
+//   palette  — dominant scene colors + a READABLE accent suggestion (sampled, then
+//              clamped to usable saturation/lightness) + warm/cool temperature
+//   optics   — background vs subject sharpness (Laplacian proxy) → suggested text
+//              blur so embed type matches the scene's depth-of-field
+//   lighting — bright-side estimate → contact-shadow direction for embed type
+
+function rgb2hsv(r, g, b) {
+  r /= 255;
+  g /= 255;
+  b /= 255;
+  const mx = Math.max(r, g, b),
+    mn = Math.min(r, g, b),
+    d = mx - mn;
+  let h = 0;
+  if (d > 0) {
+    if (mx === r) h = ((g - b) / d) % 6;
+    else if (mx === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h, s: mx === 0 ? 0 : d / mx, v: mx };
+}
+function hsv2hex(h, s, v) {
+  const c = v * s,
+    x = c * (1 - Math.abs(((h / 60) % 2) - 1)),
+    m = v - c;
+  let [r, g, b] =
+    h < 60
+      ? [c, x, 0]
+      : h < 120
+        ? [x, c, 0]
+        : h < 180
+          ? [0, c, x]
+          : h < 240
+            ? [0, x, c]
+            : h < 300
+              ? [x, 0, c]
+              : [c, 0, x];
+  const f = (n) =>
+    Math.round((n + m) * 255)
+      .toString(16)
+      .padStart(2, "0");
+  return `#${f(r)}${f(g)}${f(b)}`;
+}
+
+// dominant colors + accent suggestion from the BACKGROUND cells of a mid frame
+async function scenePalette(bgPath, occCell, GW, GH) {
+  const { data, info } = await sharp(bgPath)
+    .resize(GW, GH, { fit: "fill" })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const ch = info.channels;
+  const cells = [];
+  for (let c = 0; c < GW * GH; c++) {
+    if (occCell && occCell[c]) continue; // background only
+    cells.push([data[c * ch], data[c * ch + 1], data[c * ch + 2]]);
+  }
+  if (!cells.length) return null;
+  // dominant: quantize to 3 bits/channel, top buckets by count
+  const buckets = new Map();
+  for (const [r, g, b] of cells) {
+    const k = ((r >> 5) << 6) | ((g >> 5) << 3) | (b >> 5);
+    const e = buckets.get(k) || { n: 0, r: 0, g: 0, b: 0 };
+    e.n++;
+    e.r += r;
+    e.g += g;
+    e.b += b;
+    buckets.set(k, e);
+  }
+  const hex = (e) =>
+    "#" +
+    [e.r, e.g, e.b]
+      .map((x) =>
+        Math.round(x / e.n)
+          .toString(16)
+          .padStart(2, "0"),
+      )
+      .join("");
+  const dominant = [...buckets.values()]
+    .sort((a, b) => b.n - a.n)
+    .slice(0, 3)
+    .map((e) => ({ hex: hex(e), sharePct: +((e.n / cells.length) * 100).toFixed(1) }));
+  // chromatic accent: hue histogram over saturated cells, weighted s·v
+  const bins = Array.from({ length: 12 }, () => ({ w: 0, h: 0, s: 0, v: 0, n: 0 }));
+  let warmW = 0,
+    coolW = 0;
+  for (const [r, g, b] of cells) {
+    const { h, s, v } = rgb2hsv(r, g, b);
+    if (h <= 90 || h >= 330) warmW += s * v;
+    else if (h >= 150 && h <= 300) coolW += s * v;
+    if (s < 0.18 || v < 0.12 || v > 0.97) continue;
+    const bi = Math.floor(h / 30) % 12,
+      w = s * v;
+    const B = bins[bi];
+    B.w += w;
+    B.h += h * w;
+    B.s += s * w;
+    B.v += v * w;
+    B.n++;
+  }
+  const top = bins.reduce((a, b) => (b.w > a.w ? b : a));
+  let accent = null;
+  if (top.w > 0.5 && top.n >= 3) {
+    const h = top.h / top.w,
+      s = top.s / top.w,
+      v = top.v / top.w;
+    // clamp to a readable accent: saturated enough to read as a choice, light enough to sit on video
+    accent = hsv2hex(
+      h,
+      Math.min(0.78, Math.max(0.5, s * 1.2)),
+      Math.min(0.8, Math.max(0.55, v * 1.15)),
+    );
+  }
+  const temperature = warmW > coolW * 1.25 ? "warm" : coolW > warmW * 1.25 ? "cool" : "neutral";
+  return { dominant, accentSuggestion: accent, temperature };
+}
+
+// Laplacian-stdev sharpness proxy of a region crop (full-res)
+async function regionSharpness(imgPath, rect, W, H) {
+  const x = Math.max(0, Math.min(W - 2, Math.round(rect.x))),
+    y = Math.max(0, Math.min(H - 2, Math.round(rect.y)));
+  const w = Math.max(2, Math.min(W - x, Math.round(rect.w))),
+    h = Math.max(2, Math.min(H - y, Math.round(rect.h)));
+  // two passes: crop to a buffer FIRST, then convolve+stats on the crop — sharp's
+  // internal pipeline ordering otherwise convolves/stats the full frame and the two
+  // regions measure identical.
+  const crop = await sharp(imgPath)
+    .extract({ left: x, top: y, width: w, height: h })
+    .png()
+    .toBuffer();
+  const st = await sharp(crop)
+    .greyscale()
+    .convolve({ width: 3, height: 3, kernel: [0, 1, 0, 1, -4, 1, 0, 1, 0], scale: 1, offset: 128 })
+    .stats();
+  return st.channels[0].stdev;
+}
+
+async function sceneOptics(project, bgPath, fgPath, zones, subjectBox, W, H) {
+  let bgSharp = null,
+    subjSharp = null;
+  const bigZone = zones && zones.largest && zones.largest.px;
+  try {
+    if (bigZone && bigZone.w >= 64 && bigZone.h >= 64)
+      bgSharp = await regionSharpness(bgPath, bigZone, W, H);
+  } catch {}
+  try {
+    if (subjectBox && subjectBox.w >= 64)
+      subjSharp = await regionSharpness(bgPath, subjectBox, W, H);
+  } catch {}
+  let suggestedTextBlurPx = 0,
+    ratio = null;
+  if (bgSharp != null && subjSharp != null && subjSharp > 1) {
+    ratio = +(bgSharp / subjSharp).toFixed(3);
+    // strong bokeh → text in that depth plane should soften to match
+    suggestedTextBlurPx = ratio < 0.35 ? 1.6 : ratio < 0.55 ? 1.0 : ratio < 0.8 ? 0.5 : 0;
+  }
+  return {
+    bgSharpness: bgSharp != null ? +bgSharp.toFixed(2) : null,
+    subjSharpness: subjSharp != null ? +subjSharp.toFixed(2) : null,
+    sharpnessRatio: ratio,
+    suggestedTextBlurPx,
+  };
+}
+
+// bright-side estimate from the luminance grid → contact-shadow vector (shadow falls AWAY from light)
+function sceneLighting(lum, occCell, GW, GH) {
+  if (!lum) return null;
+  let sw = 0,
+    sx = 0,
+    sy = 0,
+    n = 0,
+    mean = 0;
+  for (let c = 0; c < GW * GH; c++) {
+    if (!occCell[c]) {
+      mean += lum[c];
+      n++;
+    }
+  }
+  if (!n) return null;
+  mean /= n;
+  for (let y = 0; y < GH; y++)
+    for (let x = 0; x < GW; x++) {
+      const c = y * GW + x;
+      if (occCell[c]) continue;
+      const w = Math.max(0, lum[c] - mean);
+      sw += w;
+      sx += w * (x / GW - 0.5);
+      sy += w * (y / GH - 0.5);
+    }
+  if (sw < 1) return { lightFrom: "flat", shadow: { dx: 0, dy: 3 } };
+  const lx = sx / sw,
+    ly = sy / sw; // light centroid offset from center, −0.5..0.5
+  const mag = Math.hypot(lx, ly);
+  if (mag < 0.04) return { lightFrom: "frontal", shadow: { dx: 0, dy: 3 } };
+  // shadow direction = opposite the light, scaled to a subtle px offset
+  const s = Math.min(1, mag / 0.25);
+  const dx = Math.round((-lx / mag) * 4 * s),
+    dy = Math.round(Math.max(1, (-ly / mag) * 4 * s + 2));
+  const compass =
+    Math.abs(lx) > Math.abs(ly) * 1.8
+      ? lx > 0
+        ? "right"
+        : "left"
+      : Math.abs(ly) > Math.abs(lx) * 1.8
+        ? ly > 0
+          ? "below"
+          : "above"
+        : `${ly > 0 ? "lower" : "upper"}-${lx > 0 ? "right" : "left"}`;
+  return { lightFrom: compass, shadow: { dx, dy } };
+}
+
+// split the transcript into sentence windows (punctuation, or a > 0.7s gap)
+function sentenceWindows(project) {
+  const tp = path.join(project, "transcript.json");
+  if (!fs.existsSync(tp)) return [];
+  let words;
+  try {
+    words = (JSON.parse(fs.readFileSync(tp, "utf8")).words || []).filter((w) => w && "start" in w);
+  } catch {
+    return [];
+  }
+  const out = [];
+  let cur = [];
+  for (let i = 0; i < words.length; i++) {
+    cur.push(words[i]);
+    const w = words[i],
+      nx = words[i + 1];
+    const ends = /[.!?…]$/.test((w.text || "").trim());
+    const gap = nx ? nx.start - w.end > 0.7 : true;
+    if (ends || gap || !nx) {
+      if (cur.length)
+        out.push({
+          in: +cur[0].start.toFixed(2),
+          out: +cur[cur.length - 1].end.toFixed(2),
+          text: cur.map((x) => x.text).join(" "),
+        });
+      cur = [];
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) {
+    console.error("usage: safe-zones.cjs <project-dir> [in out]");
+    process.exit(1);
+  }
+  const fgDir = path.join(project, "frames_fg");
+  if (!fs.existsSync(fgDir)) {
+    console.error(`[safe-zones] no ${fgDir} — run matte.cjs first`);
+    process.exit(2);
+  }
+  if (!sharp) {
+    console.error("[safe-zones] sharp unavailable — set HYPERFRAMES_ROOT");
+    process.exit(0);
+  }
+
+  const frames = fs
+    .readdirSync(fgDir)
+    .filter((f) => /\.png$/i.test(f))
+    .sort();
+  if (!frames.length) {
+    console.error("[safe-zones] no PNG frames");
+    process.exit(2);
+  }
+  const meta = await sharp(path.join(fgDir, frames[0])).metadata();
+  const W = meta.width,
+    H = meta.height;
+  const CELL = Math.max(W, H) / 48;
+  const GW = Math.max(8, Math.round(W / CELL)),
+    GH = Math.max(8, Math.round(H / CELL));
+  let fps = 24;
+  try {
+    const f = parseFloat(
+      String(fs.readFileSync(path.join(project, "matte.fps"), "utf8")).replace(/[^\d.]/g, ""),
+    );
+    if (f > 0) fps = f;
+  } catch {}
+
+  const bgDir = path.join(project, "frames_bg");
+  const hasBg = fs.existsSync(bgDir);
+  // cache evenly-sampled frame grids once (each = per-cell avg subject alpha 0..1,
+  // plus per-cell mean LUMINANCE from frames_bg — bright zones wash out cream/screen text)
+  const sampleIdx = [
+    ...new Set(
+      Array.from({ length: SAMPLES }, (_, i) =>
+        Math.min(frames.length - 1, Math.round((i / (SAMPLES - 1)) * (frames.length - 1))),
+      ),
+    ),
+  ];
+  const grids = [];
+  for (const i of sampleIdx) {
+    const { data, info } = await sharp(path.join(fgDir, frames[i]))
+      .resize(GW, GH, { fit: "fill" })
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+    const ch = info.channels,
+      g = new Float32Array(GW * GH);
+    for (let c = 0; c < GW * GH; c++) g[c] = (ch >= 4 ? data[c * ch + 3] : 255) / 255;
+    let lum = null;
+    if (hasBg && fs.existsSync(path.join(bgDir, frames[i]))) {
+      const { data: bd, info: bi } = await sharp(path.join(bgDir, frames[i]))
+        .resize(GW, GH, { fit: "fill" })
+        .greyscale()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+      const bch = bi.channels;
+      lum = new Float32Array(GW * GH);
+      for (let c = 0; c < GW * GH; c++) lum[c] = bd[c * bch];
+    }
+    grids.push({ t: i / fps, g, lum });
+  }
+  const lumWindow = (t0, t1) => {
+    const acc = new Float32Array(GW * GH);
+    let n = 0;
+    let inWin = grids.filter((s2) => s2.t >= t0 - 1e-6 && s2.t <= t1 + 1e-6 && s2.lum);
+    if (!inWin.length) inWin = grids.filter((s2) => s2.lum);
+    for (const s2 of inWin) {
+      for (let c = 0; c < GW * GH; c++) acc[c] += s2.lum[c];
+      n++;
+    }
+    if (!n) return null;
+    for (let c = 0; c < GW * GH; c++) acc[c] /= n;
+    return acc;
+  };
+  const lumSeriesWindow = (t0, t1) => {
+    let inWin = grids.filter((s2) => s2.t >= t0 - 1e-6 && s2.t <= t1 + 1e-6 && s2.lum);
+    if (!inWin.length) inWin = grids.filter((s2) => s2.lum);
+    return inWin.map((s2) => s2.lum);
+  };
+  const occWindow = (t0, t1) => {
+    const occ = new Float32Array(GW * GH);
+    let inWin = grids.filter((s) => s.t >= t0 - 1e-6 && s.t <= t1 + 1e-6);
+    if (!inWin.length) {
+      // window between samples → use nearest grid
+      const mid = (t0 + t1) / 2;
+      inWin = [grids.reduce((a, b) => (Math.abs(b.t - mid) < Math.abs(a.t - mid) ? b : a))];
+    }
+    for (const s of inWin) for (let c = 0; c < GW * GH; c++) if (s.g[c] > occ[c]) occ[c] = s.g[c];
+    return occ;
+  };
+
+  // ad-hoc window query
+  const qIn = parseFloat(process.argv[3]),
+    qOut = parseFloat(process.argv[4]);
+  if (Number.isFinite(qIn) && Number.isFinite(qOut)) {
+    const a = analyze(
+      occWindow(qIn, qOut),
+      GW,
+      GH,
+      W,
+      H,
+      lumWindow(qIn, qOut),
+      lumSeriesWindow(qIn, qOut),
+    );
+    console.log(
+      `[safe-zones] window ${qIn}-${qOut}s: ${a.recommendation.toUpperCase()}  coverage ${a.coverage}%  clearer:${a.subject.clearerSide}`,
+    );
+    const z = a.zones;
+    for (const k of ["largest", "left", "right", "top"])
+      if (z[k]) console.log(`   ${k}: ${z[k].wPct}%×${z[k].hPct}% @ (${z[k].xPct}%,${z[k].yPct}%)`);
+    console.log(JSON.stringify({ in: qIn, out: qOut, ...a }));
+    return;
+  }
+
+  const globalOcc = occWindow(-1e9, 1e9);
+  const globalLum = lumWindow(-1e9, 1e9);
+  const global = analyze(globalOcc, GW, GH, W, H, globalLum, lumSeriesWindow(-1e9, 1e9));
+  const windows = sentenceWindows(project).map((s) => {
+    const a = analyze(
+      occWindow(s.in, s.out),
+      GW,
+      GH,
+      W,
+      H,
+      lumWindow(s.in, s.out),
+      lumSeriesWindow(s.in, s.out),
+    );
+    return {
+      in: s.in,
+      out: s.out,
+      text: s.text.slice(0, 48),
+      coverage: a.coverage,
+      recommendation: a.recommendation,
+      clearerSide: a.subject.clearerSide,
+      zones: a.zones,
+    };
+  });
+
+  // ── v2: palette / optics / lighting from the mid frame + global grids ───────
+  let palette = null,
+    optics = null,
+    lighting = null;
+  try {
+    const occCellG = new Uint8Array(GW * GH);
+    for (let c = 0; c < GW * GH; c++) occCellG[c] = globalOcc[c] >= THRESH ? 1 : 0;
+    const midName = frames[Math.floor(frames.length / 2)];
+    const midBg = path.join(bgDir, midName);
+    if (hasBg && fs.existsSync(midBg)) {
+      palette = await scenePalette(midBg, occCellG, GW, GH);
+      // subject bbox in px from the global occupancy grid
+      let cx0 = GW,
+        cx1 = -1,
+        cy0 = GH,
+        cy1 = -1;
+      for (let y = 0; y < GH; y++)
+        for (let x = 0; x < GW; x++)
+          if (occCellG[y * GW + x]) {
+            if (x < cx0) cx0 = x;
+            if (x > cx1) cx1 = x;
+            if (y < cy0) cy0 = y;
+            if (y > cy1) cy1 = y;
+          }
+      const subjectBox =
+        cx1 >= 0
+          ? {
+              x: (cx0 / GW) * W,
+              y: (cy0 / GH) * H,
+              w: ((cx1 - cx0 + 1) / GW) * W,
+              h: ((cy1 - cy0 + 1) / GH) * H,
+            }
+          : null;
+      optics = await sceneOptics(
+        project,
+        midBg,
+        path.join(fgDir, midName),
+        global.zones,
+        subjectBox,
+        W,
+        H,
+      );
+      lighting = sceneLighting(globalLum, occCellG, GW, GH);
+    }
+  } catch (e) {
+    console.error(`[safe-zones] scene optics skipped — ${e.message}`);
+  }
+
+  const out = {
+    width: W,
+    height: H,
+    fps,
+    grid: { cols: GW, rows: GH },
+    ...global,
+    palette,
+    optics,
+    lighting,
+    windows,
+  };
+  fs.writeFileSync(path.join(project, "safe-zones.json"), JSON.stringify(out, null, 2));
+
+  const z = (n, zn) =>
+    zn
+      ? `${n}: ${zn.wPct}%×${zn.hPct}% @ (${zn.xPct}%,${zn.yPct}%) [${zn.areaPct}%${zn.meanLuma != null ? ` · luma ${zn.meanLuma}${zn.bright ? " ⚠BRIGHT" : ""}` : ""}]`
+      : `${n}: —`;
+  console.log(
+    `[safe-zones] ${W}×${H} grid ${GW}×${GH} @ ${fps}fps · GLOBAL coverage ${global.coverage}% · clearer ${global.subject.clearerSide} · verdict ${global.recommendation.toUpperCase()}`,
+  );
+  console.log(
+    `             ${z("largest", global.zones.largest)} | ${z("left", global.zones.left)} | ${z("right", global.zones.right)} | ${z("top", global.zones.top)}`,
+  );
+  if (global.recommendation === "embed") {
+    console.log(
+      `[safe-zones] ✅ EMBED — NARRATION planes go in the clean zones (prefer ${global.subject.clearerSide}/top).`,
+    );
+    if (global.heroAnchor)
+      console.log(
+        `[safe-zones] 🎯 HERO → centered ON the subject: plane ≈ x${global.heroAnchor.plane.xPct}% y${global.heroAnchor.plane.yPct}% w${global.heroAnchor.plane.wPct}% center · BIG (~0.22–0.34·h) · target ~30–55% occlusion${global.heroAnchor.bandLuma != null ? ` · band luma ${global.heroAnchor.bandLuma}${global.heroAnchor.washoutRisk ? " ⚠WASHOUT RISK — see heroAnchor.note" : ""}` : ""}`,
+      );
+    if (global.heroBands)
+      console.log(
+        `[safe-zones] hero bands: best top ${global.heroBands.best.topPct}% (predicted occlusion ${global.heroBands.best.occPct}%) · bg-hero ${global.heroBands.feasible ? "FEASIBLE — keep the hero EMBEDDED (fg is last resort)" : "INFEASIBLE (no band ≤62%) → hero fg"}`,
+      );
+    if (global.zones.hugLeft || global.zones.hugRight)
+      console.log(
+        `[safe-zones] hugging zones (narration belongs HERE, abutting the silhouette): L ${global.zones.hugLeft ? global.zones.hugLeft.wPct + "%×" + global.zones.hugLeft.hPct + "%@x" + global.zones.hugLeft.xPct + "%" + (global.zones.hugLeft.bright ? "⚠bright" : "") : "—"} · R ${global.zones.hugRight ? global.zones.hugRight.wPct + "%×" + global.zones.hugRight.hPct + "%@x" + global.zones.hugRight.xPct + "%" + (global.zones.hugRight.bright ? "⚠bright" : "") : "—"}`,
+      );
+  } else {
+    console.log(
+      `[safe-zones] ⚠ FG — subject fills the frame; use caption_layer:"fg" (no clean region to embed behind).`,
+    );
+  }
+  if (palette)
+    console.log(
+      `[safe-zones] 🎨 palette: dominant ${palette.dominant.map((d) => d.hex).join(" ")} · accent suggestion ${palette.accentSuggestion || "— (no chromatic anchor; use the DNA default)"} · ${palette.temperature}`,
+    );
+  if (optics && optics.sharpnessRatio != null)
+    console.log(
+      `[safe-zones] 🔭 depth: bg/subject sharpness ${optics.sharpnessRatio} → embed text blur ${optics.suggestedTextBlurPx}px${optics.suggestedTextBlurPx ? " (match the scene's depth-of-field)" : " (scene is uniformly sharp)"}`,
+    );
+  if (lighting)
+    console.log(
+      `[safe-zones] 💡 light from ${lighting.lightFrom} → contact shadow offset (${lighting.shadow.dx}px, ${lighting.shadow.dy}px)`,
+    );
+  if (windows.length) {
+    console.log(`[safe-zones] per-sentence windows (place each group using ITS window's zones):`);
+    for (const w of windows)
+      console.log(
+        `   [${w.in}-${w.out}s] ${w.recommendation.toUpperCase()} cov ${w.coverage}% clear:${w.clearerSide}  ${w.zones.largest ? `best ${w.zones.largest.wPct}%×${w.zones.largest.hPct}%@(${w.zones.largest.xPct}%,${w.zones.largest.yPct}%)` : ""}  "${w.text}"`,
+      );
+  }
+  console.log(`[safe-zones] → ${path.join(project, "safe-zones.json")}`);
+}
+main().catch((e) => {
+  console.error(`[safe-zones] (skipped — ${e.message})`);
+  process.exit(0);
+});