's data-duration ----------
// The root is the element carrying id="root"; match its full opening tag (same
// shape check-compositions.mjs uses) and read data-duration off THAT tag, not
// some inner clip's. Returns null if the file has no id="root" tag or that tag
// carries no data-duration (check-compositions already gates both — here a null
// just skips the cross-check rather than guessing).
function rootDataDuration(html) {
const tagM = html.match(/
]*\bid=["']root["'][^>]*>/i);
if (!tagM) return null;
const durM = tagM[0].match(/\bdata-duration=["']([\d.]+)["']/);
return durM ? parseFloat(durM[1]) : null;
}
// ---------- per-scene: existence + duration cross-check ----------
const durMismatches = [];
for (const { sid, scene } of playOrder) {
const compRel = `compositions/${sid}.html`;
const compAbs = join(hyperframesDir, compRel);
if (!existsSync(compAbs)) {
die(
`scene file ${compRel} missing — run check-compositions.mjs / re-dispatch worker before assembling`,
);
}
const specDur = Number(scene.estimatedDuration_s);
if (!isFinite(specDur) || specDur <= 0) {
die(
`${sid}: group_spec estimatedDuration_s missing or non-positive (${scene.estimatedDuration_s})`,
);
}
const rootDur = rootDataDuration(readFileSync(compAbs, "utf8"));
if (rootDur == null) {
anomalies.push(
`${sid}: could not read root data-duration from ${compRel} — skipped duration cross-check`,
);
} else if (Math.abs(rootDur - specDur) > DUR_EPSILON) {
durMismatches.push(`${sid}: worker root data-duration=${rootDur}s but group_spec=${specDur}s`);
}
}
if (durMismatches.length > 0) {
die(
`scene root data-duration disagrees with group_spec (voice / SFX / captions timing assume group_spec):\n ${durMismatches.join("\n ")}\n → re-dispatch the worker to honor estimatedDuration_s, or re-run prep.mjs.`,
);
}
// ---------- BGM volume: duck under narration if any scene has voice ----------
const hasAnyVoice = playOrder.some(
({ scene }) => scene.voicePath && existsSync(join(hyperframesDir, scene.voicePath)),
);
const BGM_VOLUME = hasAnyVoice ? "0.8" : "0.9";
// ---------- build elements in track order ----------
const body = [];
let voiceCount = 0;
for (let i = 0; i < playOrder.length; i++) {
const { sid, scene } = playOrder[i];
const start = scene.start_s;
const dur = scene.estimatedDuration_s;
// Voice clips share track 10 (single-lane). start_s is prep.mjs's cumulative
// sum of estimatedDuration_s, so (nextStart - start) IS the scene's own span —
// this is NOT a semantic change, just a float-exact one: computing dur this way
// makes the IEEE-754 sum (start + voiceDur) bit-exact equal to nextStart, which
// avoids spurious StaticGuard "overlaps by 5e-16s" failures when two 3-decimal
// floats sum off by a ULP (e.g. 1.771 + 3.648 = 5.4190000000000005 ≠ 5.419).
// Last scene has no successor → fall back to its own duration.
// (Root cause is the overlap guard lacking a float epsilon; this is the
// assemble-layer workaround since the skill can't patch core lint.)
const next = playOrder[i + 1];
const voiceDur = next ? next.scene.start_s - start : dur;
// CONTRACT (keep in lockstep with transitions.mjs scene-clip parser): the
// "HF-SCENE-CLIP
" marker lets transitions.mjs count expected scene clips
// independently of the attribute formatting and fail loudly if the emit
// shape below ever drifts out of sync with its regex. Do not rename the marker
// or collapse the per-attribute line layout without updating transitions.mjs.
body.push(` `);
// (track 0) scene sub-comp clip — host data-composition-id MUST equal the
// inner file's data-composition-id (= sid) or the runtime never finds the
// timeline. No class="clip" on sub-comp host divs (proven: brex / style-10).
body.push(
`
`,
);
// (track 10) voice — only when the wav is actually on disk.
if (scene.voicePath && existsSync(join(hyperframesDir, scene.voicePath))) {
body.push(
`
`,
);
voiceCount++;
} else if (scene.voicePath) {
anomalies.push(`${sid}: voicePath "${scene.voicePath}" not on disk — skipped voice
`);
}
body.push("");
}
// (track 11) BGM — Lyria is spawned detached and may not have landed yet, so
// re-check disk here (group_spec / audio_meta only promise the path).
let bgmEmitted = false;
const bgmPath = groupSpec.bgm_path;
if (bgmPath) {
if (existsSync(join(hyperframesDir, bgmPath))) {
body.push(
` `,
` `,
"",
);
bgmEmitted = true;
} else {
anomalies.push(`bgm_path "${bgmPath}" not on disk (still rendering?) — skipped BGM `);
}
}
// (track 12) captions — captions.mjs html writes this or legally skips; key off existence.
let captionsEmitted = false;
if (existsSync(join(hyperframesDir, "compositions/captions.html"))) {
body.push(
` `,
`
`,
"",
);
captionsEmitted = true;
}
// (track 20+i) SFX — emitted verbatim from group_spec.sfx[] (already sorted by
// t, file checked against the manifest, duration locked to manifest truth by
// prep). Correct-by-construction; verify-output.mjs sfx re-asserts this against the
// emitted html as the orchestrator's deterministic gate.
const sfx = Array.isArray(groupSpec.sfx) ? groupSpec.sfx : [];
let sfxEmitted = 0;
sfx.forEach((cue, i) => {
const rel = `assets/sfx/${cue.file}`;
if (!existsSync(join(hyperframesDir, rel))) {
anomalies.push(
`sfx "${cue.file}" not on disk at ${rel} — skipped (prep should have copied it)`,
);
return;
}
const vol = cue.volume != null ? cue.volume : 0.35;
if (sfxEmitted === 0) body.push(` `);
body.push(
` `,
);
sfxEmitted++;
});
// ---------- style: proven base + global brand tokens + optional @font-face ----------
const fontFaceCss = (groupSpec.font_face_css || "").trim();
const brandTokensCss = (groupSpec.brand_tokens_css || "").trim();
const headStyle = [
" * {",
" margin: 0;",
" padding: 0;",
" box-sizing: border-box;",
" }",
" html,",
" body {",
" margin: 0;",
` width: ${WIDTH}px;`,
` height: ${HEIGHT}px;`,
" overflow: hidden;",
" background: #000;",
" }",
" #root {",
" position: relative;",
` width: ${WIDTH}px;`,
` height: ${HEIGHT}px;`,
" overflow: hidden;",
" }",
" /* Sub-comp slots stretch to fill the root */",
" #root > div[data-composition-src] {",
" position: absolute;",
" inset: 0;",
" }",
];
if (brandTokensCss) {
// Global brand tokens — declared ONCE here. CSS custom properties inherit
// through the light DOM into every mounted sub-composition, so scenes use
// var(--*) without re-declaring this block locally. A scene may still override
// a token on its own #root (cascade) when it needs to (e.g. a dark scene).
headStyle.push("", " /* Brand design tokens (from design-system/chunks/tokens.css) */");
for (const line of brandTokensCss.split("\n")) headStyle.push(` ${line}`);
}
if (fontFaceCss) {
headStyle.push("", " /* Brand fonts (extracted by prep.mjs from design.html) */");
for (const line of fontFaceCss.split("\n")) headStyle.push(` ${line}`);
}
// ---------- assemble document ----------
const html = `
${body.join("\n")}
`;
writeFileSync(outPath, html);
// ---------- caption-overrides.json shim ----------
// The captions runtime fetches this file at validate time; absence yields a
// noisy validate ✗ that previously sent finalize on a ~30s debug chase. An
// empty array is a no-op override list — semantically identical to absent —
// but the file existing silences validate.
const captionOverridesPath = join(hyperframesDir, "caption-overrides.json");
let captionOverridesCreated = false;
if (!existsSync(captionOverridesPath)) {
writeFileSync(captionOverridesPath, "[]\n");
captionOverridesCreated = true;
}
// ---------- summary ----------
console.log(`✓ wrote ${outPath}`);
console.log(` scenes (track 0): ${playOrder.length}`);
console.log(` voice (track 10): ${voiceCount}`);
console.log(` bgm (track 11): ${bgmEmitted ? `yes (vol ${BGM_VOLUME})` : "no"}`);
console.log(` captions (track 12): ${captionsEmitted ? "yes" : "no"}`);
console.log(
` sfx (track 20+): ${sfxEmitted}${sfx.length !== sfxEmitted ? ` (${sfx.length - sfxEmitted} skipped)` : ""}`,
);
console.log(` total duration: ${totalDuration}s`);
console.log(` @font-face: ${fontFaceCss ? `${fontFaceCss.length}B injected` : "none"}`);
if (captionOverridesCreated) console.log(` caption-overrides.json: created empty [] shim`);
if (anomalies.length) {
console.log(`\nanomalies (non-fatal):`);
for (const a of anomalies) console.log(` - ${a}`);
}