dsh-hyperframes 0.1.1 → 0.3.0

package/skills/embedded-captions/scripts/fill-timings.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/*
+ * fill-timings.cjs — fill plan.json group/word times DIRECTLY from transcript.json,
+ * by SEQUENCE (Cinematic mode). Kills the timing-drift + duplicate-word class of
+ * occlusion/timing-gate re-tries: the agent only decides the GROUPING (which words form
+ * each group, in spoken order); times come from the transcript by position, so the
+ * second "and"/"actions" matches the right occurrence (text-matching pairs the wrong one).
+ *
+ *   node fill-timings.cjs <project-dir>
+ *
+ * Reads  <project>/plan.json (groups[].words[].text, in spoken order) + transcript.json.
+ * Writes <project>/plan.json with each word's start/end and each group's in/out filled.
+ * A group word that can't be matched keeps whatever time it had + is reported (so a typo
+ * or an added word degrades gracefully instead of silently mis-timing).
+ */
+const path = require("path");
+const fs = require("fs");
+
+const norm = (s) =>
+  String(s == null ? "" : s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+const LOOKAHEAD = 40; // how far past the pointer to search for a group word (skips dropped fillers)
+
+function fillGroup(g, tw, state) {
+  const matched = [];
+  const unmatched = [];
+  for (const w of g.words || []) {
+    const target = norm(w.text);
+    if (!target) {
+      unmatched.push(w.text);
+      continue;
+    }
+    let found = -1;
+    for (let j = state.p; j < Math.min(tw.length, state.p + LOOKAHEAD); j++) {
+      if (norm(tw[j].text) === target) {
+        found = j;
+        break;
+      }
+    }
+    if (found >= 0) {
+      w.start = tw[found].start;
+      w.end = tw[found].end;
+      matched.push(w);
+      state.p = found + 1;
+    } else {
+      unmatched.push(w.text);
+    }
+  }
+  if (matched.length) {
+    const firstStart = +matched[0].start.toFixed(3);
+    const lastEnd = +matched[matched.length - 1].end.toFixed(3);
+    // WORD start/end are filled above (deterministic). For the group's DISPLAY window we
+    // only GUARANTEE it brackets the words (never clip a word) — we do NOT tighten it:
+    // a deliberately later `out` is the apex HOLD / sentence ACCUMULATION the author set,
+    // and an earlier `in` is a pre-entry. Preserve both; clamp only if they'd clip.
+    g.in = g.in == null ? firstStart : Math.min(g.in, firstStart);
+    g.out = g.out == null ? lastEnd : Math.max(g.out, lastEnd);
+  }
+  return { matched: matched.length, unmatched };
+}
+
+function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) {
+    console.error("usage: fill-timings.cjs <project-dir>");
+    process.exit(1);
+  }
+  const planPath = path.join(project, "plan.json");
+  const trPath = path.join(project, "transcript.json");
+  let plan, trWordsRaw;
+  try {
+    plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+  } catch {
+    console.error(`[fill-timings] no plan.json (Cinematic only) — skipping`);
+    process.exit(0);
+  }
+  try {
+    trWordsRaw = JSON.parse(fs.readFileSync(trPath, "utf8")).words || [];
+  } catch {
+    console.error(`[fill-timings] no transcript.json — skipping`);
+    process.exit(0);
+  }
+  const tw = trWordsRaw.filter((w) => w && "start" in w && "end" in w);
+  if (!tw.length) {
+    console.error(`[fill-timings] transcript has no word timings — skipping`);
+    process.exit(0);
+  }
+
+  const state = { p: 0 };
+  let totalMatched = 0,
+    totalUnmatched = 0;
+  const groups = plan.groups || [];
+  // crown_group (if any) is spoken last in the standard templates; process groups in order, crown after.
+  const ordered = [...groups];
+  for (const g of ordered) {
+    const r = fillGroup(g, tw, state);
+    totalMatched += r.matched;
+    totalUnmatched += r.unmatched.length;
+    if (r.unmatched.length)
+      console.error(
+        `[fill-timings] ⚠ ${g.id || "(group)"}: ${r.unmatched.length} word(s) not found in transcript from here: ${r.unmatched.join(" ")}`,
+      );
+  }
+  if (plan.crown_group) {
+    const r = fillGroup(plan.crown_group, tw, state);
+    totalMatched += r.matched;
+    totalUnmatched += r.unmatched.length;
+    if (r.unmatched.length)
+      console.error(`[fill-timings] ⚠ crown_group: ${r.unmatched.join(" ")} not found`);
+  }
+
+  fs.writeFileSync(planPath, JSON.stringify(plan, null, 2));
+  console.log(
+    `[fill-timings] filled ${totalMatched} word time(s) from transcript by sequence` +
+      (totalUnmatched
+        ? `; ${totalUnmatched} unmatched (kept prior time — check those words)`
+        : `; all matched ✓`),
+  );
+  console.log(
+    `[fill-timings] group windows now: ${ordered.map((g) => `${g.id || "?"}[${g.in}-${g.out}]`).join(" ")}`,
+  );
+}
+main();

