Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
// fallow-ignore-file code-duplication complexity
/**
* HTML Compiler for Producer
*
* Two-phase compilation that guarantees every media element has data-end:
* 1. Static pass via core's compileTimingAttrs() (data-start + data-duration → data-end)
* 2. ffprobe resolution for elements without data-duration
*
* Also handles sub-compositions referenced via data-composition-src,
* recursively extracting nested media from sub-sub-compositions.
*/
import { createHash } from "node:crypto";
import { createReadStream, existsSync, mkdirSync, readFileSync } from "fs";
import { join, dirname, resolve, basename, relative } from "path";
import { parseHTML } from "linkedom";
import {
COMPOSITION_SOURCE_URL,
compileTimingAttrs,
injectDurations,
extractResolvedMedia,
clampDurations,
shouldClampResolvedMediaDuration,
CSS_URL_RE,
isNonRelativeUrl,
parseStrictFiniteTimingNumber,
readMediaStart,
redactTelemetryString,
resolveNaturalMediaTimelineDurationFromValues,
rewriteAssetPaths,
rewriteCssAssetUrls,
rewriteInlineStyleAssetUrls,
type RateSpec,
type ResolvedDuration,
type UnresolvedElement,
} from "@hyperframes/core";
import { MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
import {
assignBundledRuntimeCompositionIds,
assignMediaRenderIds,
type BundledHostCompositionIdentity,
buildVariablesByCompScript,
inlineSubCompositions as inlineSubCompositionsShared,
ensureExternalLinkTag,
ensureExternalScriptTag,
deferScriptsUntilFonts,
emitMountedModuleScripts,
isJavaScriptType,
prepareFlattenedInnerRoot,
emitRootCompositionVariableStyles,
readDeclaredDefaults,
parseHostVariableValues,
headStyleRuns,
inlineScriptRuns,
parsesAsScript,
styleElementsFor,
insertBeforeCloseTag,
isRuntimeFileUrl,
} from "@hyperframes/core/compiler";
import {
checkSubCompositionUsability,
type ParsableDocumentLike,
} from "@hyperframes/parsers/sub-composition-validity";
import {
isUnresolvedAssetPlaceholder,
readProjectFile,
} from "@hyperframes/parsers/asset-resolution";
import { extractMediaMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
import { isPathInside, toExternalAssetKey } from "../utils/paths.js";
import { collectRenderMedia } from "./renderMediaCollector.js";
import {
type VideoElement,
type ImageElement,
type AudioElement,
type AudioVolumeKeyframe,
type MediaProbeProfile,
analyzeKeyframeIntervals,
assertMediaPayload,
NotMediaPayloadError,
parseMasterFxChain,
probeMediaProfile,
} from "@hyperframes/engine";
import {
downloadToTemp,
fetchPublicHttpsText,
isHttpUrl,
safeDownloadUrlIdentity,
type UrlDownloadTelemetry,
} from "../utils/urlDownloader.js";
import type { Page } from "puppeteer-core";
import {
injectDeterministicFontFaces,
normalizeSystemFontPrimaryFamilies,
} from "@hyperframes/core/fonts/embed";
import { prepareAnimatedGifInputs } from "./animatedGifPrep.js";
import { createStudioPositionSeekReapplyScript } from "@hyperframes/studio-server/manual-edits-render-script";
import { getPositionEditsRenderScript } from "@hyperframes/core/runtime/position-edits-render";
import { defaultLogger, type ProducerLogger } from "../logger.js";
import { assertAssetMediaTypeProfile } from "./assetMediaType.js";
import { withMediaProbeSlot } from "../utils/mediaProbeConcurrency.js";
function logRemoteDownloadTelemetry(event: UrlDownloadTelemetry): void {
defaultLogger.info("[Compiler] Remote asset download integrity", { ...event });
}
export interface CompiledComposition {
html: string;
subCompositions: Map<string, string>;
videos: VideoElement[];
audios: AudioElement[];
images: ImageElement[];
droppedMediaIds: Set<string>;
masterFxChain?: string;
unresolvedCompositions: UnresolvedElement[];
/** Assets that resolve outside projectDir. Keys are the path used in HTML, values are absolute filesystem paths. */
externalAssets: Map<string, string>;
width: number;
height: number;
staticDuration: number;
renderModeHints: RenderModeHints;
hasShaderTransitions: boolean;
/** Author HTML/CSS/scripts use a CSS 3D rendering context (pre-CDN-inline scan). */
usesThreeDTransforms: boolean;
/** Author HTML/CSS use mix-blend-mode (pre-CDN-inline scan). */
usesMixBlendMode: boolean;
/** Ancestors of the composition root carry a background-image (gradient/url). */
hasAncestorBackgroundImage: boolean;
}
const INFERRED_MEDIA_DURATION_ATTR = "data-hf-inferred-duration";
/** Adapts linkedom's `parseHTML` to the `checkSubCompositionUsability` contract. */
function parseSubCompHtmlForValidity(html: string): ParsableDocumentLike {
return parseHTML(html).document as unknown as ParsableDocumentLike;
}
function endsWithSourceUrl(code: string): boolean {
const trimmed = code.trimEnd();
const lastLine = trimmed.slice(trimmed.lastIndexOf("\n") + 1).trimStart();
return lastLine.startsWith("//# sourceURL=") || lastLine.startsWith("//@ sourceURL=");
}
// One name for the composition's inline code lets a render keep its errors and not a widget's.
function prepareCompositionScripts(html: string): string {
const { document } = parseHTML(html);
for (const el of document.querySelectorAll("script:not([src])")) {
const isModule = (el.getAttribute("type") || "").trim().toLowerCase() === "module";
const runsAsScript = isModule || isJavaScriptType(el as unknown as Element);
const code = el.textContent ?? "";
if (!runsAsScript || endsWithSourceUrl(code)) continue;
el.textContent = `${code}\n//# sourceURL=${COMPOSITION_SOURCE_URL}`;
}
deferScriptsUntilFonts(document as unknown as Document);
return document.toString();
}
export function injectSdkPositionEditsRenderScript(html: string): string {
if (!html.includes("data-hf-edit-base-x") && !html.includes("data-hf-edit-base-y")) {
return html;
}
const scriptBody = getPositionEditsRenderScript().replace(/<\/script/gi, "<\\/script");
const script = `<script>${scriptBody}\n//# sourceURL=hyperframes://position-edits</script>`;
return insertBeforeCloseTag(html, "body", script) ?? `${html}${script}`;
}
/**
* Thrown by {@link assertSubCompositionsUsable} when one or more
* `data-composition-src` references resolve to a missing, empty, or
* unparsable file. This is the render-path enforcement of the #1 render
* failure bucket in production telemetry: a scene-authoring step (most
* commonly an AI agent) writes the `data-composition-src` reference before,
* or without ever, writing valid content into the scene file.
*
* Unlike the tolerant inliner (`packages/core/src/compiler/inlineSubCompositions.ts`,
* intentionally kept lenient for preview/studio so mid-authoring iteration
* doesn't break bundling), a render that silently drops a scene produces a
* materially broken video with no visible error — strictly worse than
* refusing to render. This check runs before any compilation work starts so
* the failure is immediate and names every offending file at once, instead
* of surfacing 45+ seconds later as a `pollSubCompositionTimelines` timeout
* or a raw `Cannot destructure property 'firstElementChild' of
* 'documentElement' as it is null` crash deep inside linkedom.
*
* Not exported — nothing needs `instanceof` narrowing on this today. Callers
* catch it generically (`catch (err: unknown)`, matching on `.message`) the
* same way they handle every other compile-time failure. Kept as a class
* (not a plain `throw new Error(...)`) so the aggregated multi-file message
* construction has a single, testable home.
*/
class EmptyCompositionError extends Error {
readonly code = "EMPTY_COMPOSITION" as const;
readonly problems: ReadonlyArray<{ srcPath: string; detail: string }>;
constructor(problems: ReadonlyArray<{ srcPath: string; detail: string }>) {
const lines = problems.map((p) => ` - ${p.srcPath}: ${p.detail}`);
super(
`${problems.length} composition file${problems.length === 1 ? "" : "s"} referenced by ` +
`data-composition-src cannot be rendered:\n${lines.join("\n")}\n\n` +
"Check that each file referenced by data-composition-src contains valid HTML with a " +
"[data-composition-id] element in a <template>, <body>, or bare fragment. If a scene-authoring " +
"step is still running, wait for it to finish before referencing the file.",
);
this.name = "EmptyCompositionError";
this.problems = problems;
}
}
/**
* Recursively walk every `data-composition-src` reference reachable from
* `html` (including nested sub-compositions) and verify each resolves to a
* usable file — exists, non-empty, parses to HTML with renderable content.
* Uses the same `checkSubCompositionUsability` helper the tolerant inliner
* and `hyperframes lint` use, so all three agree on what counts as usable.
*
* Throws {@link EmptyCompositionError} naming every offending file at once
* (not just the first one hit) if any reference is unusable. Call this
* before any compilation work starts — it deliberately duplicates a small
* amount of file-reading work that `parseSubCompositions` also does, in
* exchange for failing in milliseconds instead of after the browser has
* already launched and waited out a capture timeout.
*/
// fallow-ignore-next-line complexity
function assertSubCompositionsUsable(
html: string,
projectDir: string,
visited: Set<string> = new Set(),
): void {
const { document } = parseHTML(html);
const hosts = [...document.querySelectorAll("[data-composition-src]")];
const problems: Array<{ srcPath: string; detail: string }> = [];
for (const el of hosts) {
const srcPath = el.getAttribute("data-composition-src");
if (!srcPath) continue;
if (isUnresolvedAssetPlaceholder(srcPath)) continue; // __UPPER__ placeholder or unresolved templating token — not a real reference (shared with lint via @hyperframes/parsers)
const filePath = resolve(projectDir, srcPath);
// Circular reference guard. parseSubCompositions (below) silently
// `continue`s on a repeat visit with no reporting at all — mirror that
// silence here rather than pretend it surfaces an error somewhere else.
if (visited.has(filePath)) continue;
const read = readProjectFile(filePath);
if (read.kind === "missing") {
problems.push({ srcPath, detail: "the file does not exist" });
continue;
}
if (read.kind === "folder") {
problems.push({ srcPath, detail: "it is a folder, not an HTML file" });
continue;
}
const fileHtml = read.text;
const validity = checkSubCompositionUsability(fileHtml, parseSubCompHtmlForValidity);
if (!validity.ok) {
problems.push({
srcPath,
detail: validity.detail ?? "the file is empty or could not be parsed",
});
continue;
}
// Recurse into nested sub-compositions so a broken scene three levels
// deep is still named directly instead of surfacing as a parent-level
// "no error, just missing content" mystery.
//
// Pass `projectDir` unchanged (not dirname(filePath)) — data-composition-src
// is always resolved root-relative, even from within a nested
// sub-composition. This must match parseSubCompositions' own recursive
// call below exactly (it threads the original projectDir through every
// level too), or this pre-flight check resolves nested references to the
// wrong path and aborts renders that would have actually succeeded.
const nestedVisited = new Set(visited);
nestedVisited.add(filePath);
try {
assertSubCompositionsUsable(fileHtml, projectDir, nestedVisited);
} catch (err) {
if (err instanceof EmptyCompositionError) {
problems.push(...err.problems);
} else {
throw err;
}
}
}
if (problems.length > 0) {
throw new EmptyCompositionError(problems);
}
}
export type RenderModeHintCode =
| "iframe"
| "requestAnimationFrame"
| "htmlInCanvas"
| "captureMotionBlur";
export interface RenderModeHint {
code: RenderModeHintCode;
message: string;
}
export interface RenderModeHints {
recommendScreenshot: boolean;
reasons: RenderModeHint[];
}
const INLINE_SCRIPT_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
const COMPILER_MOUNT_BLOCK_START = "/* __HF_COMPILER_MOUNT_START__ */";
const COMPILER_MOUNT_BLOCK_END = "/* __HF_COMPILER_MOUNT_END__ */";
function stripJsComments(source: string): string {
return source.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
}
function stripCompilerMountBootstrap(source: string): string {
return source.replace(
new RegExp(
`${COMPILER_MOUNT_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${COMPILER_MOUNT_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
"g",
),
"",
);
}
/** The composition the runtime reads data-motion-blur from: `data-root="true"`, else the first. */
function runtimeRoot(document: ParentNode): Element | null {
return (
document.querySelector('[data-composition-id][data-root="true"]') ??
document.querySelector("[data-composition-id]")
);
}
export function detectRenderModeHints(html: string, pageMotionBlur?: "off"): RenderModeHints {
const reasons: RenderModeHint[] = [];
const { document } = parseHTML(html);
if (document.querySelector("canvas[layoutsubtree]")) {
reasons.push({
code: "htmlInCanvas",
message:
"Detected html-in-canvas API (layoutsubtree canvas). Chrome does not support concurrent drawElementImage across multiple workers; render is pinned to a single worker.",
});
} else if (
pageMotionBlur !== "off" &&
runtimeRoot(document)?.getAttribute("data-motion-blur") === "on"
) {
// Not pinned to one worker: k3-promo measured identical across 1 and 4 workers, 2× faster.
reasons.push({
code: "captureMotionBlur",
message:
'Detected capture motion blur (data-motion-blur="on"), which draws each frame with html-in-canvas; routed through screenshot capture mode.',
});
}
if (document.querySelector("iframe")) {
reasons.push({
code: "iframe",
message:
"Detected <iframe> in the composition DOM. Nested iframe animation is routed through screenshot capture mode for compatibility.",
});
}
let scriptMatch: RegExpExecArray | null;
const scriptPattern = new RegExp(INLINE_SCRIPT_PATTERN.source, INLINE_SCRIPT_PATTERN.flags);
while ((scriptMatch = scriptPattern.exec(html)) !== null) {
const attrs = scriptMatch[1] || "";
if (/\bsrc\s*=/i.test(attrs)) continue;
const content = stripJsComments(stripCompilerMountBootstrap(scriptMatch[2] || ""));
if (!/requestAnimationFrame\s*\(/.test(content)) continue;
reasons.push({
code: "requestAnimationFrame",
message:
"Detected raw requestAnimationFrame() in an inline script. This render is routed through screenshot capture mode with virtual time enabled.",
});
break;
}
return {
recommendScreenshot: reasons.length > 0,
reasons,
};
}
/**
* 3D rendering-context signals. drawElementImage paints elements inside a
* CSS 3D rendering context incorrectly: backface-visibility:hidden is
* ignored (mid-flip elements show their mirrored backface), sibling content
* of the 3D context can drop out of the capture, and the context's
* background is lost. Observed on real-world gen_os comps (flip-card and
* rotationX scene-entrance patterns) on macOS hardware GPU — this is a
* drawElementImage limitation, not a SwiftShader artifact.
*
* Only genuine 3D-context signals are matched: `perspective` (property or
* transform function), `transform-style: preserve-3d`, `backface-visibility`,
* `matrix3d(` / `rotate3d(`, and GSAP's `transformPerspective`. Flat
* rotationX/Y tweens without a perspective context render as 2D and are
* deliberately NOT matched, nor is the ubiquitous `translateZ(0)` promotion
* hack.
*/
const THREE_D_CONTEXT_PATTERN =
/transform-style\s*:\s*preserve-3d|backface-visibility\s*:|perspective\s*:\s*[0-9]|perspective\s*\(|matrix3d\s*\(|rotate3d\s*\(|\btransformPerspective\b/i;
export function detectThreeDTransformUsage(html: string): boolean {
return THREE_D_CONTEXT_PATTERN.test(html);
}
const MIX_BLEND_MODE_PATTERN = /mix-blend-mode\s*:/i;
function detectMixBlendModeUsage(html: string): boolean {
return MIX_BLEND_MODE_PATTERN.test(html);
}
/** A background declaration whose value paints an image (gradient or url). */
const BACKGROUND_IMAGE_DECL_PATTERN =
/(?:^|;|\{)\s*background(?:-image)?\s*:[^;}]*(?:\bgradient\s*\(|url\s*\()/i;
/**
* Background-image signals on ancestors of the composition root.
* drawElementImage only paints the captured subtree; drawElementService's
* per-frame ancestor fill replicates what lies behind it by walking up the
* DOM for the nearest non-transparent `backgroundColor`. A background-IMAGE
* (linear-gradient, url) on <body>/<html>/a wrapper reads as transparent in
* that scan, so a deeper ancestor's solid color paints instead — measured:
* a body `linear-gradient` replaced by the html background color wherever
* the subtree left pixels uncovered (30.9 dB min vs baseline), and the
* damage can set in late enough to slip past the self-verify sample grid.
* Backgrounds on elements INSIDE the root are painted correctly and are
* deliberately not matched — this walks only the root's ancestor chain and
* the style rules that select into it.
*/
export function detectAncestorBackgroundImage(html: string): boolean {
const { document } = parseHTML(html);
const root = document.querySelector("[data-composition-id]");
if (!root) return false;
const ancestors: Element[] = [];
for (let el = root.parentElement; el; el = el.parentElement) ancestors.push(el);
if (document.documentElement && !ancestors.includes(document.documentElement)) {
ancestors.push(document.documentElement);
}
// Inline styles on the ancestor chain.
for (const el of ancestors) {
const style = el.getAttribute("style");
if (style && BACKGROUND_IMAGE_DECL_PATTERN.test(`{${style}}`)) return true;
}
// <style> rules: any rule carrying an image-painting background declaration
// whose selector resolves to an ancestor of the root. Selector matching goes
// through querySelectorAll so class/id/compound selectors on wrappers are
// covered, not just literal `body`/`html`.
for (const styleEl of document.querySelectorAll("style")) {
const css = styleEl.textContent ?? "";
for (const rule of css.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
const [, selectorList = "", declarations = ""] = rule;
if (!BACKGROUND_IMAGE_DECL_PATTERN.test(`{${declarations}}`)) continue;
for (const selector of selectorList.split(",")) {
const sel = selector.trim();
if (!sel || sel.startsWith("@")) continue;
if (/^(?:html|:root)$/i.test(sel)) return true;
try {
for (const matched of document.querySelectorAll(sel)) {
if (ancestors.includes(matched)) return true;
}
} catch {
// Selector syntax linkedom can't parse (e.g. vendor pseudo) — skip.
}
}
}
}
return false;
}
const SHADER_TRANSITION_USAGE_PATTERN =
/\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;
export function detectShaderTransitionUsage(html: string): boolean {
let scriptMatch: RegExpExecArray | null;
const scriptPattern = new RegExp(INLINE_SCRIPT_PATTERN.source, INLINE_SCRIPT_PATTERN.flags);
while ((scriptMatch = scriptPattern.exec(html)) !== null) {
const attrs = scriptMatch[1] || "";
if (/\bsrc\s*=/i.test(attrs)) continue;
const content = stripJsComments(stripCompilerMountBootstrap(scriptMatch[2] || ""));
if (SHADER_TRANSITION_USAGE_PATTERN.test(content)) return true;
}
return false;
}
async function resolveMediaDuration(
src: string,
mediaStart: number,
playbackRate: RateSpec,
baseDir: string,
downloadDir: string,
tagName: string,
elementIdentity: string,
log?: ProducerLogger,
urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ duration: number | null; resolvedPath: string }> {
let filePath = src;
if (isHttpUrl(src)) {
if (!existsSync(downloadDir)) mkdirSync(downloadDir, { recursive: true });
try {
filePath = await downloadToTemp(src, downloadDir, undefined, undefined, undefined, {
onTelemetry: logRemoteDownloadTelemetry,
});
} catch {
// Download failed (e.g. 404 placeholder URL) — skip gracefully.
// The element will get duration 0 and be excluded from the render.
return { duration: null, resolvedPath: src };
}
} else {
filePath = decodedUrlPath(src);
if (!filePath.startsWith("/")) filePath = join(baseDir, filePath);
// ffprobe reads only the header of a remote source, so it is probed in place.
filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
}
if (!isHttpUrl(filePath) && !existsSync(filePath)) {
return { duration: null, resolvedPath: filePath };
}
// STUDIO-5433: attach the remote `src` to any ffprobe failure surfaced from
// this branch. `extractMediaMetadata` → `runFfprobe` intentionally redacts
// its local `filePath` out of the error message (see
// engine/utils/ffprobe.ts::redactFfprobeInput), so a bare `moov atom not
// found` in Datadog carries no attribution and requires a Temporal history
// dump to identify the offending source. Re-throwing with the `src`
// (query-string redacted via `redactTelemetryString` so pre-signed URL
// signatures never reach telemetry) makes the next occurrence diagnosable
// directly from the render error. Fail-fast semantics for the video branch
// are preserved — only the message is enriched.
const withSrcContext = (error: unknown): Error => {
// A NotMediaPayloadError already carries its own attribution AND the
// routing metadata downstream keys on — `.code = "NOT_MEDIA_PAYLOAD"`,
// `.owner = "user"`, `.retryable = false`, `.elementFingerprints`. Wrapping
// it in a bare Error drops all four, flipping a user-input bug to
// generic/system/retryable: it pages ops and re-runs the render. Pass it
// through untouched.
if (error instanceof NotMediaPayloadError) return error;
const originalMessage = error instanceof Error ? error.message : String(error);
const safeSrc = redactTelemetryString(src);
const wrapped = new Error(`${originalMessage} [src=${safeSrc}]`);
if (error instanceof Error && error.stack) wrapped.stack = error.stack;
return wrapped;
};
return withMediaProbeSlot(async () => {
let profile: MediaProbeProfile;
try {
// Payload sniff (STUDIO-5433): if an authoring bug hands us a text
// payload (e.g. an unresolved nested-composition preview URL), fail with
// a typed NotMediaPayloadError instead of letting ffprobe emit an opaque
// `[mov,mp4,...] moov atom not found` that routes as a codec bug.
// Deliberately inside this try: the audio/video split below is the
// contract, so a bad audio src must still degrade to duration 0 rather
// than take down the whole render.
await assertMediaPayload(filePath, elementIdentity);
profile = await probeMediaProfile(filePath);
} catch (error) {
// Preserve the historical split: invalid video sources surface their
// probe failure, while invalid/unreadable audio sources resolve to zero
// duration and are excluded by the compiler.
if (tagName !== "video") {
if (error instanceof NotMediaPayloadError) {
// Dropping it silently is what let STUDIO-5433 resurface downstream
// as `prepare/ffmpeg_failed` with owner "system".
log?.warn(
`[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media ` +
"file, so the element is dropped from the render. Point it at a rendered media file.",
);
}
return { duration: null, resolvedPath: filePath };
}
throw withSrcContext(error);
}
assertAssetMediaTypeProfile(tagName === "video" ? "video" : "audio", profile, elementIdentity);
let metadata: { durationSeconds: number };
if (tagName === "video") {
try {
metadata = await extractMediaMetadata(filePath);
} catch (error) {
throw withSrcContext(error);
}
} else {
try {
metadata = await extractAudioMetadata(filePath);
} catch {
// Source file has no audio stream (e.g. a silent video used as an audio src).
// Return duration 0 so the element is excluded from the composition gracefully,
// matching how missing files and failed downloads are already handled above.
return { duration: null, resolvedPath: filePath };
}
}
const fileDuration = metadata.durationSeconds;
const duration = resolveNaturalMediaTimelineDurationFromValues(
fileDuration,
mediaStart,
playbackRate,
);
return { duration, resolvedPath: filePath };
});
}
/**
* Compile a single HTML file: static pass + ffprobe for unresolved media.
* Returns compiled HTML and any unresolved composition elements that need browser resolution.
*/
function markInferredVariableMediaDurations(
html: string,
unresolvedMedia: readonly UnresolvedElement[],
): string {
const unresolvedIds = new Set(unresolvedMedia.map((element) => element.id));
if (unresolvedIds.size === 0) return html;
const { document } = parseHTML(html);
let changed = false;
for (const element of document.querySelectorAll("video[data-var-src], audio[data-var-src]")) {
if (!unresolvedIds.has(element.id)) continue;
element.setAttribute(INFERRED_MEDIA_DURATION_ATTR, "");
changed = true;
}
return changed ? document.toString() : html;
}
async function compileHtmlFile(
html: string,
baseDir: string,
downloadDir: string,
log?: ProducerLogger,
urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ html: string; unresolvedCompositions: UnresolvedElement[] }> {
const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
const mediaUnresolved = unresolved.filter(
(el) => (el.tagName === "video" || el.tagName === "audio") && el.src,
);
const unresolvedCompositions = unresolved.filter((el) => el.tagName === "div");
// Phase 1: Resolve missing durations (parallel ffprobe)
const resolvedResults = await Promise.all(
mediaUnresolved.map((el) =>
resolveMediaDuration(
el.src!,
el.mediaStart,
el.playbackRate,
baseDir,
downloadDir,
el.tagName,
el.id,
log,
urlByAbsentLocalPath,
).then(({ duration }) => ({ id: el.id, duration })),
),
);
const resolutions: ResolvedDuration[] = resolvedResults.filter(
(r): r is ResolvedDuration => r.duration != null && Number.isFinite(r.duration),
);
const markedStaticHtml = markInferredVariableMediaDurations(staticCompiled, mediaUnresolved);
let compiledHtml =
resolutions.length > 0 ? injectDurations(markedStaticHtml, resolutions) : markedStaticHtml;
// Phase 2: Bound authored audio to playable source (parallel ffprobe).
// Explicit video slots may outlive their source and hold the final frame.
const preResolved = extractResolvedMedia(compiledHtml);
const clampResults = await Promise.all(
preResolved
.filter((el) => !!el.src && !el.loop)
.map(async (el) => {
const { duration: maxDuration } = await resolveMediaDuration(
el.src!,
el.mediaStart,
el.playbackRate,
baseDir,
downloadDir,
el.tagName,
el.id,
log,
);
return { id: el.id, tagName: el.tagName, duration: el.duration, maxDuration, src: el.src! };
}),
);
const clampList: ResolvedDuration[] = [];
for (const r of clampResults) {
if (
r.maxDuration != null &&
shouldClampResolvedMediaDuration(r.tagName, r.duration, r.maxDuration)
) {
clampList.push({ id: r.id, duration: r.maxDuration });
// This clip's `data-duration` is being silently shortened to its source.
// Surface it so the author can confirm the longer slot wasn't intended.
// ponytail: top-level only — sub-composition audio still gets clamped;
// thread `log` through parseSubCompositions to warn for it too.
log?.warn(
`[compile] Audio "${r.id}" (${r.src}) is ${r.maxDuration.toFixed(2)}s but its ` +
`data-duration is ${r.duration.toFixed(2)}s, so the slot is shortened to the media ` +
`length. Set data-duration to ~${r.maxDuration.toFixed(2)}s, trim data-media-start, ` +
`or use a longer/looping source if that isn't intended.`,
);
}
}
if (clampList.length > 0) {
compiledHtml = clampDurations(compiledHtml, clampList);
}
// Strip crossorigin from video elements: the render pipeline replaces them with
// injected frame images, so the browser never needs to load the source.
// Without this, videos with crossorigin="anonymous" targeting CORS-restricted
// origins (e.g. S3 without CORS headers) keep readyState=0, blocking page setup.
compiledHtml = compiledHtml.replace(/(<video\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
// Strip crossorigin from img elements. The renderer captures DOM frames visually —
// no canvas readback — so CORS compliance is unnecessary. External images from
// CORS-restricted origins (e.g. S3) render blank when crossorigin forces a failed
// CORS request against the renderer's localhost file server.
compiledHtml = compiledHtml.replace(/(<img\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
// Strip crossorigin from audio elements. Audio is processed out-of-band via
// FFmpeg; the browser's CORS policy for audio elements is irrelevant to
// rendering. Leaving crossorigin="anonymous" causes the browser to issue a
// CORS-mode preflight from localhost, which S3 buckets without explicit CORS
// headers reject — leaving audio elements in a failed network state. The
// FFmpeg audio path reads the src URL directly and is unaffected by browser
// CORS, so stripping the attribute has no side effects.
compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
return { html: compiledHtml, unresolvedCompositions };
}
/**
* Compile every sub-composition referenced via data-composition-src, keyed by
* its source path for the inliner to hoist into the render document.
* Recurses so nested references are compiled too.
*
* Media used to be extracted here as well, with each file's clips offset onto
* the parent timeline. That is now read off the inlined document instead
* (collectRenderMedia): per-file extraction had to merge on element id, which
* is not unique across files, so colliding clips silently collapsed (#3340).
*/
async function parseSubCompositions(
html: string,
projectDir: string,
downloadDir: string,
visited: Set<string> = new Set(),
urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ subCompositions: Map<string, string> }> {
const subCompositions = new Map<string, string>();
const { document } = parseHTML(html);
const compEls = document.querySelectorAll("[data-composition-src]");
// Build work items, filtering out invalid/circular entries synchronously
const workItems: Array<{
srcPath: string;
filePath: string;
rawSubHtml: string;
nestedVisited: Set<string>;
}> = [];
for (const el of compEls) {
const srcPath = el.getAttribute("data-composition-src");
if (!srcPath) continue;
const filePath = resolve(projectDir, srcPath);
// Circular reference guard
if (visited.has(filePath)) {
continue;
}
const read = readProjectFile(filePath);
if (read.kind !== "file") {
continue;
}
const rawSubHtml = read.text;
const nestedVisited = new Set(visited);
nestedVisited.add(filePath);
workItems.push({ srcPath, filePath, rawSubHtml, nestedVisited });
}
// Parallelize file compilation + recursive parsing
const results = await Promise.all(
workItems.map(async (item) => {
const { html: compiledSub } = await compileHtmlFile(
item.rawSubHtml,
dirname(item.filePath),
downloadDir,
undefined,
urlByAbsentLocalPath,
);
const nested = await parseSubCompositions(
compiledSub,
projectDir,
downloadDir,
item.nestedVisited,
urlByAbsentLocalPath,
);
return {
srcPath: item.srcPath,
compiledSub,
nested,
};
}),
);
// Merge results
for (const r of results) {
subCompositions.set(r.srcPath, r.compiledSub);
for (const [key, value] of r.nested.subCompositions) {
subCompositions.set(key, value);
}
}
return { subCompositions };
}
/**
* Extract CSS `@import url(...)` rules that load external stylesheets (e.g. Google Fonts)
* from inline `<style>` blocks and promote them to `<link rel="stylesheet">` +
* `<link rel="preload">` in `<head>`.
*
* This moves font discovery from the CSS cascade to the document parser level so
* Chromium's `load` event and `networkidle2` correctly track them, preventing
* font-swap artifacts during frame capture.
*/
function promoteCssImportsToLinkTags(html: string): string {
const { document } = parseHTML(html);
const head = document.querySelector("head");
if (!head) return html;
const importRe = /@import\s+url\(\s*['"]?([^'")\s]+)['"]?\s*\)\s*;?/gi;
const seenUrls = new Set<string>();
const styleEls = document.querySelectorAll("style");
for (const styleEl of styleEls) {
const original = styleEl.textContent || "";
let modified = original;
let match: RegExpExecArray | null;
importRe.lastIndex = 0;
while ((match = importRe.exec(original)) !== null) {
const url = match[1] ?? "";
if (!url.startsWith("http://") && !url.startsWith("https://")) continue;
if (seenUrls.has(url)) {
modified = modified.replace(match[0], "");
continue;
}
seenUrls.add(url);
modified = modified.replace(match[0], "");
const preload = document.createElement("link");
preload.setAttribute("rel", "preload");
preload.setAttribute("href", url);
preload.setAttribute("as", "style");
head.appendChild(preload);
const link = document.createElement("link");
link.setAttribute("rel", "stylesheet");
link.setAttribute("href", url);
head.appendChild(link);
}
if (modified !== original) {
styleEl.textContent = modified;
}
}
return document.toString();
}
class ProducerHostIdentityMap extends Map<Element, BundledHostCompositionIdentity> {
readonly #document: Document;
readonly #lateInstanceByCompositionId = new Map<string, number>();
constructor(document: Document, initialHosts: Element[]) {
super(assignBundledRuntimeCompositionIds(initialHosts));
this.#document = document;
}
override get(host: Element): BundledHostCompositionIdentity | undefined {
const existing = super.get(host);
if (existing) return existing;
// The shared inliner discovers nested hosts after the producer's initial
// DOM scan. Assign those late hosts on first use so their scope and
// variables key are fixed before any content is processed.
const authoredCompositionId =
(
host.getAttribute("data-hf-original-composition-id") ||
host.getAttribute("data-composition-id") ||
""
).trim() || null;
if (!authoredCompositionId) {
const identity = { authoredCompositionId: null, runtimeCompositionId: null };
this.set(host, identity);
return identity;
}
let instanceIndex = this.#lateInstanceByCompositionId.get(authoredCompositionId) || 0;
let runtimeCompositionId: string;
do {
instanceIndex += 1;
runtimeCompositionId = `${authoredCompositionId}__hf${instanceIndex}`;
} while (
Array.from(this.#document.querySelectorAll("[data-composition-id]")).some(
(element) =>
element !== host && element.getAttribute("data-composition-id") === runtimeCompositionId,
)
);
this.#lateInstanceByCompositionId.set(authoredCompositionId, instanceIndex);
host.setAttribute("data-hf-original-composition-id", authoredCompositionId);
host.setAttribute("data-composition-id", runtimeCompositionId);
const identity = { authoredCompositionId, runtimeCompositionId };
this.set(host, identity);
return identity;
}
}
/**
* Merge each run of adjacent same-condition `<head>` `<style>` blocks into one, `@import`
* rules at its top, and merge each run of adjacent inline `<body>` `<script>` blocks
* into one, without moving any of them past a `<script src>` or module script.
*
* Mirrors the bundler's `coalesceHeadStylesAndBodyScripts` to guarantee
* identical CSS cascade order and script execution order between preview and
* export, preventing font-loading and animation-ordering regressions.
*/
function coalesceHeadStylesAndBodyScripts(html: string): string {
const { document } = parseHTML(html);
const head = document.querySelector("head");
const body = document.querySelector("body");
if (!head && !body) return html;
const styleEls = head ? Array.from(head.querySelectorAll("style")) : [];
const importRe = /@import\s+url\([^)]*\)\s*;|@import\s+["'][^"']+["']\s*;/gi;
for (const run of styleEls.length > 1 ? headStyleRuns(styleEls) : []) {
const imports: string[] = [];
const cssParts: string[] = [];
const seenImports = new Set<string>();
for (const el of run) {
const raw = (el.textContent || "").trim();
if (!raw) continue;
const nonImportCss = raw.replace(importRe, (match) => {
const cleaned = match.trim();
if (!seenImports.has(cleaned)) {
seenImports.add(cleaned);
imports.push(cleaned);
}
return "";
});
const trimmedCss = nonImportCss.trim();
if (trimmedCss) cssParts.push(trimmedCss);
}
const mergedCss = [...imports, ...cssParts].join("\n\n").trim();
if (!mergedCss) continue;
run[0]!.textContent = mergedCss;
for (const el of run.slice(1)) el.remove();
}
if (body) {
for (const { members, anchor } of inlineScriptRuns(
Array.from(body.querySelectorAll("script")),
)) {
const mergedJs = members
.map((el) => (el.textContent || "").trim())
.filter(Boolean)
.join("\n;\n")
.trim();
if (mergedJs && !parsesAsScript(mergedJs)) continue;
for (const el of members) el.remove();
if (!mergedJs) continue;
const script = document.createElement("script");
script.textContent = mergedJs;
if (anchor) anchor.before(script);
else body.appendChild(script);
}
}
return document.toString();
}
/**
* Inline sub-composition HTML into the main document using the shared
* inlining logic from @hyperframes/core. This wrapper handles the
* producer-specific concerns: parsing HTML via linkedom, resolving
* compositions from the pre-compiled map or disk, and setting explicit
* pixel dimensions on host elements for headless rendering.
*/
function inlineSubCompositions(
html: string,
subCompositions: Map<string, string>,
projectDir: string,
variableOverrides: Record<string, unknown> = {},
): string {
const { document } = parseHTML(html);
const head = document.querySelector("head");
const body = document.querySelector("body");
const hosts = Array.from(document.querySelectorAll("[data-composition-src]"));
if (!hosts.length) {
// Even with no sub-compositions, declared composition variables need a
// compile-time stylesheet so eval-time reads (GSAP .from immediateRender,
// top-level script getComputedStyle) resolve var(--slug) — the runtime's
// DOMContentLoaded injection is too late for those.
const emitted = emitRootCompositionVariableStyles(
document as unknown as Document,
{},
variableOverrides,
);
return emitted ? document.toString() : html;
}
// Assign per-instance runtime composition ids before each host is inlined,
// mirroring the preview bundler. Initial hosts are assigned as one pre-pass;
// hosts discovered by the shared inliner's queue are assigned lazily by the
// map above. When the same sub-composition (same authored
// data-composition-id) is mounted more than once — the reusable-template
// pattern from issue #2064 — each host is rewritten to a unique runtime id
// (`card__hf1`, `card__hf2`). Without this, every instance shares one
// `__hfVariablesByComp` key and one scope selector: the last mount's
// data-variable-values clobbers the earlier ones and all-but-one instance
// renders blank. #2066 fixed the single-instance case but left this
// divergence (snapshot/preview correct, render wrong).
const hostIdentityByElement = new ProducerHostIdentityMap(
document as unknown as Document,
hosts as unknown as Element[],
);
const result = inlineSubCompositionsShared(
document as unknown as Document,
hosts as unknown as Element[],
{
// hostIdentityMap gives each repeated mount a unique runtime id; the
// shared inliner's default buildScopeSelector already scopes by
// `[data-composition-id="<runtime id>"]`, matching the preview bundler.
hostIdentityMap: hostIdentityByElement,
readVariableDefaults: readDeclaredDefaults,
parseHostVariables: parseHostVariableValues,
resolveHtml: (srcPath: string) => {
let compHtml = subCompositions.get(srcPath) || null;
if (!compHtml) {
const read = readProjectFile(resolve(projectDir, srcPath));
if (read.kind === "file") compHtml = read.text;
}
return compHtml;
},
parseHtml: (htmlStr: string) => parseHTML(htmlStr).document as unknown as Document,
// Mirrors the preview bundler: a sub-composition's SIBLING assets resolve
// against its own directory, project-root refs stay as authored.
assetExists: (path: string) => existsSync(resolve(projectDir, path)),
// Preserve the authored root wrapper as a child of the host, matching
// the preview bundler's shape (htmlBundler.ts's prepareFlattenedInnerRoot,
// which the runtime compositionLoader mirrors with its own copy for the
// live-loaded case). Without this, the wrapper element (and its
// class/id) is discarded and any CSS anchored on it —
// `.wrapper-class .title`, `#wrapper-id` — is dead at render time even
// though it works in preview.
flattenInnerRoot: prepareFlattenedInnerRoot as (innerRoot: Element) => Element,
onMissingComposition: (srcPath: string, reason?: string) => {
// In the render path this is normally unreachable — compileForRender
// calls assertSubCompositionsUsable() before any of this runs, so a
// hit here means the file changed on disk between that pre-flight
// check and this later inline step (e.g. a concurrent scene-writer).
console.warn(
`[Compiler] Skipping sub-composition "${srcPath}": ${reason ?? "the file is missing or empty"}.`,
);
},
},
);
// Producer-specific: set explicit pixel dimensions on host elements so
// children using width/height: 100% resolve correctly. The runtime does
// this automatically but compiled HTML needs it inline.
for (const host of hosts) {
const hostW = host.getAttribute("data-width");
const hostH = host.getAttribute("data-height");
if (hostW && hostH) {
const existing = host.getAttribute("style") || "";
const needsWidth = !existing.includes("width");
const needsHeight = !existing.includes("height");
const additions = [
needsWidth ? `width:${hostW}px` : "",
needsHeight ? `height:${hostH}px` : "",
]
.filter(Boolean)
.join(";");
if (additions) {
host.setAttribute("style", existing ? `${existing};${additions}` : additions);
}
}
}
if (head) for (const link of result.externalLinks) ensureExternalLinkTag(document, link);
// Append collected styles to <head>
if (head) {
for (const style of styleElementsFor(document, result.styles, (css) => css.join("\n\n"))) {
head.appendChild(style);
}
}
// CDN and integrity-pinned scripts go first so plugins (e.g. TextPlugin,
// ScrollTrigger) register before composition code, as in htmlBundler. A local
// src script keeps its authored place among the inline scripts (see below).
const isHoisted = (item: { src: string; integrity?: string }) =>
Boolean(item.integrity?.trim()) || isNonRelativeUrl(item.src);
if (body) {
for (const item of result.scriptItems) {
if (item.kind === "external" && isHoisted(item)) {
ensureExternalScriptTag(document, item.src, item);
}
}
}
// Append collected inline scripts to <body>. The per-instance variables
// table MUST be written before the sub-comp scripts run — their scoped
// getVariables() reads window.__hfVariablesByComp[compId]. htmlBundler
// (preview/snapshot) prepends this; the render path emitted only the CSS
// custom properties (below) and dropped the JS table, so getVariables()
// returned {} during render and parametrized sub-comps shipped blank/default
// text (issue #2064). Same shared builder as the bundler so they stay in
// lockstep.
const variablesByCompScript = buildVariablesByCompScript(result.variablesByComp);
if (body) {
let pending = variablesByCompScript ? [variablesByCompScript] : [];
const flushInline = () => {
if (!pending.length) return;
const joined = pending.join("\n;\n");
for (const text of parsesAsScript(joined) ? [joined] : pending) {
const scriptEl = document.createElement("script");
scriptEl.textContent = text;
body.appendChild(scriptEl);
}
pending = [];
};
for (const item of result.scriptItems) {
if (item.kind === "inline") {
pending.push(item.content);
} else if (!isHoisted(item)) {
flushInline();
ensureExternalScriptTag(document, item.src, item);
}
}
flushInline();
}
if (body) {
emitMountedModuleScripts(
document as unknown as Document,
result.importMaps,
result.moduleScripts,
);
}
// Compile-time CSS custom properties (mirrors the preview bundler): root
// declarers plus one scoped rule per sub-composition host, so var(--slug)
// resolves at script eval time, not just after runtime injection.
emitRootCompositionVariableStyles(
document as unknown as Document,
result.variablesByComp,
variableOverrides,
);
// Inlining is what makes element ids ambiguous: each composition file is
// internally consistent, the union of them is not. Hand every media element a
// document-unique key here, while the merged document is in hand and before
// anything downstream keys media on an id. See core's mediaRenderIds.ts.
assignMediaRenderIds(document as unknown as Document);
return document.toString();
}
/**
* Full compilation pipeline for the producer.
*
* Returns everything the orchestrator needs: compiled HTML, all media elements,
* dimensions, and static duration.
*/
/**
* Ensure the HTML is a full document (has <html>, <head>, <body>).
* When index.html is a fragment (e.g. just a <div>), linkedom.parseHTML()
* returns a document with null head/body, causing inlineSubCompositions to
* silently discard all collected composition styles and scripts.
*/
function ensureFullDocument(html: string): string {
const trimmed = html.trim();
if (/^<!DOCTYPE\s+html/i.test(trimmed) || /^<html/i.test(trimmed)) {
return html;
}
// Wrap fragment with a proper document including margin/padding reset.
// Without this, Chrome applies default body { margin: 8px } which creates
// visible white lines at the edges of rendered video.
return `<!DOCTYPE html>\n<html>\n<head>\n <meta charset="UTF-8">\n <style>*{margin:0;padding:0;box-sizing:border-box;text-rendering:geometricPrecision}body{overflow:hidden;background:#000;font-family:"Inter",sans-serif}</style>\n</head>\n<body style="margin:0;overflow:hidden">\n${html}\n</body>\n</html>`;
}
/**
* Force subpixel glyph positioning so chrome-headless-shell (BeginFrame) and
* full Chrome (screenshot fallback) lay text out identically. `text-rendering:
* auto` resolves to `optimizeSpeed` (integer advances) in headless-shell but
* `geometricPrecision` in full Chrome — that ~1% advance-width gap shifts
* line-wrap points and any animation that reads `offsetWidth`. The `*`
* selector has zero specificity, so authored class/id rules still override.
*/
function injectTextRenderingRule(html: string): string {
const { document } = parseHTML(html);
const head = document.querySelector("head");
if (!head) return html;
if (document.querySelector("style[data-hyperframes-text-rendering]")) {
return html;
}
const styleEl = document.createElement("style");
styleEl.setAttribute("data-hyperframes-text-rendering", "true");
styleEl.textContent = "html,body,*{text-rendering:geometricPrecision}";
head.insertBefore(styleEl, head.firstChild);
return document.toString();
}
class ScriptIntegrityError extends Error {}
/** Match SRI's strongest supported digest before decoding or rewriting script bytes. */
function matchesScriptIntegrity(bytes: Uint8Array, metadata: string): boolean {
const hashes = [
...metadata.matchAll(
/(?:^|[\t\n\f\r ])(sha256|sha384|sha512)-([A-Za-z0-9+/_-]+={0,2})(?:\?[\x21-\x7e]*)?(?=$|[\t\n\f\r ])/gi,
),
];
const strongest = ["sha512", "sha384", "sha256"].find((alg) =>
hashes.some((hash) => hash[1]?.toLowerCase() === alg),
);
// Browsers ignore metadata containing no supported, syntactically valid hash.
if (!strongest) return true;
const actual = createHash(strongest).update(bytes).digest();
return hashes.some(
(hash) =>
hash[1]?.toLowerCase() === strongest && actual.equals(Buffer.from(hash[2]!, "base64")),
);
}
/**
* Download external CDN scripts and inline them into the HTML so rendering
* works without network access (Docker, CI, restricted environments).
*/
export async function inlineExternalScripts(html: string): Promise<string> {
const fullHtml = ensureFullDocument(html);
const wrappedFragment = fullHtml !== html;
const { document } = parseHTML(fullHtml);
const scripts = document.querySelectorAll("script[src]");
const externalScripts: { el: Element; src: string }[] = [];
for (const el of scripts) {
const src = (el.getAttribute("src") || "").trim();
if (src && isHttpUrl(src) && !isRuntimeFileUrl(src)) {
externalScripts.push({ el: el as unknown as Element, src });
}
}
if (externalScripts.length === 0) return html;
const downloads = await Promise.allSettled(
externalScripts.map(async ({ el, src }) => {
const response = await fetch(src, {
signal: AbortSignal.timeout(15_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status} for ${src}`);
const bytes = new Uint8Array(await response.arrayBuffer());
if (!matchesScriptIntegrity(bytes, el.getAttribute("integrity") || "")) {
throw new ScriptIntegrityError(`Subresource integrity mismatch for ${src}`);
}
return { src, text: new TextDecoder().decode(bytes) };
}),
);
for (let i = 0; i < downloads.length; i++) {
const download = downloads[i]!;
const { el, src } = externalScripts[i]!;
if (download.status === "fulfilled") {
// Escape </script in downloaded content to prevent premature tag closure.
// <\/script is safe: the HTML parser doesn't recognize it as a close tag,
// but JS treats \/ as / so the code executes identically.
const safeText = download.value.text.replace(/<\/script/gi, "<\\/script");
const inlineScript = document.createElement("script");
for (const attr of Array.from(el.attributes)) {
if (attr.name.toLowerCase() === "src") continue;
inlineScript.setAttribute(attr.name, attr.value);
}
inlineScript.textContent = `/* inlined: ${src} */\n${safeText}\n//# sourceURL=${new URL(src).href}\n`;
el.replaceWith(inlineScript);
defaultLogger.info(`[Compiler] Inlined CDN script: ${src}`);
} else {
// A verified mismatch must never fall back to an executable external tag:
// browser support for integrity metadata (including casing) can differ.
if (download.reason instanceof ScriptIntegrityError) throw download.reason;
defaultLogger.warn(
`[Compiler] WARNING: Failed to download CDN script: ${src} (${download.reason}). ` +
`The render may fail if this script is required (e.g. GSAP). ` +
`Consider bundling it locally in your project.`,
);
}
}
return wrappedFragment ? document.body.innerHTML || "" : document.toString();
}
/**
* Scan compiled HTML for asset references that resolve outside projectDir.
* For each, map the normalized in-HTML path to the real filesystem path so
* the orchestrator can copy them into the compiled output directory.
*
* Handles: src/href attributes, CSS url(), inline style url().
*/
export function collectExternalAssets(
html: string,
projectDir: string,
): { html: string; externalAssets: Map<string, string> } {
const absProjectDir = resolve(projectDir);
const externalAssets = new Map<string, string>();
function processPath(rawPath: string): string | null {
const trimmed = rawPath.trim();
if (isNonRelativeUrl(trimmed)) return null;
const absPath = resolve(absProjectDir, trimmed);
if (isPathInside(absPath, absProjectDir)) {
return null; // inside projectDir, file server handles this
}
if (!existsSync(absPath)) return null;
// resolve() already canonicalises the path (no .. components remain);
// toExternalAssetKey() produces a cross-platform relative key that
// `path.join(compileDir, key)` cannot escape on any OS.
const safeKey = toExternalAssetKey(absPath);
externalAssets.set(safeKey, absPath);
return safeKey;
}
const { document } = parseHTML(html);
// Rewrite src and href attributes
for (const el of document.querySelectorAll("[src], [href]")) {
for (const attr of ["src", "href"]) {
const val = (el.getAttribute(attr) || "").trim();
if (!val) continue;
const rewritten = processPath(val);
if (rewritten) el.setAttribute(attr, rewritten);
}
}
// Rewrite CSS url() in <style> blocks
for (const styleEl of document.querySelectorAll("style")) {
const css = styleEl.textContent || "";
if (!css.includes("url(")) continue;
const rewritten = css.replace(CSS_URL_RE, (full, quote: string, rawUrl: string) => {
const result = processPath((rawUrl || "").trim());
if (!result) return full;
return `url(${quote || ""}${result}${quote || ""})`;
});
if (rewritten !== css) styleEl.textContent = rewritten;
}
// Rewrite inline style url() on elements
for (const el of document.querySelectorAll("[style]")) {
const style = el.getAttribute("style") || "";
if (!style.includes("url(")) continue;
const rewritten = style.replace(CSS_URL_RE, (full, quote: string, rawUrl: string) => {
const result = processPath((rawUrl || "").trim());
if (!result) return full;
return `url(${quote || ""}${result}${quote || ""})`;
});
if (rewritten !== style) el.setAttribute("style", rewritten);
}
if (externalAssets.size > 0) {
defaultLogger.info(
`[Compiler] Found ${externalAssets.size} asset(s) outside project directory, will copy to render output`,
);
}
return {
html: externalAssets.size > 0 ? document.toString() : html,
externalAssets,
};
}
export const REMOTE_MEDIA_SUBDIR = "_remote_media";
// Match opening tags of <video> or <audio> elements that carry an HTTP(S) src.
// Uses [^>]* to span attributes — safe for composition elements that won't
// have `>` inside quoted attribute values (data-title etc.).
const REMOTE_MEDIA_TAG_RE =
/<(?:video|audio)\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
// <source src> on media elements (picture uses srcset, not src).
const REMOTE_SOURCE_TAG_RE = /<source\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
// Match <img> tags (including agent-pipeline-emitted variants where `src` is
// not the first attribute). Producer-side localisation is the primary fix for
// the remote-<img> flicker; frameCapture's `pollImagesReady`/`decodeAllImages`
// are the defense-in-depth layer for any remote URL that bypasses this step.
// The `(?<![\w-])` lookbehind pins the match to a real `src` attribute so we
// don't rewrite `data-src` / `data-*-src` (lazy-loader placeholders whose URL
// is not what Chrome actually paints). `srcset` is excluded by the `\s*=`.
const REMOTE_IMG_TAG_RE = /<img\b[^>]*?(?<![\w-])src\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
/**
* Download a set of remote URLs in parallel into `remoteDir`, build the
* `{ relPath → absPath }` asset map, and rewrite every occurrence of each
* URL inside `html` with its relative local path.
*
* The `warnLabel` appears in console.warn messages for download failures.
* The `logLabel` appears in the success console.log line.
* `extraRewrite`, if provided, is called per URL pair after the standard
* double/single-quote rewrite — used for url(...) CSS rewriting.
*/
async function downloadAndRewriteUrls(
urlSet: Set<string>,
html: string,
remoteDir: string,
warnLabel: string,
logLabel: string,
extraRewrite?: (html: string, url: string, relPath: string) => string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
if (urlSet.size === 0) return { html, remoteMediaAssets: new Map() };
if (!existsSync(remoteDir)) mkdirSync(remoteDir, { recursive: true });
const urlToLocal = new Map<string, string>();
await Promise.all(
[...urlSet].map(async (url) => {
try {
const localPath = await downloadToTemp(url, remoteDir, undefined, undefined, undefined, {
onTelemetry: logRemoteDownloadTelemetry,
});
urlToLocal.set(url, localPath);
} catch (err) {
const identity = safeDownloadUrlIdentity(url);
defaultLogger.warn(`[Compiler] ${warnLabel}, using original URL as fallback.`, {
urlFingerprint: identity.urlFingerprint,
host: identity.host,
error: err instanceof Error ? err.message : String(err),
});
}
}),
);
if (urlToLocal.size === 0) return { html, remoteMediaAssets: new Map() };
const remoteMediaAssets = new Map<string, string>();
const urlToRelPath = new Map<string, string>();
for (const [url, absPath] of urlToLocal) {
const relPath = `${REMOTE_MEDIA_SUBDIR}/${basename(absPath)}`;
remoteMediaAssets.set(relPath, absPath);
urlToRelPath.set(url, relPath);
}
let result = html;
for (const [url, relPath] of urlToRelPath) {
result = result.replaceAll(`"${url}"`, `"${relPath}"`).replaceAll(`'${url}'`, `'${relPath}'`);
if (extraRewrite) result = extraRewrite(result, url, relPath);
}
defaultLogger.info(`[Compiler] ${logLabel} ${urlToLocal.size} to ${REMOTE_MEDIA_SUBDIR}/`);
return { html: result, remoteMediaAssets };
}
/**
* Download any remote `src` URLs on `<video>` / `<audio>` elements and their
* `<source>` children into a local subdirectory of `downloadDir`, rewrite the
* HTML src attributes to relative paths, and return the updated HTML along with
* a map of `{ relativePath → absoluteLocalPath }` for callers to add to
* `externalAssets`.
*
* Skips URLs that fail to download (warns and preserves the original URL so
* the browser can still attempt the remote fetch as a fallback).
*
* Why: remote S3 sources require Chrome to buffer every video file over the
* network before `readyState >= 2` (HAVE_CURRENT_DATA). With 10+ large clips
* this reliably exhausts `pageReadyTimeout`, producing blank black frames for
* every clip. Localising the sources before the file server starts eliminates
* the race entirely and keeps the render hermetic.
*/
/** @internal exported for unit testing only */
export async function localizeRemoteMediaSources(
html: string,
downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
const urlSet = new Set<string>();
for (const tagRe of [REMOTE_MEDIA_TAG_RE, REMOTE_SOURCE_TAG_RE]) {
const re = new RegExp(tagRe.source, tagRe.flags);
let m: RegExpExecArray | null;
while ((m = re.exec(html)) !== null) {
if (m[1]) urlSet.add(m[1]);
}
}
return downloadAndRewriteUrls(
urlSet,
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote media download failed",
"Localized remote media source(s)",
);
}
/**
* Download any remote `src` URLs on `<img>` elements into a local subdirectory
* of `downloadDir`, rewrite the HTML src attributes to relative paths, and
* return a `{ relativePath → absoluteLocalPath }` map for the orchestrator.
*
* Why: a composition with remote S3 `<img src>` URLs reaches Chrome unchanged;
* the readiness check can pass before the image is fully decoded, *and* Chrome
* may evict decoded pixels mid-render under memory pressure and re-fetch from
* the remote origin. Either path produces blank-frame flicker. Localising the
* sources before render eliminates both races — once the file is local,
* Chrome's image cache is bounded by fast disk reads, not S3 latency, so a
* mid-render re-fetch lands within a frame instead of flickering. This is the
* primary fix; frameCapture's `pollImagesReady` is the defense-in-depth layer.
*
* Scope: only `<img src>` is localised here. Remote `srcset`,
* `<picture><source>`, SVG `<image href>`, and CSS `background-image: url()`
* outside `@font-face` are NOT covered — agent-pipeline compositions emit
* plain `<img src>`, but those are open follow-ups if other shapes appear.
*
* This bites agent-pipeline-generated compositions (astral / daphne /
* hyperion `multi-v2` outputs) which render directly without going through
* `hyperframes publish`'s archive-time localize step.
*/
/** @internal exported for unit testing only */
export async function localizeRemoteImageSources(
html: string,
downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
const urlSet = new Set<string>();
const re = new RegExp(REMOTE_IMG_TAG_RE.source, REMOTE_IMG_TAG_RE.flags);
let m: RegExpExecArray | null;
while ((m = re.exec(html)) !== null) {
if (m[1]) urlSet.add(m[1]);
}
return downloadAndRewriteUrls(
urlSet,
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote image download failed",
"Localized remote image source(s)",
);
}
// Match a remote url() inside a `background` / `background-image` CSS declaration
// (style blocks or inline style attrs). `[^;}"']*?` lets position/color tokens
// precede the url() in the shorthand while stopping at the declaration boundary.
const REMOTE_BG_URL_RE =
/background(?:-image)?\s*:\s*[^;}"']*?url\(\s*["']?(https?:\/\/[^"')]+)["']?\s*\)/gi;
/**
* Download remote CSS `background-image: url(https://...)` references and rewrite
* them to local same-origin paths.
*
* Why: `drawElementImage` (fast capture) OMITS cross-origin content, so a remote
* background image renders BLACK on the drawElement path while the screenshot
* baseline captures it (origin-agnostic) — a whole-region mismatch (e.g. 10f79c0b
* picsum.photos backgrounds, 9.3 dB). `<img>`/`<video>`/`@font-face` are localized
* by their own passes; this closes the background-image gap so the fast path sees
* the same pixels as the baseline.
*
* @internal exported for unit testing only
*/
export async function localizeRemoteBackgroundImages(
html: string,
downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
const urlSet = new Set<string>();
const re = new RegExp(REMOTE_BG_URL_RE.source, REMOTE_BG_URL_RE.flags);
let m: RegExpExecArray | null;
while ((m = re.exec(html)) !== null) {
if (m[1] && !isGoogleFontsUrl(m[1])) urlSet.add(m[1]);
}
return downloadAndRewriteUrls(
urlSet,
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote background-image download failed",
"Localized remote background-image(s)",
// Quoted url('..')/url("..") are rewritten by downloadAndRewriteUrls' default
// replaceAll; this handles the unquoted url(https://..) form.
(h, url, rel) => h.replaceAll(`url(${url})`, `url(${rel})`),
);
}
// Match url("https://...") or url('https://...') inside @font-face blocks.
// We scan the full HTML (which includes <style> blocks) — matching against
// @font-face context precisely would require a CSS parser; instead we match
// any url(https?://...) that appears inside a @font-face rule by looking for
// the surrounding context. Simple pattern: capture all HTTP url() references
// that follow a @font-face opener (before the closing brace). The regex is
// applied to the CSS text extracted from <style> blocks so it can't
// accidentally match JavaScript string literals.
const REMOTE_FONTFACE_URL_RE = /url\(["']?(https?:\/\/[^"')]+)["']?\)/gi;
/**
* Download any remote font URLs from `@font-face` src declarations, rewrite
* the CSS `url(...)` references to local paths, and return a map of assets.
*
* Why: `@font-face { src: url("https://s3.../font.ttf") }` fails in the
* renderer because Chrome makes a CORS-mode fetch from the local file server
* origin (http://localhost:PORT) and S3 does not echo that origin back in
* Access-Control-Allow-Origin. The font load is rejected, Chrome falls back
* to the next font in the stack (e.g. Arial). Downloading the font file
* before render and rewriting to a local path eliminates the CORS race.
*/
/** Returns true for URLs belonging to Google Fonts (handled by the deterministic font injector). */
function isGoogleFontsUrl(href: string): boolean {
try {
const host = new URL(href).hostname.toLowerCase();
return host === "fonts.googleapis.com" || host === "fonts.gstatic.com";
} catch {
return /fonts\.googleapis\.com|fonts\.gstatic\.com/i.test(href);
}
}
const MAX_STYLESHEET_BYTES = 2 * 1024 * 1024;
async function fetchExternalStylesheetCss(href: string): Promise<string | null> {
const identity = safeDownloadUrlIdentity(href);
try {
return await fetchPublicHttpsText(href, {
maxBytes: MAX_STYLESHEET_BYTES,
timeoutMs: 15_000,
});
} catch (err) {
defaultLogger.warn("[Compiler] External stylesheet fetch failed, preserving link tag.", {
urlFingerprint: identity.urlFingerprint,
host: identity.host,
error: err instanceof Error ? err.message : String(err),
});
return null;
}
}
/**
* Extract all `@font-face { ... }` blocks from a CSS string, preserving the
* full rule text (including the `@font-face` keyword and braces).
*
* Uses a depth-tracking scan instead of `[^}]*` so blocks with nested
* descriptor values that happen to contain `}` (rare but valid in
* `format(...)` hints with custom idents) are captured correctly.
*/
function extractFontFaceBlocks(css: string): string[] {
const blocks: string[] = [];
const atRule = /@font-face\s*/gi;
let m: RegExpExecArray | null;
while ((m = atRule.exec(css)) !== null) {
const openIdx = css.indexOf("{", m.index + m[0].length);
if (openIdx === -1) break;
let depth = 1;
let i = openIdx + 1;
for (; i < css.length && depth > 0; i++) {
if (css[i] === "{") depth++;
else if (css[i] === "}") depth--;
}
if (depth === 0) {
blocks.push(css.slice(m.index, i));
atRule.lastIndex = i;
}
}
return blocks;
}
/**
* Find all external `<link rel="stylesheet">` tags pointing to non-Google
* CDNs, fetch their CSS, and replace the `<link>` with an inline `<style>`
* containing only the `@font-face` rules. This allows Phase 2 (the existing
* inline scan) to pick up and localise the font file URLs.
*
* Google Fonts links are excluded because the deterministic font injector
* handles those. If a fetch fails or the CSS has no `@font-face` blocks,
* the original `<link>` tag is preserved (graceful degradation).
*/
// fallow-ignore-next-line complexity
async function inlineExternalFontStylesheets(html: string): Promise<string> {
const linkRe = /<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi;
const hrefRe = /\bhref=["']([^"']+)["']/i;
const linkMatches: { fullMatch: string; href: string }[] = [];
let linkMatch: RegExpExecArray | null;
while ((linkMatch = linkRe.exec(html)) !== null) {
const tag = linkMatch[0];
const hrefMatch = hrefRe.exec(tag);
if (!hrefMatch?.[1]) continue;
const href = hrefMatch[1];
if (!/^https?:\/\//i.test(href)) continue;
if (isGoogleFontsUrl(href)) continue;
linkMatches.push({ fullMatch: tag, href });
}
if (linkMatches.length === 0) return html;
const MAX_CONCURRENT_STYLESHEET_FETCHES = 4;
const fetches: { fullMatch: string; href: string; css: string | null }[] = [];
for (let i = 0; i < linkMatches.length; i += MAX_CONCURRENT_STYLESHEET_FETCHES) {
const batch = linkMatches.slice(i, i + MAX_CONCURRENT_STYLESHEET_FETCHES);
const results = await Promise.all(
batch.map(async ({ fullMatch, href }) => {
const css = await fetchExternalStylesheetCss(href);
return { fullMatch, href, css };
}),
);
fetches.push(...results);
}
let result = html;
for (const { fullMatch, href, css } of fetches) {
if (css === null) continue;
const fontFaceBlocks = extractFontFaceBlocks(css);
if (fontFaceBlocks.length === 0) continue;
const identity = safeDownloadUrlIdentity(href);
const inlineStyle = `<style>/* Inlined external font stylesheet */\n${fontFaceBlocks.join("\n")}\n</style>`;
result = result.replace(fullMatch, inlineStyle);
defaultLogger.info("[Compiler] Inlined external @font-face rule(s)", {
count: fontFaceBlocks.length,
urlFingerprint: identity.urlFingerprint,
host: identity.host,
});
}
return result;
}
/**
* Collect all remote `url(https://...)` references inside `@font-face` blocks
* found in `<style>` tags.
*/
// fallow-ignore-next-line complexity
function collectFontFaceUrls(html: string): Set<string> {
const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
const urlSet = new Set<string>();
let styleMatch: RegExpExecArray | null;
while ((styleMatch = styleBlockRe.exec(html)) !== null) {
const cssText = styleMatch[1] ?? "";
// Depth-tracking scanner to correctly handle @font-face blocks that
// contain nested braces (e.g. unicode-range fallback rules).
let i = 0;
while (i < cssText.length) {
const atIdx = cssText.indexOf("@font-face", i);
if (atIdx === -1) break;
const braceStart = cssText.indexOf("{", atIdx);
if (braceStart === -1) break;
let depth = 1;
let j = braceStart + 1;
while (j < cssText.length && depth > 0) {
if (cssText[j] === "{") depth++;
else if (cssText[j] === "}") depth--;
j++;
}
const block = cssText.slice(braceStart + 1, j - 1);
const urlRe = new RegExp(REMOTE_FONTFACE_URL_RE.source, REMOTE_FONTFACE_URL_RE.flags);
let urlMatch: RegExpExecArray | null;
while ((urlMatch = urlRe.exec(block)) !== null) {
if (urlMatch[1]) urlSet.add(urlMatch[1]);
}
i = j;
}
}
return urlSet;
}
/** @internal exported for unit testing only */
export async function localizeRemoteFontFaces(
html: string,
downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
// Phase 1: Inline @font-face rules from external <link rel="stylesheet"> tags.
const processed = await inlineExternalFontStylesheets(html);
// Phase 2: Download font file URLs from all @font-face blocks (both
// pre-existing inline blocks and the ones just inlined from external sheets).
const urlSet = collectFontFaceUrls(processed);
return downloadAndRewriteUrls(
urlSet,
processed,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote font download failed",
"Localized remote font face(s)",
(h, url, relPath) => h.replaceAll(`url(${url})`, `url("${relPath}")`),
);
}
// `file:` joins data: and http(s): in the exclusion list. Without it an
// absolute `file:///abs/path/font.ttf` src was read as a project-RELATIVE path,
// resolved to `<projectDir>/file:/abs/path/...`, and the failed read was
// swallowed below — leaving the rule untouched for the browser to reject.
const LOCAL_FONTFACE_URL_RE = /url\(["']?(?!data:|file:|https?:\/\/)([^"')]+)["']?\)/gi;
/**
* Match one `url(<path>)` occurrence, with or without quotes, for a literal
* path. Exported for tests: the suffix-collision it prevents is invisible in
* ordinary projects and easy to reintroduce.
*/
export function urlOccurrenceRe(localPath: string): RegExp {
const escaped = localPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
return new RegExp(`url\\((["']?)${escaped}\\1\\)`, "g");
}
// Base64 expands bytes by ~33%, then immutable HTML replacements retain more
// string copies while compiling. Files up to and including 5 MiB remain inline;
// the first byte above that stays file-backed. This conservative ceiling keeps
// verified 19 MiB+ TTC collections out of the V8 heap while both local and
// distributed file servers continue serving project assets at authored paths.
const MAX_LOCAL_FONT_DATA_URI_BYTES = 5 * 1024 * 1024;
type LocalFontRead = { kind: "file-backed" } | { kind: "inline"; buffer: Buffer };
async function readLocalFont(absPath: string): Promise<LocalFontRead> {
const chunks: Buffer[] = [];
let totalBytes = 0;
for await (const chunk of createReadStream(absPath)) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
totalBytes += buffer.length;
if (totalBytes > MAX_LOCAL_FONT_DATA_URI_BYTES) {
return { kind: "file-backed" };
}
chunks.push(buffer);
}
return { kind: "inline", buffer: Buffer.concat(chunks, totalBytes) };
}
// fallow-ignore-next-line complexity
async function embedLocalFontFaces(html: string, projectDir: string): Promise<string> {
const { fontToDataUri: toDataUri } = await import("@hyperframes/core/fonts/embed");
const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
const fontFaceRe = /@font-face\s*\{([^}]*)\}/gi;
let result = html;
const embeddedPaths = new Set<string>();
const dataUriByAbsolutePath = new Map<string, string>();
const fileBackedAbsolutePaths = new Set<string>();
let styleMatch: RegExpExecArray | null;
while ((styleMatch = styleBlockRe.exec(html)) !== null) {
const cssText = styleMatch[1] ?? "";
const ffRe = new RegExp(fontFaceRe.source, fontFaceRe.flags);
let ffMatch: RegExpExecArray | null;
while ((ffMatch = ffRe.exec(cssText)) !== null) {
const block = ffMatch[1] ?? "";
const urlRe = new RegExp(LOCAL_FONTFACE_URL_RE.source, LOCAL_FONTFACE_URL_RE.flags);
let urlMatch: RegExpExecArray | null;
while ((urlMatch = urlRe.exec(block)) !== null) {
const localPath = urlMatch[1];
if (!localPath || embeddedPaths.has(localPath)) continue;
const absPath = localPath.startsWith("/") ? localPath : resolve(projectDir, localPath);
if (!isPathInside(absPath, projectDir)) continue;
const ext = absPath.match(/\.(woff2?|ttf|otf|ttc)$/i)?.[1]?.toLowerCase() ?? "ttf";
try {
if (fileBackedAbsolutePaths.has(absPath)) {
embeddedPaths.add(localPath);
continue;
}
let dataUri = dataUriByAbsolutePath.get(absPath);
if (!dataUri) {
const font = await readLocalFont(absPath);
if (font.kind === "file-backed") {
fileBackedAbsolutePaths.add(absPath);
defaultLogger.info(
`[Compiler] Kept large local font file-backed: ${localPath} (> ${(MAX_LOCAL_FONT_DATA_URI_BYTES / 1024 / 1024).toFixed(1)} MB)`,
);
embeddedPaths.add(localPath);
continue;
}
dataUri = await toDataUri(font.buffer, ext, { compressToWoff2: false });
dataUriByAbsolutePath.set(absPath, dataUri);
defaultLogger.info(
`[Compiler] Embedded local font file: ${localPath} (${(font.buffer.length / 1024).toFixed(0)} KB → data URI)`,
);
}
// Anchored on the `url(...)` occurrence, not a bare substring. A
// plain replaceAll of `localPath` also rewrites that text anywhere
// else it appears -- including inside a LONGER url whose tail
// happens to match, e.g. embedding `fonts/x.ttf` would corrupt an
// untouched `url("file:///abs/fonts/x.ttf")` into
// `url("file:///abs/<data-uri>")`. Any two paths where one is a
// suffix of the other collide the same way. Every sibling rewrite
// in this file already anchors like this.
result = result.replace(urlOccurrenceRe(localPath), `url("${dataUri}")`);
embeddedPaths.add(localPath);
} catch (error) {
// Keep the original path: a font that cannot be read must not fail
// the render. Logged rather than silently swallowed -- a silent skip
// here means the composition renders in a fallback typeface and
// nothing says why.
defaultLogger.warn(
`[Compiler] Could not embed local font ${localPath}: ${
error instanceof Error ? error.message : String(error)
}`,
);
}
}
}
}
return result;
}
/**
* Optional behavior toggles for {@link compileForRender}. All fields are
* additive; omitting `options` preserves the in-process renderer's defaults.
*/
export interface CompileForRenderOptions {
/**
* Logger for compile-time diagnostics (e.g. the data-duration vs. media
* mismatch warning). Optional so non-render callers can omit it.
*/
log?: ProducerLogger;
/** Absolute project paths not on disk, readable at these URLs instead. */
urlByAbsentLocalPath?: ReadonlyMap<string, string>;
/**
* Threaded through to {@link injectDeterministicFontFaces}. When `true`,
* deterministic font resolution and exhausted transient fetch failures
* surface as typed errors instead of silently falling back to system fonts.
* Distributed `plan()` sets this to `true` so font availability is part of
* the planDir's content-addressed hash. Default `false` preserves the
* in-process behavior.
*/
failClosedFontFetch?: boolean;
/**
* When `true`, fonts not resolved by the bundled alias map or Google Fonts
* are located on the local filesystem, compressed to woff2, and embedded.
* Default `true` for local renders. Distributed callers pass `false` to
* prevent host-specific font capture from leaking into the planDir.
*/
allowSystemFontCapture?: boolean;
/** Caller cancellation propagated through compile-time font fetches. */
abortSignal?: AbortSignal;
/**
* Optional persistent cache directory for prep-time animated GIF → WebM
* transcodes. When omitted, the render's downloadDir is used.
*/
animatedGifCacheDir?: string;
/** FFmpeg timeout for animated GIF transcodes. */
ffmpegProcessTimeout?: number;
/**
* Render-time variable overrides (`--variables`). Layered over declared
* defaults in the compile-time CSS custom-property stylesheet so eval-time
* reads (GSAP .from immediateRender) see the overridden value — the
* `window.__hfVariables` injection covers script reads, not var() in CSS.
*/
variables?: Record<string, unknown>;
pageMotionBlur?: "off";
}
const GSAP_CDN_BASE = gsapCdnDist();
function rewriteUnresolvableGsapToCdn(html: string, projectDir: string): string {
return html.replace(
/(<script\b[^>]*\bsrc=["'])([^"']*gsap[^"']*\/dist\/([^"']+))(["'][^>]*>)/gi,
(full, prefix, src, file, suffix) => {
if (/^https?:\/\//i.test(src)) return full;
const absPath = resolve(projectDir, src);
if (existsSync(absPath)) return full;
defaultLogger.info(
`[Compiler] Rewriting missing gsap script to CDN: ${src} → ${GSAP_CDN_BASE}${file}`,
);
return `${prefix}${GSAP_CDN_BASE}${file}${suffix}`;
},
);
}
/**
* Preserve a nested entry document's browser URL base when compilation moves
* it to compiled/index.html. Use the same sibling-first/project-root-fallback
* rule as mounted sub-compositions so both supported entry modes agree.
*/
function rebaseDirectEntryAssetPaths(html: string, projectDir: string, htmlPath: string): string {
if (!isPathInside(htmlPath, projectDir)) return html;
const entryPath = relative(projectDir, htmlPath).replace(/\\/g, "/");
if (!entryPath.includes("/")) return html;
const { document } = parseHTML(html);
const assetExists = (path: string) => existsSync(resolve(projectDir, path));
rewriteAssetPaths(
document.querySelectorAll("[src], [href]"),
entryPath,
(el: Element, attr: string) => el.getAttribute(attr),
(el: Element, attr: string, value: string) => el.setAttribute(attr, value),
assetExists,
);
rewriteInlineStyleAssetUrls(
document.querySelectorAll("[style]"),
entryPath,
(el: Element) => el.getAttribute("style"),
(el: Element, value: string) => el.setAttribute("style", value),
assetExists,
);
for (const style of document.querySelectorAll("style")) {
style.textContent = rewriteCssAssetUrls(style.textContent || "", entryPath, assetExists);
}
return document.toString();
}
/**
* Compile an HTML composition project into a single self-contained HTML string
* with all media metadata resolved.
*/
// fallow-ignore-next-line complexity
export async function compileForRender(
projectDir: string,
htmlPath: string,
downloadDir: string,
options: CompileForRenderOptions = {},
): Promise<CompiledComposition> {
const entryHtml = rebaseDirectEntryAssetPaths(
readFileSync(htmlPath, "utf-8"),
projectDir,
htmlPath,
);
const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);
// Pre-flight: every data-composition-src reference must resolve to a
// usable file before we spend any time compiling, launching a browser, or
// waiting out a capture timeout. See EmptyCompositionError for why this is
// unconditional (not gated behind --strict like lint warnings) — a render
// that silently drops a scene is strictly worse than one that refuses to
// start.
assertSubCompositionsUsable(rawHtml, projectDir);
const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
rawHtml,
projectDir,
downloadDir,
options.log,
options.urlByAbsentLocalPath,
);
// Compile each referenced sub-composition so the inliner can hoist it.
const { subCompositions } = await parseSubCompositions(
compiledHtml,
projectDir,
downloadDir,
undefined,
options.urlByAbsentLocalPath,
);
// Ensure the HTML is a full document before inlining sub-compositions.
// When index.html is a fragment (no <html>/<head>/<body>), linkedom.parseHTML()
// returns a document with null head/body, which causes inlineSubCompositions to
// silently discard all collected composition styles and scripts.
const fullHtml = ensureFullDocument(compiledHtml);
// Inline sub-compositions into the main HTML so the runtime takes the same
// synchronous code path as the bundled preview (no async fetch of
// data-composition-src). This mirrors what htmlBundler.ts does for preview.
const inlinedHtml = inlineSubCompositions(
fullHtml,
subCompositions,
projectDir,
options.variables ?? {},
);
// Strip preload="none" from media elements — the renderer needs to load all
// media upfront for frame capture. Users add this to reduce browser memory in
// preview, but it causes the headless renderer to never load the media, leading
// to 45s timeout failures.
const sanitizedHtml = inlinedHtml.replace(
/(<(?:video|audio)\b[^>]*?)\s+preload\s*=\s*["']none["']/gi,
"$1",
);
const renderModeHints = detectRenderModeHints(sanitizedHtml, options.pageMotionBlur);
const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
// Detected BEFORE inlineExternalScripts: GSAP's own source contains
// `transformPerspective`, so scanning post-inline HTML would flag every
// composition that loads GSAP from a CDN.
const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
const usesMixBlendMode = detectMixBlendModeUsage(sanitizedHtml);
const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
injectTextRenderingRule(
coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml)),
),
);
const coalescedHtml = await injectDeterministicFontFaces(normalizedFontHtml, {
logger: defaultLogger,
failClosedFontFetch: options.failClosedFontFetch === true,
allowSystemFontCapture: options.allowSystemFontCapture,
abortSignal: options.abortSignal,
});
// CDN scripts are inlined after coalescing so they stay separate from the merged inline runs.
const assembledHtml = await inlineExternalScripts(coalescedHtml);
// Inject studio position seek re-apply script when positions are baked into HTML.
// GSAP overwrites the `translate` CSS property on every frame seek; this script
// re-asserts the CSS custom property var() form after each seek so dragged
// positions survive frame-by-frame rendering without a JSON sidecar.
const HF_POSITION_ATTRS = [
'data-hf-studio-path-offset="true"',
'data-hf-studio-box-size="true"',
'data-hf-studio-rotation="true"',
'data-hf-studio-motion="',
];
const hasPositionEdits = HF_POSITION_ATTRS.some((attr) => assembledHtml.includes(attr));
const htmlWithPositionScript = hasPositionEdits
? (insertBeforeCloseTag(
assembledHtml,
"body",
`<script>${createStudioPositionSeekReapplyScript()}\n//# sourceURL=hyperframes://position-seek-reapply</script>`,
) ?? assembledHtml)
: assembledHtml;
const htmlWithDeferredScripts = prepareCompositionScripts(
injectSdkPositionEditsRenderScript(htmlWithPositionScript),
);
// Download remote <video> and <audio> sources to compiledDir and rewrite the
// src attributes so the renderer reads from localhost. Remote S3 URLs cause
// Chrome to spend the entire pageReadyTimeout buffering 10+ large video files
// over the network; any that don't reach readyState >= 2 in time render as
// blank black frames. Localising them eliminates the race.
const { html: htmlWithLocalMedia, remoteMediaAssets } = await localizeRemoteMediaSources(
htmlWithDeferredScripts,
downloadDir,
);
// Download remote <img> sources. Same race shape as video/audio: the
// readiness gate can pass before Chrome decodes the pixels, and Chrome can
// evict decoded pixels mid-render and re-fetch, producing intermittent
// blank-frame flicker. Localising to disk removes both races.
const { html: htmlWithLocalImages, remoteMediaAssets: remoteImageAssets } =
await localizeRemoteImageSources(htmlWithLocalMedia, downloadDir);
// Download remote CSS background-image url() references. drawElementImage omits
// cross-origin content, so remote backgrounds render black on the fast path;
// localising them to same-origin closes that gap.
const { html: htmlWithLocalBg, remoteMediaAssets: remoteBgAssets } =
await localizeRemoteBackgroundImages(htmlWithLocalImages, downloadDir);
// Download remote @font-face src URLs and rewrite to local paths.
// Remote font URLs fail with a CORS rejection at render time (S3 does not
// allow http://localhost:PORT as origin), causing Chrome to silently fall
// back to the next font in the stack.
const { html: htmlWithLocalizedFonts, remoteMediaAssets: remoteFontAssets } =
await localizeRemoteFontFaces(htmlWithLocalBg, downloadDir);
const gifSourceAssets = new Map<string, string>(remoteImageAssets);
const {
html: htmlWithPreparedGifs,
preparedAssets: preparedGifAssets,
preparedGifs,
} = await prepareAnimatedGifInputs(htmlWithLocalizedFonts, {
projectDir,
downloadDir,
cacheDir: options.animatedGifCacheDir,
sourceAssets: gifSourceAssets,
timeoutMs: options.ffmpegProcessTimeout,
});
if (preparedGifs.length > 0) {
defaultLogger.info(`[Compiler] Prepared ${preparedGifs.length} animated GIF input(s) as WebM`);
}
const embeddedHtml = await embedLocalFontFaces(htmlWithPreparedGifs, projectDir);
// Collect assets that resolve outside projectDir (e.g. ../shared-assets/hero.png).
// These can't be served by the file server, so we map them to paths the
// orchestrator will copy into the compiled output directory.
const { html, externalAssets } = collectExternalAssets(embeddedHtml, projectDir);
for (const [relPath, absPath] of remoteMediaAssets) {
externalAssets.set(relPath, absPath);
}
for (const [relPath, absPath] of remoteImageAssets) {
externalAssets.set(relPath, absPath);
}
for (const [relPath, absPath] of remoteBgAssets) {
externalAssets.set(relPath, absPath);
}
for (const [relPath, absPath] of remoteFontAssets) {
externalAssets.set(relPath, absPath);
}
for (const [relPath, absPath] of preparedGifAssets) {
externalAssets.set(relPath, absPath);
}
// Read the media list off the inlined document rather than merging the
// per-file lists. Merging deduplicated by element id, which is only unique
// within one composition file: two scenes declaring `<video id="clip">` — or
// two bare `<video>`s, both auto-numbered `hf-video-0` — collapsed into one
// entry and injected frames onto whichever element came first. See #3340.
const { videos, audios, images, droppedMediaIds } = collectRenderMedia(html);
const masterFxChain = parseMasterFxChain(html);
// Advisory video checks (sparse keyframes, VFR). Fire-and-forget — these spawn
// ffprobe subprocesses and should not block compilation since they only produce warnings.
// The two probes run in sequence rather than in parallel: the keyframe analysis needs
// the video stream's own duration to classify a single-keyframe (single-GOP) file.
for (const video of videos) {
if (isHttpUrl(video.src)) continue;
const videoPath = resolve(projectDir, video.src);
const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
(async () => {
const metadata = await withMediaProbeSlot(() => extractMediaMetadata(videoPath));
const analysis = await withMediaProbeSlot(() =>
analyzeKeyframeIntervals(videoPath, metadata),
);
if (analysis.isProblematic) {
defaultLogger.warn(
`[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). ` +
`This causes seek failures and frame freezing. Re-encode with: ${reencode}`,
);
}
if (metadata.isVFR) {
// defaultLogger (stderr), not console.info (stdout) — matches the sibling
// warning above; a stdout line here corrupts `check --json` / `validate --json`.
defaultLogger.warn(
`[Compiler] Video "${video.id}" is variable frame rate (VFR); ` +
`the engine will normalize it to CFR before frame extraction. ` +
`If rendering feels slow on this video, pre-encode once with: ${reencode}`,
);
}
})().catch(() => {});
}
// Read dimensions from root composition element using DOM parser
const { document } = parseHTML(html);
const rootEl = document.querySelector("[data-composition-id]");
const width = rootEl ? parseInt(rootEl.getAttribute("data-width") || "1080", 10) : 1080;
const height = rootEl ? parseInt(rootEl.getAttribute("data-height") || "1920", 10) : 1920;
// Static duration (may be 0 if set at runtime by GSAP)
const staticDuration = rootEl
? (parseStrictFiniteTimingNumber(rootEl.getAttribute("data-duration")) ??
parseStrictFiniteTimingNumber(rootEl.getAttribute("data-composition-duration")) ??
0)
: 0;
return {
html,
subCompositions,
videos,
audios,
images,
droppedMediaIds,
...(masterFxChain ? { masterFxChain } : {}),
unresolvedCompositions,
externalAssets,
width,
height,
staticDuration,
renderModeHints,
hasShaderTransitions,
usesThreeDTransforms,
usesMixBlendMode,
hasAncestorBackgroundImage,
};
}
/**
* Discover media elements from the browser DOM after JavaScript has run.
* This catches videos/audios whose `src` is set dynamically via JS
* (e.g. `document.getElementById("pip-video").src = URL`), which the
* static regex parsers miss because the HTML has `src=""`. Clips are keyed
* by `data-hf-render-id` when present — author ids collide across inlined
* scenes, and this snapshot is the only identity those empty-src elements get.
*/
export interface BrowserMediaElement {
id: string;
tagName: "video" | "audio" | "image";
src: string;
start: number;
end: number;
duration: number;
/** True when compilation inferred duration from the fallback source. */
durationInferred: boolean;
mediaStart: number;
loop: boolean;
hasAudio: boolean;
volume: number;
/** The `muted` attribute/property. Preview silences muted media; the mix must too. */
muted: boolean;
}
export interface BrowserAudioVolumeAutomation {
id: string;
keyframes: AudioVolumeKeyframe[];
}
export async function discoverMediaFromBrowser(page: Page): Promise<BrowserMediaElement[]> {
const elements = await page.evaluate(() => {
const results: {
id: string;
tagName: "video" | "audio" | "image";
src: string;
start: number;
endRaw: string | null;
durationRaw: string | null;
intrinsicDuration: number;
durationInferred: boolean;
playbackStartRaw: string | null;
mediaStartRaw: string | null;
loop: boolean;
hasAudio: boolean;
volume: number;
muted: boolean;
}[] = [];
const autoImageIds = new Map<Element, string>();
let autoImageId = 0;
document.querySelectorAll("img[src]").forEach((image) => {
if (!image.id) autoImageIds.set(image, `hf-img-${autoImageId++}`);
});
const mediaEls = new Set<Element>(
document.querySelectorAll("video[data-start], audio[data-start], img[data-var-src]"),
);
// A variable-bound <picture><source> changes the owning image's currentSrc;
// the <img> fallback itself does not necessarily carry data-var-src.
document.querySelectorAll("picture source[data-var-src]").forEach((source) => {
const image = source.closest("picture")?.querySelector("img");
if (image) mediaEls.add(image);
});
mediaEls.forEach((el) => {
const htmlEl = el as HTMLVideoElement | HTMLAudioElement | HTMLImageElement;
const isImage = htmlEl.tagName.toLowerCase() === "img";
const tagName: "video" | "audio" | "image" = isImage
? "image"
: htmlEl.tagName.toLowerCase() === "video"
? "video"
: "audio";
// Render id is document-unique after inlining; author id is only unique
// per composition file. Empty-src media is skipped by the static parse
// and lives or dies on this snapshot — keying by author id collapses
// colliding scenes onto one clip (residual of #3340).
const id =
htmlEl.getAttribute("data-hf-render-id") ||
htmlEl.id ||
(isImage ? autoImageIds.get(htmlEl) : undefined);
if (!id) return;
// currentSrc is authoritative for <video>/<audio><source> and responsive images.
const ownSrc = htmlEl.getAttribute("src");
const blankSrc =
ownSrc !== null && ownSrc.trim() === "" && !htmlEl.querySelector("source[src]");
const src = blankSrc ? "" : htmlEl.currentSrc || htmlEl.src || ownSrc || "";
const start = parseFloat(htmlEl.getAttribute("data-start") || "0");
const endRaw = htmlEl.getAttribute("data-end");
const durationRaw = htmlEl.getAttribute("data-duration");
const durationInferred = htmlEl.hasAttribute("data-hf-inferred-duration");
const intrinsicDuration = isImage
? 0
: (htmlEl as HTMLVideoElement | HTMLAudioElement).duration;
const playbackStartRaw = htmlEl.getAttribute("data-playback-start");
const mediaStartRaw = htmlEl.getAttribute("data-media-start");
const loop = htmlEl.hasAttribute("loop");
const hasAudio = htmlEl.getAttribute("data-has-audio") === "true";
const volume = parseFloat(htmlEl.getAttribute("data-volume") || "1");
const muted =
!isImage &&
(htmlEl.hasAttribute("muted") || (htmlEl as HTMLVideoElement | HTMLAudioElement).muted);
results.push({
id,
tagName,
src,
start,
endRaw,
durationRaw,
intrinsicDuration,
durationInferred,
playbackStartRaw,
mediaStartRaw,
loop,
hasAudio,
volume,
muted,
});
});
return results;
});
return elements.map(
({ endRaw, durationRaw, intrinsicDuration, playbackStartRaw, mediaStartRaw, ...element }) => ({
...element,
end: parseStrictFiniteTimingNumber(endRaw) ?? 0,
duration:
element.durationInferred && Number.isFinite(intrinsicDuration) && intrinsicDuration > 0
? intrinsicDuration
: (parseStrictFiniteTimingNumber(durationRaw) ?? 0),
mediaStart: readMediaStart({
getAttribute(name: string) {
if (name === "data-playback-start") return playbackStartRaw;
if (name === "data-media-start") return mediaStartRaw;
return null;
},
}),
}),
);
}
export async function discoverAudioVolumeAutomationFromTimeline(
page: Page,
audioIds: string[],
compositionDuration: number,
sampleFps: number,
): Promise<BrowserAudioVolumeAutomation[]> {
if (audioIds.length === 0 || compositionDuration <= 0) return [];
const sampleStep = 1 / Math.min(60, Math.max(1, sampleFps));
const rawWindows = await page.evaluate((ids: string[]) => {
return ids.flatMap((id) => {
const el =
window.__hfMediaEl?.(id) ??
document.getElementById(id) ??
document.getElementById(id.replace(/-audio$/, ""));
if (!(el instanceof HTMLAudioElement) && !(el instanceof HTMLVideoElement)) return [];
return [
{
id,
startRaw: el.dataset.start ?? null,
endRaw: el.dataset.end ?? null,
durationRaw: el.dataset.duration ?? null,
},
];
});
}, audioIds);
const clips = rawWindows.map(({ id, startRaw, endRaw, durationRaw }) => {
const start = parseStrictFiniteTimingNumber(startRaw) ?? 0;
const authoredDuration = parseStrictFiniteTimingNumber(durationRaw);
const authoredEnd = parseStrictFiniteTimingNumber(endRaw);
const end =
authoredDuration != null && authoredDuration > 0
? start + authoredDuration
: authoredEnd != null && authoredEnd > start
? authoredEnd
: compositionDuration;
return { id, start, end };
});
return page.evaluate(
({ clips, duration, step, maxGain }) => {
const results: { id: string; keyframes: { time: number; volume: number }[] }[] = [];
const clampGain = (value: number) =>
Number.isFinite(value) ? Math.max(0, Math.min(maxGain, value)) : 1;
// `HTMLMediaElement.volume` is spec-clamped to [0,1], so a clip authored
// above unity — or a GSAP tween seeded from one — reads back as 0 dB and
// the whole authored boost is lost from the mix. Shadow the accessor for
// the probe so the authored value survives; the native setter still gets
// the clamped value. Mirrors `withUnclampedVolume` in
// packages/core/src/audioGain.ts, which the preview probe uses; this copy
// exists only because the probe body is serialized into the page.
//
// Guarded because this body is also executed directly by tests that stand
// in for a Page, where there is no DOM and no HTMLMediaElement.
const volumeDescriptor =
typeof HTMLMediaElement === "undefined"
? undefined
: Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
const nativeVolumeGet = volumeDescriptor?.get;
const nativeVolumeSet = volumeDescriptor?.set;
const withUnclampedVolume = <T>(el: HTMLMediaElement, probe: () => T): T => {
if (!nativeVolumeGet || !nativeVolumeSet) return probe();
let authored = Number(nativeVolumeGet.call(el));
Object.defineProperty(el, "volume", {
configurable: true,
get: () => authored,
set: (value: number) => {
authored = Number(value);
nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
},
});
try {
return probe();
} finally {
delete (el as unknown as Record<"volume", unknown>).volume;
nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
}
};
const timelines = (window as unknown as { __timelines?: Record<string, unknown> })
.__timelines;
if (!timelines) return results;
const rootEl = document.querySelector("[data-composition-id]");
const compId = rootEl?.getAttribute("data-composition-id");
if (!compId) return results;
const tl = timelines[compId] as
| {
totalTime?: (t: number, suppressEvents?: boolean) => unknown;
seek?: (t: number, suppressEvents?: boolean) => unknown;
}
| undefined;
if (!tl) return results;
const seekTl = (t: number) => {
if (typeof tl.totalTime === "function") {
tl.totalTime(t, true);
} else if (typeof tl.seek === "function") {
tl.seek(t, true);
}
};
for (const { id, start, end } of clips) {
const el =
window.__hfMediaEl?.(id) ??
document.getElementById(id) ??
document.getElementById(id.replace(/-audio$/, ""));
if (!(el instanceof HTMLAudioElement) && !(el instanceof HTMLVideoElement)) continue;
const sampleStart = Math.max(0, start);
const sampleEnd = Math.min(duration, end);
const initialVolumeAttr = Number.parseFloat(el.dataset.volume ?? "");
const keyframes = withUnclampedVolume(el, () => {
if (Number.isFinite(initialVolumeAttr)) {
el.volume = clampGain(initialVolumeAttr);
}
const keyframes: { time: number; volume: number }[] = [];
let previousSample: { time: number; volume: number } | undefined;
for (let t = sampleStart; t <= sampleEnd + 0.000001; t = Math.min(sampleEnd, t + step)) {
seekTl(t);
const rawVolume = Number(el.volume);
if (!Number.isFinite(rawVolume)) {
if (t === sampleEnd) break;
continue;
}
const volume = clampGain(rawVolume);
const sample = {
time: Number(t.toFixed(6)),
volume: Number(volume.toFixed(6)),
};
const last = keyframes.at(-1);
if (!last || Math.abs(last.volume - volume) > 0.0001) {
// Retain the preceding real sample when compression omitted a flat
// run. Continuous ramps already have that sample as their last
// keyframe, so their interpolation remains unchanged.
if (last && previousSample && previousSample.time > last.time) {
keyframes.push(previousSample);
}
keyframes.push(sample);
} else if (t === sampleEnd && sample.time > last.time) {
keyframes.push(sample);
}
previousSample = sample;
if (t === sampleEnd) break;
}
return keyframes;
});
const staticAttr = Number.parseFloat(el.dataset.volume ?? "");
const staticVolume = Number.isFinite(staticAttr) ? clampGain(staticAttr) : 1;
const hasAutomation = keyframes.some(
(keyframe) => Math.abs(keyframe.volume - staticVolume) > 0.0001,
);
if (hasAutomation) {
results.push({ id, keyframes });
}
}
seekTl(0);
return results;
},
{ clips, duration: compositionDuration, step: sampleStep, maxGain: MAX_AUDIO_GAIN },
);
}
export interface VideoVisibilityWindow {
videoId: string;
visibleStart: number;
visibleEnd: number;
}
/**
* Seek the GSAP timeline to discover when each video's parent scene is visible.
* Only processes videos with the data-hf-auto-start sentinel (auto-injected timing).
*/
export async function discoverVideoVisibilityFromTimeline(
page: Page,
compositionDuration: number,
): Promise<VideoVisibilityWindow[]> {
if (compositionDuration <= 0) return [];
return page.evaluate((duration: number) => {
const results: { videoId: string; visibleStart: number; visibleEnd: number }[] = [];
const videos = document.querySelectorAll("video[data-hf-auto-start]");
if (videos.length === 0) return results;
const timelines = (window as unknown as { __timelines?: Record<string, unknown> }).__timelines;
if (!timelines) return results;
const rootEl = document.querySelector("[data-composition-id]");
const compId = rootEl?.getAttribute("data-composition-id");
if (!compId) return results;
const tl = timelines[compId] as
| {
totalTime?: (t: number, suppressEvents?: boolean) => unknown;
seek?: (t: number, suppressEvents?: boolean) => unknown;
}
| undefined;
if (!tl) return results;
const seekTl = (t: number) => {
if (typeof tl.totalTime === "function") {
tl.totalTime(t, true);
} else if (typeof tl.seek === "function") {
tl.seek(t, true);
}
};
const SAMPLE_STEP = 0.1;
const BINARY_PRECISION = 1 / 60;
// Seek once per timestep and sample every video — seeking dominates and is
// independent of which element we read.
const entries: {
id: string;
sceneEl: Element;
firstVisible: number | null;
lastVisible: number | null;
}[] = [];
for (const videoEl of videos) {
const id = videoEl.getAttribute?.("data-hf-render-id") || videoEl.id;
if (!id) continue;
entries.push({
id,
sceneEl: videoEl.closest(".scene") || videoEl,
firstVisible: null,
lastVisible: null,
});
}
if (entries.length === 0) return results;
for (let t = 0; t <= duration; t += SAMPLE_STEP) {
seekTl(t);
for (const entry of entries) {
const opacity = parseFloat(window.getComputedStyle(entry.sceneEl).opacity);
if (opacity > 0) {
if (entry.firstVisible === null) entry.firstVisible = t;
entry.lastVisible = t;
}
}
}
// Per-video boundary refinement (cheap: O(log(step)) seeks each).
for (const entry of entries) {
const { id, sceneEl, firstVisible, lastVisible } = entry;
if (firstVisible === null || lastVisible === null) continue;
// Binary search left boundary
let lo = Math.max(0, firstVisible - SAMPLE_STEP);
let hi = firstVisible;
while (hi - lo > BINARY_PRECISION) {
const mid = (lo + hi) / 2;
seekTl(mid);
const opacity = parseFloat(window.getComputedStyle(sceneEl).opacity);
if (opacity > 0) hi = mid;
else lo = mid;
}
const exactStart = hi;
// Binary search right boundary
lo = lastVisible;
hi = Math.min(duration, lastVisible + SAMPLE_STEP);
while (hi - lo > BINARY_PRECISION) {
const mid = (lo + hi) / 2;
seekTl(mid);
const opacity = parseFloat(window.getComputedStyle(sceneEl).opacity);
if (opacity > 0) lo = mid;
else hi = mid;
}
const exactEnd = lo;
results.push({
videoId: id,
visibleStart: Math.max(0, exactStart),
visibleEnd: Math.min(duration, exactEnd),
});
}
seekTl(0);
return results;
}, compositionDuration);
}
/**
* Resolve composition durations via Puppeteer by querying window.__timelines.
* The page must already have the interceptor loaded and timelines registered.
*/
export async function resolveCompositionDurations(
page: Page,
unresolved: UnresolvedElement[],
): Promise<ResolvedDuration[]> {
if (unresolved.length === 0) return [];
const ids = unresolved.map((el) => el.id);
const results = await page.evaluate((compIds: string[]) => {
const win = window as unknown as { __timelines?: Record<string, { duration(): number }> };
const timelines = win.__timelines || {};
const resolved: {
id: string;
duration: number;
source: string;
durationRaw?: string;
compositionDurationRaw?: string;
}[] = [];
for (const id of compIds) {
// Try window.__timelines[id].duration() first (GSAP timeline)
const tl = timelines[id];
let dur = 0;
try {
dur = typeof tl?.duration === "function" ? Number(tl.duration()) : 0;
} catch {
dur = 0;
}
if (dur > 0) {
resolved.push({ id, duration: dur, source: "__timelines" });
continue;
}
// Fallback: check for authored duration on the element itself
const el = document.getElementById(id);
if (el) {
const durationRaw = el.getAttribute("data-duration");
const compositionDurationRaw = el.getAttribute("data-composition-duration");
if (durationRaw != null || compositionDurationRaw != null) {
resolved.push({
id,
duration: 0,
source: "data-duration",
...(durationRaw != null ? { durationRaw } : {}),
...(compositionDurationRaw != null ? { compositionDurationRaw } : {}),
});
continue;
}
}
resolved.push({ id, duration: 0, source: "unresolved" });
}
return resolved;
}, ids);
const resolutions: ResolvedDuration[] = [];
for (const r of results) {
const duration =
parseStrictFiniteTimingNumber(r.durationRaw) ??
parseStrictFiniteTimingNumber(r.compositionDurationRaw) ??
r.duration;
if (duration != null && duration > 0) {
resolutions.push({ id: r.id, duration });
}
}
return resolutions;
}
/**
* Re-compile after composition durations are resolved.
* Injects durations into the HTML and re-parses sub-composition media with proper bounds.
*/
export async function recompileWithResolutions(
compiled: CompiledComposition,
resolutions: ResolvedDuration[],
projectDir: string,
downloadDir: string,
): Promise<CompiledComposition> {
if (resolutions.length === 0) return compiled;
const html = injectDurations(compiled.html, resolutions);
// Re-resolve the sub-composition map against the updated HTML, but keep the
// media list from the first pass. Resolving a composition's duration stamps a
// `data-end` on its host, and re-collecting would newly clamp clips to it —
// a retiming, not an identity fix. `compiled.videos` was already collected
// from this same inlined document, so it is complete and correctly keyed.
const { subCompositions } = await parseSubCompositions(html, projectDir, downloadDir);
const { videos, audios, images } = compiled;
const remaining = compiled.unresolvedCompositions.filter(
(c) => !resolutions.some((r) => r.id === c.id),
);
return {
...compiled,
html,
subCompositions,
videos,
audios,
images,
unresolvedCompositions: remaining,
renderModeHints: compiled.renderModeHints,
hasShaderTransitions: compiled.hasShaderTransitions,
};
}