dsh-hyperframes 0.2.0 → 0.3.1

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * check-overflow.cjs — mode-agnostic frame-overflow WARNING for custom mode.
+ *
+ * Template mode has check-occlusion.cjs (which also flags frame-edge overflow),
+ * but custom mode runs no gates. This is the cheap safety net: it loads the
+ * rendered index.html, seeks the GSAP timeline across the clip, and flags ANY
+ * visible text element (regardless of class) whose box leaves the canvas — i.e.
+ * captions that fall off-frame (the bug we otherwise only catch by eye).
+ *
+ * WARNING ONLY — never fails the build (custom designs may bleed intentionally).
+ * Exit 0 if it ran (with or without findings); exit 3 if it couldn't run.
+ *
+ * Usage: node check-overflow.cjs <project-dir>
+ */
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const HF_ROOTS = [
+  process.env.HYPERFRAMES_ROOT,
+  path.resolve(__dirname, "../../.."),
+  path.join(os.homedir(), "Downloads", "hyperframes"),
+].filter(Boolean);
+let puppeteer = null;
+for (const root of HF_ROOTS) {
+  const cands = [path.join(root, "node_modules", "puppeteer")];
+  const bunDir = path.join(root, "node_modules", ".bun");
+  try {
+    if (fs.existsSync(bunDir)) {
+      for (const d of fs.readdirSync(bunDir))
+        if (d.startsWith("puppeteer@"))
+          cands.push(path.join(bunDir, d, "node_modules", "puppeteer"));
+    }
+  } catch {
+    /* ignore */
+  }
+  for (const p of cands) {
+    try {
+      if (fs.existsSync(p)) {
+        puppeteer = require(p);
+        break;
+      }
+    } catch {}
+  }
+  if (puppeteer) break;
+}
+if (!puppeteer) {
+  console.error("[overflow] puppeteer not found");
+  process.exit(3);
+}
+
+async function main() {
+  const projectDir = process.argv[2];
+  const htmlName = process.argv[3] || "index.html"; // Standard mode passes "rail.html" to gate the rail too
+  const indexPath = path.resolve(projectDir, htmlName);
+  if (!fs.existsSync(indexPath)) {
+    console.error(`[overflow] missing ${indexPath}`);
+    process.exit(2);
+  }
+
+  const html = fs.readFileSync(indexPath, "utf8");
+  const num = (re, d) => {
+    const m = html.match(re);
+    return m ? parseFloat(m[1]) : d;
+  };
+  const W = num(/data-width="([0-9.]+)"/, 1920);
+  const H = num(/data-height="([0-9.]+)"/, 1080);
+  const DUR = num(/data-duration="([0-9.]+)"/, 8);
+
+  const exe =
+    process.platform === "darwin"
+      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      : "/usr/bin/google-chrome";
+  const browser = await puppeteer.launch({
+    headless: "new",
+    executablePath: fs.existsSync(exe) ? exe : undefined,
+    args: [
+      "--disable-web-security",
+      "--allow-file-access-from-files",
+      `--window-size=${W},${H}`,
+      "--disable-dev-shm-usage",
+    ],
+  });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: Math.round(W), height: Math.round(H), deviceScaleFactor: 1 });
+    const waitTL = async () => {
+      const t0 = Date.now();
+      while (Date.now() - t0 < 12000) {
+        if (await page.evaluate(() => !!(window.__timelines && window.__timelines.main)))
+          return true;
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      return false;
+    };
+    await page.goto(`file://${indexPath}`, { waitUntil: "load", timeout: 20000 });
+    let hasTL = await waitTL();
+    if (!hasTL) {
+      // GSAP loads from CDN — a blip leaves no timeline; retry once
+      await page.reload({ waitUntil: "load", timeout: 20000 }).catch(() => {});
+      hasTL = await waitTL();
+    }
+    if (!hasTL) {
+      // NEVER claim "ok" when we couldn't actually evaluate the animated layout.
+      console.error(
+        "[overflow] ⚠ timeline did not register (GSAP CDN blocked?) — overflow check " +
+          "INCONCLUSIVE; eyeball the render for off-frame captions.",
+      );
+      await browser.close();
+      process.exit(0);
+    }
+    await page.evaluate(async () => {
+      try {
+        await document.fonts.ready;
+      } catch {}
+    });
+
+    const times = Array.from({ length: 9 }, (_, i) => +((DUR * i) / 8).toFixed(2));
+    const found = new Map(); // key text → worst offense
+
+    for (const t of times) {
+      await page.evaluate((t) => {
+        window.__timelines.main.seek(t);
+        void document.body.offsetHeight;
+      }, t);
+      await new Promise((r) => setTimeout(r, 25));
+      const offenders = await page.evaluate(
+        (W, H) => {
+          const M = 2; // tolerance px
+          const root = document.querySelector("#stage") || document.body;
+          const out = [];
+          for (const el of root.querySelectorAll("*")) {
+            if (el.tagName === "VIDEO" || el.tagName === "AUDIO") continue;
+            const own = [...el.childNodes]
+              .filter((n) => n.nodeType === 3)
+              .map((n) => n.textContent.trim())
+              .join(" ")
+              .trim();
+            if (!own) continue;
+            const cs = getComputedStyle(el);
+            if (
+              cs.display === "none" ||
+              cs.visibility === "hidden" ||
+              parseFloat(cs.opacity) < 0.06
+            )
+              continue;
+            const b = el.getBoundingClientRect();
+            if (b.width === 0 || b.height === 0) continue;
+            const off = {
+              left: Math.max(0, Math.round(-b.left - M)),
+              right: Math.max(0, Math.round(b.right - W - M)),
+              top: Math.max(0, Math.round(-b.top - M)),
+              bottom: Math.max(0, Math.round(b.bottom - H - M)),
+            };
+            if (off.left || off.right || off.top || off.bottom)
+              out.push({ text: own.slice(0, 42), off });
+          }
+          return out;
+        },
+        W,
+        H,
+      );
+      for (const o of offenders) {
+        const sides = Object.entries(o.off)
+          .filter(([, v]) => v > 0)
+          .map(([s, v]) => `${s} ${v}px`)
+          .join(", ");
+        const prev = found.get(o.text);
+        const score = Object.values(o.off).reduce((a, b) => a + b, 0);
+        if (!prev || score > prev.score) found.set(o.text, { sides, score, t });
+      }
+    }
+
+    if (found.size === 0) {
+      console.log(`[overflow] ok — no caption text leaves the ${W}x${H} frame`);
+    } else {
+      console.error(
+        `[overflow] ⚠ ${found.size} caption(s) leave the frame (custom mode — WARNING only, not blocking):`,
+      );
+      for (const [text, info] of found)
+        console.error(`           "${text}"  → off-frame: ${info.sides}  (@${info.t}s)`);
+      console.error(
+        `[overflow] if unintentional, reposition/resize; if it's deliberate bleed, ignore.`,
+      );
+    }
+  } finally {
+    await browser.close();
+  }
+}
+main().catch((e) => {
+  console.error("[overflow]", e.message);
+  process.exit(3);
+});