package/skills/embedded-captions/scripts/fit-fonts.cjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/*
+ * fit-fonts.cjs — shrink any plan.json caption group whose single line would overflow
+ * its box, BEFORE render (Cinematic mode). Kills the "font too big → off-frame → shrink
+ * → re-render" overflow round. Estimates rendered width from character count × a
+ * per-family advance × the group's font-size, compares to the group's box width (its
+ * plane width, else the frame), and only ever SHRINKS to fit. Approximate by design —
+ * it prevents gross overflow; check-overflow.cjs remains the exact terminal check.
+ *
+ *   node fit-fonts.cjs <project-dir>
+ */
+const path = require("path");
+const fs = require("fs");
+
+// rough per-family advance (em per char, caps-ish). Condensed faces are narrow; pixel
+// faces wide. Default is conservative. (Estimate only — gate confirms.)
+const ADV = {
+  anton: 0.44,
+  oswald: 0.45,
+  teko: 0.4,
+  "saira stencil one": 0.46,
+  "bebas neue": 0.4,
+  "press start 2p": 1.05,
+  vt323: 0.52,
+  monoton: 0.62,
+  "special elite": 0.55,
+  "jetbrains mono": 0.6,
+  "space mono": 0.6,
+  "ibm plex mono": 0.6,
+  "source code pro": 0.6,
+  "archivo black": 0.62,
+  bangers: 0.5,
+  "bodoni moda": 0.5,
+  "playfair display": 0.52,
+  cinzel: 0.62,
+  "cormorant garamond": 0.45,
+  fredoka: 0.55,
+  "baloo 2": 0.55,
+  "permanent marker": 0.55,
+  caveat: 0.4,
+  orbitron: 0.66,
+  sora: 0.54,
+  "space grotesk": 0.54,
+};
+const DEFAULT_ADV = 0.56;
+
+const cssVal = (css, prop) => {
+  const m = String(css || "").match(new RegExp(prop + "\\s*:\\s*([^;}]+)", "i"));
+  return m ? m[1].trim() : null;
+};
+function familyOf(css) {
+  const v = cssVal(css, "font-family");
+  if (!v) return "inter";
+  return v
+    .split(",")[0]
+    .trim()
+    .replace(/^['"]|['"]$/g, "")
+    .toLowerCase();
+}
+function sizePxOf(css, H) {
+  const v = cssVal(css, "font-size");
+  if (!v) return null;
+  let m;
+  if ((m = v.match(/calc\(\s*([\d.]+)\s*\*\s*var\(--h\)\s*\)/i))) return parseFloat(m[1]) * H;
+  if ((m = v.match(/([\d.]+)\s*cqh/i))) return (parseFloat(m[1]) / 100) * H;
+  if ((m = v.match(/([\d.]+)\s*vh/i))) return (parseFloat(m[1]) / 100) * H;
+  if ((m = v.match(/([\d.]+)\s*px/i))) return parseFloat(m[1]);
+  return null;
+}
+function planeWidthPx(plan, plane, W) {
+  const p = plan.planes && plan.planes[plane];
+  const css = p && (typeof p === "string" ? p : p.css);
+  const v = cssVal(css, "width");
+  if (!v) return null;
+  let m;
+  if ((m = v.match(/([\d.]+)\s*%/))) return (parseFloat(m[1]) / 100) * W;
+  if ((m = v.match(/([\d.]+)\s*px/))) return parseFloat(m[1]);
+  return null;
+}
+function setFontSize(css, fracOfH) {
+  const decl = `font-size: calc(${fracOfH.toFixed(3)} * var(--h))`;
+  if (/font-size\s*:/i.test(css || "")) return String(css).replace(/font-size\s*:\s*[^;}]+/i, decl);
+  return (css ? css.replace(/\s*$/, "").replace(/;?\s*$/, "; ") : "") + decl + ";";
+}
+
+function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) {
+    console.error("usage: fit-fonts.cjs <project-dir>");
+    process.exit(1);
+  }
+  const planPath = path.join(project, "plan.json");
+  let plan;
+  try {
+    plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+  } catch {
+    console.error("[fit-fonts] no plan.json (Cinematic only) — skipping");
+    process.exit(0);
+  }
+  const W = plan.width || 1920,
+    H = plan.height || 1080;
+  const groups = (plan.groups || []).concat(plan.crown_group ? [plan.crown_group] : []);
+  const MARGIN = 0.92; // leave 8% breathing room inside the box
+  const HERO_MIN_FRAC = 0.18; // a hero below ~0.18·h isn't "big" — keep it punchy, widen its box instead
+
+  let changed = 0;
+  for (const g of groups) {
+    const text = (g.words || []).map((w) => w.text).join(" ");
+    const nChars = text.replace(/\s/g, "").length + (g.words || []).length * 0.5; // glyphs + ~half-space gaps
+    if (nChars < 1) continue;
+    const fam = familyOf(g.css);
+    let adv = ADV[fam] ?? DEFAULT_ADV;
+    if (/text-transform\s*:\s*uppercase/i.test(g.css || "") || text === text.toUpperCase())
+      adv *= 1.05;
+    const sizePx = sizePxOf(g.css, H);
+    if (!sizePx) continue; // no explicit size → template default handles it
+    const boxW = (g.plane ? planeWidthPx(plan, g.plane, W) : null) || W;
+    const usable = boxW * MARGIN;
+    // A WRAPPING group only overflows if a SINGLE word is wider than the box (the rest
+    // wraps). A NOWRAP group must fit its whole line. So don't shrink wrapping narration
+    // down to one line — only force the whole line for nowrap; else just the longest word.
+    const nowrap = /white-space\s*:\s*nowrap/i.test(g.css || "");
+    const longestWord = (g.words || []).reduce(
+      (m, w) => Math.max(m, String(w.text || "").replace(/\s/g, "").length),
+      0,
+    );
+    const constrainChars = nowrap ? nChars : longestWord;
+    if (constrainChars < 1) continue;
+    const estW = constrainChars * adv * sizePx;
+    if (estW > usable) {
+      const newPx = usable / (constrainChars * adv);
+      let frac = Math.max(0.02, newPx / H);
+      const isHero = g.hero === true || /^(hero|crown)$/i.test(g.plane || "");
+      if (isHero && frac < HERO_MIN_FRAC) {
+        // The hero must stay BIG. If it won't fit its box while staying punchy, the BOX is
+        // too narrow (the hero should span the subject) — keep it at the floor + flag it,
+        // rather than silently shrinking the peak into a small word.
+        frac = HERO_MIN_FRAC;
+        g.css = setFontSize(g.css, frac);
+        changed++;
+        console.log(
+          `[fit-fonts] ⚠ ${g.id || "(group)"} HERO "${text.slice(0, 28)}" won't fit box ${Math.round(usable)}px while staying big → KEPT at floor ${frac}·h. WIDEN the hero plane (it should span the subject, centered), not shrink the peak.`,
+        );
+        continue;
+      }
+      g.css = setFontSize(g.css, frac);
+      changed++;
+      console.log(
+        `[fit-fonts] ${g.id || "(group)"}: "${text.slice(0, 28)}" (${nowrap ? "nowrap line" : "longest word"}) est ${Math.round(estW)}px > box ${Math.round(usable)}px → shrink to ${frac.toFixed(3)}·h (${Math.round(newPx)}px)`,
+      );
+    }
+  }
+  if (changed) {
+    fs.writeFileSync(planPath, JSON.stringify(plan, null, 2));
+    console.log(`[fit-fonts] shrank ${changed} group(s) to fit; wrote plan.json`);
+  } else console.log("[fit-fonts] all groups fit their box — no change");
+}
+main();

