dsh-hyperframes 0.9.1 → 0.9.2

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

@@ -1,195 +0,0 @@
-#!/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.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
-  process.env.HYPERFRAMES_ROOT,
-  path.resolve(__dirname, "../../.."),
-  path.join(os.homedir(), "Downloads", "hyperframes"),
-].filter(Boolean);
-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

@@ -1,237 +0,0 @@
-#!/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.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
-  process.env.HYPERFRAMES_ROOT,
-  path.resolve(__dirname, "../../.."),
-  path.join(os.homedir(), "Downloads", "hyperframes"),
-].filter(Boolean);
-
-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 (install project dependencies per embedded-captions SKILL.md Runtime prerequisites)",
-    );
-
-  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

@@ -1,173 +0,0 @@
-#!/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")));