package/skills/embedded-captions/scripts/check-rail-climax.cjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/*
+ * check-rail-climax.cjs — enforce the Rail ↔ climax hand-off (PIPELINE.md).
+ *
+ *   node check-rail-climax.cjs <project-dir>
+ *
+ * The embed climax is a PROMOTED word — lifted out of the rail into the hero
+ * layer. It must NEVER also be revealed in the rail. This gate loads index.html
+ * (the climax) and rail.html (the verbatim rail) in headless Chromium, finds the
+ * climax's on-screen window + its word(s), then checks whether the rail reveals
+ * any of those same words DURING that window. If it does, the promoted word is
+ * duplicated on screen → exit 2 (the render aborts). Standard mode only.
+ *
+ * Conservative by design: only a CONFIRMED duplicate fails. Anything we can't
+ * determine (no rail.html, no puppeteer, timeline never registers, no climax)
+ * exits 0 — infra problems never block a render.
+ */
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const HF_ROOTS = [
+  process.env.HYPERFRAMES_ROOT,
+  path.resolve(__dirname, "../../.."),
+  path.join(os.homedir(), "Downloads", "hyperframes"),
+].filter(Boolean);
+
+function findInBun(root, pkg, sub) {
+  const cands = [path.join(root, "node_modules", pkg)];
+  const bunDir = path.join(root, "node_modules", ".bun");
+  try {
+    if (fs.existsSync(bunDir))
+      for (const d of fs.readdirSync(bunDir))
+        if (d.startsWith(pkg + "@")) cands.push(path.join(bunDir, d, "node_modules", pkg));
+  } catch {
+    /* ignore */
+  }
+  for (const c of cands) {
+    const p = sub ? path.join(c, sub) : c;
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+let puppeteer = null,
+  gsapSource = null;
+for (const root of HF_ROOTS) {
+  if (!puppeteer) {
+    const p = findInBun(root, "puppeteer");
+    if (p) {
+      try {
+        puppeteer = require(p);
+      } catch {}
+    }
+  }
+  if (!gsapSource) {
+    const g = findInBun(root, "gsap", path.join("dist", "gsap.min.js"));
+    if (g) gsapSource = fs.readFileSync(g, "utf8");
+  }
+}
+
+const norm = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+const toks = (s) =>
+  String(s)
+    .split(/\s+/)
+    .map(norm)
+    .filter((t) => t.length >= 2);
+
+function ok(msg) {
+  if (msg) console.log(msg);
+  process.exit(0);
+} // can't-determine / pass → never blocks
+function fail(msg) {
+  console.error(msg);
+  process.exit(2);
+}
+
+async function newPage(browser, W, H) {
+  const page = await browser.newPage();
+  await page.setViewport({ width: W, height: H, deviceScaleFactor: 1 });
+  if (gsapSource) {
+    await page.evaluateOnNewDocument(gsapSource);
+    await page.setRequestInterception(true);
+    page.on("request", (req) => {
+      const u = req.url();
+      if (req.resourceType() === "script" && /gsap/i.test(u) && /^https?:/i.test(u)) req.abort();
+      else req.continue();
+    });
+  }
+  return page;
+}
+async function load(page, file) {
+  await page.goto(`file://${file}`, { waitUntil: "load", timeout: 15000 });
+  const start = Date.now();
+  while (Date.now() - start < 12000) {
+    if (await page.evaluate(() => !!(window.__timelines && window.__timelines.main))) {
+      try {
+        await page.evaluate(async () => {
+          await document.fonts.ready;
+        });
+      } catch {}
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return false;
+}
+// visible text of a selector at time t, by seeking the page's main timeline.
+// Visibility must be EFFECTIVE (own opacity × every ancestor's): a rail line that
+// fades out as a CONTAINER leaves its word spans at opacity:1 — checking only the
+// span's own style false-positives on text that is actually invisible.
+async function visibleAt(page, t, selector, childSel) {
+  return page.evaluate(
+    (t, selector, childSel) => {
+      const tl = window.__timelines.main;
+      tl.seek(t);
+      void document.body.offsetHeight;
+      const eff = (el) => {
+        let o = 1,
+          n = el;
+        while (n && n.nodeType === 1) {
+          const cs = getComputedStyle(n);
+          if (cs.display === "none" || cs.visibility === "hidden") return 0;
+          o *= +cs.opacity;
+          n = n.parentElement;
+        }
+        return o;
+      };
+      const out = [];
+      for (const el of document.querySelectorAll(selector)) {
+        if (eff(el) < 0.05) continue;
+        const kids = childSel ? [...el.querySelectorAll(childSel)] : [];
+        if (kids.length) {
+          for (const k of kids) {
+            if (eff(k) > 0.05) out.push(k.textContent);
+          }
+        } else if ((el.textContent || "").trim()) out.push(el.textContent);
+      }
+      return out.join(" ").trim();
+    },
+    t,
+    selector,
+    childSel,
+  );
+}
+
+async function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) ok("[rail-climax] usage: check-rail-climax.cjs <project-dir>");
+  const indexPath = path.join(project, "index.html");
+  const railPath = path.join(project, "rail.html");
+  if (!fs.existsSync(railPath) || !fs.existsSync(indexPath))
+    ok("[rail-climax] no rail.html+index.html — not Standard, skipping");
+  if (!puppeteer) ok("[rail-climax] puppeteer unavailable — skipping (set HYPERFRAMES_ROOT)");
+
+  const exe =
+    process.platform === "darwin"
+      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      : "/usr/bin/google-chrome";
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: "new",
+      executablePath: fs.existsSync(exe) ? exe : undefined,
+      args: ["--disable-web-security", "--allow-file-access-from-files", "--disable-dev-shm-usage"],
+    });
+  } catch (e) {
+    ok(`[rail-climax] could not launch Chromium — skipping (${e.message})`);
+  }
+
+  try {
+    // index.html → climax window + climax word tokens
+    const ip = await newPage(browser, 1920, 1080);
+    if (!(await load(ip, indexPath)))
+      ok("[rail-climax] index timeline never registered — skipping");
+    const dur =
+      +(await ip.evaluate(() => {
+        const r = document.querySelector("#root") || document.querySelector("[data-duration]");
+        return (r && r.dataset && r.dataset.duration) || 0;
+      })) || 30;
+    const STEP = 0.1;
+    const climaxTokens = new Set();
+    let winIn = null,
+      winOut = null;
+    for (let t = 0; t <= dur + 0.001; t += STEP) {
+      const txt = await visibleAt(ip, +t.toFixed(2), ".climax", "span,.w");
+      if (txt) {
+        toks(txt).forEach((w) => climaxTokens.add(w));
+        if (winIn === null) winIn = t;
+        winOut = t;
+      }
+    }
+    if (!climaxTokens.size || winIn === null)
+      ok("[rail-climax] no visible climax found in index.html — skipping");
+
+    // rail.html → words visible during [winIn, winOut]
+    const rp = await newPage(browser, 1920, 1080);
+    if (!(await load(rp, railPath))) ok("[rail-climax] rail timeline never registered — skipping");
+    const hits = new Map(); // token -> first t seen
+    for (let t = Math.max(0, winIn - STEP); t <= winOut + 0.001; t += STEP) {
+      const railToks = new Set(toks(await visibleAt(rp, +t.toFixed(2), ".w", null)));
+      for (const w of climaxTokens) if (railToks.has(w) && !hits.has(w)) hits.set(w, +t.toFixed(2));
+    }
+
+    if (hits.size) {
+      const list = [...hits.entries()]
+        .map(([w, t]) => `"${w}" (rail shows it at t=${t}s)`)
+        .join(", ");
+      fail(
+        `[rail-climax] ✗ DUPLICATE PROMOTED WORD: the climax word(s) ${[...climaxTokens].map((w) => `"${w}"`).join(", ")} ` +
+          `are on screen during the climax window [${winIn.toFixed(2)}–${winOut.toFixed(2)}s], ` +
+          `and the rail ALSO reveals: ${list}.\n` +
+          `  The promoted word must be handed off, never duplicated — see PIPELINE.md "Rail ↔ climax hand-off":\n` +
+          `  freeze the rail before the promoted word, let the climax carry it, hold the climax across the rail's\n` +
+          `  page-flip, and exit it at the end of the thought. The rail must never reveal the promoted word.`,
+      );
+    }
+    console.log(
+      `[rail-climax] ✓ ok — promoted word(s) ${[...climaxTokens].map((w) => `"${w}"`).join(", ")} not duplicated in the rail (window ${winIn.toFixed(2)}–${winOut.toFixed(2)}s)`,
+    );
+  } finally {
+    await Promise.race([browser.close().catch(() => {}), new Promise((r) => setTimeout(r, 8000))]);
+  }
+}
+main()
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error(`[rail-climax] (skipped — ${e.message})`);
+    process.exit(0);
+  });

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/* check-timing.cjs — verify plan.json word timings vs transcript.json (1:1 port of check-timing.py).
+ *   node check-timing.cjs <project-dir> [--strict]
+ */
+const path = require("path");
+const fs = require("fs");
+
+const DRIFT_TOL = 0.08;
+const CREATIVE_SUBS = {
+  "15%": ["fifteen", "percent"],
+  "1/3": ["one", "third"],
+  "2x": ["two", "times"],
+};
+const norm = (s) =>
+  String(s)
+    .replace(/^[ .,?!"']+|[ .,?!"']+$/g, "")
+    .toLowerCase();
+const splitPacked = (t) =>
+  String(t)
+    .split(/<br>|\s+/)
+    .filter(Boolean);
+
+function estimateVerticalBand(css, words, fw, fh) {
+  const top = css.match(/top:\s*(-?[\d.]+)%/);
+  if (!top) return null;
+  const topPct = parseFloat(top[1]);
+  const sizeM = css.match(/font-size:\s*calc\(\s*([\d.]+)\s*\*\s*var\(--h\)\s*\)/);
+  const fontPx = sizeM ? parseFloat(sizeM[1]) * fh : 0.05 * fh;
+  const lhM = css.match(/line-height:\s*([\d.]+)/);
+  const lh = lhM ? parseFloat(lhM[1]) : 1.1;
+  const charW = /uppercase/i.test(css) ? 0.72 : 0.6;
+  let lineCount = 1,
+    cur = 0;
+  const spaceW = fontPx * 0.3;
+  for (const w of words) {
+    const parts = String(w.text).split(/<br>/);
+    parts.forEach((part, i) => {
+      const pw = part.length * fontPx * charW;
+      if (i > 0) {
+        lineCount++;
+        cur = pw;
+      } else {
+        const test = cur + (cur > 0 ? spaceW : 0) + pw;
+        if (test > fw && cur > 0) {
+          lineCount++;
+          cur = pw;
+        } else cur = test;
+      }
+    });
+  }
+  return [topPct, topPct + (100 * (lineCount * fontPx * lh)) / fh];
+}
+
+function check(project, strict) {
+  const plan = JSON.parse(fs.readFileSync(path.join(project, "plan.json"), "utf8"));
+  const t = JSON.parse(fs.readFileSync(path.join(project, "transcript.json"), "utf8"));
+  const seq = (t.words || [])
+    .filter((w) => w.type === "word")
+    .map((w) => [norm(w.text), w.start, w.end]);
+  const issues = [];
+  const fw = plan.width || 720,
+    fh = plan.height || 1290;
+  const groups = plan.groups || [];
+  const bands = groups.map((g) =>
+    g.plane
+      ? [g.id || "?", g.in, g.out, null, true]
+      : [
+          g.id || "?",
+          g.in,
+          g.out,
+          estimateVerticalBand(g.css || "", g.words || [], fw, fh),
+          g.allow_overlap || false,
+        ],
+  );
+  for (let i = 0; i < bands.length; i++) {
+    const [gi, ai, bi, bbi, oki] = bands[i];
+    if (!bbi) continue;
+    for (let j = i + 1; j < bands.length; j++) {
+      const [gj, aj, bj, bbj, okj] = bands[j];
+      if (!bbj || oki || okj) continue;
+      if (Math.min(bi, bj) - Math.max(ai, aj) <= 0.05) continue;
+      if (Math.min(bbi[1], bbj[1]) - Math.max(bbi[0], bbj[0]) > 2.0)
+        issues.push(
+          `[${gi}↔${gj}] groups overlap in time (${Math.max(ai, aj).toFixed(2)}–${Math.min(bi, bj).toFixed(2)}s) AND vertically (band ${Math.max(bbi[0], bbj[0]).toFixed(0)}%–${Math.min(bbi[1], bbj[1]).toFixed(0)}%) — reposition one or add "allow_overlap": true if deliberate.`,
+        );
+    }
+  }
+  let ti = 0;
+  for (const g of groups) {
+    const gid = g.id || "?",
+      gin = g.in,
+      gout = g.out;
+    const ws = (g.words || []).map((w) => w.start),
+      we = (g.words || []).map((w) => w.end);
+    if (ws.length && gin != null) {
+      const e = Math.min(...ws);
+      if (e < gin - 0.01)
+        issues.push(
+          `[${gid}] group.in=${gin.toFixed(2)} but earliest word starts at ${e.toFixed(2)} — word delayed by ${(gin - e >= 0 ? "+" : "") + (gin - e).toFixed(2)}s. Lower group.in.`,
+        );
+    }
+    if (we.length && gout != null) {
+      const l = Math.max(...we);
+      if (l > gout + 0.01)
+        issues.push(
+          `[${gid}] group.out=${gout.toFixed(2)} but latest word ends at ${l.toFixed(2)} — word clipped. Raise group.out.`,
+        );
+    }
+    for (const w of g.words || []) {
+      // Exact pairing: a compiler that KNOWS the transcript index emits `ti` —
+      // duplicate words then pair by POSITION, not text-search (which grabs the
+      // first occurrence and reports a phantom drift). Sanity-check the text; on
+      // mismatch fall back to the text matcher below.
+      if (
+        Number.isInteger(w.ti) &&
+        seq[w.ti] &&
+        seq[w.ti][0] === norm(splitPacked(w.text)[0] || "")
+      ) {
+        const drift = w.start - seq[w.ti][1];
+        if (Math.abs(drift) > DRIFT_TOL)
+          issues.push(
+            `[${gid}] '${norm(w.text)}': plan=${w.start.toFixed(3)} transcript=${seq[w.ti][1].toFixed(3)} drift ${(drift >= 0 ? "+" : "") + drift.toFixed(3)}s`,
+          );
+        ti = w.ti + 1;
+        continue;
+      }
+      const parts = splitPacked(w.text).map(norm);
+      parts.forEach((part, pi) => {
+        if (!part) return;
+        if (part in CREATIVE_SUBS) {
+          for (const sub of CREATIVE_SUBS[part]) {
+            const j = seq.findIndex((s, k) => k >= ti && s[0] === sub);
+            if (j >= 0) ti = j + 1;
+          }
+          return;
+        }
+        let found = seq.findIndex((s, k) => k >= ti && s[0] === part);
+        if (found < 0) found = seq.findIndex((s) => s[0] === part);
+        if (found < 0) {
+          issues.push(`[${gid}] '${part}': NOT IN TRANSCRIPT (plan start=${w.start.toFixed(3)})`);
+          return;
+        }
+        const ts = seq[found][1];
+        ti = found + 1;
+        if (pi === 0) {
+          const drift = w.start - ts;
+          if (Math.abs(drift) > DRIFT_TOL)
+            issues.push(
+              `[${gid}] '${part}': plan=${w.start.toFixed(3)} transcript=${ts.toFixed(3)} drift ${(drift >= 0 ? "+" : "") + drift.toFixed(3)}s`,
+            );
+        } else
+          issues.push(
+            `[${gid}] '${part}' packed with '${parts[0]}': transcript=${ts.toFixed(3)} but entry has no distinct timing — split into separate word entries`,
+          );
+      });
+    }
+  }
+  const name = path.basename(project);
+  if (!issues.length) {
+    console.log(`${name}: timing OK ✓ (${seq.length} transcript words)`);
+    return 0;
+  }
+  console.log(`${name}: ${issues.length} timing issue(s):`);
+  for (const i of issues) console.log(`  ${i}`);
+  return strict ? 1 : 0;
+}
+
+const args = process.argv.slice(2).filter((a) => a !== "--strict");
+if (!args.length) {
+  console.error("usage: check-timing.cjs <project-dir> [--strict]");
+  process.exit(2);
+}
+process.exit(check(path.resolve(args[0]), process.argv.includes("--strict")));