package/skills/embedded-captions/scripts/gen-stroke-path.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""gen-stroke-path.py — generalized draw-on path generator.
+
+Lays out ANY word in a single-line (pen-path) SVG font — Hershey/EMS — and emits
+one continuous-dash-revealable path `d`. The glyph data IS the pen path, so
+stroke-order reveal is exact by construction for any text, no per-word tuning.
+
+Usage: gen-stroke-path.py <font.svg> <text> <target_width_px> <baseline_y> <x0>
+Prints: the path `d` string + layout info on stderr.
+"""
+import re, sys
+
+# Windows sizes stdio to the ANSI code page (cp1252). These scripts emit UTF-8 on
+# every platform; say so rather than depending on the console's code page. Carry
+# `errors` across: reconfigure() resets it to "strict", and CPython deliberately gives
+# stderr "backslashreplace" so the diagnostic path can never itself raise.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+font_path, text, target_w, baseline_y, x0 = (
+    sys.argv[1], sys.argv[2], float(sys.argv[3]), float(sys.argv[4]), float(sys.argv[5]))
+
+# SVG fonts are UTF-8 and each glyph's `unicode="…"` attribute IS a literal character.
+# Decoded with the platform default, a non-ASCII glyph key silently becomes the wrong
+# character (or raises) on Windows, so that glyph never matches the requested text.
+svg = open(font_path, encoding="utf-8").read()
+glyphs = {}
+for m in re.finditer(r'<glyph\s+unicode="(.)"[^>]*?horiz-adv-x="([\d.]+)"(?:[^>]*?d="([^"]*)")?', svg):
+    ch, adv, d = m.group(1), float(m.group(2)), m.group(3) or ""
+    glyphs[ch] = (adv, d)
+# default advance for space
+space_adv = glyphs.get(" ", (300, ""))[0]
+
+# total advance width in font units
+total = 0.0
+for ch in text:
+    total += glyphs.get(ch, (space_adv, ""))[0]
+s = target_w / total                       # scale font-units → px
+
+out = []
+cursor = 0.0
+NUM = re.compile(r"[-\d.]+")
+for ch in text:
+    adv, d = glyphs.get(ch, (space_adv, ""))
+    if d:
+        # polylines only (M/L): transform every coordinate pair
+        toks = re.findall(r"([ML])\s+([-\d.]+)\s+([-\d.]+)", d)
+        for cmd, xs, ys in toks:
+            x = x0 + (cursor + float(xs)) * s
+            y = baseline_y - float(ys) * s          # SVG-font y is UP; flip
+            out.append(f"{cmd} {x:.1f} {y:.1f}")
+    cursor += adv
+
+print(" ".join(out))
+print(f"[gen] chars={len(text)} scale={s:.3f} width={total*s:.0f}px "
+      f"subpaths={sum(1 for o in out if o.startswith('M'))}", file=sys.stderr)

package/skills/embedded-captions/scripts/inject-fonts.cjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/*
+ * inject-fonts.cjs — inline the @font-face blocks each HTML actually uses.
+ *
+ *   node inject-fonts.cjs <project-dir> [file.html ...]
+ *
+ * hyperframes' renderer only auto-supplies its ~18 CANONICAL_FONTS. Every other
+ * family (Anton, Bangers, VT323, Press Start 2P, …) falls back to a generic font
+ * unless the HTML ships a local @font-face — even when it "looks fine" locally,
+ * because that only works when the font happens to be installed as a system font.
+ * On a clean/offline/CI machine it silently degrades. (hyperframes' own font
+ * linter flags exactly this: font_family_without_font_face.)
+ *
+ * This step reads the bundled font library (modes/standard/fonts/fonts.css —
+ * base64 woff2, no sub-resources), finds which of those families the HTML uses,
+ * and inlines just those @font-face blocks into a <style id="hf-embedded-fonts">.
+ * Idempotent (re-running replaces the block). Families already declared in the
+ * HTML, hyperframes-canonical families, and CSS generics are left untouched.
+ *
+ * Runs BEFORE the layout gates + render so measure-layout and the capture both
+ * see the real glyph metrics, never a fallback.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const SKILL_ROOT = path.resolve(__dirname, "..");
+const FONTS_CSS = path.join(SKILL_ROOT, "modes", "standard", "fonts", "fonts.css");
+const MARKER = "hf-embedded-fonts";
+
+const GENERIC = new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-serif",
+  "ui-sans-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "math",
+  "emoji",
+  "fangsong",
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "revert-layer",
+]);
+
+// Parse fonts.css → Map<lowercased family, [ @font-face block strings ]>.
+function loadFontLibrary() {
+  let css;
+  try {
+    css = fs.readFileSync(FONTS_CSS, "utf8");
+  } catch {
+    console.error(
+      `[inject-fonts] missing ${FONTS_CSS} — run modes/standard/fonts/build-fonts-css.cjs`,
+    );
+    process.exit(2);
+  }
+  const lib = new Map();
+  // base64 data-URIs contain no "}", so [^}]* safely bounds a block.
+  const blockRe = /@font-face\s*\{[^}]*\}/gi;
+  const famRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
+  let m;
+  while ((m = blockRe.exec(css)) !== null) {
+    const fam = m[0].match(famRe);
+    if (!fam) continue;
+    const key = fam[2].trim().toLowerCase();
+    if (!lib.has(key)) lib.set(key, []);
+    lib.get(key).push(m[0]);
+  }
+  return lib;
+}
+
+// Families referenced anywhere in the HTML: CSS `font-family:` (in <style> or
+// inline style="") and the data-font-family attribute hyperframes also honors.
+function usedFamilies(html) {
+  const out = new Set();
+  const add = (stack) => {
+    for (const part of String(stack).split(",")) {
+      const name = part
+        .trim()
+        .replace(/^['"]|['"]$/g, "")
+        .trim()
+        .toLowerCase();
+      if (name && !GENERIC.has(name) && !/^var\(/.test(name)) out.add(name);
+    }
+  };
+  // strip existing @font-face so we don't re-list the family it declares
+  const body = html.replace(/@font-face\s*\{[^}]*\}/gi, "");
+  for (const mm of body.matchAll(/font-family\s*:\s*([^;}{]+)/gi)) add(mm[1]);
+  for (const mm of html.matchAll(/data-font-family\s*=\s*["']([^"']+)["']/gi)) add(mm[1]);
+  return out;
+}
+
+// Families the HTML ALREADY declares via @font-face — leave those alone.
+function declaredFamilies(html) {
+  const out = new Set();
+  const famRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
+  for (const mm of html.matchAll(/@font-face\s*\{[^}]*\}/gi)) {
+    const f = mm[0].match(famRe);
+    if (f) out.add(f[2].trim().toLowerCase());
+  }
+  return out;
+}
+
+function injectInto(file, lib) {
+  let html;
+  try {
+    html = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  // drop any previous injection so this is idempotent
+  html = html.replace(new RegExp(`\\s*<style id="${MARKER}">[\\s\\S]*?</style>`, "i"), "");
+
+  const used = usedFamilies(html);
+  const already = declaredFamilies(html);
+  const blocks = [];
+  const inlined = [];
+  for (const fam of used) {
+    if (already.has(fam)) continue;
+    const lb = lib.get(fam);
+    if (!lb) continue; // canonical / system / unknown — not ours to supply
+    blocks.push(...lb);
+    inlined.push(fam);
+  }
+  if (!blocks.length) {
+    fs.writeFileSync(file, html);
+    return { file: path.basename(file), inlined: [] };
+  }
+  const style = `<style id="${MARKER}">\n/* auto-embedded by inject-fonts.cjs — deterministic template fonts */\n${blocks.join("\n")}\n</style>`;
+  // Prefer right after <head...>; fall back to before </head>, then <html>, then prepend.
+  if (/<head[^>]*>/i.test(html)) html = html.replace(/<head[^>]*>/i, (m0) => `${m0}\n${style}`);
+  else if (/<\/head>/i.test(html)) html = html.replace(/<\/head>/i, `${style}\n</head>`);
+  else if (/<html[^>]*>/i.test(html))
+    html = html.replace(/<html[^>]*>/i, (m0) => `${m0}\n${style}`);
+  else html = style + "\n" + html;
+
+  fs.writeFileSync(file, html);
+  return { file: path.basename(file), inlined };
+}
+
+function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) {
+    console.error("usage: inject-fonts.cjs <project-dir> [file.html ...]");
+    process.exit(1);
+  }
+  const lib = loadFontLibrary();
+  let files = process.argv.slice(3);
+  if (!files.length) files = ["index.html", "rail.html", "index_fg.html"];
+  files = files.map((f) => (path.isAbsolute(f) ? f : path.join(project, f)));
+
+  let touched = 0;
+  for (const f of files) {
+    const r = injectInto(f, lib);
+    if (r == null) continue;
+    if (r.inlined.length) {
+      console.log(`[inject-fonts] ${r.file}: embedded ${r.inlined.join(", ")}`);
+      touched++;
+    } else console.log(`[inject-fonts] ${r.file}: no non-canonical fonts to embed`);
+  }
+  if (!touched)
+    console.log(`[inject-fonts] nothing embedded (all fonts canonical/system or already declared)`);
+}
+main();