Files
hyperframes/packages/producer/src/services/htmlCompiler.ts
T
Andy CheighandClaude Opus 5.5 524ea46bf9 fix(producer,parsers): render compile never looks for a scene's assets on another computer (#8063)
A scene mounted as `\\host\share/scene.html` read its own file from inside the
project, but its sibling assets were looked up next to `\\host\share`, which on
Windows connects to that host and sends the user's login. The compile's asset
checks now report any path outside the project as missing without touching the
disk, and a data-composition-src with a leading `\` or `./` is rewritten to the
project file it names before its assets are resolved.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 09:41:24 +00:00

3192 lines
124 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
import {
cssRuleMatches,
cssUrlMatches,
fontFaceBlockMatches,
hasBackgroundImageDeclaration,
importRuleMatches,
localFontFaceUrlMatches,
remoteBackgroundUrlMatches,
remoteFontFaceUrlMatches,
replaceMatches,
styleBlockMatches,
stylesheetLinkMatches,
} from "@hyperframes/parsers/css-url-scans";
// 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, sep } from "path";
import { parseHTML } from "linkedom";
import { bundledScript } from "./bundledScripts.js";
import {
inlineScriptBlocks,
remoteSrcUrls,
removeDelimitedRuns,
replaceGsapDistScripts,
stripCrossoriginAttr,
stripPreloadNone,
} from "./htmlTagScans.js";
import {
COMPOSITION_SOURCE_URL,
compileTimingAttrs,
injectDurations,
extractResolvedMedia,
clampDurations,
shouldClampResolvedMediaDuration,
isNonRelativeUrl,
parseStrictFiniteTimingNumber,
readMediaStart,
redactTelemetryString,
resolveNaturalMediaTimelineDurationFromValues,
rewriteAssetPath,
rewriteAssetPaths,
rewriteCssAssetUrls,
rewriteInlineStyleAssetUrls,
type RateSpec,
type ResolvedDuration,
type UnresolvedElement,
terminalText,
} from "@hyperframes/core";
import { MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
import { CAPTURE_CANVAS_SELECTOR } from "@hyperframes/core/html-in-canvas";
import { readPlaybackRate } from "@hyperframes/parsers/media-duration";
import { resolveRateSpec } from "@hyperframes/core/speed-ramp";
import { gsapCdnDist, normalizeGsapBaseUrl } from "@hyperframes/core/gsap-cdn";
import {
assignBundledRuntimeCompositionIds,
assignMediaRenderIds,
type BundledHostCompositionIdentity,
emitVariablesByCompScript,
inlineSubCompositions as inlineSubCompositionsShared,
ensureExternalLinkTag,
ensureExternalScriptTag,
deferScriptsUntilFonts,
emitMountedModuleScripts,
isJavaScriptType,
prepareFlattenedInnerRoot,
emitRootCompositionVariableStyles,
readDeclaredDefaults,
parseHostVariableValues,
boundMediaSrc,
headStyleRuns,
isAlwaysAppliedStyle,
dedupeFontFaceRules,
inlineScriptRuns,
parsesAsScript,
styleElementsFor,
insertBeforeCloseTag,
isRuntimeFileUrl,
} from "@hyperframes/core/compiler";
import {
checkSubCompositionUsability,
type ParsableDocumentLike,
} from "@hyperframes/parsers/sub-composition-validity";
import {
isUnresolvedAssetPlaceholder,
namesAnotherNetworkRoot,
projectAssetExists,
readProjectFile,
readTextFile,
resolveCompositionSrc,
} from "@hyperframes/parsers/asset-resolution";
import { isPrivateFileUnder, isStudioPrivatePath } from "@hyperframes/core/safe-path";
import { linksOutside } from "@hyperframes/studio-server/outside-file";
import { extractMediaMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
import { assertCompositionFileSize, CompositionExpansionBudget } from "./compositionSizeLimit.js";
import {
escapesAssetRoot,
isPathInside,
leftOutOfRender,
outsideAssetRefusal,
type OutsideFilePolicy,
refusesOutsideLink,
toExternalAssetKey,
} from "../utils/paths.js";
import { collectHiddenVideoIds, collectRenderMedia } from "./renderMediaCollector.js";
import {
type VideoElement,
type ImageElement,
type AudioElement,
type AudioVolumeKeyframe,
type MediaProbeProfile,
analyzeKeyframeIntervals,
assertMediaPayload,
isPrivateUnderAssetRoots,
NotMediaPayloadError,
parseMasterFxChain,
probeMediaProfile,
} from "@hyperframes/engine";
import {
downloadToTemp,
fetchPublicHttpsBytes,
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 { prepareHeifImageInputs } from "./heifImagePrep.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.debug("[Compiler] Remote asset download integrity", { ...event });
}
export interface CompiledComposition {
html: string;
subCompositions: Map<string, string>;
videos: VideoElement[];
audios: AudioElement[];
images: ImageElement[];
droppedMediaIds: Set<string>;
gradedCanvas: boolean;
masterFxChain?: string;
unresolvedCompositions: UnresolvedElement[];
variablesByComp: Record<string, Record<string, unknown>>;
/** 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;
/** 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;
}
}
/** The html with each data-composition-src as the project-relative path it names (%xx decoded, no leading /, \ or ./). */
function normalizeCompositionSrcs(html: string, projectDir: string): string {
return html.replace(/(\bdata-composition-src=)(["'])([^"']*)\2/g, (whole, name, quote, value) => {
if (!value.includes("%") && !/^\.?[\\/]/.test(value)) return whole;
const file = resolveCompositionSrc(projectDir, value);
if (file === null) return whole;
return `${name}${quote}${relative(projectDir, file).split(sep).join("/")}${quote}`;
});
}
const COMPOSITION_FILE = /\.html?$/i;
const NOT_A_COMPOSITION_FILE = "it is not an .html file, so it is refused";
function resolveCompositionPath(
projectDir: string,
src: string,
assetRoot: string | undefined,
): string | null {
const file = resolveCompositionSrc(projectDir, src);
return file === null || escapesAssetRoot(file, assetRoot) ? null : file;
}
function resolveCompositionFile(
projectDir: string,
src: string,
assetRoot: string | undefined,
): string | null {
const file = resolveCompositionPath(projectDir, src, assetRoot);
return file !== null && COMPOSITION_FILE.test(file) ? file : null;
}
const OUTSIDE_COMPOSITION_NEEDS_FLAG =
"it is outside the project, and any scripts in it would run; move it into the project, or pass --include-outside-files to hyperframes render, to include it";
/** A trusted local render was not told to run markup whose real file is outside the project. */
const runsOutsideMarkupUnasked = (
projectDir: string,
filePath: string,
assetRoot: string | undefined,
outsideFiles: OutsideFilePolicy,
): boolean =>
assetRoot === undefined && !outsideFiles.includeScripts && linksOutside(projectDir, filePath);
/** The readers check again, so a file swapped for an outside link after the pre-flight is still refused. */
function assertOutsideMarkupAsked(
projectDir: string,
filePath: string,
srcPath: string,
assetRoot: string | undefined,
outsideFiles: OutsideFilePolicy,
): void {
if (runsOutsideMarkupUnasked(projectDir, filePath, assetRoot, outsideFiles)) {
throw new EmptyCompositionError([{ srcPath, detail: OUTSIDE_COMPOSITION_NEEDS_FLAG }]);
}
}
// Git metadata, env files and the app's `.hyperframes/` records are never inlined into a render, as preview refuses them.
const isPrivateCompositionFile = (projectDir: string, filePath: string): boolean =>
isPrivateFileUnder(projectDir, filePath, isStudioPrivatePath);
type CompositionProblem = { srcPath: string; detail: string };
const mountSrcsUnder = (root: ParentNode): string[] =>
[...root.querySelectorAll("[data-composition-src]")]
.map((el) => el.getAttribute("data-composition-src"))
.filter((srcPath): srcPath is string => !!srcPath && !isUnresolvedAssetPlaceholder(srcPath));
/** `templated` holds the mounts inside `<template>` content, which a document query does not see. */
function compositionSrcsIn(html: string): { mounts: string[]; templated: string[] } {
const { document } = parseHTML(html);
const templated: string[] = [];
const templates = [...document.querySelectorAll("template")];
for (let template = templates.pop(); template; template = templates.pop()) {
templated.push(...mountSrcsUnder(template.content));
templates.push(...template.content.querySelectorAll("template"));
}
return { mounts: mountSrcsUnder(document), templated };
}
function compositionPathProblem(
projectDir: string,
filePath: string,
assetRoot: string | undefined,
outsideFiles: OutsideFilePolicy,
): string | null {
if (outsideAssetRefusal(projectDir, filePath) === "blocklisted") {
return "it is outside the project in a private location";
}
if (runsOutsideMarkupUnasked(projectDir, filePath, assetRoot, outsideFiles)) {
return OUTSIDE_COMPOSITION_NEEDS_FLAG;
}
if (isPrivateCompositionFile(projectDir, filePath)) {
return "it is git metadata, an env file or a private tool record";
}
return COMPOSITION_FILE.test(filePath) ? null : NOT_A_COMPOSITION_FILE;
}
function readSubCompositionFile(
filePath: string,
srcPath: string,
): { detail: string } | { bytes: number; mounts: string[]; templated: string[] } {
assertCompositionFileSize(filePath, srcPath);
const read = readProjectFile(filePath);
if (read.kind === "missing") return { detail: "the file does not exist" };
if (read.kind === "folder") return { detail: "it is a folder, not an HTML file" };
const validity = checkSubCompositionUsability(read.text, parseSubCompHtmlForValidity);
if (!validity.ok)
return { detail: validity.detail ?? "the file is empty or could not be parsed" };
return { bytes: Buffer.byteLength(read.text), ...compositionSrcsIn(read.text) };
}
/**
* 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.
*/
function assertSubCompositionsUsable(
html: string,
projectDir: string,
assetRoot: string | undefined,
outsideFiles: OutsideFilePolicy,
): void {
const budget = new CompositionExpansionBudget();
const files = new Map<string, ReturnType<typeof readSubCompositionFile>>();
const problems = new Map<string, CompositionProblem>();
const report = (srcPath: string, detail: string) =>
problems.set(`${srcPath}\0${detail}`, { srcPath, detail });
// The files on the current mount chain. A repeat is a cycle, which the compiler skips silently too.
const chain = new Set<string>();
const paths = new Map<string, { detail: string } | { filePath: string }>();
const resolveMount = (srcPath: string): { detail: string } | { filePath: string } => {
const filePath = resolveCompositionPath(projectDir, srcPath, assetRoot);
if (filePath === null) return { detail: "it is outside the project folder" };
const detail = compositionPathProblem(projectDir, filePath, assetRoot, outsideFiles);
return detail ? { detail } : { filePath };
};
// data-composition-src resolves root-relative at every level, as parseSubCompositions and the inliner
// resolve it, so `projectDir` stays unchanged. Each path is checked, and each file read, once.
// A mount inside a template is charged to the budget but not reported: the inliner skips it with a warning.
const walk = (srcPaths: readonly string[], quiet: boolean): void => {
for (const srcPath of srcPaths) {
let resolved = paths.get(srcPath);
if (!resolved) {
resolved = resolveMount(srcPath);
paths.set(srcPath, resolved);
}
if ("detail" in resolved) {
if (!quiet) report(srcPath, resolved.detail);
continue;
}
const { filePath } = resolved;
if (chain.has(filePath)) continue;
let file = files.get(filePath);
if (!file) {
file = readSubCompositionFile(filePath, srcPath);
files.set(filePath, file);
}
if ("detail" in file) {
if (!quiet) report(srcPath, file.detail);
continue;
}
budget.charge(srcPath, file.bytes);
chain.add(filePath);
walk(file.mounts, quiet);
walk(file.templated, true);
chain.delete(filePath);
}
};
const entry = compositionSrcsIn(html);
walk(entry.mounts, false);
walk(entry.templated, true);
if (problems.size > 0) {
throw new EmptyCompositionError([...problems.values()]);
}
}
export type RenderModeHintCode =
| "iframe"
| "requestAnimationFrame"
| "htmlInCanvas"
| "captureMotionBlur";
export interface RenderModeHint {
code: RenderModeHintCode;
message: string;
}
export interface RenderModeHints {
recommendScreenshot: boolean;
reasons: RenderModeHint[];
}
const COMPILER_MOUNT_BLOCK_START = "/* __HF_COMPILER_MOUNT_START__ */";
const COMPILER_MOUNT_BLOCK_END = "/* __HF_COMPILER_MOUNT_END__ */";
function stripJsComments(source: string): string {
return removeDelimitedRuns(source.replace(/\/\/.*$/gm, ""), "/*", "*/");
}
function stripCompilerMountBootstrap(source: string): string {
return removeDelimitedRuns(source, COMPILER_MOUNT_BLOCK_START, COMPILER_MOUNT_BLOCK_END);
}
/** 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(CAPTURE_CANVAS_SELECTOR)) {
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 motion blur (data-motion-blur="on"), drawn per frame with an SVG filter or, on the capture tier, 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.",
});
}
for (const { attrs, body } of inlineScriptBlocks(html)) {
if (/\bsrc\s*=/i.test(attrs)) continue;
const content = stripJsComments(stripCompilerMountBootstrap(body));
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);
}
/**
* 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 && hasBackgroundImageDeclaration(`{${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 { parts: rule } of cssRuleMatches(css)) {
const [, selectorList, declarations] = rule;
if (!hasBackgroundImageDeclaration(`{${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 {
for (const { attrs, body } of inlineScriptBlocks(html)) {
if (/\bsrc\s*=/i.test(attrs)) continue;
const content = stripJsComments(stripCompilerMountBootstrap(body));
if (SHADER_TRANSITION_USAGE_PATTERN.test(content)) return true;
}
return false;
}
type SourceProbe = { profile: MediaProbeProfile; fileDuration: number | null } | { error: unknown };
/** One probe per unique source for a whole compile, whatever number of elements point at it. */
type SourceProbes = Map<string, Promise<SourceProbe>>;
async function resolveMediaDuration(
src: string,
mediaStart: number,
playbackRate: RateSpec,
projectDir: string,
baseDir: string,
downloadDir: string,
tagName: string,
elementIdentity: string,
log?: ProducerLogger,
urlByAbsentLocalPath?: ReadonlyMap<string, string>,
probes?: SourceProbes,
assetRoot?: string,
): Promise<{ duration: number | null; resolvedPath: string }> {
let filePath = src;
if (isHttpUrl(src)) {
const remoteDir = join(downloadDir, REMOTE_MEDIA_SUBDIR);
if (!existsSync(remoteDir)) mkdirSync(remoteDir, { recursive: true });
try {
filePath = await downloadToTemp(src, remoteDir, 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);
if (
escapesAssetRoot(filePath, assetRoot) ||
isPrivateUnderAssetRoots(filePath, [projectDir, downloadDir])
) {
return { duration: null, resolvedPath: filePath };
}
// ffprobe reads only the header of a remote source, so it is probed in place.
filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
if (!isHttpUrl(filePath) && namesAnotherNetworkRoot(baseDir, filePath)) {
return { duration: null, resolvedPath: 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;
};
const probe = () =>
withMediaProbeSlot(async (): Promise<SourceProbe> => {
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.
await assertMediaPayload(filePath, elementIdentity);
const profile = await probeMediaProfile(filePath);
if (tagName === "video") {
return { profile, fileDuration: (await extractMediaMetadata(filePath)).durationSeconds };
}
try {
return { profile, fileDuration: (await extractAudioMetadata(filePath)).durationSeconds };
} catch {
// Source file has no audio stream (e.g. a silent video used as an audio src).
// Duration 0 excludes the element from the composition, as missing files do.
return { profile, fileDuration: null };
}
} catch (error) {
return { error };
}
});
const key = `${tagName}\0${filePath}`;
let probed = probes?.get(key);
if (!probed) {
probed = probe();
probes?.set(key, probed);
}
const outcome = await probed;
if ("error" in outcome) {
// Invalid video sources surface their probe failure; invalid or unreadable
// audio sources resolve to zero duration and are excluded by the compiler.
if (tagName !== "video") {
if (outcome.error instanceof NotMediaPayloadError) {
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(outcome.error);
}
assertAssetMediaTypeProfile(
tagName === "video" ? "video" : "audio",
outcome.profile,
elementIdentity,
);
if (outcome.fileDuration === null) return { duration: null, resolvedPath: filePath };
const duration = resolveNaturalMediaTimelineDurationFromValues(
outcome.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,
projectDir: string,
baseDir: string,
downloadDir: string,
log?: ProducerLogger,
urlByAbsentLocalPath?: ReadonlyMap<string, string>,
probes?: SourceProbes,
assetRoot?: 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,
projectDir,
baseDir,
downloadDir,
el.tagName,
el.id,
log,
urlByAbsentLocalPath,
probes,
assetRoot,
).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 hiddenVideoIds = collectHiddenVideoIds(compiledHtml);
const clampResults = await Promise.all(
preResolved
.filter((el) => !!el.src && !el.loop && !hiddenVideoIds.has(el.id))
.map(async (el) => {
const { duration: maxDuration } = await resolveMediaDuration(
el.src!,
el.mediaStart,
el.playbackRate,
projectDir,
baseDir,
downloadDir,
el.tagName,
el.id,
log,
undefined,
probes,
assetRoot,
);
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 = stripCrossoriginAttr(compiledHtml, "video");
// 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 = stripCrossoriginAttr(compiledHtml, "img");
// 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 = stripCrossoriginAttr(compiledHtml, "audio");
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>,
probes?: SourceProbes,
assetRoot?: string,
outsideFiles: OutsideFilePolicy = {},
compiledSrcs: Set<string> = new Set(),
): 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 = resolveCompositionFile(projectDir, srcPath, assetRoot);
if (filePath === null || isPrivateCompositionFile(projectDir, filePath)) continue;
// Circular reference guard
if (visited.has(filePath)) {
continue;
}
// A path compiles the same wherever it is mounted, so each one is compiled once per render.
if (compiledSrcs.has(srcPath)) continue;
compiledSrcs.add(srcPath);
assertOutsideMarkupAsked(projectDir, filePath, srcPath, assetRoot, outsideFiles);
assertCompositionFileSize(filePath, srcPath);
const read = readProjectFile(filePath);
if (read.kind !== "file") {
continue;
}
const rawSubHtml = normalizeCompositionSrcs(read.text, projectDir);
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(
rewriteUnresolvableGsapToCdn(item.rawSubHtml, projectDir, item.srcPath),
projectDir,
dirname(item.filePath),
downloadDir,
undefined,
urlByAbsentLocalPath,
probes,
assetRoot,
);
const nested = await parseSubCompositions(
compiledSub,
projectDir,
downloadDir,
item.nestedVisited,
urlByAbsentLocalPath,
probes,
assetRoot,
outsideFiles,
compiledSrcs,
);
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 liveStyles = [...document.querySelectorAll("style")].filter(isAlwaysAppliedStyle);
const dedupedStyles = dedupeFontFaceRules(liveStyles.map((el) => el.textContent || ""));
liveStyles.forEach((el, i) => {
el.textContent = dedupedStyles[i] ?? "";
});
const styleEls = head ? Array.from(head.querySelectorAll("style")) : [];
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 = replaceMatches(raw, importRuleMatches(raw), (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>,
assetRoot: string | undefined,
outsideFiles: OutsideFilePolicy,
): { html: string; variablesByComp: Record<string, Record<string, unknown>> } {
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 { html: emitted ? document.toString() : html, variablesByComp: {} };
}
const budget = new CompositionExpansionBudget();
const readOnce = new Map<string, string | null>();
const readMountHtml = (srcPath: string): string | null => {
const filePath = resolveCompositionFile(projectDir, srcPath, assetRoot);
if (filePath) {
assertOutsideMarkupAsked(projectDir, filePath, srcPath, assetRoot, outsideFiles);
assertCompositionFileSize(filePath, srcPath);
}
const read =
filePath && !isPrivateCompositionFile(projectDir, filePath)
? readProjectFile(filePath)
: null;
return read?.kind === "file"
? rewriteUnresolvableGsapToCdn(
normalizeCompositionSrcs(read.text, projectDir),
projectDir,
srcPath,
)
: null;
};
const resolveMountHtml = (srcPath: string): string | null => {
const compiled = subCompositions.get(srcPath);
if (compiled) return compiled;
if (!readOnce.has(srcPath)) readOnce.set(srcPath, readMountHtml(srcPath));
return readOnce.get(srcPath) ?? null;
};
// 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) => {
const compHtml = resolveMountHtml(srcPath);
if (compHtml) budget.charge(srcPath, Buffer.byteLength(compHtml));
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: projectAssetExists(projectDir),
// 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(
terminalText(
`[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);
}
}
}
// The per-instance variables table must exist before the sub-comp scripts run (their scoped getVariables() reads
// it); the render path once dropped it (issue #2064). Same shared emitter as the bundler so they stay in lockstep.
emitVariablesByCompScript(document as unknown as Document, result.variablesByComp);
if (body) {
let pending: string[] = [];
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 { html: document.toString(), variablesByComp: result.variablesByComp };
}
/**
* 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")),
);
}
const MAX_SCRIPT_BYTES = 16 * 1024 * 1024;
/** The operator's `HYPERFRAMES_GSAP_BASE_URL` may be on this machine; a composition's own URLs never are. */
function operatorGsapMirror(): string | undefined {
const raw = process.env.HYPERFRAMES_GSAP_BASE_URL?.trim();
if (!raw || raw.startsWith("/")) return undefined;
try {
return `${normalizeGsapBaseUrl(raw)}/`;
} catch {
return undefined;
}
}
async function downloadScript(src: string, mirror: string | undefined): Promise<Uint8Array> {
if (mirror && new URL(src).href.startsWith(mirror)) {
const response = await fetch(src, { redirect: "error", signal: AbortSignal.timeout(15_000) });
if (!response.ok) throw new Error(`HTTP ${response.status} for ${src}`);
const bytes = new Uint8Array(await response.arrayBuffer());
if (bytes.byteLength > MAX_SCRIPT_BYTES) throw new Error(`Script over 16 MiB: ${src}`);
return bytes;
}
return fetchPublicHttpsBytes(src, { maxBytes: MAX_SCRIPT_BYTES, timeoutMs: 15_000 });
}
/**
* 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 mirror = operatorGsapMirror();
const downloads = await Promise.allSettled(
externalScripts.map(async ({ el, src }) => {
const integrity = el.getAttribute("integrity") || "";
// The host's own copy needs no network; one that fails the tag's integrity metadata is not used.
const bundled = bundledScript(src);
if (bundled && matchesScriptIntegrity(bundled, integrity)) {
return { src, text: new TextDecoder().decode(bundled) };
}
const bytes = await downloadScript(src, mirror);
if (!matchesScriptIntegrity(bytes, 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.debug(`[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,
log: ProducerLogger = defaultLogger,
file = "index.html",
policy: OutsideFilePolicy = {},
): { html: string; externalAssets: Map<string, string> } {
const absProjectDir = resolve(projectDir);
const externalAssets = new Map<string, string>();
const leftOut = new Set<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
}
const onShare = namesAnotherNetworkRoot(absProjectDir, absPath);
if (!onShare && !existsSync(absPath)) return null;
const refusal = onShare ? "network_share" : outsideAssetRefusal(absProjectDir, absPath, policy);
if (refusal) {
if (!leftOut.has(trimmed)) log.warn(`[Compiler] ${leftOutOfRender(file, trimmed, refusal)}`);
leftOut.add(trimmed);
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 = replaceMatches(css, cssUrlMatches(css), (full, quote, rawUrl) => {
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 = replaceMatches(style, cssUrlMatches(style), (full, quote, rawUrl) => {
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.debug(
`[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";
/**
* 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.debug(`[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([...remoteSrcUrls(html, "media"), ...remoteSrcUrls(html, "source")]);
const localized = await downloadAndRewriteUrls(
urlSet,
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote media download failed",
"Localized remote media source(s)",
);
return { ...localized, html: dropBindingOnLocalizedMedia(localized.html) };
}
/**
* A bound element now holds the downloaded copy. Its `data-var-src` would make the browser set the
* link back, giving the clip a second name and its sound a second lane.
*/
function dropBindingOnLocalizedMedia(html: string): string {
if (!html.includes("data-var-src")) return html;
const { document } = parseHTML(html);
let changed = false;
for (const el of document.querySelectorAll("video[data-var-src], audio[data-var-src]")) {
if (el.closest("[data-variable-values]")) continue;
if (!el.getAttribute("src")?.startsWith(`${REMOTE_MEDIA_SUBDIR}/`)) continue;
el.removeAttribute("data-var-src");
changed = true;
}
return changed ? document.toString() : html;
}
/**
* 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> }> {
// frameCapture's `pollImagesReady`/`decodeAllImages` cover any remote URL this misses.
const urlSet = new Set(remoteSrcUrls(html, "img"));
return downloadAndRewriteUrls(
urlSet,
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote image download failed",
"Localized remote image source(s)",
);
}
/**
* 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>();
for (const { parts } of remoteBackgroundUrlMatches(html)) {
if (parts[1] && !isGoogleFontsUrl(parts[1])) urlSet.add(parts[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})`),
);
}
/**
* 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.
*
* @internal exported for unit testing only
*/
export function extractFontFaceBlocks(css: string): string[] {
const blocks: string[] = [];
const closes = matchingBraces(css);
const atRule = /@font-face\s*/gi;
let open = -1;
for (let m = atRule.exec(css); m; m = atRule.exec(css)) {
if (open < atRule.lastIndex) open = css.indexOf("{", atRule.lastIndex);
if (open === -1) break;
const close = closes.get(open);
if (close === undefined) continue;
blocks.push(css.slice(m.index, close + 1));
atRule.lastIndex = close + 1;
}
return blocks;
}
/** The `}` that closes each `{` that has one, as a depth count from that `{` finds it. */
function matchingBraces(css: string): Map<number, number> {
const closes = new Map<number, number>();
const unclosed: number[] = [];
for (let i = 0; i < css.length; i++) {
if (css[i] === "{") unclosed.push(i);
else if (css[i] === "}" && unclosed.length > 0) closes.set(unclosed.pop()!, i);
}
return closes;
}
/**
* 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 hrefRe = /\bhref=["']([^"']+)["']/i;
const linkMatches: { fullMatch: string; href: string }[] = [];
for (const { parts } of stylesheetLinkMatches(html)) {
const tag = parts[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.debug("[Compiler] Inlined external @font-face rule(s)", {
count: fontFaceBlocks.length,
urlFingerprint: identity.urlFingerprint,
host: identity.host,
});
}
return result;
}
// Families a linked project stylesheet declares with an @font-face file the project ships.
function projectStylesheetFontFamilies(html: string, projectDir: string): string[] {
const families: string[] = [];
for (const {
parts: [tag],
} of stylesheetLinkMatches(html)) {
const href = /\bhref=["']([^"']+)["']/i.exec(tag)?.[1];
if (!href || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href)) continue;
const sheet = resolve(projectDir, decodedUrlPath(href).replace(/^(?:\.?\/)+/, ""));
if (!isPathInside(sheet, projectDir) || !existsSync(sheet)) continue;
for (const face of extractFontFaceBlocks(readFileSync(sheet, "utf8"))) {
const family = /font-family\s*:\s*([^;}]+)/i
.exec(face)?.[1]
?.trim()
.replace(/^['"]|['"]$/g, "");
const shipsFile = [...localFontFaceUrlMatches(face)].some(({ parts: [, url = ""] }) => {
const path = decodedUrlPath(url);
const file = path.startsWith("/")
? resolve(projectDir, `.${path}`)
: resolve(dirname(sheet), path);
return isPathInside(file, projectDir) && existsSync(file);
});
if (family && shipsFile) families.push(family);
}
}
return families;
}
/**
* 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 urlSet = new Set<string>();
for (const { parts } of styleBlockMatches(html)) {
const cssText = parts[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);
for (const { parts } of remoteFontFaceUrlMatches(block)) {
if (parts[1]) urlSet.add(parts[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> }> {
return localizeFontFaceUrls(await inlineExternalFontStylesheets(html), downloadDir);
}
/** Download the remote font files of the page's inline @font-face rules and point the rules at them. */
function localizeFontFaceUrls(
html: string,
downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
return downloadAndRewriteUrls(
collectFontFaceUrls(html),
html,
join(downloadDir, REMOTE_MEDIA_SUBDIR),
"Remote font download failed",
"Localized remote font face(s)",
(h, url, relPath) => h.replaceAll(`url(${url})`, `url("${relPath}")`),
);
}
/**
* 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,
assetRoot: string | undefined,
log: ProducerLogger = defaultLogger,
): Promise<string> {
const { fontToDataUri: toDataUri } = await import("@hyperframes/core/fonts/embed");
let result = html;
const embeddedPaths = new Set<string>();
const dataUriByAbsolutePath = new Map<string, string>();
const fileBackedAbsolutePaths = new Set<string>();
for (const { parts: style } of styleBlockMatches(html)) {
for (const { parts: face } of fontFaceBlockMatches(style[1])) {
const block = face[1];
for (const { parts } of localFontFaceUrlMatches(block)) {
const localPath = parts[1];
if (!localPath || embeddedPaths.has(localPath)) continue;
const absPath = localPath.startsWith("/") ? localPath : resolve(projectDir, localPath);
if (!isPathInside(absPath, projectDir) || escapesAssetRoot(absPath, assetRoot)) continue;
// A project font that is a link leading outside obeys the same policy as the file server.
if (refusesOutsideLink(projectDir, absPath, (line) => log.warn(`[Compiler] ${line}`))) {
embeddedPaths.add(localPath);
continue;
}
if (isPrivateCompositionFile(projectDir, absPath)) 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.debug(
`[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.debug(
`[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;
/** Persistent cache directory for the animated GIF and HEIC prep transcodes; defaults to downloadDir. */
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";
/** Trusted local renders only (CLI, Studio): import files markup reaches outside projectDir. */
allowOutsideProjectAssets?: boolean;
includeOutsideScripts?: boolean;
}
/** Renders follow the same `HYPERFRAMES_GSAP_BASE_URL` mirror as Studio preview. */
function renderGsapDist(): string {
try {
return gsapCdnDist(undefined, normalizeGsapBaseUrl(process.env.HYPERFRAMES_GSAP_BASE_URL));
} catch (cause) {
throw new Error(
"Invalid HYPERFRAMES_GSAP_BASE_URL: use an absolute HTTPS npm mirror root (plain HTTP only for localhost) without credentials, query, or fragment",
{ cause },
);
}
}
/** `compSrcPath` resolves a sub-composition's script the way the inliner will hoist it. */
function rewriteUnresolvableGsapToCdn(
html: string,
projectDir: string,
compSrcPath?: string,
): string {
let gsapDist: string | undefined;
const exists = (path: string) => {
const file = resolve(projectDir, path);
return !namesAnotherNetworkRoot(projectDir, file) && existsSync(file);
};
return replaceGsapDistScripts(html, (full, prefix, src, file, suffix) => {
if (/^https?:\/\//i.test(src)) return full;
if (exists(compSrcPath ? rewriteAssetPath(compSrcPath, src, exists) : src)) return full;
gsapDist ??= renderGsapDist();
defaultLogger.debug(`[Compiler] Rewriting missing gsap script: ${src} → ${gsapDist}${file}`);
return `${prefix}${gsapDist}${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 = projectAssetExists(projectDir);
rewriteAssetPaths(
document.querySelectorAll("[src], [href], [srcset]"),
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();
}
/**
* Point each `data-var-src` video/audio at the clip its variable names, so the length and sound read below
* are the bound clip's. Media under a per-instance `data-variable-values` host keeps the browser's answer.
*/
function bindVariableMediaSources(html: string, variables: Record<string, unknown>): string {
if (!html.includes("data-var-src")) return html;
const { document } = parseHTML(html);
const declared: Record<string, unknown> = {};
for (const el of document.querySelectorAll("[data-composition-variables]")) {
Object.assign(declared, readDeclaredDefaults(el));
}
const values = { ...declared, ...variables };
let changed = false;
for (const el of document.querySelectorAll("video[data-var-src], audio[data-var-src]")) {
if (el.closest("[data-variable-values]")) continue;
const src = boundMediaSrc(el, values);
if (src === null || el.getAttribute("src") === src) continue;
el.setAttribute("src", src);
changed = true;
}
return changed ? document.toString() : html;
}
const entryFileName = (projectDir: string, htmlPath: string) =>
isPathInside(htmlPath, projectDir)
? relative(projectDir, htmlPath).split(sep).join("/")
: basename(htmlPath);
/**
* 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 assetRoot = options.allowOutsideProjectAssets ? undefined : projectDir;
const outsideFiles: OutsideFilePolicy = { includeScripts: options.includeOutsideScripts };
if (isPathInside(htmlPath, projectDir) && escapesAssetRoot(htmlPath, assetRoot)) {
throw new Error(`Entry file ${htmlPath} leads outside the project folder`);
}
if (
isPathInside(htmlPath, projectDir) &&
runsOutsideMarkupUnasked(projectDir, htmlPath, assetRoot, outsideFiles)
) {
throw new Error(`Entry file ${htmlPath} ${OUTSIDE_COMPOSITION_NEEDS_FLAG}`);
}
if (!COMPOSITION_FILE.test(htmlPath)) {
throw new Error(`Entry file ${htmlPath} is not an .html file, so it is refused`);
}
assertCompositionFileSize(htmlPath, basename(htmlPath));
const entryHtml = rebaseDirectEntryAssetPaths(readTextFile(htmlPath), projectDir, htmlPath);
const rawHtml = bindVariableMediaSources(
normalizeCompositionSrcs(rewriteUnresolvableGsapToCdn(entryHtml, projectDir), projectDir),
options.variables ?? {},
);
// 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, assetRoot, outsideFiles);
const probes: SourceProbes = new Map();
const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
rawHtml,
projectDir,
projectDir,
downloadDir,
options.log,
options.urlByAbsentLocalPath,
probes,
assetRoot,
);
// Compile each referenced sub-composition so the inliner can hoist it.
const { subCompositions } = await parseSubCompositions(
compiledHtml,
projectDir,
downloadDir,
undefined,
options.urlByAbsentLocalPath,
probes,
assetRoot,
outsideFiles,
);
// 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 { html: inlinedHtml, variablesByComp } = inlineSubCompositions(
fullHtml,
subCompositions,
projectDir,
options.variables ?? {},
assetRoot,
outsideFiles,
);
// 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 = stripPreloadNone(inlinedHtml);
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 hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
// Remote font stylesheets join the page first, or the font check below cannot see them.
const fontSheetHtml = await inlineExternalFontStylesheets(
promoteCssImportsToLinkTags(sanitizedHtml),
);
const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
injectTextRenderingRule(coalesceHeadStylesAndBodyScripts(fontSheetHtml)),
);
const coalescedHtml = await injectDeterministicFontFaces(normalizedFontHtml, {
logger: defaultLogger,
failClosedFontFetch: options.failClosedFontFetch === true,
allowSystemFontCapture: options.allowSystemFontCapture,
projectFontFamilies: projectStylesheetFontFamilies(fontSheetHtml, projectDir),
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 localizeFontFaceUrls(htmlWithLocalBg, downloadDir);
// Chrome cannot decode HEIC, and ffprobe reads a tiled one as video streams,
// so convert to JPEG before the media-type preflight sees it.
const {
html: htmlWithJpegs,
preparedAssets: preparedHeifAssets,
preparedImages: preparedHeifImages,
} = await prepareHeifImageInputs(htmlWithLocalizedFonts, {
projectDir,
downloadDir,
cacheDir: options.animatedGifCacheDir,
sourceAssets: remoteImageAssets,
timeoutMs: options.ffmpegProcessTimeout,
allowOutsideFiles: assetRoot === undefined,
});
if (preparedHeifImages.length > 0) {
defaultLogger.debug(`[Compiler] Converted ${preparedHeifImages.length} HEIC image(s) to JPEG`);
}
const gifSourceAssets = new Map<string, string>(remoteImageAssets);
const {
html: htmlWithPreparedGifs,
preparedAssets: preparedGifAssets,
preparedGifs,
} = await prepareAnimatedGifInputs(htmlWithJpegs, {
projectDir,
downloadDir,
cacheDir: options.animatedGifCacheDir,
sourceAssets: gifSourceAssets,
timeoutMs: options.ffmpegProcessTimeout,
allowOutsideFiles: assetRoot === undefined,
});
if (preparedGifs.length > 0) {
defaultLogger.debug(`[Compiler] Prepared ${preparedGifs.length} animated GIF input(s) as WebM`);
}
const embeddedHtml = await embedLocalFontFaces(
htmlWithPreparedGifs,
projectDir,
assetRoot,
options.log,
);
// 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 } = options.allowOutsideProjectAssets
? collectExternalAssets(
embeddedHtml,
projectDir,
options.log,
entryFileName(projectDir, htmlPath),
{ includeScripts: options.includeOutsideScripts },
)
: { html: embeddedHtml, externalAssets: new Map<string, string>() };
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);
}
for (const [relPath, absPath] of preparedHeifAssets) {
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, gradedCanvas } = 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.
const advised = new Set<string>();
for (const video of videos) {
if (isHttpUrl(video.src)) continue;
const videoPath = resolve(projectDir, video.src);
if (
advised.has(videoPath) ||
namesAnotherNetworkRoot(projectDir, videoPath) ||
!existsSync(videoPath) ||
escapesAssetRoot(videoPath, assetRoot) ||
isPrivateUnderAssetRoots(videoPath, [projectDir, downloadDir])
)
continue;
advised.add(videoPath);
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). ` +
`Long GOPs can make preview seeking slower; rendering is unaffected. If preview seeking is slow, 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,
gradedCanvas,
...(masterFxChain ? { masterFxChain } : {}),
unresolvedCompositions,
variablesByComp,
externalAssets,
width,
height,
staticDuration,
renderModeHints,
hasShaderTransitions,
usesThreeDTransforms,
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;
playbackRate: RateSpec;
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;
playbackRateRaw: string | null;
automationRaw: string | null;
defaultPlaybackRate: number;
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 resolvedSrc = htmlEl.currentSrc || htmlEl.src || htmlEl.getAttribute("src") || "";
const withoutQueryAndHash = (url: string) => url.replace(/[?#][\s\S]*$/, "");
const isPageItself = withoutQueryAndHash(resolvedSrc) === withoutQueryAndHash(location.href);
const src = isPageItself ? "" : resolvedSrc;
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 playbackRateRaw = htmlEl.getAttribute("data-playback-rate");
const automationRaw = htmlEl.getAttribute("data-automation");
// playbackRate can include the transport speed; defaultPlaybackRate is the clip's own rate.
const defaultPlaybackRate = isImage
? 1
: (htmlEl as HTMLVideoElement | HTMLAudioElement).defaultPlaybackRate;
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,
playbackRateRaw,
automationRaw,
defaultPlaybackRate,
loop,
hasAudio,
volume,
muted,
});
});
return results;
});
return elements.map(
({
endRaw,
durationRaw,
intrinsicDuration,
playbackStartRaw,
mediaStartRaw,
playbackRateRaw,
automationRaw,
defaultPlaybackRate,
...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;
},
}),
playbackRate: resolveRateSpec(
automationRaw,
readPlaybackRate(
(name) => (name === "data-playback-rate" ? playbackRateRaw : null),
defaultPlaybackRate,
),
),
}),
);
}
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,
assetRoot?: string,
outsideFiles: OutsideFilePolicy = {},
): 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,
undefined,
undefined,
undefined,
assetRoot,
outsideFiles,
);
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,
};
}