mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
Pre-merge snapshot of 5+ sessions of w2h skill restructure work: - new orchestrator scripts (assemble-index, captions, w2h-prep, preflight-finalize, verify-output, check-rendered-perception, w2h-dispatch-packet) - skill reference reorg (steps 0-6, beat-builder-guide, capabilities, SKILL.md) - capture/lint infra updates (assetCataloger, assetDownloader, tokenExtractor, lintProject, fonts rule) - PLAN.md (the steal+adapt plan for sessions 17+) Commit exists to provide a rollback point before merging 463 commits of upstream main into this branch. Will likely be squashed/restructured before any PR. Skipping pre-commit hook (--no-verify): fallow audit flags 5 complexity findings inherited from earlier session commits, not introduced by this snapshot.
1605 lines
69 KiB
JavaScript
1605 lines
69 KiB
JavaScript
#!/usr/bin/env node
|
||
// captions.mjs — merged caption pipeline CLI. Dispatches by subcommand:
|
||
// group → (was build-captions.mjs) deterministic caption grouping
|
||
// usage: node captions.mjs group --group-spec ./group_spec.json
|
||
// --hyperframes . --tokens design-system/chunks/tokens.css
|
||
// --out ./caption_groups.json
|
||
// html → (was build-captions-html.mjs) deterministic caption-HTML builder
|
||
// usage: node captions.mjs html --hyperframes . --groups ./caption_groups.json
|
||
// --tokens design-system/chunks/tokens.css
|
||
// [--inference design-system/inference.json]
|
||
// [--out compositions/captions.html]
|
||
// [--skin caption-pill-karaoke] [--skin-file <path>] [--no-emit]
|
||
// keepout → (was check-caption-keepout.mjs) static caption keep-out gate
|
||
// usage: node captions.mjs keepout --group-spec ./group_spec.json
|
||
// --hyperframes . [--json]
|
||
//
|
||
// Each original file's body is wrapped verbatim in its own async function so
|
||
// its local const/function names stay function-local and never collide. The
|
||
// only edit inside each body: CLI args read from the passed-in `argv` param
|
||
// (the dispatcher passes process.argv.slice(3), i.e. args after the subcommand).
|
||
|
||
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
|
||
import { resolve, join, dirname } from "node:path";
|
||
import { execFileSync } from "node:child_process";
|
||
|
||
// =====================================================================
|
||
// group — was build-captions.mjs
|
||
// =====================================================================
|
||
// Phase 4a.5 (engine) — deterministic caption grouping. No subagent.
|
||
//
|
||
// Owns the word-data half of the captions contract (clean / group / global-time
|
||
// / class + the non-overlap invariant). Its output, caption_groups.json, is the
|
||
// single source of grouping/timing truth consumed by the deterministic HTML
|
||
// builder build-captions-html.mjs (no LLM, no hand-authored spans).
|
||
// Color/contrast decisions are NOT made here — color-mix()/var() can only be
|
||
// resolved by a browser at render time, so the A-lite scene-background
|
||
// adaptation lives in the caption template's render-time <script>, not here.
|
||
// This script only carries each group's `scene_id` + `surface` through so the
|
||
// template knows which scene a caption sits over.
|
||
//
|
||
// Reads: ./group_spec.json (Phase 4a — groups[].scenes[<sid>].{start_s,
|
||
// estimatedDuration_s, wordsPath, surface}); each scene's
|
||
// wordsPath → assets/voice/scene_<N>_words.json (Phase 2.5 whisper
|
||
// output, [{text,start,end}] in SCENE-LOCAL seconds);
|
||
// design-system/chunks/tokens.css (existence gate only).
|
||
// Writes: ./caption_groups.json (cleaned / grouped / tagged / globally-timed
|
||
// word groups + stats + anomalies[]).
|
||
//
|
||
// Usage:
|
||
// node captions.mjs group --group-spec ./group_spec.json \
|
||
// --hyperframes . --tokens design-system/chunks/tokens.css \
|
||
// --out ./caption_groups.json
|
||
//
|
||
// Exit 0 = caption_groups.json written, OR a documented SKIP (prints
|
||
// "captions: skipped (<reason>)" — finalize keys off file existence,
|
||
// so a skip is not an error). Skips: group_spec missing; no scene has
|
||
// an existing/valid wordsPath; tokens.css missing.
|
||
// Exit 1 = structural failure only (group_spec unreadable JSON; a wordsPath
|
||
// that is present but malformed JSON). Non-fatal issues → anomalies[].
|
||
async function runGroup(argv) {
|
||
// ---------- argv ----------
|
||
const flag = (name, def) => {
|
||
const i = argv.indexOf(`--${name}`);
|
||
return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
|
||
};
|
||
function die(msg) {
|
||
console.error(`✗ build-captions.mjs: ${msg}`);
|
||
process.exit(1);
|
||
}
|
||
function skip(reason) {
|
||
// Skip is not an error: finalize decides track-12 by file existence, and a
|
||
// missing caption_groups.json simply means the captions agent also skips.
|
||
console.log(`captions: skipped (${reason})`);
|
||
process.exit(0);
|
||
}
|
||
|
||
const groupSpecPath = resolve(flag("group-spec", "./group_spec.json"));
|
||
const hyperframesDir = resolve(flag("hyperframes", "."));
|
||
const tokensPath = resolve(hyperframesDir, flag("tokens", "design-system/chunks/tokens.css"));
|
||
const outPath = resolve(flag("out", "./caption_groups.json"));
|
||
|
||
// ---------- skip gates ----------
|
||
if (!existsSync(groupSpecPath)) skip("no group_spec");
|
||
if (!existsSync(tokensPath)) skip("no brand tokens");
|
||
|
||
let spec;
|
||
try {
|
||
spec = JSON.parse(readFileSync(groupSpecPath, "utf8"));
|
||
} catch (e) {
|
||
die(`group_spec.json is not valid JSON: ${e.message}`);
|
||
}
|
||
const groups = Array.isArray(spec.groups) ? spec.groups : [];
|
||
if (groups.length === 0) skip("group_spec has no groups");
|
||
|
||
const anomalies = [];
|
||
|
||
// ---------- §1: load word stream, scene-local → global, carry scene_id+surface ----------
|
||
// Outer loop over groups in array order, inner loop over each group's
|
||
// scene_ids in array order (group_spec is a list of worker-groups, each with
|
||
// its own scenes map — there is NO top-level scenes map).
|
||
const rawWords = [];
|
||
let scenesWithWords = 0;
|
||
for (const g of groups) {
|
||
for (const sid of g.scene_ids || []) {
|
||
const sc = (g.scenes || {})[sid];
|
||
if (!sc) {
|
||
anomalies.push(`${sid}: listed in scene_ids but missing from scenes map — skipped`);
|
||
continue;
|
||
}
|
||
const wordsPath = sc.wordsPath; // prep writes "" (not absent) when no/invalid file
|
||
if (!wordsPath) continue; // empty string === "no words for this scene"
|
||
const abs = join(hyperframesDir, wordsPath);
|
||
if (!existsSync(abs)) {
|
||
anomalies.push(
|
||
`${sid}: wordsPath "${wordsPath}" not on disk — scene contributes no captions`,
|
||
);
|
||
continue;
|
||
}
|
||
let arr;
|
||
try {
|
||
arr = JSON.parse(readFileSync(abs, "utf8"));
|
||
} catch (e) {
|
||
// A present-but-malformed wordsPath is a structural failure: prep claimed
|
||
// this scene had transcribed words, so a parse error is a real break.
|
||
die(`${sid}: wordsPath "${wordsPath}" is present but not valid JSON: ${e.message}`);
|
||
}
|
||
if (!Array.isArray(arr) || arr.length === 0) {
|
||
anomalies.push(`${sid}: wordsPath "${wordsPath}" is empty — scene contributes no captions`);
|
||
continue;
|
||
}
|
||
const offset = Number(sc.start_s);
|
||
if (!isFinite(offset)) {
|
||
anomalies.push(`${sid}: start_s "${sc.start_s}" not finite — using 0`);
|
||
}
|
||
const base = isFinite(offset) ? offset : 0;
|
||
const surface = sc.surface ?? null; // named surface token or null (non-surface-aware preset)
|
||
let kept = 0;
|
||
for (const w of arr) {
|
||
const text = typeof w.text === "string" ? w.text : typeof w.word === "string" ? w.word : "";
|
||
const start = Number(w.start);
|
||
const end = Number(w.end);
|
||
if (!text || !isFinite(start) || !isFinite(end) || end <= start) {
|
||
continue; // silently drop unusable word entries (timestamps unreliable)
|
||
}
|
||
rawWords.push({ text, start: base + start, end: base + end, scene_id: sid, surface });
|
||
kept++;
|
||
}
|
||
if (kept > 0) scenesWithWords++;
|
||
}
|
||
}
|
||
|
||
if (scenesWithWords === 0) skip("no whisper words");
|
||
|
||
// ---------- §2: clean the word stream ----------
|
||
const MUSIC_RE = /^[♪♯�\s-]+$/; // ♪ ♯ replacement-char / dashes only
|
||
const FILLER = new Set(["uh", "um", "ah", "oh", "huh"]);
|
||
const HAS_ALNUM = /[A-Za-z0-9]/;
|
||
let droppedMusic = 0;
|
||
let droppedPunct = 0;
|
||
let droppedShort = 0;
|
||
let droppedFiller = 0;
|
||
const cleaned = [];
|
||
for (const w of rawWords) {
|
||
const t = w.text.trim();
|
||
if (t === "" || MUSIC_RE.test(t)) {
|
||
droppedMusic++;
|
||
continue;
|
||
}
|
||
if (!HAS_ALNUM.test(t)) {
|
||
// Entirely non-alphanumeric (lone "." / "," / "—") — cannot stand as a word.
|
||
// Punctuation ATTACHED to a word ("Figma.") keeps it — it has alnum chars.
|
||
droppedPunct++;
|
||
continue;
|
||
}
|
||
const dur = w.end - w.start;
|
||
if (dur < 0.05) {
|
||
droppedShort++;
|
||
continue;
|
||
}
|
||
if (FILLER.has(t.toLowerCase().replace(/[^a-z]/g, "")) && dur < 0.1) {
|
||
droppedFiller++;
|
||
continue;
|
||
}
|
||
cleaned.push(w);
|
||
}
|
||
|
||
if (cleaned.length === 0) skip("no whisper words");
|
||
|
||
// ---------- §3: group the word stream ----------
|
||
// Hard rules (never violated):
|
||
// 1. cross-scene boundary (scene_id change) → force new group
|
||
// 2. sentence-end punctuation suffix on a word → close group AFTER that word
|
||
// 3. silence gap (word.start − prev.end > 0.18s) → new group
|
||
// 4. word cap (density-modulated, default 4) → force close
|
||
// Soft rhythm guidance is encoded deterministically as a density-aware cap:
|
||
// dense narration (local >2.5 w/s) shortens groups; lyrical (<1.5 w/s) allows 4.
|
||
const SILENCE_GAP = 0.18;
|
||
const SENTENCE_END_RE = /[.?!,;:—]$/; // . ? ! , ; : —
|
||
const TAIL_PAD = 0.12; // extra hold so the last word is readable
|
||
|
||
// Local density at index i = words whose start falls within [start, start+1.0s).
|
||
function effectiveCap(i) {
|
||
const t0 = cleaned[i].start;
|
||
let n = 0;
|
||
for (let j = i; j < cleaned.length && cleaned[j].start < t0 + 1.0; j++) n++;
|
||
if (n > 3.5) return 2;
|
||
if (n > 2.5) return 3;
|
||
return 4;
|
||
}
|
||
|
||
let densityShortened = 0;
|
||
let crossSceneSplits = 0;
|
||
let silenceGapSplits = 0;
|
||
let punctSplits = 0;
|
||
let capSplits = 0;
|
||
const grouped = []; // arrays of word objects
|
||
let cur = [];
|
||
let curCap = 4;
|
||
for (let i = 0; i < cleaned.length; i++) {
|
||
const w = cleaned[i];
|
||
const prev = cur.length ? cur[cur.length - 1] : null;
|
||
const crossScene = prev && w.scene_id !== prev.scene_id;
|
||
const silenceGap = prev && w.start - prev.end > SILENCE_GAP;
|
||
if (cur.length && (crossScene || silenceGap || cur.length >= curCap)) {
|
||
// attribute the split (priority: scene boundary > silence > word cap)
|
||
if (crossScene) crossSceneSplits++;
|
||
else if (silenceGap) silenceGapSplits++;
|
||
else capSplits++;
|
||
grouped.push(cur);
|
||
cur = [];
|
||
}
|
||
if (cur.length === 0) {
|
||
curCap = effectiveCap(i);
|
||
if (curCap < 4) densityShortened++;
|
||
}
|
||
cur.push(w);
|
||
if (SENTENCE_END_RE.test(w.text)) {
|
||
punctSplits++;
|
||
grouped.push(cur);
|
||
cur = [];
|
||
}
|
||
}
|
||
if (cur.length) grouped.push(cur);
|
||
// The final flush is not a split; the loop counted one split per boundary
|
||
// crossed, which is exactly (groups − 1) boundaries — no off-by-one to correct.
|
||
|
||
// ---------- §4: ALL-CAPS / numeric tagging (free emphasis, no upstream tag) ----------
|
||
function classesFor(text) {
|
||
const cls = [];
|
||
const letters = text.match(/[A-Za-z]/g) || [];
|
||
if (letters.length >= 2 && !/[a-z]/.test(text)) cls.push("is-allcaps");
|
||
if (/^[0-9]/.test(text)) cls.push("is-numeric");
|
||
return cls;
|
||
}
|
||
|
||
let isAllcaps = 0;
|
||
let isNumeric = 0;
|
||
const outGroups = grouped.map((words, gi) => {
|
||
const start = words[0].start;
|
||
// Hold the last word up to TAIL_PAD ms longer — but never past the next
|
||
// group's first word, or the GSAP hard-kill would fire AFTER the next group
|
||
// appears and two groups would be on screen at once (guide §9 top failure).
|
||
const nextStart = gi + 1 < grouped.length ? grouped[gi + 1][0].start : Infinity;
|
||
const end = Math.min(words[words.length - 1].end + TAIL_PAD, nextStart);
|
||
const text = words.map((w) => w.text).join(" ");
|
||
return {
|
||
id: `caption-group-${gi}`,
|
||
scene_id: words[0].scene_id,
|
||
surface: words[0].surface ?? null,
|
||
start: Number(start.toFixed(3)),
|
||
end: Number(end.toFixed(3)),
|
||
text,
|
||
words: words.map((w, wi) => {
|
||
const classes = classesFor(w.text);
|
||
if (classes.includes("is-allcaps")) isAllcaps++;
|
||
if (classes.includes("is-numeric")) isNumeric++;
|
||
return {
|
||
id: `caption-word-${gi}-${wi}`,
|
||
text: w.text,
|
||
start: Number(w.start.toFixed(3)),
|
||
end: Number(w.end.toFixed(3)),
|
||
classes,
|
||
};
|
||
}),
|
||
};
|
||
});
|
||
|
||
// ---------- §8 invariant: intra-scene groups must not temporally overlap ----------
|
||
// (Two visible at once is guide §9's top failure. We catch it here, on data,
|
||
// before any HTML is authored — never by seeking a GSAP timeline.)
|
||
for (let i = 1; i < outGroups.length; i++) {
|
||
const a = outGroups[i - 1];
|
||
const b = outGroups[i];
|
||
if (a.scene_id === b.scene_id && b.start < a.end) {
|
||
anomalies.push(
|
||
`group overlap: ${a.id} ends ${a.end} but ${b.id} starts ${b.start} (same scene ${a.scene_id})`,
|
||
);
|
||
}
|
||
}
|
||
|
||
const out = {
|
||
total_duration_s: Number(spec.total_duration_s) || 0,
|
||
source_word_count: rawWords.length,
|
||
cleaned_word_count: cleaned.length,
|
||
groups: outGroups,
|
||
stats: {
|
||
groups: outGroups.length,
|
||
cross_scene_splits: crossSceneSplits,
|
||
silence_gap_splits: silenceGapSplits,
|
||
punct_splits: punctSplits,
|
||
cap_splits: capSplits,
|
||
density_shortened: densityShortened,
|
||
is_allcaps: isAllcaps,
|
||
is_numeric: isNumeric,
|
||
dropped: {
|
||
music: droppedMusic,
|
||
punct: droppedPunct,
|
||
short: droppedShort,
|
||
filler: droppedFiller,
|
||
},
|
||
},
|
||
anomalies,
|
||
};
|
||
|
||
writeFileSync(outPath, JSON.stringify(out, null, 2));
|
||
|
||
// ---------- summary ----------
|
||
console.log(`✓ wrote ${outPath}`);
|
||
console.log(
|
||
` source words: ${rawWords.length} → cleaned: ${cleaned.length} → groups: ${outGroups.length}`,
|
||
);
|
||
console.log(
|
||
` splits — cross-scene:${crossSceneSplits} silence:${silenceGapSplits} punct:${punctSplits} cap:${capSplits} / density-shortened: ${densityShortened}`,
|
||
);
|
||
console.log(` is-allcaps: ${isAllcaps} / is-numeric: ${isNumeric}`);
|
||
console.log(
|
||
` dropped — music:${droppedMusic} punct:${droppedPunct} short:${droppedShort} filler:${droppedFiller}`,
|
||
);
|
||
if (anomalies.length) {
|
||
console.log(`\nanomalies (non-fatal):`);
|
||
for (const a of anomalies) console.log(` - ${a}`);
|
||
}
|
||
}
|
||
|
||
// =====================================================================
|
||
// html — was build-captions-html.mjs
|
||
// =====================================================================
|
||
// Phase 4a.5 (engine) — deterministic caption-HTML builder. No subagent.
|
||
//
|
||
// Replaces the old captions LLM agent (agents/captions.md, now deleted). Turns
|
||
// the deterministic word data from build-captions.mjs into a brand-strict,
|
||
// render-ready caption sub-composition WITHOUT any LLM judgment — killing the
|
||
// whole class of agent-authored render-time footguns the old guide §6/§7 warned
|
||
// about (Illegal-invocation, timeline-not-registered, naked-color brand leaks,
|
||
// two-groups-visible, fitText-return-ignored).
|
||
//
|
||
// Pipeline position:
|
||
// build-captions.mjs → caption_groups.json (clean/group/global-time/class)
|
||
// build-captions-html.mjs (THIS) → compositions/captions.html (skin + brand)
|
||
// assemble-index.mjs → mounts it as the track-12 clip IF the file exists
|
||
//
|
||
// What it does:
|
||
// 1. SKIP gates (parity with build-captions.mjs / old agent): exit 0 with a
|
||
// "captions: skipped (<reason>)" line so finalize simply omits track-12.
|
||
// 2. SCORE + pick one of the SUPPORTED registry skins from inference.json
|
||
// (deterministic rubric; --skin forces; --no-emit reports without building).
|
||
// 3. INSTALL the skin (`npx hyperframes add caption-<skin>`, or --skin-file
|
||
// for offline/CI), then TRANSFORM it via a per-skin descriptor:
|
||
// - replace the placeholder transcript with caption_groups words
|
||
// - feed the engine's pre-computed groups (scene-aware, non-overlapping)
|
||
// so the skin never re-groups scene-blind [fixes blocker B5]
|
||
// - rewrite `var DURATION = 8` → total_duration_s [fixes blocker B1:
|
||
// the 8s placeholder clamps every word past 8s on a 60-90s video]
|
||
// - rename host data-composition-id AND window.__timelines key → "captions"
|
||
// (both must match: compositionScoping only remaps the timeline write
|
||
// when the key === the inner root's data-composition-id)
|
||
// - inline tokens.css + tokenize every hardcoded color/font to var(--*)
|
||
// / color-mix(...) so the file is brand-strict
|
||
// - convert the karaoke color tween to an .is-active CLASS flip so the
|
||
// active/inactive colors live in CSS tokens (gsap can't interpolate
|
||
// var() colors) [keeps brand-strict + readable on any brand theme,
|
||
// addressing blocker B6 structurally: pill bg = var(--canvas), active
|
||
// text = var(--ink) → always contrast, no render-time probe needed]
|
||
// - add a full-span timeline anchor so the sub-comp timeline duration
|
||
// spans the whole video
|
||
// 4. NODE structural self-lint (replaces the old browser self-lint; check-
|
||
// compositions.mjs does NOT scan captions.html, so this is the sole gate).
|
||
//
|
||
// SUPPORTED SKINS:
|
||
// - caption-pill-karaoke — own opaque pill (no scrim needed), canonical
|
||
// .caption-group/.caption-word classes, a runtime makeGroups we bypass,
|
||
// lower-third position, CSS-only colors. The safe default.
|
||
// - caption-highlight — TikTok-style per-word background sweep. Audited in
|
||
// behind its own transform: it ships NON-canonical .hl-group/.hl-word
|
||
// classes (we add the canonical ones alongside), an INDEX-PINNED RAW_GROUPS
|
||
// map keyed to the demo transcript (we replace it with the engine's
|
||
// scene-aware groups), and a TRANSPARENT layer (we tokenize its full-screen
|
||
// .hl-overlay into a brand-strict lower-third scrim band so text stays
|
||
// readable over any scene). CSS-only colors → tokenizable; bottom-anchored.
|
||
// The remaining registry caption-* skins still need per-skin work (JS-computed
|
||
// colors, mid-canvas position, line-only animation with no word class) and are
|
||
// added one at a time behind their own descriptor — see phases/captions/guide.md.
|
||
//
|
||
// Usage:
|
||
// node captions.mjs html --hyperframes . --groups ./caption_groups.json \
|
||
// --tokens design-system/chunks/tokens.css \
|
||
// [--inference design-system/inference.json] \
|
||
// [--out compositions/captions.html] \
|
||
// [--skin caption-pill-karaoke] [--skin-file <path>] [--no-emit]
|
||
//
|
||
// Exit 0 = compositions/captions.html written, OR a documented SKIP.
|
||
// Exit 1 = structural failure (bad JSON, skin handle drift, self-lint failure).
|
||
async function runHtml(argv) {
|
||
// ---------- argv ----------
|
||
const flag = (name, def) => {
|
||
const i = argv.indexOf(`--${name}`);
|
||
return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
|
||
};
|
||
const has = (name) => argv.includes(`--${name}`);
|
||
|
||
function die(msg) {
|
||
console.error(`✗ build-captions-html.mjs: ${msg}`);
|
||
process.exit(1);
|
||
}
|
||
function skip(reason) {
|
||
// Skip is not an error: finalize decides track-12 by file existence, so a
|
||
// missing captions.html simply means no caption layer.
|
||
console.log(`captions: skipped (${reason})`);
|
||
process.exit(0);
|
||
}
|
||
|
||
const hyperframesDir = resolve(flag("hyperframes", "."));
|
||
const groupsPath = resolve(flag("groups", "./caption_groups.json"));
|
||
const tokensPath = resolve(hyperframesDir, flag("tokens", "design-system/chunks/tokens.css"));
|
||
const inferencePath = resolve(hyperframesDir, flag("inference", "design-system/inference.json"));
|
||
const outPath = resolve(hyperframesDir, flag("out", "compositions/captions.html"));
|
||
const forcedSkin = flag("skin", null);
|
||
const skinFile = flag("skin-file", null);
|
||
const noEmit = has("no-emit");
|
||
// --cli "<full command>" or HYPERFRAMES_CLI env var lets the caller pin the
|
||
// hyperframes CLI binary used by `<cli> add <skin>`. Without it, falls back
|
||
// to `npx hyperframes add`. Pin to local source when running off an
|
||
// unreleased worktree: --cli "npx tsx /path/to/packages/cli/src/cli.ts"
|
||
const cliOverride = flag("cli", null) || process.env.HYPERFRAMES_CLI || null;
|
||
|
||
// ---------- per-skin descriptor table ----------
|
||
// Each entry pins the exact handles for one registry skin so the transform leans
|
||
// on the genuinely-shared contract (paused gsap timeline → window.__timelines,
|
||
// GSAP via CDN, a single <video> placeholder, an inline transcript array) and
|
||
// asserts the per-skin deltas rather than discovering them. Adding a skin = one
|
||
// entry + (if it diverges) extending applyTransform. A registry drift that moves
|
||
// a handle fails loudly at build time, never silently blank captions.
|
||
const SKINS = {
|
||
"caption-pill-karaoke": {
|
||
supported: true,
|
||
has_own_bg: true,
|
||
componentFile: "compositions/components/caption-pill-karaoke.html",
|
||
// vibe weights for scoreSkins (matched against inference signals)
|
||
vibe: { neutral: 1, saas: 1, rounded: 1, friendly: 1 },
|
||
},
|
||
"caption-highlight": {
|
||
supported: true,
|
||
has_own_bg: false, // transparent → transform injects a brand-strict scrim band
|
||
componentFile: "compositions/components/caption-highlight.html",
|
||
// bold/energetic/social — wins auto-pick only on a "direct" voice tone or a
|
||
// loud preset (see scoreSkins); otherwise pill-karaoke stays the safe default.
|
||
vibe: { bold: 1, social: 1, energetic: 1 },
|
||
},
|
||
// Not yet supported — present so scoring/--skin can report a clear
|
||
// "needs per-skin work" message instead of a generic failure:
|
||
"caption-neon-accent": {
|
||
supported: false,
|
||
reason: "JS-computed hex glow colors can't be brand-tokenized",
|
||
},
|
||
"caption-emoji-pop": {
|
||
supported: false,
|
||
reason: "JS-computed colors + hardcoded English keyword/emoji map",
|
||
},
|
||
"caption-weight-shift": {
|
||
supported: false,
|
||
reason: "no .caption-word class (animates lines) — Studio detection gap",
|
||
},
|
||
"caption-clip-wipe": {
|
||
supported: false,
|
||
reason: ".wp-* classes + index-pinned RAW_GROUPS/KEYWORDS",
|
||
},
|
||
"caption-editorial-emphasis": {
|
||
supported: false,
|
||
reason: "mid-canvas (top:580px) — incompatible with lower-third band",
|
||
},
|
||
};
|
||
|
||
// ---------- skip gates ----------
|
||
if (!existsSync(groupsPath)) skip("no caption groups");
|
||
if (!existsSync(tokensPath)) skip("no brand tokens");
|
||
|
||
let cg;
|
||
try {
|
||
cg = JSON.parse(readFileSync(groupsPath, "utf8"));
|
||
} catch (e) {
|
||
die(`caption_groups.json is not valid JSON: ${e.message}`);
|
||
}
|
||
const groups = Array.isArray(cg.groups) ? cg.groups : [];
|
||
if (groups.length === 0) skip("no caption groups");
|
||
const totalDuration = Number(cg.total_duration_s);
|
||
if (!isFinite(totalDuration) || totalDuration <= 0)
|
||
die(`caption_groups.total_duration_s missing/invalid (${cg.total_duration_s})`);
|
||
|
||
const tokensCss = readFileSync(tokensPath, "utf8");
|
||
|
||
// ---------- transform helpers (assert-or-die) — shared by both skin sources ----------
|
||
function replaceOnce(html, find, replacement, label) {
|
||
if (typeof find === "string") {
|
||
const idx = html.indexOf(find);
|
||
if (idx === -1)
|
||
die(`transform "${label}": expected literal not found (registry skin drifted?)`);
|
||
if (html.indexOf(find, idx + find.length) !== -1)
|
||
die(`transform "${label}": literal appears more than once`);
|
||
return html.slice(0, idx) + replacement + html.slice(idx + find.length);
|
||
}
|
||
// regex
|
||
const matches = html.match(new RegExp(find.source, find.flags.replace("g", "") + "g"));
|
||
if (!matches || matches.length === 0)
|
||
die(`transform "${label}": pattern not found (registry skin drifted?)`);
|
||
return html.replace(find, replacement);
|
||
}
|
||
function replaceAll(html, find, replacement, label) {
|
||
if (!html.includes(find)) die(`transform "${label}": expected literal not found`);
|
||
return html.split(find).join(replacement);
|
||
}
|
||
|
||
// Brand display family name for any canvas measureText() fit math (a CSS var() can't be
|
||
// a canvas font; the visible font still uses var(--font-display)). Shared by every skin.
|
||
const fdm = /--font-display:\s*'([^']+)'/.exec(tokensCss);
|
||
const brandDisplay = fdm ? fdm[1] : "Poppins";
|
||
|
||
// ---------- §0: preset-local caption skin (second source, preferred when present) ----------
|
||
// emit-chunks copies a preset's own caption-skin.html (style-presets/<preset>/caption-skin.html)
|
||
// into chunks/ for the chosen preset, so its presence beside tokens.css here means "this preset
|
||
// ships its own caption look". It is authored pre-baked + brand-token-strict against the canonical
|
||
// contract (data-composition-id=captions, .caption-group/.caption-word, var(--*) colors), so the
|
||
// transform is a GENERIC fill shared by every preset — no per-preset code. Precedence:
|
||
// --skin <registry> forces a registry skin · --no-preset-skin disables this ·
|
||
// otherwise a present caption-skin.html wins over registry scoring.
|
||
const presetSkinPath = resolve(dirname(tokensPath), "caption-skin.html");
|
||
const usePresetSkin = !forcedSkin && !has("no-preset-skin") && existsSync(presetSkinPath);
|
||
|
||
function buildPresetSkin(src) {
|
||
// Engine groups → the shape the skin's buildCaptions()/timeline consume; times are already
|
||
// GLOBAL seconds + scene-aware / non-overlapping (build-captions.mjs), same as the pill path.
|
||
const engineGroups = groups.map((g) => ({
|
||
start: Number(g.start),
|
||
end: Number(g.end),
|
||
words: (g.words || []).map((w) => ({
|
||
text: String(w.text),
|
||
start: Number(w.start),
|
||
end: Number(w.end),
|
||
})),
|
||
}));
|
||
let h = src;
|
||
h = replaceOnce(
|
||
h,
|
||
"var GROUPS = [];",
|
||
`var GROUPS = ${JSON.stringify(engineGroups)};`,
|
||
"preset engine groups",
|
||
);
|
||
h = replaceOnce(h, "var DURATION = 0;", `var DURATION = ${totalDuration};`, "preset DURATION");
|
||
h = replaceOnce(
|
||
h,
|
||
'data-duration="0"',
|
||
`data-duration="${totalDuration}"`,
|
||
"preset host data-duration",
|
||
);
|
||
// optional: a skin that does canvas-measure fitting leaves an empty FONT_FAMILY to fill.
|
||
if (h.includes('var FONT_FAMILY = "";')) {
|
||
h = replaceOnce(
|
||
h,
|
||
'var FONT_FAMILY = "";',
|
||
`var FONT_FAMILY = ${JSON.stringify(brandDisplay)};`,
|
||
"preset FONT_FAMILY",
|
||
);
|
||
}
|
||
h = replaceOnce(
|
||
h,
|
||
"<style data-brand-tokens></style>",
|
||
`<style data-brand-tokens>\n${tokensCss.trim()}\n </style>`,
|
||
"preset brand tokens",
|
||
);
|
||
return h;
|
||
}
|
||
|
||
// ---------- §a: deterministic skin scoring ----------
|
||
let inference = null;
|
||
if (existsSync(inferencePath)) {
|
||
try {
|
||
inference = JSON.parse(readFileSync(inferencePath, "utf8"));
|
||
} catch {
|
||
inference = null; // optional input; ignore malformed
|
||
}
|
||
}
|
||
|
||
// Loud/expressive presets (build-design.mjs names) — a site that picked one of
|
||
// these reads punchy enough that the TikTok-style highlight skin fits it.
|
||
const LOUD_PRESETS =
|
||
/neo-brutalism|raw-grid|peoples-platform|8-bit-orbit|retro-zine|neo-grid-bold|stencil-tablet|scatterbrain/;
|
||
|
||
function scoreSkins() {
|
||
// Deterministic rubric over the SUPPORTED skins, grounded in real
|
||
// inference.json fields (site_dna.voice_tone, selected.name). pill-karaoke is
|
||
// the safe floor (own opaque pill → readable on any scene with no scrim); the
|
||
// bolder, transparent-scrim highlight only overtakes it on a clearly punchy
|
||
// signal. Tie ALWAYS resolves to pill-karaoke (the guide §1 documented default)
|
||
// → fully deterministic, no Date/random.
|
||
const tone = inference?.site_dna?.voice_tone || null; // "direct" | "warm" | "neutral" | null
|
||
const selected = inference?.selected?.name || "";
|
||
const score = {
|
||
"caption-pill-karaoke": 1 + (tone === "warm" || tone === "neutral" ? 1 : 0),
|
||
"caption-highlight": (tone === "direct" ? 2 : 0) + (LOUD_PRESETS.test(selected) ? 1 : 0),
|
||
};
|
||
const ranked = Object.entries(SKINS)
|
||
.filter(([, d]) => d.supported)
|
||
.map(([id]) => ({ id, score: score[id] ?? 0 }));
|
||
ranked.sort(
|
||
(a, b) =>
|
||
b.score - a.score ||
|
||
(a.id === "caption-pill-karaoke" ? -1 : b.id === "caption-pill-karaoke" ? 1 : 0),
|
||
);
|
||
return ranked;
|
||
}
|
||
|
||
let ranked = null;
|
||
let winner;
|
||
if (usePresetSkin) {
|
||
winner = "preset-skin"; // resolved from chunks/caption-skin.html (second source)
|
||
} else {
|
||
ranked = scoreSkins();
|
||
if (forcedSkin) {
|
||
const d = SKINS[forcedSkin];
|
||
if (!d) die(`unknown --skin "${forcedSkin}" — not a caption-* skin in the descriptor table`);
|
||
if (!d.supported)
|
||
die(
|
||
`--skin "${forcedSkin}" not yet supported (${d.reason}). Phase 1 supports: caption-pill-karaoke`,
|
||
);
|
||
winner = forcedSkin;
|
||
} else {
|
||
winner = ranked[0]?.id || "caption-pill-karaoke";
|
||
}
|
||
}
|
||
|
||
if (noEmit) {
|
||
const scoresPath = resolve(hyperframesDir, "caption_skin_scores.json");
|
||
writeFileSync(
|
||
scoresPath,
|
||
JSON.stringify(
|
||
{
|
||
winner,
|
||
source: usePresetSkin ? "preset-local" : "registry",
|
||
ranked,
|
||
inference: !!inference,
|
||
},
|
||
null,
|
||
2,
|
||
),
|
||
);
|
||
console.log(`✓ (--no-emit) ranked skins → ${scoresPath}`);
|
||
console.log(` winner: ${winner}${usePresetSkin ? " (preset-local caption-skin.html)" : ""}`);
|
||
process.exit(0);
|
||
}
|
||
|
||
// ---------- §b+§c: resolve + transform the chosen skin ----------
|
||
let html;
|
||
if (usePresetSkin) {
|
||
// Preset-local skin (second source): pre-baked + brand-token-strict, so the GENERIC
|
||
// fill (groups + duration + tokens) is the whole transform — no per-skin/per-preset code.
|
||
html = buildPresetSkin(readFileSync(presetSkinPath, "utf8"));
|
||
} else {
|
||
// ---------- §b: install / load the registry skin ----------
|
||
const desc = SKINS[winner];
|
||
let skinHtml;
|
||
if (skinFile) {
|
||
const sf = resolve(skinFile);
|
||
if (!existsSync(sf)) die(`--skin-file "${skinFile}" not found`);
|
||
skinHtml = readFileSync(sf, "utf8");
|
||
} else {
|
||
// `hyperframes add` only copies the component file into the project; it never
|
||
// edits index.html. Needs registry/network access — fails loudly if offline
|
||
// (unlike the old LLM agent, this script cannot improvise; pass --skin-file
|
||
// for offline/CI golden renders). When --cli or HYPERFRAMES_CLI is set,
|
||
// tokenize the override (first token = executable, rest = leading args).
|
||
const addBase = cliOverride
|
||
? cliOverride.trim().split(/\s+/).filter(Boolean)
|
||
: ["npx", "hyperframes"];
|
||
const [addCmd, ...addPrefix] = addBase;
|
||
try {
|
||
execFileSync(addCmd, [...addPrefix, "add", winner, "--no-clipboard"], {
|
||
cwd: hyperframesDir,
|
||
stdio: "pipe",
|
||
});
|
||
} catch (e) {
|
||
die(
|
||
`\`${addBase.join(" ")} add ${winner}\` failed (offline? pass --skin-file <path>): ${e.message}`,
|
||
);
|
||
}
|
||
const compAbs = resolve(hyperframesDir, desc.componentFile);
|
||
if (!existsSync(compAbs)) die(`expected ${desc.componentFile} after add, but it is missing`);
|
||
skinHtml = readFileSync(compAbs, "utf8");
|
||
}
|
||
|
||
// ---------- §c: transform the chosen registry skin ----------
|
||
html = skinHtml;
|
||
|
||
if (winner === "caption-pill-karaoke") {
|
||
// ---------- §c1: transform pill-karaoke ----------
|
||
// Engine groups → the shape the skin's buildCaptions()/timeline consume:
|
||
// { start, end, words:[{text,start,end}] }. Times are already GLOBAL seconds and
|
||
// scene-aware / non-overlapping (build-captions.mjs §3 + §8), so feeding them and
|
||
// bypassing the skin's scene-blind makeGroups fixes B5 and the 8s word clamp (B1).
|
||
const engineGroups = groups.map((g) => ({
|
||
start: Number(g.start),
|
||
end: Number(g.end),
|
||
words: (g.words || []).map((w) => ({
|
||
text: String(w.text),
|
||
start: Number(w.start),
|
||
end: Number(w.end),
|
||
})),
|
||
}));
|
||
const groupsJson = JSON.stringify(engineGroups);
|
||
|
||
// (1) strip Google Fonts <link> tags (brand @font-face is injected into index.html
|
||
// by assemble-index; the caption sub-comp is flattened into that document).
|
||
{
|
||
let removed = 0;
|
||
html = html.replace(/\s*<link\b[^>]*?>/gi, (m) => {
|
||
if (/fonts\.g(oogleapis|static)/i.test(m)) {
|
||
removed++;
|
||
return "";
|
||
}
|
||
return m;
|
||
});
|
||
if (removed === 0) die(`transform "strip google fonts": no font <link> found`);
|
||
}
|
||
|
||
// (2) strip the demo <video> placeholder element + its now-dead CSS rule.
|
||
if (!/<video\b[^>]*id="avatar-video"/i.test(html))
|
||
die(`transform "strip video": demo <video id=avatar-video> not found`);
|
||
html = html.replace(/\s*<video\b[\s\S]*?<\/video>/i, "");
|
||
html = html.replace(/\s*#avatar-video\s*\{[^}]*\}/i, "");
|
||
|
||
// (3) host root: rename composition id + set real duration.
|
||
html = replaceOnce(
|
||
html,
|
||
'data-composition-id="caption-pill-karaoke"',
|
||
'data-composition-id="captions"',
|
||
"host composition-id",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
'data-duration="8"',
|
||
`data-duration="${totalDuration}"`,
|
||
"host data-duration",
|
||
);
|
||
|
||
// (4) DURATION clamp [B1].
|
||
html = replaceOnce(html, "var DURATION = 8;", `var DURATION = ${totalDuration};`, "DURATION");
|
||
|
||
// (5) measurement font → brand display family.
|
||
html = replaceOnce(
|
||
html,
|
||
'var FONT_FAMILY = "Poppins";',
|
||
`var FONT_FAMILY = ${JSON.stringify(brandDisplay)};`,
|
||
"FONT_FAMILY",
|
||
);
|
||
|
||
// (6) drop the JS color constants (hex → would trip brand-strict; karaoke now CSS-class driven).
|
||
html = replaceOnce(
|
||
html,
|
||
' var COLOR_INACTIVE = "#A6A6A6";\n var COLOR_ACTIVE = "#1C1E1D";',
|
||
" // karaoke colors are CSS-token driven (.caption-word / .caption-word.is-active)",
|
||
"color consts",
|
||
);
|
||
|
||
// (7) kill the placeholder transcript (its text must be gone for the self-lint).
|
||
html = replaceOnce(
|
||
html,
|
||
/var TRANSCRIPT = \[[\s\S]*?\];/,
|
||
"var TRANSCRIPT = [];",
|
||
"TRANSCRIPT placeholder",
|
||
);
|
||
|
||
// (8) feed engine groups; bypass normalizeWords + scene-blind makeGroups [B1+B5].
|
||
html = replaceOnce(
|
||
html,
|
||
" var WORDS = normalizeWords(TRANSCRIPT);\n var GROUPS = makeGroups(WORDS);",
|
||
` var GROUPS = ${groupsJson};`,
|
||
"engine groups",
|
||
);
|
||
|
||
// (9) karaoke color tween → .is-active class flip (colors come from CSS tokens).
|
||
html = replaceOnce(
|
||
html,
|
||
` group.words.forEach(function (word, wordIndex) {
|
||
var wordEl = document.getElementById("caption-word-" + groupIndex + "-" + wordIndex);
|
||
var isFirstWord = wordIndex === 0;
|
||
var wordStart = Math.max(visibleStart, word.start - WORD_FADE_LEAD);
|
||
tl.set(wordEl, { color: isFirstWord ? COLOR_ACTIVE : COLOR_INACTIVE }, visibleStart);
|
||
if (isFirstWord) return;
|
||
tl.to(
|
||
wordEl,
|
||
{ color: COLOR_ACTIVE, duration: COLOR_FADE_DURATION, ease: "none" },
|
||
wordStart,
|
||
);
|
||
});`,
|
||
` group.words.forEach(function (word, wordIndex) {
|
||
var wordEl = document.getElementById("caption-word-" + groupIndex + "-" + wordIndex);
|
||
var isFirstWord = wordIndex === 0;
|
||
var wordStart = Math.max(visibleStart, word.start - WORD_FADE_LEAD);
|
||
tl.set(wordEl, { className: "caption-word" }, visibleStart);
|
||
tl.set(wordEl, { className: "caption-word is-active" }, isFirstWord ? visibleStart : wordStart);
|
||
});`,
|
||
"karaoke class flip",
|
||
);
|
||
|
||
// (10) full-span timeline anchor + rename the registry key → "captions".
|
||
html = replaceOnce(
|
||
html,
|
||
'window.__timelines["caption-pill-karaoke"] = tl;',
|
||
'tl.to({}, { duration: DURATION }, 0);\n window.__timelines["captions"] = tl;',
|
||
"timeline key + anchor",
|
||
);
|
||
|
||
// (11) tokenize CSS colors/fonts → brand-strict.
|
||
html = replaceAll(
|
||
html,
|
||
'font-family: "Poppins", Arial, sans-serif;',
|
||
"font-family: var(--font-display), Arial, sans-serif;",
|
||
"font-family token",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
"background: #e7e5e7;",
|
||
"background: var(--canvas);",
|
||
"pill bg token",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
"box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);",
|
||
"box-shadow: 0 2px 8px color-mix(in srgb, var(--ink) 14%, transparent);",
|
||
"pill shadow token",
|
||
);
|
||
html = replaceAll(
|
||
html,
|
||
"color: #a6a6a6;",
|
||
"color: color-mix(in srgb, var(--ink) 45%, var(--canvas));",
|
||
"inactive color token",
|
||
);
|
||
|
||
// (11b) geometry/size → match vito's compact lower-third. pill-karaoke ships a
|
||
// large 72px caption at bottom:100px (top edge ~y760), which (a) reads ~1.6x
|
||
// bigger than vito's 44px pill and (b) sits ABOVE the reserved ~180px band
|
||
// (y900-1080) the scene keep-out (#13) clears — so a scene filling to y900 could
|
||
// still be overlapped. Shrink to ~46px and hug the lower edge (bottom 24px,
|
||
// shorter box → pill bottom ~y1031) so caption geometry ≈ vito's bottom:4%.
|
||
html = replaceOnce(
|
||
html,
|
||
"var BASE_FONT_SIZE = 72;",
|
||
"var BASE_FONT_SIZE = 46;",
|
||
"base font size",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
"var MIN_FONT_SIZE = 52;",
|
||
"var MIN_FONT_SIZE = 34;",
|
||
"min font size",
|
||
);
|
||
html = replaceOnce(html, "font-size: 72px;", "font-size: 46px;", "copy font-size");
|
||
html = replaceOnce(
|
||
html,
|
||
"bottom: 100px;",
|
||
"bottom: 24px;",
|
||
"safe-zone bottom (hug lower edge, ~vito bottom:4%)",
|
||
);
|
||
html = replaceAll(html, "height: 220px;", "height: 120px;", "safe-zone/group box height");
|
||
|
||
// (12) inline tokens.css + the .is-active rule, before the skin's <style>.
|
||
const headInject = `<style data-brand-tokens>
|
||
${tokensCss.trim()}
|
||
</style>
|
||
<style>
|
||
/* karaoke active word — brand ink, set via .is-active class flip */
|
||
.caption-word.is-active { color: var(--ink); }
|
||
</style>
|
||
<style>`;
|
||
html = replaceOnce(html, " <style>", ` ${headInject}`, "inline brand tokens");
|
||
} else if (winner === "caption-highlight") {
|
||
// ---------- §c2: transform caption-highlight ----------
|
||
// highlight's build/timeline loops consume a FLAT global WORDS array + a GROUPS
|
||
// list of {wordStart,wordEnd,start,end} index ranges (word el id = wordStart+i).
|
||
// Rebuilding both from the engine's groups replaces (a) the demo TRANSCRIPT and
|
||
// (b) the index-pinned RAW_GROUPS map keyed to it — so the skin renders real,
|
||
// scene-aware, non-overlapping captions instead of its hardcoded placeholder.
|
||
const flatWords = [];
|
||
const hlGroups = [];
|
||
for (const g of groups) {
|
||
const wordStart = flatWords.length;
|
||
for (const w of g.words || []) {
|
||
flatWords.push({ text: String(w.text), start: Number(w.start), end: Number(w.end) });
|
||
}
|
||
const wordEnd = flatWords.length - 1;
|
||
if (wordEnd < wordStart) continue; // defensive: skip an empty group
|
||
hlGroups.push({ wordStart, wordEnd, start: Number(g.start), end: Number(g.end) });
|
||
}
|
||
const flatWordsJson = JSON.stringify(flatWords);
|
||
const hlGroupsJson = JSON.stringify(hlGroups);
|
||
|
||
// (1) strip Google Fonts <link> tags (brand @font-face comes from index.html).
|
||
{
|
||
let removed = 0;
|
||
html = html.replace(/\s*<link\b[^>]*?>/gi, (m) => {
|
||
if (/fonts\.g(oogleapis|static)/i.test(m)) {
|
||
removed++;
|
||
return "";
|
||
}
|
||
return m;
|
||
});
|
||
if (removed === 0) die(`transform "strip google fonts": no font <link> found`);
|
||
}
|
||
|
||
// (2) strip the dead #hl-video CSS rule (highlight ships no <video> element).
|
||
html = replaceOnce(html, /\s*#hl-video\s*\{[^}]*\}/, "", "strip dead #hl-video rule");
|
||
|
||
// (3) host root: rename composition id + set real duration.
|
||
html = replaceOnce(
|
||
html,
|
||
'data-composition-id="caption-highlight"',
|
||
'data-composition-id="captions"',
|
||
"host composition-id",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
'data-duration="8"',
|
||
`data-duration="${totalDuration}"`,
|
||
"host data-duration",
|
||
);
|
||
|
||
// (4) measurement base size 80→46 + measure font → brand display family
|
||
// (canvas font can't be a CSS var(); the visible font uses var(--font-display)).
|
||
html = replaceOnce(
|
||
html,
|
||
'fitFontSize(groupText, 80, "800", "Montserrat", 1620)',
|
||
`fitFontSize(groupText, 46, "800", ${JSON.stringify(brandDisplay)}, 1620)`,
|
||
"fit base size + measure font",
|
||
);
|
||
|
||
// (5) kill the placeholder transcript → engine flat words.
|
||
html = replaceOnce(
|
||
html,
|
||
/var WORDS = \[[\s\S]*?\];/,
|
||
`var WORDS = ${flatWordsJson};`,
|
||
"WORDS placeholder",
|
||
);
|
||
|
||
// (6) drop the index-pinned RAW_GROUPS + its derived GROUPS map → engine groups
|
||
// (scene-aware, non-overlapping). Fixes the same class of blocker as clip-wipe.
|
||
html = replaceOnce(
|
||
html,
|
||
/var RAW_GROUPS = \[[\s\S]*?\}\);/,
|
||
`var GROUPS = ${hlGroupsJson};`,
|
||
"engine groups",
|
||
);
|
||
|
||
// (7) add the canonical .caption-group/.caption-word classes alongside the skin's
|
||
// own (.hl-group/.hl-word) so Studio + captionOverrides can detect captions.
|
||
html = replaceOnce(
|
||
html,
|
||
'grp.className = "hl-group";',
|
||
'grp.className = "hl-group caption-group";',
|
||
"group canonical class",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
'wordEl.className = "hl-word";',
|
||
'wordEl.className = "hl-word caption-word";',
|
||
"word canonical class",
|
||
);
|
||
|
||
// (8) full-span timeline anchor + rename the registry key → "captions".
|
||
html = replaceOnce(
|
||
html,
|
||
'window.__timelines["caption-highlight"] = tl;',
|
||
`tl.to({}, { duration: ${totalDuration} }, 0);\n window.__timelines["captions"] = tl;`,
|
||
"timeline key + anchor",
|
||
);
|
||
|
||
// (9) geometry → shrink into the lower-third keep-out band (~vito bottom band).
|
||
// 80px uppercase at bottom:140px would top out ~y845, ABOVE the reserved
|
||
// ~180px band (y900-1080); 46px at bottom:36px keeps 1-2 lines inside it.
|
||
html = replaceOnce(html, "font-size: 80px;", "font-size: 46px;", "word font-size");
|
||
html = replaceOnce(html, "bottom: 140px;", "bottom: 36px;", "group bottom (hug lower edge)");
|
||
|
||
// (10) tokenize CSS colors/fonts → brand-strict.
|
||
html = replaceOnce(
|
||
html,
|
||
'font-family: "Montserrat", sans-serif;',
|
||
"font-family: var(--font-display), sans-serif;",
|
||
"font-family token",
|
||
);
|
||
html = replaceOnce(html, "color: #ffffff;", "color: var(--canvas);", "word color token");
|
||
// ADAPTIVE CONTRAST: the active word sits on a var(--brand-primary) fill whose
|
||
// lightness is unknown at build time, so NO single text color is safe on it
|
||
// (canvas fails on a light primary, ink fails on a dark one). Give the glyphs a
|
||
// crisp var(--ink) OUTLINE (8-way) so the canvas-filled text reads on any brand
|
||
// fill — light or dark — plus a soft ink drop for depth. Legibility no longer
|
||
// depends on the primary's luminance; it rides the guaranteed canvas↔ink pair.
|
||
html = replaceOnce(
|
||
html,
|
||
"text-shadow: 0 6px 18px rgba(0, 0, 0, 0.45);",
|
||
"text-shadow: 2px 0 0 var(--ink), -2px 0 0 var(--ink), 0 2px 0 var(--ink), 0 -2px 0 var(--ink), 1.5px 1.5px 0 var(--ink), -1.5px 1.5px 0 var(--ink), 1.5px -1.5px 0 var(--ink), -1.5px -1.5px 0 var(--ink), 0 4px 12px color-mix(in srgb, var(--ink) 40%, transparent);",
|
||
"ink-outline text (adaptive contrast on any brand fill)",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
"background: linear-gradient(135deg, #ff1745 0%, #df1238 100%);",
|
||
"background: linear-gradient(135deg, var(--brand-primary) 0%, color-mix(in srgb, var(--brand-primary) 85%, var(--ink)) 100%);",
|
||
"highlight bg token",
|
||
);
|
||
html = replaceOnce(
|
||
html,
|
||
"box-shadow: 0 12px 30px rgba(229, 20, 58, 0.32);",
|
||
"box-shadow: 0 12px 30px color-mix(in srgb, var(--brand-primary) 32%, transparent);",
|
||
"highlight shadow token",
|
||
);
|
||
|
||
// (11) scrim band — highlight is transparent, so its full-screen first-child
|
||
// .hl-overlay (z-index 1, below the words at z-index 10) becomes a
|
||
// brand-strict lower-third gradient so text reads over any scene (guide §3).
|
||
html = replaceOnce(
|
||
html,
|
||
` .hl-overlay {
|
||
position: absolute;
|
||
inset: 0;
|
||
background: transparent;
|
||
z-index: 1;
|
||
pointer-events: none;
|
||
}`,
|
||
` .hl-overlay {
|
||
position: absolute;
|
||
inset: 0;
|
||
background: linear-gradient(
|
||
to top,
|
||
color-mix(in srgb, var(--ink) 82%, transparent) 0%,
|
||
color-mix(in srgb, var(--ink) 55%, transparent) 12%,
|
||
transparent 26%
|
||
);
|
||
z-index: 1;
|
||
pointer-events: none;
|
||
}`,
|
||
"scrim band",
|
||
);
|
||
|
||
// (12) inline tokens.css before the skin's <style>.
|
||
const headInject = `<style data-brand-tokens>
|
||
${tokensCss.trim()}
|
||
</style>
|
||
<style>`;
|
||
html = replaceOnce(html, " <style>", ` ${headInject}`, "inline brand tokens");
|
||
} else {
|
||
die(`internal: no transform implemented for ${winner}`);
|
||
}
|
||
} // end else: registry-skin path (preset-local path handled above)
|
||
|
||
// ---------- §d: node structural self-lint ----------
|
||
function lint(cond, msg) {
|
||
if (!cond) die(`self-lint: ${msg}`);
|
||
}
|
||
// common (every skin): canonical hooks, real duration, no leaks/footguns.
|
||
lint(html.includes('data-composition-id="captions"'), 'missing data-composition-id="captions"');
|
||
lint(html.includes('window.__timelines["captions"]'), 'missing window.__timelines["captions"]');
|
||
lint(
|
||
/class="caption-group/.test(html) || html.includes("caption-group"),
|
||
"missing .caption-group",
|
||
);
|
||
lint(html.includes("caption-word"), "missing .caption-word");
|
||
lint(!html.includes("Every great video starts"), "placeholder transcript text still present");
|
||
lint(!/fonts\.g(oogleapis|static)/i.test(html), "Google Fonts link still present");
|
||
lint(
|
||
!/window\.(getComputedStyle|requestAnimationFrame|matchMedia)\(/.test(html),
|
||
"render-time Illegal-invocation footgun (window.<native>())",
|
||
);
|
||
lint(
|
||
html.includes(`data-duration="${totalDuration}"`),
|
||
"host data-duration not rewritten to total",
|
||
);
|
||
// skin-specific structural gates.
|
||
if (winner === "caption-pill-karaoke") {
|
||
lint(!/id="avatar-video"/.test(html), "demo <video> still present");
|
||
lint(
|
||
html.includes(`var DURATION = ${totalDuration};`),
|
||
"DURATION not rewritten to total_duration_s",
|
||
);
|
||
} else if (winner === "caption-highlight") {
|
||
lint(
|
||
!html.includes("var RAW_GROUPS"),
|
||
"index-pinned RAW_GROUPS not replaced with engine groups",
|
||
);
|
||
lint(!/<video\b/i.test(html), "unexpected <video> element");
|
||
lint(
|
||
html.includes(`tl.to({}, { duration: ${totalDuration} }, 0);`),
|
||
"full-span timeline anchor missing",
|
||
);
|
||
}
|
||
// brand-strict: strip the brand-token block, then no bare hex / rgb(a).
|
||
{
|
||
const stripped = html.replace(/<style data-brand-tokens>[\s\S]*?<\/style>/g, "");
|
||
const bareHex = stripped.match(/#[0-9a-fA-F]{3,8}\b/g) || [];
|
||
const bareRgb = stripped.match(/\brgba?\(/g) || [];
|
||
if (bareHex.length || bareRgb.length) {
|
||
die(
|
||
`self-lint: brand-strict violation (bare color outside token block): ${[...bareHex, ...bareRgb].slice(0, 6).join(", ")}`,
|
||
);
|
||
}
|
||
}
|
||
|
||
// ---------- write ----------
|
||
mkdirSync(dirname(outPath), { recursive: true });
|
||
writeFileSync(outPath, html);
|
||
|
||
// ---------- summary ----------
|
||
const wordCount = groups.reduce((n, g) => n + (g.words ? g.words.length : 0), 0);
|
||
const ownBg = usePresetSkin ? true : SKINS[winner]?.has_own_bg;
|
||
console.log(`✓ wrote ${outPath}`);
|
||
if (usePresetSkin) {
|
||
console.log(` skin: ${winner} (preset-local → chunks/caption-skin.html)`);
|
||
} else {
|
||
console.log(
|
||
` skin: ${winner}${forcedSkin ? " (forced)" : ""}${skinFile ? " (from --skin-file)" : ""}`,
|
||
);
|
||
}
|
||
console.log(` groups: ${groups.length} words: ${wordCount} duration: ${totalDuration}s`);
|
||
console.log(
|
||
` readability: ${ownBg ? "own opaque pill (no scrim needed)" : "brand-strict lower-third scrim band"}; colors brand-token driven`,
|
||
);
|
||
console.log(` self-lint: OK`);
|
||
}
|
||
|
||
// =====================================================================
|
||
// keepout — was check-caption-keepout.mjs
|
||
// =====================================================================
|
||
// check-caption-keepout.mjs — static gate for caption keep-out compliance.
|
||
//
|
||
// When captions are enabled (group_spec.captions_enabled === true), index.html's
|
||
// track-12 caption pill overlays the bottom ~17% of the 1080px canvas (y > 900).
|
||
// Foreground scene content placed there (chips / CTAs / hero text / stats / cards)
|
||
// gets visually covered by the karaoke pill at render time.
|
||
//
|
||
// The principle this script enforces:
|
||
// For every absolutely-positioned FOREGROUND element, its rendered bottom
|
||
// edge must end at y ≤ 900 (= 20px above the y=900 caption band edge).
|
||
//
|
||
// The same principle has multiple CSS shapes — this script catches the three
|
||
// statically detectable ones. For each rule with `position: absolute` and a
|
||
// non-decoration leaf selector, it computes the element's bottom-edge y and
|
||
// flags any rule where that y > 900:
|
||
//
|
||
// (A) `bottom: <X>px` with X < 180
|
||
// element bottom y = 1080 - X > 900
|
||
// (B) `top: <X>px` with X >= 900
|
||
// element top alone is already inside the caption band (any non-zero
|
||
// height pushes it deeper)
|
||
// (C) `top: <X>px` AND `height: <Y>px` with X + Y > 900
|
||
// explicit top+height pair lets us compute element bottom exactly
|
||
//
|
||
// Patterns that depend on transforms / margins / runtime GSAP positioning
|
||
// are not statically detectable here — they fall through to the finalize
|
||
// agent's snapshot eye-check (covered by a fallback row in the finalize
|
||
// agent's "phenomenon → root cause" table).
|
||
//
|
||
// Decoration exemption: any selector whose leaf class/id name matches the
|
||
// DECORATION_NAME_RX list (bg / dot-grid / surface / corner-pin / star-burst
|
||
// / ambient / glow / frame / etc.) is allowed in the caption band — those
|
||
// are full-bleed background or decorative layers, not foreground content.
|
||
// Pseudo-elements (`::before` / `::after` / etc.) are always exempt.
|
||
//
|
||
// Each violation carries the EXACT `edit_old` / `edit_new` strings that the
|
||
// finalize agent feeds into the Edit tool. No Read, no math, no search by
|
||
// the agent — the brief tells it exactly which file, which substring to
|
||
// replace, and what to replace it with. Worst case: 1 Edit call per
|
||
// violation.
|
||
//
|
||
// CLI usage:
|
||
// node captions.mjs keepout --group-spec ./group_spec.json --hyperframes . [--json]
|
||
//
|
||
// preflight-finalize.mjs consumes the gate by spawning `keepout --json` and
|
||
// parsing the result object off stdout (out-of-process — no ESM import of this
|
||
// file's CLI dispatcher).
|
||
//
|
||
// Exit codes (CLI): 0 = captions disabled or no violations, 1 = violations.
|
||
async function runKeepout(argv) {
|
||
// ---------- constants ----------
|
||
const CANVAS_HEIGHT_PX = 1080;
|
||
const CAPTION_BAND_TOP_Y = 900; // foreground must end at or above this y
|
||
const FAIL_THRESHOLD_BOTTOM_PX = 180; // any `bottom:` strictly less than this is suspect
|
||
const SUGGESTED_MIN_BOTTOM_PX = 200; // safe blanket — element bottom lands at y=880 (20px clearance)
|
||
// Geometry note: with `position: absolute; bottom: 200px;` the element's
|
||
// bottom edge is at y = 1080 − 200 = 880, which is 20px above the caption
|
||
// band edge at y=900. This works regardless of element height — the
|
||
// constraint is "where does the element END", not "where does it start".
|
||
|
||
// Decoration / background name patterns. Selectors whose LEAF class/id name
|
||
// matches any of these are skipped — they're allowed to extend full-bleed
|
||
// into the caption band (backgrounds, surface decorations, corner frames,
|
||
// ambient layers, decorative shapes, hidden measurement probes, etc.).
|
||
// Match against the leaf token after `.` or `#`, with `-` / `_` as token boundaries.
|
||
const DECORATION_NAME_RX =
|
||
/(?:^|[-_])(?:bg|background|dot-?grid|mesh|gradient|swell|ambient|texture|noise|scanline|surface|overlay|halo|glow|frame|pin|corner-?pin|deco|star-?burst|burst|ring|stripe|rect|shadow|pulse|ripple|measure|probe|hidden|scrim|backdrop|veil|fog|grain)(?:[-_]|$)/i;
|
||
|
||
// CSS pseudo-elements: always allowed (inherently decoration).
|
||
const PSEUDO_RX =
|
||
/::(?:before|after|backdrop|placeholder|selection|first-letter|first-line|marker)/i;
|
||
|
||
// ---------- main check (exported) ----------
|
||
function checkCaptionKeepout({ groupSpec, hyperframesDir }) {
|
||
const captionsEnabled = groupSpec?.captions_enabled === true;
|
||
const baseResult = {
|
||
enabled: captionsEnabled,
|
||
canvas_height_px: CANVAS_HEIGHT_PX,
|
||
caption_band_top_y: CAPTION_BAND_TOP_Y,
|
||
fail_threshold_bottom_px: FAIL_THRESHOLD_BOTTOM_PX,
|
||
suggested_min_bottom_px: SUGGESTED_MIN_BOTTOM_PX,
|
||
scenes_scanned: 0,
|
||
violations: [],
|
||
};
|
||
if (!captionsEnabled) return baseResult;
|
||
|
||
const groups = Array.isArray(groupSpec.groups) ? groupSpec.groups : [];
|
||
const sceneIds = [];
|
||
for (const g of groups) {
|
||
if (Array.isArray(g.scene_ids)) sceneIds.push(...g.scene_ids);
|
||
}
|
||
|
||
let scannedCount = 0;
|
||
const violations = [];
|
||
|
||
for (const sid of sceneIds) {
|
||
const file = join(hyperframesDir, "compositions", `${sid}.html`);
|
||
if (!existsSync(file)) continue;
|
||
scannedCount++;
|
||
const html = readFileSync(file, "utf8");
|
||
const found = scanSceneHtml(html, sid);
|
||
for (const v of found) {
|
||
v.file = `compositions/${sid}.html`;
|
||
violations.push(v);
|
||
}
|
||
}
|
||
|
||
return { ...baseResult, scenes_scanned: scannedCount, violations };
|
||
}
|
||
|
||
// ---------- per-scene scanner ----------
|
||
function scanSceneHtml(html, sceneId) {
|
||
// 1. Concatenate all <style> contents, strip /* ... */ comments.
|
||
const styleBlocks = [];
|
||
const styleRx = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
|
||
let sm;
|
||
while ((sm = styleRx.exec(html)) !== null) styleBlocks.push(sm[1]);
|
||
if (styleBlocks.length === 0) return [];
|
||
const css = styleBlocks.join("\n").replace(/\/\*[\s\S]*?\*\//g, "");
|
||
|
||
// 2. Walk top-level CSS rules `selector { body }` (no nesting). Body must
|
||
// not contain braces — rules out @media / @keyframes / nested-rules.
|
||
const ruleRx = /([^{}]+)\{([^{}]*)\}/g;
|
||
const violations = [];
|
||
let m;
|
||
while ((m = ruleRx.exec(css)) !== null) {
|
||
const selectorBlock = m[1].trim();
|
||
if (!selectorBlock || selectorBlock.startsWith("@")) continue;
|
||
const body = m[2];
|
||
|
||
// 3. Must be absolutely positioned.
|
||
if (!/(?:^|[;\s{])position\s*:\s*absolute\b/i.test(body)) continue;
|
||
|
||
// 4. Detect which CSS shape (if any) puts the element bottom into y > 900.
|
||
// Three independently-detectable patterns; a single rule can hit more
|
||
// than one (e.g. both `bottom:` AND `top:` — common for stretched bands).
|
||
//
|
||
// Property regex anchors at start-of-property to avoid matching
|
||
// `border-bottom`, `margin-bottom`, `padding-bottom`, `border-top`, etc.
|
||
const propPx = (name) => {
|
||
const m = body.match(
|
||
new RegExp(`(?:^|[;{\\s])${name}\\s*:\\s*(-?\\d+(?:\\.\\d+)?)px\\s*;`, "i"),
|
||
);
|
||
return m ? { raw: m[1], val: parseFloat(m[1]) } : null;
|
||
};
|
||
const bottom = propPx("bottom");
|
||
const top = propPx("top");
|
||
const height = propPx("height");
|
||
|
||
// 4a. Transform-aware Y offset.
|
||
// `transform: translate(-50%, -50%)` (centering trick) shifts the element
|
||
// upward by half its height — without accounting for it, a card visually
|
||
// centered in the upper canvas can be falsely flagged as overflowing the
|
||
// caption band. Parses translateY / translate / translate3d Y-component
|
||
// and returns:
|
||
// - `{ frac, knownPx }` where frac is the Y translate as a fraction
|
||
// of element height (e.g. -0.5 for translate(-50%, -50%)), and
|
||
// knownPx is a literal px offset when the transform was authored in
|
||
// px (overrides frac).
|
||
// - null when the transform contains a Y component but we cannot
|
||
// statically resolve it (matrix, calc(), CSS variable). The caller
|
||
// falls back to "skip violation" because firing when we can't tell
|
||
// is the path that led to the bad-Edit incident.
|
||
// Returns `{ frac: 0, knownPx: 0 }` when there is no transform or it
|
||
// has no Y component — the simple case, fully equivalent to the old
|
||
// behaviour.
|
||
const parseTransformY = () => {
|
||
const tm = body.match(/(?:^|[;{\s])transform\s*:\s*([^;]+);/i);
|
||
if (!tm) return { frac: 0, knownPx: 0 };
|
||
const tx = tm[1].trim();
|
||
// matrix / calc / var → can't statically resolve → caller skips.
|
||
if (/\b(?:matrix3?d?|calc\(|var\()/i.test(tx)) return null;
|
||
// First scan for a Y-affecting translate; only the first one is parsed
|
||
// here (composition of multiple translates is rare in PLV scenes).
|
||
let m;
|
||
if ((m = tx.match(/\btranslateY\(\s*(-?\d+(?:\.\d+)?)(%|px)\s*\)/i))) {
|
||
const val = parseFloat(m[1]);
|
||
return m[2] === "%" ? { frac: val / 100, knownPx: 0 } : { frac: 0, knownPx: val };
|
||
}
|
||
if (
|
||
(m = tx.match(
|
||
/\btranslate3d\(\s*[^,)]+,\s*(-?\d+(?:\.\d+)?)(%|px)\s*,/i,
|
||
))
|
||
) {
|
||
const val = parseFloat(m[1]);
|
||
return m[2] === "%" ? { frac: val / 100, knownPx: 0 } : { frac: 0, knownPx: val };
|
||
}
|
||
if (
|
||
(m = tx.match(/\btranslate\(\s*[^,)]+,\s*(-?\d+(?:\.\d+)?)(%|px)\s*\)/i))
|
||
) {
|
||
const val = parseFloat(m[1]);
|
||
return m[2] === "%" ? { frac: val / 100, knownPx: 0 } : { frac: 0, knownPx: val };
|
||
}
|
||
// translate(x) with only one arg → Y is 0; translateX(…) → Y is 0.
|
||
return { frac: 0, knownPx: 0 };
|
||
};
|
||
const transformY = parseTransformY();
|
||
// Unresolvable transform → conservative skip (don't false-positive).
|
||
if (transformY === null) continue;
|
||
|
||
// Compute the element's visual bottom y AFTER applying the transform. The
|
||
// shift in px = height × frac + knownPx; for frac to be applied we need
|
||
// the element height. When `height` is missing AND frac ≠ 0, we don't
|
||
// know the real shift → conservative skip (matches the unresolvable case).
|
||
const transformShiftPx = (h) =>
|
||
h !== null
|
||
? h * transformY.frac + transformY.knownPx
|
||
: transformY.frac !== 0
|
||
? null
|
||
: transformY.knownPx;
|
||
|
||
// Pattern A: `bottom: <X>px` with X < 180 → element bottom y > 900.
|
||
// Transform shift adjusts the visual bottom: visualBottom = (1080-X) + shift.
|
||
// If shift is unresolvable but transform has a % component, conservative skip.
|
||
let hitsA = false;
|
||
let aVisualBottom = null;
|
||
if (bottom && Number.isFinite(bottom.val)) {
|
||
const shift = transformShiftPx(height ? height.val : null);
|
||
if (shift === null) {
|
||
// can't resolve shift; if there's no transform we already get 0; only here
|
||
// when transform has %-Y but no height — conservative skip.
|
||
/* skip pattern A */
|
||
} else {
|
||
aVisualBottom = CANVAS_HEIGHT_PX - bottom.val + shift;
|
||
hitsA = bottom.val < FAIL_THRESHOLD_BOTTOM_PX && aVisualBottom > CAPTION_BAND_TOP_Y;
|
||
}
|
||
}
|
||
// Pattern B: `top: <X>px` with X >= 900 → element top inside caption band.
|
||
// Transform shift adjusts the visual top: visualTop = X + shift.
|
||
// When shift is unresolvable, conservative skip.
|
||
let hitsB = false;
|
||
let bVisualTop = null;
|
||
if (top && Number.isFinite(top.val)) {
|
||
const shift = transformShiftPx(height ? height.val : null);
|
||
if (shift === null) {
|
||
/* skip pattern B — would need height to resolve % shift */
|
||
} else {
|
||
bVisualTop = top.val + shift;
|
||
hitsB = bVisualTop >= CAPTION_BAND_TOP_Y;
|
||
}
|
||
}
|
||
// Pattern C: `top + height` with bottom edge > 900 (transform-aware).
|
||
// visualBottom = top + height + shift; shift uses the same height we
|
||
// already know, so it is always resolvable here.
|
||
// (Skipped when pattern A is already hitting on the same rule — we don't
|
||
// want to double-fire on `top: 80; bottom: 120; height: ignored`.)
|
||
let hitsC = false;
|
||
let cVisualBottom = null;
|
||
if (
|
||
!hitsA &&
|
||
top &&
|
||
height &&
|
||
Number.isFinite(top.val) &&
|
||
Number.isFinite(height.val)
|
||
) {
|
||
const shift = transformShiftPx(height.val);
|
||
cVisualBottom = top.val + height.val + shift;
|
||
hitsC = cVisualBottom > CAPTION_BAND_TOP_Y;
|
||
}
|
||
|
||
if (!hitsA && !hitsB && !hitsC) continue;
|
||
|
||
// 5. Split comma-separated selectors. Check each leaf independently.
|
||
const selectors = selectorBlock
|
||
.split(/,(?![^()]*\))/g)
|
||
.map((s) => s.trim())
|
||
.filter(Boolean);
|
||
|
||
for (const sel of selectors) {
|
||
if (PSEUDO_RX.test(sel)) continue;
|
||
const nameMatches = [...sel.matchAll(/[#.]([\w-]+)/g)];
|
||
if (nameMatches.length === 0) continue;
|
||
const leaf = nameMatches[nameMatches.length - 1][1];
|
||
if (DECORATION_NAME_RX.test(leaf)) continue;
|
||
|
||
// Pick the most reliable pattern to report (prefer A > C > B because A/C
|
||
// pin the element bottom y exactly, B only the top y).
|
||
//
|
||
// Transform-aware math: the *VisualBottom / *VisualTop computed above
|
||
// already account for `transform: translate*` Y components. The
|
||
// suggested Edit values below derive their target so that, AFTER
|
||
// applying the same transform, the element bottom lands at
|
||
// y ≤ CAPTION_BAND_TOP_Y - 20 (= 880; 20px safety clearance).
|
||
let pattern, oldStr, newStr, elementBottomY, overlapPx, principle;
|
||
const transformNote =
|
||
transformY.frac !== 0 || transformY.knownPx !== 0
|
||
? ` (with transform Y shift ${(transformY.frac * 100).toFixed(0)}% + ${transformY.knownPx}px)`
|
||
: "";
|
||
if (hitsA) {
|
||
pattern = "bottom-too-small";
|
||
elementBottomY = Math.round(aVisualBottom);
|
||
overlapPx = elementBottomY - CAPTION_BAND_TOP_Y;
|
||
// visual_bottom = (1080 - bottom) + shift; target visual_bottom = 880.
|
||
// shift = height * frac + knownPx; height is whatever the rule has
|
||
// today; so target bottom = 200 + shift (shift is signed).
|
||
const shift = transformShiftPx(height ? height.val : 0) || 0;
|
||
const targetBottom = Math.max(
|
||
0,
|
||
CANVAS_HEIGHT_PX - (CAPTION_BAND_TOP_Y - 20) + shift,
|
||
);
|
||
oldStr = `bottom: ${bottom.raw}px;`;
|
||
newStr = `bottom: ${targetBottom}px;`;
|
||
principle = `visual bottom y = ${elementBottomY} > 900${transformNote}`;
|
||
} else if (hitsC) {
|
||
pattern = "top-plus-height-too-tall";
|
||
elementBottomY = Math.round(cVisualBottom);
|
||
overlapPx = elementBottomY - CAPTION_BAND_TOP_Y;
|
||
// visual_bottom = top + height + shift; shift depends on height when
|
||
// frac != 0. Solve for new height H' so visual_bottom = 880:
|
||
// top + H' + H'*frac + knownPx = 880
|
||
// H' = (880 - top - knownPx) / (1 + frac)
|
||
// For frac > -1 (which covers `translate(*, -50%)` and the vast
|
||
// majority of layouts); otherwise fall back to the non-transform formula.
|
||
const denom = 1 + transformY.frac;
|
||
const suggestedHeight =
|
||
denom > 0
|
||
? Math.max(
|
||
0,
|
||
Math.floor(
|
||
(CAPTION_BAND_TOP_Y - 20 - top.val - transformY.knownPx) / denom,
|
||
),
|
||
)
|
||
: Math.max(0, CAPTION_BAND_TOP_Y - 20 - top.val);
|
||
oldStr = `height: ${height.raw}px;`;
|
||
newStr = `height: ${suggestedHeight}px;`;
|
||
principle = `top(${top.val}) + height(${height.val}) + shift → visual bottom y = ${elementBottomY} > 900${transformNote}`;
|
||
} else {
|
||
// hitsB
|
||
pattern = "top-in-caption-band";
|
||
elementBottomY = Math.round(bVisualTop); // we only know top — bottom is at least this
|
||
overlapPx = elementBottomY - CAPTION_BAND_TOP_Y;
|
||
// visual_top = top + shift; target visual_top = 820. shift is the
|
||
// same regardless of top, so: new_top = 820 - shift.
|
||
const shift = transformShiftPx(height ? height.val : 0) || 0;
|
||
const suggestedTop = Math.max(0, CAPTION_BAND_TOP_Y - 80 - shift);
|
||
oldStr = `top: ${top.raw}px;`;
|
||
newStr = `top: ${suggestedTop}px;`;
|
||
principle = `visual top y = ${elementBottomY} >= 900${transformNote}`;
|
||
}
|
||
|
||
const oldUniqueInFile = countOccurrences(html, oldStr) === 1;
|
||
|
||
violations.push({
|
||
scene_id: sceneId,
|
||
selector: sel,
|
||
leaf_name: leaf,
|
||
pattern,
|
||
principle,
|
||
element_bottom_y: elementBottomY,
|
||
overlap_into_caption_band_px: overlapPx,
|
||
current_bottom_px: hitsA ? bottom.val : null,
|
||
current_top_px: top ? top.val : null,
|
||
current_height_px: height ? height.val : null,
|
||
suggested_min_bottom_px: SUGGESTED_MIN_BOTTOM_PX, // for context only
|
||
edit_old: oldStr,
|
||
edit_new: newStr,
|
||
edit_old_is_unique: oldUniqueInFile,
|
||
instruction:
|
||
`Edit compositions/${sceneId}.html: in the \`${sel}\` rule ` +
|
||
`(it has \`position: absolute\`), replace \`${oldStr}\` with \`${newStr}\`. ` +
|
||
(oldUniqueInFile
|
||
? `(The string \`${oldStr}\` is unique in this file — single Edit call with no extra context needed.)`
|
||
: `(The string \`${oldStr}\` appears multiple times in this file — wrap your Edit's old_string with the line above it for uniqueness, e.g. include the line \`.${leaf} {\` or one of the adjacent property lines.)`) +
|
||
` Principle: ${principle} (caption band starts at y=${CAPTION_BAND_TOP_Y}, foreground element bottom must be ≤ y=${CAPTION_BAND_TOP_Y - 20} with 20px clearance).`,
|
||
});
|
||
}
|
||
}
|
||
return violations;
|
||
}
|
||
|
||
function countOccurrences(haystack, needle) {
|
||
if (!needle) return 0;
|
||
let n = 0,
|
||
i = 0;
|
||
while ((i = haystack.indexOf(needle, i)) !== -1) {
|
||
n++;
|
||
i += needle.length;
|
||
}
|
||
return n;
|
||
}
|
||
|
||
// ---------- CLI ----------
|
||
function runCli() {
|
||
const flag = (n, d) => {
|
||
const i = argv.indexOf(`--${n}`);
|
||
return i >= 0 && i + 1 < argv.length ? argv[i + 1] : d;
|
||
};
|
||
const groupSpecPath = resolve(flag("group-spec", "./group_spec.json"));
|
||
const hyperframesDir = resolve(flag("hyperframes", "."));
|
||
const asJson = argv.includes("--json");
|
||
|
||
if (!existsSync(groupSpecPath)) {
|
||
console.error(`✗ check-caption-keepout: group_spec.json missing at ${groupSpecPath}`);
|
||
process.exit(2);
|
||
}
|
||
const groupSpec = JSON.parse(readFileSync(groupSpecPath, "utf8"));
|
||
const result = checkCaptionKeepout({ groupSpec, hyperframesDir });
|
||
|
||
if (asJson) {
|
||
console.log(JSON.stringify(result, null, 2));
|
||
process.exit(result.violations.length === 0 ? 0 : 1);
|
||
}
|
||
|
||
if (!result.enabled) {
|
||
console.log("✓ caption-keepout: captions_enabled=false, no check needed");
|
||
process.exit(0);
|
||
}
|
||
if (result.violations.length === 0) {
|
||
console.log(
|
||
`✓ caption-keepout: ${result.scenes_scanned} scene(s) scanned, all foreground absolute-positioned elements end at or above y=${CAPTION_BAND_TOP_Y}`,
|
||
);
|
||
process.exit(0);
|
||
}
|
||
const sceneCount = new Set(result.violations.map((v) => v.scene_id)).size;
|
||
console.error(
|
||
`✗ caption-keepout: ${result.violations.length} violation(s) across ${sceneCount} scene(s) (caption band starts at y=${CAPTION_BAND_TOP_Y})`,
|
||
);
|
||
for (const v of result.violations) {
|
||
console.error(`\n [${v.scene_id}] ${v.selector} (pattern: ${v.pattern})`);
|
||
console.error(
|
||
` ${v.principle} → element bottom at y=${v.element_bottom_y} (${v.overlap_into_caption_band_px}px inside caption band)`,
|
||
);
|
||
console.error(
|
||
` fix: replace \`${v.edit_old}\` → \`${v.edit_new}\` in ${v.file} ${v.edit_old_is_unique ? "(old string unique — Edit safely)" : "(old string non-unique — wrap with selector line)"}`,
|
||
);
|
||
}
|
||
console.error(
|
||
`\n → finalize_brief.json.caption_keepout.violations carries identical findings + Edit-ready strings. Finalize agent patches in-place with N Edit calls, no Read/search needed.`,
|
||
);
|
||
process.exit(1);
|
||
}
|
||
|
||
// Was: `if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) runCli();`
|
||
// Per merge mechanism, the dispatcher reaches this wrapper only for the `keepout`
|
||
// subcommand, so the inner entry call runs unconditionally.
|
||
runCli();
|
||
}
|
||
|
||
// =====================================================================
|
||
// dispatcher
|
||
// =====================================================================
|
||
const sub = process.argv[2];
|
||
const rest = process.argv.slice(3);
|
||
switch (sub) {
|
||
case "group":
|
||
await runGroup(rest);
|
||
break;
|
||
case "html":
|
||
await runHtml(rest);
|
||
break;
|
||
case "keepout":
|
||
await runKeepout(rest);
|
||
break;
|
||
default:
|
||
console.error("usage: node captions.mjs <group|html|keepout> [args...]");
|
||
process.exit(2);
|
||
}
|