Skip to content

Write HTML. Render video. Built for agents.

110 KB
Raw Blame
import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
// fallow-ignore-file code-duplication complexity
/**
 * HTML Compiler for Producer
 *
 * Two-phase compilation that guarantees every media element has data-end:
 * 1. Static pass via core's compileTimingAttrs() (data-start + data-duration → data-end)
 * 2. ffprobe resolution for elements without data-duration
 *
 * Also handles sub-compositions referenced via data-composition-src,
 * recursively extracting nested media from sub-sub-compositions.
 */

import { createHash } from "node:crypto";
import { createReadStream, existsSync, mkdirSync, readFileSync } from "fs";
import { join, dirname, resolve, basename, relative } from "path";
import { parseHTML } from "linkedom";
import {
  COMPOSITION_SOURCE_URL,
  compileTimingAttrs,
  injectDurations,
  extractResolvedMedia,
  clampDurations,
  shouldClampResolvedMediaDuration,
  CSS_URL_RE,
  isNonRelativeUrl,
  parseStrictFiniteTimingNumber,
  readMediaStart,
  redactTelemetryString,
  resolveNaturalMediaTimelineDurationFromValues,
  rewriteAssetPaths,
  rewriteCssAssetUrls,
  rewriteInlineStyleAssetUrls,
  type RateSpec,
  type ResolvedDuration,
  type UnresolvedElement,
} from "@hyperframes/core";
import { MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
import {
  assignBundledRuntimeCompositionIds,
  assignMediaRenderIds,
  type BundledHostCompositionIdentity,
  buildVariablesByCompScript,
  inlineSubCompositions as inlineSubCompositionsShared,
  ensureExternalLinkTag,
  ensureExternalScriptTag,
  deferScriptsUntilFonts,
  emitMountedModuleScripts,
  isJavaScriptType,
  prepareFlattenedInnerRoot,
  emitRootCompositionVariableStyles,
  readDeclaredDefaults,
  parseHostVariableValues,
  headStyleRuns,
  inlineScriptRuns,
  parsesAsScript,
  styleElementsFor,
  insertBeforeCloseTag,
  isRuntimeFileUrl,
} from "@hyperframes/core/compiler";
import {
  checkSubCompositionUsability,
  type ParsableDocumentLike,
} from "@hyperframes/parsers/sub-composition-validity";
import {
  isUnresolvedAssetPlaceholder,
  readProjectFile,
} from "@hyperframes/parsers/asset-resolution";
import { extractMediaMetadata, extractAudioMetadata } from "../utils/ffprobe.js";
import { isPathInside, toExternalAssetKey } from "../utils/paths.js";
import { collectRenderMedia } from "./renderMediaCollector.js";
import {
  type VideoElement,
  type ImageElement,
  type AudioElement,
  type AudioVolumeKeyframe,
  type MediaProbeProfile,
  analyzeKeyframeIntervals,
  assertMediaPayload,
  NotMediaPayloadError,
  parseMasterFxChain,
  probeMediaProfile,
} from "@hyperframes/engine";
import {
  downloadToTemp,
  fetchPublicHttpsText,
  isHttpUrl,
  safeDownloadUrlIdentity,
  type UrlDownloadTelemetry,
} from "../utils/urlDownloader.js";
import type { Page } from "puppeteer-core";
import {
  injectDeterministicFontFaces,
  normalizeSystemFontPrimaryFamilies,
} from "@hyperframes/core/fonts/embed";
import { prepareAnimatedGifInputs } from "./animatedGifPrep.js";
import { createStudioPositionSeekReapplyScript } from "@hyperframes/studio-server/manual-edits-render-script";
import { getPositionEditsRenderScript } from "@hyperframes/core/runtime/position-edits-render";
import { defaultLogger, type ProducerLogger } from "../logger.js";
import { assertAssetMediaTypeProfile } from "./assetMediaType.js";
import { withMediaProbeSlot } from "../utils/mediaProbeConcurrency.js";

function logRemoteDownloadTelemetry(event: UrlDownloadTelemetry): void {
  defaultLogger.info("[Compiler] Remote asset download integrity", { ...event });
}

export interface CompiledComposition {
  html: string;
  subCompositions: Map<string, string>;
  videos: VideoElement[];
  audios: AudioElement[];
  images: ImageElement[];
  droppedMediaIds: Set<string>;
  masterFxChain?: string;
  unresolvedCompositions: UnresolvedElement[];
  /** Assets that resolve outside projectDir. Keys are the path used in HTML, values are absolute filesystem paths. */
  externalAssets: Map<string, string>;
  width: number;
  height: number;
  staticDuration: number;
  renderModeHints: RenderModeHints;
  hasShaderTransitions: boolean;
  /** Author HTML/CSS/scripts use a CSS 3D rendering context (pre-CDN-inline scan). */
  usesThreeDTransforms: boolean;
  /** Author HTML/CSS use mix-blend-mode (pre-CDN-inline scan). */
  usesMixBlendMode: boolean;
  /** Ancestors of the composition root carry a background-image (gradient/url). */
  hasAncestorBackgroundImage: boolean;
}

const INFERRED_MEDIA_DURATION_ATTR = "data-hf-inferred-duration";

/** Adapts linkedom's `parseHTML` to the `checkSubCompositionUsability` contract. */
function parseSubCompHtmlForValidity(html: string): ParsableDocumentLike {
  return parseHTML(html).document as unknown as ParsableDocumentLike;
}

function endsWithSourceUrl(code: string): boolean {
  const trimmed = code.trimEnd();
  const lastLine = trimmed.slice(trimmed.lastIndexOf("\n") + 1).trimStart();
  return lastLine.startsWith("//# sourceURL=") || lastLine.startsWith("//@ sourceURL=");
}

// One name for the composition's inline code lets a render keep its errors and not a widget's.
function prepareCompositionScripts(html: string): string {
  const { document } = parseHTML(html);
  for (const el of document.querySelectorAll("script:not([src])")) {
    const isModule = (el.getAttribute("type") || "").trim().toLowerCase() === "module";
    const runsAsScript = isModule || isJavaScriptType(el as unknown as Element);
    const code = el.textContent ?? "";
    if (!runsAsScript || endsWithSourceUrl(code)) continue;
    el.textContent = `${code}\n//# sourceURL=${COMPOSITION_SOURCE_URL}`;
  }
  deferScriptsUntilFonts(document as unknown as Document);
  return document.toString();
}

export function injectSdkPositionEditsRenderScript(html: string): string {
  if (!html.includes("data-hf-edit-base-x") && !html.includes("data-hf-edit-base-y")) {
    return html;
  }
  const scriptBody = getPositionEditsRenderScript().replace(/<\/script/gi, "<\\/script");
  const script = `<script>${scriptBody}\n//# sourceURL=hyperframes://position-edits</script>`;
  return insertBeforeCloseTag(html, "body", script) ?? `${html}${script}`;
}

/**
 * Thrown by {@link assertSubCompositionsUsable} when one or more
 * `data-composition-src` references resolve to a missing, empty, or
 * unparsable file. This is the render-path enforcement of the #1 render
 * failure bucket in production telemetry: a scene-authoring step (most
 * commonly an AI agent) writes the `data-composition-src` reference before,
 * or without ever, writing valid content into the scene file.
 *
 * Unlike the tolerant inliner (`packages/core/src/compiler/inlineSubCompositions.ts`,
 * intentionally kept lenient for preview/studio so mid-authoring iteration
 * doesn't break bundling), a render that silently drops a scene produces a
 * materially broken video with no visible error — strictly worse than
 * refusing to render. This check runs before any compilation work starts so
 * the failure is immediate and names every offending file at once, instead
 * of surfacing 45+ seconds later as a `pollSubCompositionTimelines` timeout
 * or a raw `Cannot destructure property 'firstElementChild' of
 * 'documentElement' as it is null` crash deep inside linkedom.
 *
 * Not exported — nothing needs `instanceof` narrowing on this today. Callers
 * catch it generically (`catch (err: unknown)`, matching on `.message`) the
 * same way they handle every other compile-time failure. Kept as a class
 * (not a plain `throw new Error(...)`) so the aggregated multi-file message
 * construction has a single, testable home.
 */
class EmptyCompositionError extends Error {
  readonly code = "EMPTY_COMPOSITION" as const;
  readonly problems: ReadonlyArray<{ srcPath: string; detail: string }>;

  constructor(problems: ReadonlyArray<{ srcPath: string; detail: string }>) {
    const lines = problems.map((p) => `  - ${p.srcPath}: ${p.detail}`);
    super(
      `${problems.length} composition file${problems.length === 1 ? "" : "s"} referenced by ` +
        `data-composition-src cannot be rendered:\n${lines.join("\n")}\n\n` +
        "Check that each file referenced by data-composition-src contains valid HTML with a " +
        "[data-composition-id] element in a <template>, <body>, or bare fragment. If a scene-authoring " +
        "step is still running, wait for it to finish before referencing the file.",
    );
    this.name = "EmptyCompositionError";
    this.problems = problems;
  }
}

/**
 * Recursively walk every `data-composition-src` reference reachable from
 * `html` (including nested sub-compositions) and verify each resolves to a
 * usable file — exists, non-empty, parses to HTML with renderable content.
 * Uses the same `checkSubCompositionUsability` helper the tolerant inliner
 * and `hyperframes lint` use, so all three agree on what counts as usable.
 *
 * Throws {@link EmptyCompositionError} naming every offending file at once
 * (not just the first one hit) if any reference is unusable. Call this
 * before any compilation work starts — it deliberately duplicates a small
 * amount of file-reading work that `parseSubCompositions` also does, in
 * exchange for failing in milliseconds instead of after the browser has
 * already launched and waited out a capture timeout.
 */
// fallow-ignore-next-line complexity
function assertSubCompositionsUsable(
  html: string,
  projectDir: string,
  visited: Set<string> = new Set(),
): void {
  const { document } = parseHTML(html);
  const hosts = [...document.querySelectorAll("[data-composition-src]")];
  const problems: Array<{ srcPath: string; detail: string }> = [];

  for (const el of hosts) {
    const srcPath = el.getAttribute("data-composition-src");
    if (!srcPath) continue;
    if (isUnresolvedAssetPlaceholder(srcPath)) continue; // __UPPER__ placeholder or unresolved templating token — not a real reference (shared with lint via @hyperframes/parsers)

    const filePath = resolve(projectDir, srcPath);
    // Circular reference guard. parseSubCompositions (below) silently
    // `continue`s on a repeat visit with no reporting at all — mirror that
    // silence here rather than pretend it surfaces an error somewhere else.
    if (visited.has(filePath)) continue;

    const read = readProjectFile(filePath);
    if (read.kind === "missing") {
      problems.push({ srcPath, detail: "the file does not exist" });
      continue;
    }
    if (read.kind === "folder") {
      problems.push({ srcPath, detail: "it is a folder, not an HTML file" });
      continue;
    }

    const fileHtml = read.text;
    const validity = checkSubCompositionUsability(fileHtml, parseSubCompHtmlForValidity);
    if (!validity.ok) {
      problems.push({
        srcPath,
        detail: validity.detail ?? "the file is empty or could not be parsed",
      });
      continue;
    }

    // Recurse into nested sub-compositions so a broken scene three levels
    // deep is still named directly instead of surfacing as a parent-level
    // "no error, just missing content" mystery.
    //
    // Pass `projectDir` unchanged (not dirname(filePath)) — data-composition-src
    // is always resolved root-relative, even from within a nested
    // sub-composition. This must match parseSubCompositions' own recursive
    // call below exactly (it threads the original projectDir through every
    // level too), or this pre-flight check resolves nested references to the
    // wrong path and aborts renders that would have actually succeeded.
    const nestedVisited = new Set(visited);
    nestedVisited.add(filePath);
    try {
      assertSubCompositionsUsable(fileHtml, projectDir, nestedVisited);
    } catch (err) {
      if (err instanceof EmptyCompositionError) {
        problems.push(...err.problems);
      } else {
        throw err;
      }
    }
  }

  if (problems.length > 0) {
    throw new EmptyCompositionError(problems);
  }
}

export type RenderModeHintCode =
  | "iframe"
  | "requestAnimationFrame"
  | "htmlInCanvas"
  | "captureMotionBlur";

export interface RenderModeHint {
  code: RenderModeHintCode;
  message: string;
}

export interface RenderModeHints {
  recommendScreenshot: boolean;
  reasons: RenderModeHint[];
}

const INLINE_SCRIPT_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
const COMPILER_MOUNT_BLOCK_START = "/* __HF_COMPILER_MOUNT_START__ */";
const COMPILER_MOUNT_BLOCK_END = "/* __HF_COMPILER_MOUNT_END__ */";

function stripJsComments(source: string): string {
  return source.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
}

function stripCompilerMountBootstrap(source: string): string {
  return source.replace(
    new RegExp(
      `${COMPILER_MOUNT_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${COMPILER_MOUNT_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
      "g",
    ),
    "",
  );
}

/** The composition the runtime reads data-motion-blur from: `data-root="true"`, else the first. */
function runtimeRoot(document: ParentNode): Element | null {
  return (
    document.querySelector('[data-composition-id][data-root="true"]') ??
    document.querySelector("[data-composition-id]")
  );
}

export function detectRenderModeHints(html: string, pageMotionBlur?: "off"): RenderModeHints {
  const reasons: RenderModeHint[] = [];
  const { document } = parseHTML(html);

  if (document.querySelector("canvas[layoutsubtree]")) {
    reasons.push({
      code: "htmlInCanvas",
      message:
        "Detected html-in-canvas API (layoutsubtree canvas). Chrome does not support concurrent drawElementImage across multiple workers; render is pinned to a single worker.",
    });
  } else if (
    pageMotionBlur !== "off" &&
    runtimeRoot(document)?.getAttribute("data-motion-blur") === "on"
  ) {
    // Not pinned to one worker: k3-promo measured identical across 1 and 4 workers, 2× faster.
    reasons.push({
      code: "captureMotionBlur",
      message:
        'Detected capture motion blur (data-motion-blur="on"), which draws each frame with html-in-canvas; routed through screenshot capture mode.',
    });
  }

  if (document.querySelector("iframe")) {
    reasons.push({
      code: "iframe",
      message:
        "Detected <iframe> in the composition DOM. Nested iframe animation is routed through screenshot capture mode for compatibility.",
    });
  }

  let scriptMatch: RegExpExecArray | null;
  const scriptPattern = new RegExp(INLINE_SCRIPT_PATTERN.source, INLINE_SCRIPT_PATTERN.flags);
  while ((scriptMatch = scriptPattern.exec(html)) !== null) {
    const attrs = scriptMatch[1] || "";
    if (/\bsrc\s*=/i.test(attrs)) continue;
    const content = stripJsComments(stripCompilerMountBootstrap(scriptMatch[2] || ""));
    if (!/requestAnimationFrame\s*\(/.test(content)) continue;
    reasons.push({
      code: "requestAnimationFrame",
      message:
        "Detected raw requestAnimationFrame() in an inline script. This render is routed through screenshot capture mode with virtual time enabled.",
    });
    break;
  }

  return {
    recommendScreenshot: reasons.length > 0,
    reasons,
  };
}

/**
 * 3D rendering-context signals. drawElementImage paints elements inside a
 * CSS 3D rendering context incorrectly: backface-visibility:hidden is
 * ignored (mid-flip elements show their mirrored backface), sibling content
 * of the 3D context can drop out of the capture, and the context's
 * background is lost. Observed on real-world gen_os comps (flip-card and
 * rotationX scene-entrance patterns) on macOS hardware GPU — this is a
 * drawElementImage limitation, not a SwiftShader artifact.
 *
 * Only genuine 3D-context signals are matched: `perspective` (property or
 * transform function), `transform-style: preserve-3d`, `backface-visibility`,
 * `matrix3d(` / `rotate3d(`, and GSAP's `transformPerspective`. Flat
 * rotationX/Y tweens without a perspective context render as 2D and are
 * deliberately NOT matched, nor is the ubiquitous `translateZ(0)` promotion
 * hack.
 */
const THREE_D_CONTEXT_PATTERN =
  /transform-style\s*:\s*preserve-3d|backface-visibility\s*:|perspective\s*:\s*[0-9]|perspective\s*\(|matrix3d\s*\(|rotate3d\s*\(|\btransformPerspective\b/i;

export function detectThreeDTransformUsage(html: string): boolean {
  return THREE_D_CONTEXT_PATTERN.test(html);
}

const MIX_BLEND_MODE_PATTERN = /mix-blend-mode\s*:/i;

function detectMixBlendModeUsage(html: string): boolean {
  return MIX_BLEND_MODE_PATTERN.test(html);
}

/** A background declaration whose value paints an image (gradient or url). */
const BACKGROUND_IMAGE_DECL_PATTERN =
  /(?:^|;|\{)\s*background(?:-image)?\s*:[^;}]*(?:\bgradient\s*\(|url\s*\()/i;

/**
 * Background-image signals on ancestors of the composition root.
 * drawElementImage only paints the captured subtree; drawElementService's
 * per-frame ancestor fill replicates what lies behind it by walking up the
 * DOM for the nearest non-transparent `backgroundColor`. A background-IMAGE
 * (linear-gradient, url) on <body>/<html>/a wrapper reads as transparent in
 * that scan, so a deeper ancestor's solid color paints instead — measured:
 * a body `linear-gradient` replaced by the html background color wherever
 * the subtree left pixels uncovered (30.9 dB min vs baseline), and the
 * damage can set in late enough to slip past the self-verify sample grid.
 * Backgrounds on elements INSIDE the root are painted correctly and are
 * deliberately not matched — this walks only the root's ancestor chain and
 * the style rules that select into it.
 */
export function detectAncestorBackgroundImage(html: string): boolean {
  const { document } = parseHTML(html);
  const root = document.querySelector("[data-composition-id]");
  if (!root) return false;
  const ancestors: Element[] = [];
  for (let el = root.parentElement; el; el = el.parentElement) ancestors.push(el);
  if (document.documentElement && !ancestors.includes(document.documentElement)) {
    ancestors.push(document.documentElement);
  }
  // Inline styles on the ancestor chain.
  for (const el of ancestors) {
    const style = el.getAttribute("style");
    if (style && BACKGROUND_IMAGE_DECL_PATTERN.test(`{${style}}`)) return true;
  }
  // <style> rules: any rule carrying an image-painting background declaration
  // whose selector resolves to an ancestor of the root. Selector matching goes
  // through querySelectorAll so class/id/compound selectors on wrappers are
  // covered, not just literal `body`/`html`.
  for (const styleEl of document.querySelectorAll("style")) {
    const css = styleEl.textContent ?? "";
    for (const rule of css.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
      const [, selectorList = "", declarations = ""] = rule;
      if (!BACKGROUND_IMAGE_DECL_PATTERN.test(`{${declarations}}`)) continue;
      for (const selector of selectorList.split(",")) {
        const sel = selector.trim();
        if (!sel || sel.startsWith("@")) continue;
        if (/^(?:html|:root)$/i.test(sel)) return true;
        try {
          for (const matched of document.querySelectorAll(sel)) {
            if (ancestors.includes(matched)) return true;
          }
        } catch {
          // Selector syntax linkedom can't parse (e.g. vendor pseudo) — skip.
        }
      }
    }
  }
  return false;
}

const SHADER_TRANSITION_USAGE_PATTERN =
  /\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;

export function detectShaderTransitionUsage(html: string): boolean {
  let scriptMatch: RegExpExecArray | null;
  const scriptPattern = new RegExp(INLINE_SCRIPT_PATTERN.source, INLINE_SCRIPT_PATTERN.flags);
  while ((scriptMatch = scriptPattern.exec(html)) !== null) {
    const attrs = scriptMatch[1] || "";
    if (/\bsrc\s*=/i.test(attrs)) continue;
    const content = stripJsComments(stripCompilerMountBootstrap(scriptMatch[2] || ""));
    if (SHADER_TRANSITION_USAGE_PATTERN.test(content)) return true;
  }

  return false;
}

async function resolveMediaDuration(
  src: string,
  mediaStart: number,
  playbackRate: RateSpec,
  baseDir: string,
  downloadDir: string,
  tagName: string,
  elementIdentity: string,
  log?: ProducerLogger,
  urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ duration: number | null; resolvedPath: string }> {
  let filePath = src;

  if (isHttpUrl(src)) {
    if (!existsSync(downloadDir)) mkdirSync(downloadDir, { recursive: true });
    try {
      filePath = await downloadToTemp(src, downloadDir, undefined, undefined, undefined, {
        onTelemetry: logRemoteDownloadTelemetry,
      });
    } catch {
      // Download failed (e.g. 404 placeholder URL) — skip gracefully.
      // The element will get duration 0 and be excluded from the render.
      return { duration: null, resolvedPath: src };
    }
  } else {
    filePath = decodedUrlPath(src);
    if (!filePath.startsWith("/")) filePath = join(baseDir, filePath);
    // ffprobe reads only the header of a remote source, so it is probed in place.
    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
  }

  if (!isHttpUrl(filePath) && !existsSync(filePath)) {
    return { duration: null, resolvedPath: filePath };
  }

  // STUDIO-5433: attach the remote `src` to any ffprobe failure surfaced from
  // this branch. `extractMediaMetadata` → `runFfprobe` intentionally redacts
  // its local `filePath` out of the error message (see
  // engine/utils/ffprobe.ts::redactFfprobeInput), so a bare `moov atom not
  // found` in Datadog carries no attribution and requires a Temporal history
  // dump to identify the offending source. Re-throwing with the `src`
  // (query-string redacted via `redactTelemetryString` so pre-signed URL
  // signatures never reach telemetry) makes the next occurrence diagnosable
  // directly from the render error. Fail-fast semantics for the video branch
  // are preserved — only the message is enriched.
  const withSrcContext = (error: unknown): Error => {
    // A NotMediaPayloadError already carries its own attribution AND the
    // routing metadata downstream keys on — `.code = "NOT_MEDIA_PAYLOAD"`,
    // `.owner = "user"`, `.retryable = false`, `.elementFingerprints`. Wrapping
    // it in a bare Error drops all four, flipping a user-input bug to
    // generic/system/retryable: it pages ops and re-runs the render. Pass it
    // through untouched.
    if (error instanceof NotMediaPayloadError) return error;
    const originalMessage = error instanceof Error ? error.message : String(error);
    const safeSrc = redactTelemetryString(src);
    const wrapped = new Error(`${originalMessage} [src=${safeSrc}]`);
    if (error instanceof Error && error.stack) wrapped.stack = error.stack;
    return wrapped;
  };

  return withMediaProbeSlot(async () => {
    let profile: MediaProbeProfile;
    try {
      // Payload sniff (STUDIO-5433): if an authoring bug hands us a text
      // payload (e.g. an unresolved nested-composition preview URL), fail with
      // a typed NotMediaPayloadError instead of letting ffprobe emit an opaque
      // `[mov,mp4,...] moov atom not found` that routes as a codec bug.
      // Deliberately inside this try: the audio/video split below is the
      // contract, so a bad audio src must still degrade to duration 0 rather
      // than take down the whole render.
      await assertMediaPayload(filePath, elementIdentity);
      profile = await probeMediaProfile(filePath);
    } catch (error) {
      // Preserve the historical split: invalid video sources surface their
      // probe failure, while invalid/unreadable audio sources resolve to zero
      // duration and are excluded by the compiler.
      if (tagName !== "video") {
        if (error instanceof NotMediaPayloadError) {
          // Dropping it silently is what let STUDIO-5433 resurface downstream
          // as `prepare/ffmpeg_failed` with owner "system".
          log?.warn(
            `[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media ` +
              "file, so the element is dropped from the render. Point it at a rendered media file.",
          );
        }
        return { duration: null, resolvedPath: filePath };
      }
      throw withSrcContext(error);
    }
    assertAssetMediaTypeProfile(tagName === "video" ? "video" : "audio", profile, elementIdentity);

    let metadata: { durationSeconds: number };
    if (tagName === "video") {
      try {
        metadata = await extractMediaMetadata(filePath);
      } catch (error) {
        throw withSrcContext(error);
      }
    } else {
      try {
        metadata = await extractAudioMetadata(filePath);
      } catch {
        // Source file has no audio stream (e.g. a silent video used as an audio src).
        // Return duration 0 so the element is excluded from the composition gracefully,
        // matching how missing files and failed downloads are already handled above.
        return { duration: null, resolvedPath: filePath };
      }
    }

    const fileDuration = metadata.durationSeconds;
    const duration = resolveNaturalMediaTimelineDurationFromValues(
      fileDuration,
      mediaStart,
      playbackRate,
    );

    return { duration, resolvedPath: filePath };
  });
}

/**
 * Compile a single HTML file: static pass + ffprobe for unresolved media.
 * Returns compiled HTML and any unresolved composition elements that need browser resolution.
 */
function markInferredVariableMediaDurations(
  html: string,
  unresolvedMedia: readonly UnresolvedElement[],
): string {
  const unresolvedIds = new Set(unresolvedMedia.map((element) => element.id));
  if (unresolvedIds.size === 0) return html;

  const { document } = parseHTML(html);
  let changed = false;
  for (const element of document.querySelectorAll("video[data-var-src], audio[data-var-src]")) {
    if (!unresolvedIds.has(element.id)) continue;
    element.setAttribute(INFERRED_MEDIA_DURATION_ATTR, "");
    changed = true;
  }
  return changed ? document.toString() : html;
}

async function compileHtmlFile(
  html: string,
  baseDir: string,
  downloadDir: string,
  log?: ProducerLogger,
  urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ html: string; unresolvedCompositions: UnresolvedElement[] }> {
  const { html: staticCompiled, unresolved } = compileTimingAttrs(html);

  const mediaUnresolved = unresolved.filter(
    (el) => (el.tagName === "video" || el.tagName === "audio") && el.src,
  );

  const unresolvedCompositions = unresolved.filter((el) => el.tagName === "div");

  // Phase 1: Resolve missing durations (parallel ffprobe)
  const resolvedResults = await Promise.all(
    mediaUnresolved.map((el) =>
      resolveMediaDuration(
        el.src!,
        el.mediaStart,
        el.playbackRate,
        baseDir,
        downloadDir,
        el.tagName,
        el.id,
        log,
        urlByAbsentLocalPath,
      ).then(({ duration }) => ({ id: el.id, duration })),
    ),
  );
  const resolutions: ResolvedDuration[] = resolvedResults.filter(
    (r): r is ResolvedDuration => r.duration != null && Number.isFinite(r.duration),
  );

  const markedStaticHtml = markInferredVariableMediaDurations(staticCompiled, mediaUnresolved);
  let compiledHtml =
    resolutions.length > 0 ? injectDurations(markedStaticHtml, resolutions) : markedStaticHtml;

  // Phase 2: Bound authored audio to playable source (parallel ffprobe).
  // Explicit video slots may outlive their source and hold the final frame.
  const preResolved = extractResolvedMedia(compiledHtml);
  const clampResults = await Promise.all(
    preResolved
      .filter((el) => !!el.src && !el.loop)
      .map(async (el) => {
        const { duration: maxDuration } = await resolveMediaDuration(
          el.src!,
          el.mediaStart,
          el.playbackRate,
          baseDir,
          downloadDir,
          el.tagName,
          el.id,
          log,
        );
        return { id: el.id, tagName: el.tagName, duration: el.duration, maxDuration, src: el.src! };
      }),
  );
  const clampList: ResolvedDuration[] = [];
  for (const r of clampResults) {
    if (
      r.maxDuration != null &&
      shouldClampResolvedMediaDuration(r.tagName, r.duration, r.maxDuration)
    ) {
      clampList.push({ id: r.id, duration: r.maxDuration });
      // This clip's `data-duration` is being silently shortened to its source.
      // Surface it so the author can confirm the longer slot wasn't intended.
      // ponytail: top-level only — sub-composition audio still gets clamped;
      // thread `log` through parseSubCompositions to warn for it too.
      log?.warn(
        `[compile] Audio "${r.id}" (${r.src}) is ${r.maxDuration.toFixed(2)}s but its ` +
          `data-duration is ${r.duration.toFixed(2)}s, so the slot is shortened to the media ` +
          `length. Set data-duration to ~${r.maxDuration.toFixed(2)}s, trim data-media-start, ` +
          `or use a longer/looping source if that isn't intended.`,
      );
    }
  }

  if (clampList.length > 0) {
    compiledHtml = clampDurations(compiledHtml, clampList);
  }

  // Strip crossorigin from video elements: the render pipeline replaces them with
  // injected frame images, so the browser never needs to load the source.
  // Without this, videos with crossorigin="anonymous" targeting CORS-restricted
  // origins (e.g. S3 without CORS headers) keep readyState=0, blocking page setup.
  compiledHtml = compiledHtml.replace(/(<video\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");

  // Strip crossorigin from img elements. The renderer captures DOM frames visually —
  // no canvas readback — so CORS compliance is unnecessary. External images from
  // CORS-restricted origins (e.g. S3) render blank when crossorigin forces a failed
  // CORS request against the renderer's localhost file server.
  compiledHtml = compiledHtml.replace(/(<img\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");

  // Strip crossorigin from audio elements. Audio is processed out-of-band via
  // FFmpeg; the browser's CORS policy for audio elements is irrelevant to
  // rendering. Leaving crossorigin="anonymous" causes the browser to issue a
  // CORS-mode preflight from localhost, which S3 buckets without explicit CORS
  // headers reject — leaving audio elements in a failed network state. The
  // FFmpeg audio path reads the src URL directly and is unaffected by browser
  // CORS, so stripping the attribute has no side effects.
  compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");

  return { html: compiledHtml, unresolvedCompositions };
}

/**
 * Compile every sub-composition referenced via data-composition-src, keyed by
 * its source path for the inliner to hoist into the render document.
 * Recurses so nested references are compiled too.
 *
 * Media used to be extracted here as well, with each file's clips offset onto
 * the parent timeline. That is now read off the inlined document instead
 * (collectRenderMedia): per-file extraction had to merge on element id, which
 * is not unique across files, so colliding clips silently collapsed (#3340).
 */
async function parseSubCompositions(
  html: string,
  projectDir: string,
  downloadDir: string,
  visited: Set<string> = new Set(),
  urlByAbsentLocalPath?: ReadonlyMap<string, string>,
): Promise<{ subCompositions: Map<string, string> }> {
  const subCompositions = new Map<string, string>();

  const { document } = parseHTML(html);
  const compEls = document.querySelectorAll("[data-composition-src]");

  // Build work items, filtering out invalid/circular entries synchronously
  const workItems: Array<{
    srcPath: string;
    filePath: string;
    rawSubHtml: string;
    nestedVisited: Set<string>;
  }> = [];

  for (const el of compEls) {
    const srcPath = el.getAttribute("data-composition-src");
    if (!srcPath) continue;

    const filePath = resolve(projectDir, srcPath);

    // Circular reference guard
    if (visited.has(filePath)) {
      continue;
    }

    const read = readProjectFile(filePath);
    if (read.kind !== "file") {
      continue;
    }

    const rawSubHtml = read.text;
    const nestedVisited = new Set(visited);
    nestedVisited.add(filePath);

    workItems.push({ srcPath, filePath, rawSubHtml, nestedVisited });
  }

  // Parallelize file compilation + recursive parsing
  const results = await Promise.all(
    workItems.map(async (item) => {
      const { html: compiledSub } = await compileHtmlFile(
        item.rawSubHtml,
        dirname(item.filePath),
        downloadDir,
        undefined,
        urlByAbsentLocalPath,
      );

      const nested = await parseSubCompositions(
        compiledSub,
        projectDir,
        downloadDir,
        item.nestedVisited,
        urlByAbsentLocalPath,
      );

      return {
        srcPath: item.srcPath,
        compiledSub,
        nested,
      };
    }),
  );

  // Merge results
  for (const r of results) {
    subCompositions.set(r.srcPath, r.compiledSub);

    for (const [key, value] of r.nested.subCompositions) {
      subCompositions.set(key, value);
    }
  }

  return { subCompositions };
}

/**
 * Extract CSS `@import url(...)` rules that load external stylesheets (e.g. Google Fonts)
 * from inline `<style>` blocks and promote them to `<link rel="stylesheet">` +
 * `<link rel="preload">` in `<head>`.
 *
 * This moves font discovery from the CSS cascade to the document parser level so
 * Chromium's `load` event and `networkidle2` correctly track them, preventing
 * font-swap artifacts during frame capture.
 */
function promoteCssImportsToLinkTags(html: string): string {
  const { document } = parseHTML(html);
  const head = document.querySelector("head");
  if (!head) return html;

  const importRe = /@import\s+url\(\s*['"]?([^'")\s]+)['"]?\s*\)\s*;?/gi;
  const seenUrls = new Set<string>();
  const styleEls = document.querySelectorAll("style");

  for (const styleEl of styleEls) {
    const original = styleEl.textContent || "";
    let modified = original;
    let match: RegExpExecArray | null;
    importRe.lastIndex = 0;
    while ((match = importRe.exec(original)) !== null) {
      const url = match[1] ?? "";
      if (!url.startsWith("http://") && !url.startsWith("https://")) continue;
      if (seenUrls.has(url)) {
        modified = modified.replace(match[0], "");
        continue;
      }
      seenUrls.add(url);
      modified = modified.replace(match[0], "");

      const preload = document.createElement("link");
      preload.setAttribute("rel", "preload");
      preload.setAttribute("href", url);
      preload.setAttribute("as", "style");
      head.appendChild(preload);

      const link = document.createElement("link");
      link.setAttribute("rel", "stylesheet");
      link.setAttribute("href", url);
      head.appendChild(link);
    }
    if (modified !== original) {
      styleEl.textContent = modified;
    }
  }

  return document.toString();
}

class ProducerHostIdentityMap extends Map<Element, BundledHostCompositionIdentity> {
  readonly #document: Document;
  readonly #lateInstanceByCompositionId = new Map<string, number>();

  constructor(document: Document, initialHosts: Element[]) {
    super(assignBundledRuntimeCompositionIds(initialHosts));
    this.#document = document;
  }

  override get(host: Element): BundledHostCompositionIdentity | undefined {
    const existing = super.get(host);
    if (existing) return existing;

    // The shared inliner discovers nested hosts after the producer's initial
    // DOM scan. Assign those late hosts on first use so their scope and
    // variables key are fixed before any content is processed.
    const authoredCompositionId =
      (
        host.getAttribute("data-hf-original-composition-id") ||
        host.getAttribute("data-composition-id") ||
        ""
      ).trim() || null;
    if (!authoredCompositionId) {
      const identity = { authoredCompositionId: null, runtimeCompositionId: null };
      this.set(host, identity);
      return identity;
    }

    let instanceIndex = this.#lateInstanceByCompositionId.get(authoredCompositionId) || 0;
    let runtimeCompositionId: string;
    do {
      instanceIndex += 1;
      runtimeCompositionId = `${authoredCompositionId}__hf${instanceIndex}`;
    } while (
      Array.from(this.#document.querySelectorAll("[data-composition-id]")).some(
        (element) =>
          element !== host && element.getAttribute("data-composition-id") === runtimeCompositionId,
      )
    );
    this.#lateInstanceByCompositionId.set(authoredCompositionId, instanceIndex);

    host.setAttribute("data-hf-original-composition-id", authoredCompositionId);
    host.setAttribute("data-composition-id", runtimeCompositionId);
    const identity = { authoredCompositionId, runtimeCompositionId };
    this.set(host, identity);
    return identity;
  }
}

/**
 * Merge each run of adjacent same-condition `<head>` `<style>` blocks into one, `@import`
 * rules at its top, and merge each run of adjacent inline `<body>` `<script>` blocks
 * into one, without moving any of them past a `<script src>` or module script.
 *
 * Mirrors the bundler's `coalesceHeadStylesAndBodyScripts` to guarantee
 * identical CSS cascade order and script execution order between preview and
 * export, preventing font-loading and animation-ordering regressions.
 */

function coalesceHeadStylesAndBodyScripts(html: string): string {
  const { document } = parseHTML(html);
  const head = document.querySelector("head");
  const body = document.querySelector("body");
  if (!head && !body) return html;

  const styleEls = head ? Array.from(head.querySelectorAll("style")) : [];
  const importRe = /@import\s+url\([^)]*\)\s*;|@import\s+["'][^"']+["']\s*;/gi;
  for (const run of styleEls.length > 1 ? headStyleRuns(styleEls) : []) {
    const imports: string[] = [];
    const cssParts: string[] = [];
    const seenImports = new Set<string>();

    for (const el of run) {
      const raw = (el.textContent || "").trim();
      if (!raw) continue;
      const nonImportCss = raw.replace(importRe, (match) => {
        const cleaned = match.trim();
        if (!seenImports.has(cleaned)) {
          seenImports.add(cleaned);
          imports.push(cleaned);
        }
        return "";
      });
      const trimmedCss = nonImportCss.trim();
      if (trimmedCss) cssParts.push(trimmedCss);
    }

    const mergedCss = [...imports, ...cssParts].join("\n\n").trim();
    if (!mergedCss) continue;
    run[0]!.textContent = mergedCss;
    for (const el of run.slice(1)) el.remove();
  }

  if (body) {
    for (const { members, anchor } of inlineScriptRuns(
      Array.from(body.querySelectorAll("script")),
    )) {
      const mergedJs = members
        .map((el) => (el.textContent || "").trim())
        .filter(Boolean)
        .join("\n;\n")
        .trim();
      if (mergedJs && !parsesAsScript(mergedJs)) continue;
      for (const el of members) el.remove();
      if (!mergedJs) continue;
      const script = document.createElement("script");
      script.textContent = mergedJs;
      if (anchor) anchor.before(script);
      else body.appendChild(script);
    }
  }

  return document.toString();
}

/**
 * Inline sub-composition HTML into the main document using the shared
 * inlining logic from @hyperframes/core. This wrapper handles the
 * producer-specific concerns: parsing HTML via linkedom, resolving
 * compositions from the pre-compiled map or disk, and setting explicit
 * pixel dimensions on host elements for headless rendering.
 */
function inlineSubCompositions(
  html: string,
  subCompositions: Map<string, string>,
  projectDir: string,
  variableOverrides: Record<string, unknown> = {},
): string {
  const { document } = parseHTML(html);
  const head = document.querySelector("head");
  const body = document.querySelector("body");
  const hosts = Array.from(document.querySelectorAll("[data-composition-src]"));

  if (!hosts.length) {
    // Even with no sub-compositions, declared composition variables need a
    // compile-time stylesheet so eval-time reads (GSAP .from immediateRender,
    // top-level script getComputedStyle) resolve var(--slug) — the runtime's
    // DOMContentLoaded injection is too late for those.
    const emitted = emitRootCompositionVariableStyles(
      document as unknown as Document,
      {},
      variableOverrides,
    );
    return emitted ? document.toString() : html;
  }

  // Assign per-instance runtime composition ids before each host is inlined,
  // mirroring the preview bundler. Initial hosts are assigned as one pre-pass;
  // hosts discovered by the shared inliner's queue are assigned lazily by the
  // map above. When the same sub-composition (same authored
  // data-composition-id) is mounted more than once — the reusable-template
  // pattern from issue #2064 — each host is rewritten to a unique runtime id
  // (`card__hf1`, `card__hf2`). Without this, every instance shares one
  // `__hfVariablesByComp` key and one scope selector: the last mount's
  // data-variable-values clobbers the earlier ones and all-but-one instance
  // renders blank. #2066 fixed the single-instance case but left this
  // divergence (snapshot/preview correct, render wrong).
  const hostIdentityByElement = new ProducerHostIdentityMap(
    document as unknown as Document,
    hosts as unknown as Element[],
  );

  const result = inlineSubCompositionsShared(
    document as unknown as Document,
    hosts as unknown as Element[],
    {
      // hostIdentityMap gives each repeated mount a unique runtime id; the
      // shared inliner's default buildScopeSelector already scopes by
      // `[data-composition-id="<runtime id>"]`, matching the preview bundler.
      hostIdentityMap: hostIdentityByElement,
      readVariableDefaults: readDeclaredDefaults,
      parseHostVariables: parseHostVariableValues,
      resolveHtml: (srcPath: string) => {
        let compHtml = subCompositions.get(srcPath) || null;
        if (!compHtml) {
          const read = readProjectFile(resolve(projectDir, srcPath));
          if (read.kind === "file") compHtml = read.text;
        }
        return compHtml;
      },
      parseHtml: (htmlStr: string) => parseHTML(htmlStr).document as unknown as Document,
      // Mirrors the preview bundler: a sub-composition's SIBLING assets resolve
      // against its own directory, project-root refs stay as authored.
      assetExists: (path: string) => existsSync(resolve(projectDir, path)),
      // Preserve the authored root wrapper as a child of the host, matching
      // the preview bundler's shape (htmlBundler.ts's prepareFlattenedInnerRoot,
      // which the runtime compositionLoader mirrors with its own copy for the
      // live-loaded case). Without this, the wrapper element (and its
      // class/id) is discarded and any CSS anchored on it —
      // `.wrapper-class .title`, `#wrapper-id` — is dead at render time even
      // though it works in preview.
      flattenInnerRoot: prepareFlattenedInnerRoot as (innerRoot: Element) => Element,
      onMissingComposition: (srcPath: string, reason?: string) => {
        // In the render path this is normally unreachable — compileForRender
        // calls assertSubCompositionsUsable() before any of this runs, so a
        // hit here means the file changed on disk between that pre-flight
        // check and this later inline step (e.g. a concurrent scene-writer).
        console.warn(
          `[Compiler] Skipping sub-composition "${srcPath}": ${reason ?? "the file is missing or empty"}.`,
        );
      },
    },
  );

  // Producer-specific: set explicit pixel dimensions on host elements so
  // children using width/height: 100% resolve correctly. The runtime does
  // this automatically but compiled HTML needs it inline.
  for (const host of hosts) {
    const hostW = host.getAttribute("data-width");
    const hostH = host.getAttribute("data-height");
    if (hostW && hostH) {
      const existing = host.getAttribute("style") || "";
      const needsWidth = !existing.includes("width");
      const needsHeight = !existing.includes("height");
      const additions = [
        needsWidth ? `width:${hostW}px` : "",
        needsHeight ? `height:${hostH}px` : "",
      ]
        .filter(Boolean)
        .join(";");
      if (additions) {
        host.setAttribute("style", existing ? `${existing};${additions}` : additions);
      }
    }
  }

  if (head) for (const link of result.externalLinks) ensureExternalLinkTag(document, link);

  // Append collected styles to <head>
  if (head) {
    for (const style of styleElementsFor(document, result.styles, (css) => css.join("\n\n"))) {
      head.appendChild(style);
    }
  }

  // CDN and integrity-pinned scripts go first so plugins (e.g. TextPlugin,
  // ScrollTrigger) register before composition code, as in htmlBundler. A local
  // src script keeps its authored place among the inline scripts (see below).
  const isHoisted = (item: { src: string; integrity?: string }) =>
    Boolean(item.integrity?.trim()) || isNonRelativeUrl(item.src);
  if (body) {
    for (const item of result.scriptItems) {
      if (item.kind === "external" && isHoisted(item)) {
        ensureExternalScriptTag(document, item.src, item);
      }
    }
  }

  // Append collected inline scripts to <body>. The per-instance variables
  // table MUST be written before the sub-comp scripts run — their scoped
  // getVariables() reads window.__hfVariablesByComp[compId]. htmlBundler
  // (preview/snapshot) prepends this; the render path emitted only the CSS
  // custom properties (below) and dropped the JS table, so getVariables()
  // returned {} during render and parametrized sub-comps shipped blank/default
  // text (issue #2064). Same shared builder as the bundler so they stay in
  // lockstep.
  const variablesByCompScript = buildVariablesByCompScript(result.variablesByComp);
  if (body) {
    let pending = variablesByCompScript ? [variablesByCompScript] : [];
    const flushInline = () => {
      if (!pending.length) return;
      const joined = pending.join("\n;\n");
      for (const text of parsesAsScript(joined) ? [joined] : pending) {
        const scriptEl = document.createElement("script");
        scriptEl.textContent = text;
        body.appendChild(scriptEl);
      }
      pending = [];
    };
    for (const item of result.scriptItems) {
      if (item.kind === "inline") {
        pending.push(item.content);
      } else if (!isHoisted(item)) {
        flushInline();
        ensureExternalScriptTag(document, item.src, item);
      }
    }
    flushInline();
  }
  if (body) {
    emitMountedModuleScripts(
      document as unknown as Document,
      result.importMaps,
      result.moduleScripts,
    );
  }

  // Compile-time CSS custom properties (mirrors the preview bundler): root
  // declarers plus one scoped rule per sub-composition host, so var(--slug)
  // resolves at script eval time, not just after runtime injection.
  emitRootCompositionVariableStyles(
    document as unknown as Document,
    result.variablesByComp,
    variableOverrides,
  );

  // Inlining is what makes element ids ambiguous: each composition file is
  // internally consistent, the union of them is not. Hand every media element a
  // document-unique key here, while the merged document is in hand and before
  // anything downstream keys media on an id. See core's mediaRenderIds.ts.
  assignMediaRenderIds(document as unknown as Document);

  return document.toString();
}

/**
 * Full compilation pipeline for the producer.
 *
 * Returns everything the orchestrator needs: compiled HTML, all media elements,
 * dimensions, and static duration.
 */
/**
 * Ensure the HTML is a full document (has <html>, <head>, <body>).
 * When index.html is a fragment (e.g. just a <div>), linkedom.parseHTML()
 * returns a document with null head/body, causing inlineSubCompositions to
 * silently discard all collected composition styles and scripts.
 */
function ensureFullDocument(html: string): string {
  const trimmed = html.trim();
  if (/^<!DOCTYPE\s+html/i.test(trimmed) || /^<html/i.test(trimmed)) {
    return html;
  }
  // Wrap fragment with a proper document including margin/padding reset.
  // Without this, Chrome applies default body { margin: 8px } which creates
  // visible white lines at the edges of rendered video.
  return `<!DOCTYPE html>\n<html>\n<head>\n  <meta charset="UTF-8">\n  <style>*{margin:0;padding:0;box-sizing:border-box;text-rendering:geometricPrecision}body{overflow:hidden;background:#000;font-family:"Inter",sans-serif}</style>\n</head>\n<body style="margin:0;overflow:hidden">\n${html}\n</body>\n</html>`;
}

/**
 * Force subpixel glyph positioning so chrome-headless-shell (BeginFrame) and
 * full Chrome (screenshot fallback) lay text out identically. `text-rendering:
 * auto` resolves to `optimizeSpeed` (integer advances) in headless-shell but
 * `geometricPrecision` in full Chrome — that ~1% advance-width gap shifts
 * line-wrap points and any animation that reads `offsetWidth`. The `*`
 * selector has zero specificity, so authored class/id rules still override.
 */
function injectTextRenderingRule(html: string): string {
  const { document } = parseHTML(html);
  const head = document.querySelector("head");
  if (!head) return html;

  if (document.querySelector("style[data-hyperframes-text-rendering]")) {
    return html;
  }

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

  return document.toString();
}

class ScriptIntegrityError extends Error {}

/** Match SRI's strongest supported digest before decoding or rewriting script bytes. */
function matchesScriptIntegrity(bytes: Uint8Array, metadata: string): boolean {
  const hashes = [
    ...metadata.matchAll(
      /(?:^|[\t\n\f\r ])(sha256|sha384|sha512)-([A-Za-z0-9+/_-]+={0,2})(?:\?[\x21-\x7e]*)?(?=$|[\t\n\f\r ])/gi,
    ),
  ];
  const strongest = ["sha512", "sha384", "sha256"].find((alg) =>
    hashes.some((hash) => hash[1]?.toLowerCase() === alg),
  );
  // Browsers ignore metadata containing no supported, syntactically valid hash.
  if (!strongest) return true;
  const actual = createHash(strongest).update(bytes).digest();
  return hashes.some(
    (hash) =>
      hash[1]?.toLowerCase() === strongest && actual.equals(Buffer.from(hash[2]!, "base64")),
  );
}

/**
 * Download external CDN scripts and inline them into the HTML so rendering
 * works without network access (Docker, CI, restricted environments).
 */
export async function inlineExternalScripts(html: string): Promise<string> {
  const fullHtml = ensureFullDocument(html);
  const wrappedFragment = fullHtml !== html;
  const { document } = parseHTML(fullHtml);
  const scripts = document.querySelectorAll("script[src]");
  const externalScripts: { el: Element; src: string }[] = [];

  for (const el of scripts) {
    const src = (el.getAttribute("src") || "").trim();
    if (src && isHttpUrl(src) && !isRuntimeFileUrl(src)) {
      externalScripts.push({ el: el as unknown as Element, src });
    }
  }

  if (externalScripts.length === 0) return html;

  const downloads = await Promise.allSettled(
    externalScripts.map(async ({ el, src }) => {
      const response = await fetch(src, {
        signal: AbortSignal.timeout(15_000),
      });
      if (!response.ok) throw new Error(`HTTP ${response.status} for ${src}`);
      const bytes = new Uint8Array(await response.arrayBuffer());
      if (!matchesScriptIntegrity(bytes, el.getAttribute("integrity") || "")) {
        throw new ScriptIntegrityError(`Subresource integrity mismatch for ${src}`);
      }
      return { src, text: new TextDecoder().decode(bytes) };
    }),
  );

  for (let i = 0; i < downloads.length; i++) {
    const download = downloads[i]!;
    const { el, src } = externalScripts[i]!;
    if (download.status === "fulfilled") {
      // Escape </script in downloaded content to prevent premature tag closure.
      // <\/script is safe: the HTML parser doesn't recognize it as a close tag,
      // but JS treats \/ as / so the code executes identically.
      const safeText = download.value.text.replace(/<\/script/gi, "<\\/script");
      const inlineScript = document.createElement("script");
      for (const attr of Array.from(el.attributes)) {
        if (attr.name.toLowerCase() === "src") continue;
        inlineScript.setAttribute(attr.name, attr.value);
      }
      inlineScript.textContent = `/* inlined: ${src} */\n${safeText}\n//# sourceURL=${new URL(src).href}\n`;
      el.replaceWith(inlineScript);
      defaultLogger.info(`[Compiler] Inlined CDN script: ${src}`);
    } else {
      // A verified mismatch must never fall back to an executable external tag:
      // browser support for integrity metadata (including casing) can differ.
      if (download.reason instanceof ScriptIntegrityError) throw download.reason;
      defaultLogger.warn(
        `[Compiler] WARNING: Failed to download CDN script: ${src} (${download.reason}). ` +
          `The render may fail if this script is required (e.g. GSAP). ` +
          `Consider bundling it locally in your project.`,
      );
    }
  }

  return wrappedFragment ? document.body.innerHTML || "" : document.toString();
}

/**
 * Scan compiled HTML for asset references that resolve outside projectDir.
 * For each, map the normalized in-HTML path to the real filesystem path so
 * the orchestrator can copy them into the compiled output directory.
 *
 * Handles: src/href attributes, CSS url(), inline style url().
 */
export function collectExternalAssets(
  html: string,
  projectDir: string,
): { html: string; externalAssets: Map<string, string> } {
  const absProjectDir = resolve(projectDir);
  const externalAssets = new Map<string, string>();

  function processPath(rawPath: string): string | null {
    const trimmed = rawPath.trim();
    if (isNonRelativeUrl(trimmed)) return null;
    const absPath = resolve(absProjectDir, trimmed);
    if (isPathInside(absPath, absProjectDir)) {
      return null; // inside projectDir, file server handles this
    }
    if (!existsSync(absPath)) return null;
    // resolve() already canonicalises the path (no .. components remain);
    // toExternalAssetKey() produces a cross-platform relative key that
    // `path.join(compileDir, key)` cannot escape on any OS.
    const safeKey = toExternalAssetKey(absPath);
    externalAssets.set(safeKey, absPath);
    return safeKey;
  }

  const { document } = parseHTML(html);

  // Rewrite src and href attributes
  for (const el of document.querySelectorAll("[src], [href]")) {
    for (const attr of ["src", "href"]) {
      const val = (el.getAttribute(attr) || "").trim();
      if (!val) continue;
      const rewritten = processPath(val);
      if (rewritten) el.setAttribute(attr, rewritten);
    }
  }

  // Rewrite CSS url() in <style> blocks
  for (const styleEl of document.querySelectorAll("style")) {
    const css = styleEl.textContent || "";
    if (!css.includes("url(")) continue;
    const rewritten = css.replace(CSS_URL_RE, (full, quote: string, rawUrl: string) => {
      const result = processPath((rawUrl || "").trim());
      if (!result) return full;
      return `url(${quote || ""}${result}${quote || ""})`;
    });
    if (rewritten !== css) styleEl.textContent = rewritten;
  }

  // Rewrite inline style url() on elements
  for (const el of document.querySelectorAll("[style]")) {
    const style = el.getAttribute("style") || "";
    if (!style.includes("url(")) continue;
    const rewritten = style.replace(CSS_URL_RE, (full, quote: string, rawUrl: string) => {
      const result = processPath((rawUrl || "").trim());
      if (!result) return full;
      return `url(${quote || ""}${result}${quote || ""})`;
    });
    if (rewritten !== style) el.setAttribute("style", rewritten);
  }

  if (externalAssets.size > 0) {
    defaultLogger.info(
      `[Compiler] Found ${externalAssets.size} asset(s) outside project directory, will copy to render output`,
    );
  }

  return {
    html: externalAssets.size > 0 ? document.toString() : html,
    externalAssets,
  };
}

export const REMOTE_MEDIA_SUBDIR = "_remote_media";
// Match opening tags of <video> or <audio> elements that carry an HTTP(S) src.
// Uses [^>]* to span attributes — safe for composition elements that won't
// have `>` inside quoted attribute values (data-title etc.).
const REMOTE_MEDIA_TAG_RE =
  /<(?:video|audio)\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
// <source src> on media elements (picture uses srcset, not src).
const REMOTE_SOURCE_TAG_RE = /<source\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
// Match <img> tags (including agent-pipeline-emitted variants where `src` is
// not the first attribute). Producer-side localisation is the primary fix for
// the remote-<img> flicker; frameCapture's `pollImagesReady`/`decodeAllImages`
// are the defense-in-depth layer for any remote URL that bypasses this step.
// The `(?<![\w-])` lookbehind pins the match to a real `src` attribute so we
// don't rewrite `data-src` / `data-*-src` (lazy-loader placeholders whose URL
// is not what Chrome actually paints). `srcset` is excluded by the `\s*=`.
const REMOTE_IMG_TAG_RE = /<img\b[^>]*?(?<![\w-])src\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;

/**
 * Download a set of remote URLs in parallel into `remoteDir`, build the
 * `{ relPath → absPath }` asset map, and rewrite every occurrence of each
 * URL inside `html` with its relative local path.
 *
 * The `warnLabel` appears in console.warn messages for download failures.
 * The `logLabel` appears in the success console.log line.
 * `extraRewrite`, if provided, is called per URL pair after the standard
 * double/single-quote rewrite — used for url(...) CSS rewriting.
 */
async function downloadAndRewriteUrls(
  urlSet: Set<string>,
  html: string,
  remoteDir: string,
  warnLabel: string,
  logLabel: string,
  extraRewrite?: (html: string, url: string, relPath: string) => string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
  if (urlSet.size === 0) return { html, remoteMediaAssets: new Map() };
  if (!existsSync(remoteDir)) mkdirSync(remoteDir, { recursive: true });

  const urlToLocal = new Map<string, string>();
  await Promise.all(
    [...urlSet].map(async (url) => {
      try {
        const localPath = await downloadToTemp(url, remoteDir, undefined, undefined, undefined, {
          onTelemetry: logRemoteDownloadTelemetry,
        });
        urlToLocal.set(url, localPath);
      } catch (err) {
        const identity = safeDownloadUrlIdentity(url);
        defaultLogger.warn(`[Compiler] ${warnLabel}, using original URL as fallback.`, {
          urlFingerprint: identity.urlFingerprint,
          host: identity.host,
          error: err instanceof Error ? err.message : String(err),
        });
      }
    }),
  );

  if (urlToLocal.size === 0) return { html, remoteMediaAssets: new Map() };

  const remoteMediaAssets = new Map<string, string>();
  const urlToRelPath = new Map<string, string>();
  for (const [url, absPath] of urlToLocal) {
    const relPath = `${REMOTE_MEDIA_SUBDIR}/${basename(absPath)}`;
    remoteMediaAssets.set(relPath, absPath);
    urlToRelPath.set(url, relPath);
  }

  let result = html;
  for (const [url, relPath] of urlToRelPath) {
    result = result.replaceAll(`"${url}"`, `"${relPath}"`).replaceAll(`'${url}'`, `'${relPath}'`);
    if (extraRewrite) result = extraRewrite(result, url, relPath);
  }

  defaultLogger.info(`[Compiler] ${logLabel} ${urlToLocal.size} to ${REMOTE_MEDIA_SUBDIR}/`);
  return { html: result, remoteMediaAssets };
}

/**
 * Download any remote `src` URLs on `<video>` / `<audio>` elements and their
 * `<source>` children into a local subdirectory of `downloadDir`, rewrite the
 * HTML src attributes to relative paths, and return the updated HTML along with
 * a map of `{ relativePath → absoluteLocalPath }` for callers to add to
 * `externalAssets`.
 *
 * Skips URLs that fail to download (warns and preserves the original URL so
 * the browser can still attempt the remote fetch as a fallback).
 *
 * Why: remote S3 sources require Chrome to buffer every video file over the
 * network before `readyState >= 2` (HAVE_CURRENT_DATA). With 10+ large clips
 * this reliably exhausts `pageReadyTimeout`, producing blank black frames for
 * every clip. Localising the sources before the file server starts eliminates
 * the race entirely and keeps the render hermetic.
 */
/** @internal exported for unit testing only */
export async function localizeRemoteMediaSources(
  html: string,
  downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
  const urlSet = new Set<string>();
  for (const tagRe of [REMOTE_MEDIA_TAG_RE, REMOTE_SOURCE_TAG_RE]) {
    const re = new RegExp(tagRe.source, tagRe.flags);
    let m: RegExpExecArray | null;
    while ((m = re.exec(html)) !== null) {
      if (m[1]) urlSet.add(m[1]);
    }
  }
  return downloadAndRewriteUrls(
    urlSet,
    html,
    join(downloadDir, REMOTE_MEDIA_SUBDIR),
    "Remote media download failed",
    "Localized remote media source(s)",
  );
}

/**
 * Download any remote `src` URLs on `<img>` elements into a local subdirectory
 * of `downloadDir`, rewrite the HTML src attributes to relative paths, and
 * return a `{ relativePath → absoluteLocalPath }` map for the orchestrator.
 *
 * Why: a composition with remote S3 `<img src>` URLs reaches Chrome unchanged;
 * the readiness check can pass before the image is fully decoded, *and* Chrome
 * may evict decoded pixels mid-render under memory pressure and re-fetch from
 * the remote origin. Either path produces blank-frame flicker. Localising the
 * sources before render eliminates both races — once the file is local,
 * Chrome's image cache is bounded by fast disk reads, not S3 latency, so a
 * mid-render re-fetch lands within a frame instead of flickering. This is the
 * primary fix; frameCapture's `pollImagesReady` is the defense-in-depth layer.
 *
 * Scope: only `<img src>` is localised here. Remote `srcset`,
 * `<picture><source>`, SVG `<image href>`, and CSS `background-image: url()`
 * outside `@font-face` are NOT covered — agent-pipeline compositions emit
 * plain `<img src>`, but those are open follow-ups if other shapes appear.
 *
 * This bites agent-pipeline-generated compositions (astral / daphne /
 * hyperion `multi-v2` outputs) which render directly without going through
 * `hyperframes publish`'s archive-time localize step.
 */
/** @internal exported for unit testing only */
export async function localizeRemoteImageSources(
  html: string,
  downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
  const urlSet = new Set<string>();
  const re = new RegExp(REMOTE_IMG_TAG_RE.source, REMOTE_IMG_TAG_RE.flags);
  let m: RegExpExecArray | null;
  while ((m = re.exec(html)) !== null) {
    if (m[1]) urlSet.add(m[1]);
  }
  return downloadAndRewriteUrls(
    urlSet,
    html,
    join(downloadDir, REMOTE_MEDIA_SUBDIR),
    "Remote image download failed",
    "Localized remote image source(s)",
  );
}

// Match a remote url() inside a `background` / `background-image` CSS declaration
// (style blocks or inline style attrs). `[^;}"']*?` lets position/color tokens
// precede the url() in the shorthand while stopping at the declaration boundary.
const REMOTE_BG_URL_RE =
  /background(?:-image)?\s*:\s*[^;}"']*?url\(\s*["']?(https?:\/\/[^"')]+)["']?\s*\)/gi;

/**
 * Download remote CSS `background-image: url(https://...)` references and rewrite
 * them to local same-origin paths.
 *
 * Why: `drawElementImage` (fast capture) OMITS cross-origin content, so a remote
 * background image renders BLACK on the drawElement path while the screenshot
 * baseline captures it (origin-agnostic) — a whole-region mismatch (e.g. 10f79c0b
 * picsum.photos backgrounds, 9.3 dB). `<img>`/`<video>`/`@font-face` are localized
 * by their own passes; this closes the background-image gap so the fast path sees
 * the same pixels as the baseline.
 *
 * @internal exported for unit testing only
 */
export async function localizeRemoteBackgroundImages(
  html: string,
  downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
  const urlSet = new Set<string>();
  const re = new RegExp(REMOTE_BG_URL_RE.source, REMOTE_BG_URL_RE.flags);
  let m: RegExpExecArray | null;
  while ((m = re.exec(html)) !== null) {
    if (m[1] && !isGoogleFontsUrl(m[1])) urlSet.add(m[1]);
  }
  return downloadAndRewriteUrls(
    urlSet,
    html,
    join(downloadDir, REMOTE_MEDIA_SUBDIR),
    "Remote background-image download failed",
    "Localized remote background-image(s)",
    // Quoted url('..')/url("..") are rewritten by downloadAndRewriteUrls' default
    // replaceAll; this handles the unquoted url(https://..) form.
    (h, url, rel) => h.replaceAll(`url(${url})`, `url(${rel})`),
  );
}

// Match url("https://...") or url('https://...') inside @font-face blocks.
// We scan the full HTML (which includes <style> blocks) — matching against
// @font-face context precisely would require a CSS parser; instead we match
// any url(https?://...) that appears inside a @font-face rule by looking for
// the surrounding context. Simple pattern: capture all HTTP url() references
// that follow a @font-face opener (before the closing brace). The regex is
// applied to the CSS text extracted from <style> blocks so it can't
// accidentally match JavaScript string literals.
const REMOTE_FONTFACE_URL_RE = /url\(["']?(https?:\/\/[^"')]+)["']?\)/gi;

/**
 * Download any remote font URLs from `@font-face` src declarations, rewrite
 * the CSS `url(...)` references to local paths, and return a map of assets.
 *
 * Why: `@font-face { src: url("https://s3.../font.ttf") }` fails in the
 * renderer because Chrome makes a CORS-mode fetch from the local file server
 * origin (http://localhost:PORT) and S3 does not echo that origin back in
 * Access-Control-Allow-Origin. The font load is rejected, Chrome falls back
 * to the next font in the stack (e.g. Arial). Downloading the font file
 * before render and rewriting to a local path eliminates the CORS race.
 */
/** Returns true for URLs belonging to Google Fonts (handled by the deterministic font injector). */
function isGoogleFontsUrl(href: string): boolean {
  try {
    const host = new URL(href).hostname.toLowerCase();
    return host === "fonts.googleapis.com" || host === "fonts.gstatic.com";
  } catch {
    return /fonts\.googleapis\.com|fonts\.gstatic\.com/i.test(href);
  }
}

const MAX_STYLESHEET_BYTES = 2 * 1024 * 1024;

async function fetchExternalStylesheetCss(href: string): Promise<string | null> {
  const identity = safeDownloadUrlIdentity(href);
  try {
    return await fetchPublicHttpsText(href, {
      maxBytes: MAX_STYLESHEET_BYTES,
      timeoutMs: 15_000,
    });
  } catch (err) {
    defaultLogger.warn("[Compiler] External stylesheet fetch failed, preserving link tag.", {
      urlFingerprint: identity.urlFingerprint,
      host: identity.host,
      error: err instanceof Error ? err.message : String(err),
    });
    return null;
  }
}

/**
 * Extract all `@font-face { ... }` blocks from a CSS string, preserving the
 * full rule text (including the `@font-face` keyword and braces).
 *
 * Uses a depth-tracking scan instead of `[^}]*` so blocks with nested
 * descriptor values that happen to contain `}` (rare but valid in
 * `format(...)` hints with custom idents) are captured correctly.
 */
function extractFontFaceBlocks(css: string): string[] {
  const blocks: string[] = [];
  const atRule = /@font-face\s*/gi;
  let m: RegExpExecArray | null;
  while ((m = atRule.exec(css)) !== null) {
    const openIdx = css.indexOf("{", m.index + m[0].length);
    if (openIdx === -1) break;
    let depth = 1;
    let i = openIdx + 1;
    for (; i < css.length && depth > 0; i++) {
      if (css[i] === "{") depth++;
      else if (css[i] === "}") depth--;
    }
    if (depth === 0) {
      blocks.push(css.slice(m.index, i));
      atRule.lastIndex = i;
    }
  }
  return blocks;
}

/**
 * Find all external `<link rel="stylesheet">` tags pointing to non-Google
 * CDNs, fetch their CSS, and replace the `<link>` with an inline `<style>`
 * containing only the `@font-face` rules. This allows Phase 2 (the existing
 * inline scan) to pick up and localise the font file URLs.
 *
 * Google Fonts links are excluded because the deterministic font injector
 * handles those. If a fetch fails or the CSS has no `@font-face` blocks,
 * the original `<link>` tag is preserved (graceful degradation).
 */
// fallow-ignore-next-line complexity
async function inlineExternalFontStylesheets(html: string): Promise<string> {
  const linkRe = /<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi;
  const hrefRe = /\bhref=["']([^"']+)["']/i;

  const linkMatches: { fullMatch: string; href: string }[] = [];
  let linkMatch: RegExpExecArray | null;
  while ((linkMatch = linkRe.exec(html)) !== null) {
    const tag = linkMatch[0];
    const hrefMatch = hrefRe.exec(tag);
    if (!hrefMatch?.[1]) continue;
    const href = hrefMatch[1];
    if (!/^https?:\/\//i.test(href)) continue;
    if (isGoogleFontsUrl(href)) continue;
    linkMatches.push({ fullMatch: tag, href });
  }

  if (linkMatches.length === 0) return html;

  const MAX_CONCURRENT_STYLESHEET_FETCHES = 4;
  const fetches: { fullMatch: string; href: string; css: string | null }[] = [];
  for (let i = 0; i < linkMatches.length; i += MAX_CONCURRENT_STYLESHEET_FETCHES) {
    const batch = linkMatches.slice(i, i + MAX_CONCURRENT_STYLESHEET_FETCHES);
    const results = await Promise.all(
      batch.map(async ({ fullMatch, href }) => {
        const css = await fetchExternalStylesheetCss(href);
        return { fullMatch, href, css };
      }),
    );
    fetches.push(...results);
  }

  let result = html;
  for (const { fullMatch, href, css } of fetches) {
    if (css === null) continue;
    const fontFaceBlocks = extractFontFaceBlocks(css);
    if (fontFaceBlocks.length === 0) continue;
    const identity = safeDownloadUrlIdentity(href);
    const inlineStyle = `<style>/* Inlined external font stylesheet */\n${fontFaceBlocks.join("\n")}\n</style>`;
    result = result.replace(fullMatch, inlineStyle);
    defaultLogger.info("[Compiler] Inlined external @font-face rule(s)", {
      count: fontFaceBlocks.length,
      urlFingerprint: identity.urlFingerprint,
      host: identity.host,
    });
  }
  return result;
}

/**
 * Collect all remote `url(https://...)` references inside `@font-face` blocks
 * found in `<style>` tags.
 */
// fallow-ignore-next-line complexity
function collectFontFaceUrls(html: string): Set<string> {
  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
  const urlSet = new Set<string>();

  let styleMatch: RegExpExecArray | null;
  while ((styleMatch = styleBlockRe.exec(html)) !== null) {
    const cssText = styleMatch[1] ?? "";
    // Depth-tracking scanner to correctly handle @font-face blocks that
    // contain nested braces (e.g. unicode-range fallback rules).
    let i = 0;
    while (i < cssText.length) {
      const atIdx = cssText.indexOf("@font-face", i);
      if (atIdx === -1) break;
      const braceStart = cssText.indexOf("{", atIdx);
      if (braceStart === -1) break;
      let depth = 1;
      let j = braceStart + 1;
      while (j < cssText.length && depth > 0) {
        if (cssText[j] === "{") depth++;
        else if (cssText[j] === "}") depth--;
        j++;
      }
      const block = cssText.slice(braceStart + 1, j - 1);
      const urlRe = new RegExp(REMOTE_FONTFACE_URL_RE.source, REMOTE_FONTFACE_URL_RE.flags);
      let urlMatch: RegExpExecArray | null;
      while ((urlMatch = urlRe.exec(block)) !== null) {
        if (urlMatch[1]) urlSet.add(urlMatch[1]);
      }
      i = j;
    }
  }
  return urlSet;
}

/** @internal exported for unit testing only */
export async function localizeRemoteFontFaces(
  html: string,
  downloadDir: string,
): Promise<{ html: string; remoteMediaAssets: Map<string, string> }> {
  // Phase 1: Inline @font-face rules from external <link rel="stylesheet"> tags.
  const processed = await inlineExternalFontStylesheets(html);

  // Phase 2: Download font file URLs from all @font-face blocks (both
  // pre-existing inline blocks and the ones just inlined from external sheets).
  const urlSet = collectFontFaceUrls(processed);

  return downloadAndRewriteUrls(
    urlSet,
    processed,
    join(downloadDir, REMOTE_MEDIA_SUBDIR),
    "Remote font download failed",
    "Localized remote font face(s)",
    (h, url, relPath) => h.replaceAll(`url(${url})`, `url("${relPath}")`),
  );
}

// `file:` joins data: and http(s): in the exclusion list. Without it an
// absolute `file:///abs/path/font.ttf` src was read as a project-RELATIVE path,
// resolved to `<projectDir>/file:/abs/path/...`, and the failed read was
// swallowed below — leaving the rule untouched for the browser to reject.
const LOCAL_FONTFACE_URL_RE = /url\(["']?(?!data:|file:|https?:\/\/)([^"')]+)["']?\)/gi;

/**
 * Match one `url(<path>)` occurrence, with or without quotes, for a literal
 * path. Exported for tests: the suffix-collision it prevents is invisible in
 * ordinary projects and easy to reintroduce.
 */
export function urlOccurrenceRe(localPath: string): RegExp {
  const escaped = localPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  return new RegExp(`url\\((["']?)${escaped}\\1\\)`, "g");
}
// Base64 expands bytes by ~33%, then immutable HTML replacements retain more
// string copies while compiling. Files up to and including 5 MiB remain inline;
// the first byte above that stays file-backed. This conservative ceiling keeps
// verified 19 MiB+ TTC collections out of the V8 heap while both local and
// distributed file servers continue serving project assets at authored paths.
const MAX_LOCAL_FONT_DATA_URI_BYTES = 5 * 1024 * 1024;

type LocalFontRead = { kind: "file-backed" } | { kind: "inline"; buffer: Buffer };

async function readLocalFont(absPath: string): Promise<LocalFontRead> {
  const chunks: Buffer[] = [];
  let totalBytes = 0;
  for await (const chunk of createReadStream(absPath)) {
    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
    totalBytes += buffer.length;
    if (totalBytes > MAX_LOCAL_FONT_DATA_URI_BYTES) {
      return { kind: "file-backed" };
    }
    chunks.push(buffer);
  }
  return { kind: "inline", buffer: Buffer.concat(chunks, totalBytes) };
}

// fallow-ignore-next-line complexity
async function embedLocalFontFaces(html: string, projectDir: string): Promise<string> {
  const { fontToDataUri: toDataUri } = await import("@hyperframes/core/fonts/embed");
  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
  const fontFaceRe = /@font-face\s*\{([^}]*)\}/gi;
  let result = html;
  const embeddedPaths = new Set<string>();
  const dataUriByAbsolutePath = new Map<string, string>();
  const fileBackedAbsolutePaths = new Set<string>();

  let styleMatch: RegExpExecArray | null;
  while ((styleMatch = styleBlockRe.exec(html)) !== null) {
    const cssText = styleMatch[1] ?? "";
    const ffRe = new RegExp(fontFaceRe.source, fontFaceRe.flags);
    let ffMatch: RegExpExecArray | null;
    while ((ffMatch = ffRe.exec(cssText)) !== null) {
      const block = ffMatch[1] ?? "";
      const urlRe = new RegExp(LOCAL_FONTFACE_URL_RE.source, LOCAL_FONTFACE_URL_RE.flags);
      let urlMatch: RegExpExecArray | null;
      while ((urlMatch = urlRe.exec(block)) !== null) {
        const localPath = urlMatch[1];
        if (!localPath || embeddedPaths.has(localPath)) continue;
        const absPath = localPath.startsWith("/") ? localPath : resolve(projectDir, localPath);
        if (!isPathInside(absPath, projectDir)) continue;
        const ext = absPath.match(/\.(woff2?|ttf|otf|ttc)$/i)?.[1]?.toLowerCase() ?? "ttf";
        try {
          if (fileBackedAbsolutePaths.has(absPath)) {
            embeddedPaths.add(localPath);
            continue;
          }
          let dataUri = dataUriByAbsolutePath.get(absPath);
          if (!dataUri) {
            const font = await readLocalFont(absPath);
            if (font.kind === "file-backed") {
              fileBackedAbsolutePaths.add(absPath);
              defaultLogger.info(
                `[Compiler] Kept large local font file-backed: ${localPath} (> ${(MAX_LOCAL_FONT_DATA_URI_BYTES / 1024 / 1024).toFixed(1)} MB)`,
              );
              embeddedPaths.add(localPath);
              continue;
            }
            dataUri = await toDataUri(font.buffer, ext, { compressToWoff2: false });
            dataUriByAbsolutePath.set(absPath, dataUri);
            defaultLogger.info(
              `[Compiler] Embedded local font file: ${localPath} (${(font.buffer.length / 1024).toFixed(0)} KB → data URI)`,
            );
          }
          // Anchored on the `url(...)` occurrence, not a bare substring. A
          // plain replaceAll of `localPath` also rewrites that text anywhere
          // else it appears -- including inside a LONGER url whose tail
          // happens to match, e.g. embedding `fonts/x.ttf` would corrupt an
          // untouched `url("file:///abs/fonts/x.ttf")` into
          // `url("file:///abs/<data-uri>")`. Any two paths where one is a
          // suffix of the other collide the same way. Every sibling rewrite
          // in this file already anchors like this.
          result = result.replace(urlOccurrenceRe(localPath), `url("${dataUri}")`);
          embeddedPaths.add(localPath);
        } catch (error) {
          // Keep the original path: a font that cannot be read must not fail
          // the render. Logged rather than silently swallowed -- a silent skip
          // here means the composition renders in a fallback typeface and
          // nothing says why.
          defaultLogger.warn(
            `[Compiler] Could not embed local font ${localPath}: ${
              error instanceof Error ? error.message : String(error)
            }`,
          );
        }
      }
    }
  }
  return result;
}

/**
 * Optional behavior toggles for {@link compileForRender}. All fields are
 * additive; omitting `options` preserves the in-process renderer's defaults.
 */
export interface CompileForRenderOptions {
  /**
   * Logger for compile-time diagnostics (e.g. the data-duration vs. media
   * mismatch warning). Optional so non-render callers can omit it.
   */
  log?: ProducerLogger;
  /** Absolute project paths not on disk, readable at these URLs instead. */
  urlByAbsentLocalPath?: ReadonlyMap<string, string>;
  /**
   * Threaded through to {@link injectDeterministicFontFaces}. When `true`,
   * deterministic font resolution and exhausted transient fetch failures
   * surface as typed errors instead of silently falling back to system fonts.
   * Distributed `plan()` sets this to `true` so font availability is part of
   * the planDir's content-addressed hash. Default `false` preserves the
   * in-process behavior.
   */
  failClosedFontFetch?: boolean;
  /**
   * When `true`, fonts not resolved by the bundled alias map or Google Fonts
   * are located on the local filesystem, compressed to woff2, and embedded.
   * Default `true` for local renders. Distributed callers pass `false` to
   * prevent host-specific font capture from leaking into the planDir.
   */
  allowSystemFontCapture?: boolean;
  /** Caller cancellation propagated through compile-time font fetches. */
  abortSignal?: AbortSignal;
  /**
   * Optional persistent cache directory for prep-time animated GIF → WebM
   * transcodes. When omitted, the render's downloadDir is used.
   */
  animatedGifCacheDir?: string;
  /** FFmpeg timeout for animated GIF transcodes. */
  ffmpegProcessTimeout?: number;
  /**
   * Render-time variable overrides (`--variables`). Layered over declared
   * defaults in the compile-time CSS custom-property stylesheet so eval-time
   * reads (GSAP .from immediateRender) see the overridden value — the
   * `window.__hfVariables` injection covers script reads, not var() in CSS.
   */
  variables?: Record<string, unknown>;
  pageMotionBlur?: "off";
}

const GSAP_CDN_BASE = gsapCdnDist();

function rewriteUnresolvableGsapToCdn(html: string, projectDir: string): string {
  return html.replace(
    /(<script\b[^>]*\bsrc=["'])([^"']*gsap[^"']*\/dist\/([^"']+))(["'][^>]*>)/gi,
    (full, prefix, src, file, suffix) => {
      if (/^https?:\/\//i.test(src)) return full;
      const absPath = resolve(projectDir, src);
      if (existsSync(absPath)) return full;
      defaultLogger.info(
        `[Compiler] Rewriting missing gsap script to CDN: ${src} → ${GSAP_CDN_BASE}${file}`,
      );
      return `${prefix}${GSAP_CDN_BASE}${file}${suffix}`;
    },
  );
}

/**
 * Preserve a nested entry document's browser URL base when compilation moves
 * it to compiled/index.html. Use the same sibling-first/project-root-fallback
 * rule as mounted sub-compositions so both supported entry modes agree.
 */
function rebaseDirectEntryAssetPaths(html: string, projectDir: string, htmlPath: string): string {
  if (!isPathInside(htmlPath, projectDir)) return html;
  const entryPath = relative(projectDir, htmlPath).replace(/\\/g, "/");
  if (!entryPath.includes("/")) return html;

  const { document } = parseHTML(html);
  const assetExists = (path: string) => existsSync(resolve(projectDir, path));
  rewriteAssetPaths(
    document.querySelectorAll("[src], [href]"),
    entryPath,
    (el: Element, attr: string) => el.getAttribute(attr),
    (el: Element, attr: string, value: string) => el.setAttribute(attr, value),
    assetExists,
  );
  rewriteInlineStyleAssetUrls(
    document.querySelectorAll("[style]"),
    entryPath,
    (el: Element) => el.getAttribute("style"),
    (el: Element, value: string) => el.setAttribute("style", value),
    assetExists,
  );
  for (const style of document.querySelectorAll("style")) {
    style.textContent = rewriteCssAssetUrls(style.textContent || "", entryPath, assetExists);
  }
  return document.toString();
}

/**
 * Compile an HTML composition project into a single self-contained HTML string
 * with all media metadata resolved.
 */
// fallow-ignore-next-line complexity
export async function compileForRender(
  projectDir: string,
  htmlPath: string,
  downloadDir: string,
  options: CompileForRenderOptions = {},
): Promise<CompiledComposition> {
  const entryHtml = rebaseDirectEntryAssetPaths(
    readFileSync(htmlPath, "utf-8"),
    projectDir,
    htmlPath,
  );
  const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);

  // Pre-flight: every data-composition-src reference must resolve to a
  // usable file before we spend any time compiling, launching a browser, or
  // waiting out a capture timeout. See EmptyCompositionError for why this is
  // unconditional (not gated behind --strict like lint warnings) — a render
  // that silently drops a scene is strictly worse than one that refuses to
  // start.
  assertSubCompositionsUsable(rawHtml, projectDir);

  const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
    rawHtml,
    projectDir,
    downloadDir,
    options.log,
    options.urlByAbsentLocalPath,
  );

  // Compile each referenced sub-composition so the inliner can hoist it.
  const { subCompositions } = await parseSubCompositions(
    compiledHtml,
    projectDir,
    downloadDir,
    undefined,
    options.urlByAbsentLocalPath,
  );

  // Ensure the HTML is a full document before inlining sub-compositions.
  // When index.html is a fragment (no <html>/<head>/<body>), linkedom.parseHTML()
  // returns a document with null head/body, which causes inlineSubCompositions to
  // silently discard all collected composition styles and scripts.
  const fullHtml = ensureFullDocument(compiledHtml);

  // Inline sub-compositions into the main HTML so the runtime takes the same
  // synchronous code path as the bundled preview (no async fetch of
  // data-composition-src). This mirrors what htmlBundler.ts does for preview.
  const inlinedHtml = inlineSubCompositions(
    fullHtml,
    subCompositions,
    projectDir,
    options.variables ?? {},
  );

  // Strip preload="none" from media elements — the renderer needs to load all
  // media upfront for frame capture. Users add this to reduce browser memory in
  // preview, but it causes the headless renderer to never load the media, leading
  // to 45s timeout failures.
  const sanitizedHtml = inlinedHtml.replace(
    /(<(?:video|audio)\b[^>]*?)\s+preload\s*=\s*["']none["']/gi,
    "$1",
  );
  const renderModeHints = detectRenderModeHints(sanitizedHtml, options.pageMotionBlur);
  const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
  // Detected BEFORE inlineExternalScripts: GSAP's own source contains
  // `transformPerspective`, so scanning post-inline HTML would flag every
  // composition that loads GSAP from a CDN.
  const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
  const usesMixBlendMode = detectMixBlendModeUsage(sanitizedHtml);
  const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);

  const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
    injectTextRenderingRule(
      coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml)),
    ),
  );

  const coalescedHtml = await injectDeterministicFontFaces(normalizedFontHtml, {
    logger: defaultLogger,
    failClosedFontFetch: options.failClosedFontFetch === true,
    allowSystemFontCapture: options.allowSystemFontCapture,
    abortSignal: options.abortSignal,
  });

  // CDN scripts are inlined after coalescing so they stay separate from the merged inline runs.
  const assembledHtml = await inlineExternalScripts(coalescedHtml);

  // Inject studio position seek re-apply script when positions are baked into HTML.
  // GSAP overwrites the `translate` CSS property on every frame seek; this script
  // re-asserts the CSS custom property var() form after each seek so dragged
  // positions survive frame-by-frame rendering without a JSON sidecar.
  const HF_POSITION_ATTRS = [
    'data-hf-studio-path-offset="true"',
    'data-hf-studio-box-size="true"',
    'data-hf-studio-rotation="true"',
    'data-hf-studio-motion="',
  ];
  const hasPositionEdits = HF_POSITION_ATTRS.some((attr) => assembledHtml.includes(attr));
  const htmlWithPositionScript = hasPositionEdits
    ? (insertBeforeCloseTag(
        assembledHtml,
        "body",
        `<script>${createStudioPositionSeekReapplyScript()}\n//# sourceURL=hyperframes://position-seek-reapply</script>`,
      ) ?? assembledHtml)
    : assembledHtml;
  const htmlWithDeferredScripts = prepareCompositionScripts(
    injectSdkPositionEditsRenderScript(htmlWithPositionScript),
  );

  // Download remote <video> and <audio> sources to compiledDir and rewrite the
  // src attributes so the renderer reads from localhost. Remote S3 URLs cause
  // Chrome to spend the entire pageReadyTimeout buffering 10+ large video files
  // over the network; any that don't reach readyState >= 2 in time render as
  // blank black frames. Localising them eliminates the race.
  const { html: htmlWithLocalMedia, remoteMediaAssets } = await localizeRemoteMediaSources(
    htmlWithDeferredScripts,
    downloadDir,
  );

  // Download remote <img> sources. Same race shape as video/audio: the
  // readiness gate can pass before Chrome decodes the pixels, and Chrome can
  // evict decoded pixels mid-render and re-fetch, producing intermittent
  // blank-frame flicker. Localising to disk removes both races.
  const { html: htmlWithLocalImages, remoteMediaAssets: remoteImageAssets } =
    await localizeRemoteImageSources(htmlWithLocalMedia, downloadDir);

  // Download remote CSS background-image url() references. drawElementImage omits
  // cross-origin content, so remote backgrounds render black on the fast path;
  // localising them to same-origin closes that gap.
  const { html: htmlWithLocalBg, remoteMediaAssets: remoteBgAssets } =
    await localizeRemoteBackgroundImages(htmlWithLocalImages, downloadDir);

  // Download remote @font-face src URLs and rewrite to local paths.
  // Remote font URLs fail with a CORS rejection at render time (S3 does not
  // allow http://localhost:PORT as origin), causing Chrome to silently fall
  // back to the next font in the stack.
  const { html: htmlWithLocalizedFonts, remoteMediaAssets: remoteFontAssets } =
    await localizeRemoteFontFaces(htmlWithLocalBg, downloadDir);

  const gifSourceAssets = new Map<string, string>(remoteImageAssets);
  const {
    html: htmlWithPreparedGifs,
    preparedAssets: preparedGifAssets,
    preparedGifs,
  } = await prepareAnimatedGifInputs(htmlWithLocalizedFonts, {
    projectDir,
    downloadDir,
    cacheDir: options.animatedGifCacheDir,
    sourceAssets: gifSourceAssets,
    timeoutMs: options.ffmpegProcessTimeout,
  });
  if (preparedGifs.length > 0) {
    defaultLogger.info(`[Compiler] Prepared ${preparedGifs.length} animated GIF input(s) as WebM`);
  }

  const embeddedHtml = await embedLocalFontFaces(htmlWithPreparedGifs, projectDir);

  // Collect assets that resolve outside projectDir (e.g. ../shared-assets/hero.png).
  // These can't be served by the file server, so we map them to paths the
  // orchestrator will copy into the compiled output directory.
  const { html, externalAssets } = collectExternalAssets(embeddedHtml, projectDir);

  for (const [relPath, absPath] of remoteMediaAssets) {
    externalAssets.set(relPath, absPath);
  }
  for (const [relPath, absPath] of remoteImageAssets) {
    externalAssets.set(relPath, absPath);
  }
  for (const [relPath, absPath] of remoteBgAssets) {
    externalAssets.set(relPath, absPath);
  }
  for (const [relPath, absPath] of remoteFontAssets) {
    externalAssets.set(relPath, absPath);
  }
  for (const [relPath, absPath] of preparedGifAssets) {
    externalAssets.set(relPath, absPath);
  }

  // Read the media list off the inlined document rather than merging the
  // per-file lists. Merging deduplicated by element id, which is only unique
  // within one composition file: two scenes declaring `<video id="clip">` — or
  // two bare `<video>`s, both auto-numbered `hf-video-0` — collapsed into one
  // entry and injected frames onto whichever element came first. See #3340.
  const { videos, audios, images, droppedMediaIds } = collectRenderMedia(html);
  const masterFxChain = parseMasterFxChain(html);

  // Advisory video checks (sparse keyframes, VFR). Fire-and-forget — these spawn
  // ffprobe subprocesses and should not block compilation since they only produce warnings.
  // The two probes run in sequence rather than in parallel: the keyframe analysis needs
  // the video stream's own duration to classify a single-keyframe (single-GOP) file.
  for (const video of videos) {
    if (isHttpUrl(video.src)) continue;
    const videoPath = resolve(projectDir, video.src);
    const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
    (async () => {
      const metadata = await withMediaProbeSlot(() => extractMediaMetadata(videoPath));
      const analysis = await withMediaProbeSlot(() =>
        analyzeKeyframeIntervals(videoPath, metadata),
      );
      if (analysis.isProblematic) {
        defaultLogger.warn(
          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). ` +
            `This causes seek failures and frame freezing. Re-encode with: ${reencode}`,
        );
      }
      if (metadata.isVFR) {
        // defaultLogger (stderr), not console.info (stdout) — matches the sibling
        // warning above; a stdout line here corrupts `check --json` / `validate --json`.
        defaultLogger.warn(
          `[Compiler] Video "${video.id}" is variable frame rate (VFR); ` +
            `the engine will normalize it to CFR before frame extraction. ` +
            `If rendering feels slow on this video, pre-encode once with: ${reencode}`,
        );
      }
    })().catch(() => {});
  }

  // Read dimensions from root composition element using DOM parser
  const { document } = parseHTML(html);
  const rootEl = document.querySelector("[data-composition-id]");

  const width = rootEl ? parseInt(rootEl.getAttribute("data-width") || "1080", 10) : 1080;
  const height = rootEl ? parseInt(rootEl.getAttribute("data-height") || "1920", 10) : 1920;

  // Static duration (may be 0 if set at runtime by GSAP)
  const staticDuration = rootEl
    ? (parseStrictFiniteTimingNumber(rootEl.getAttribute("data-duration")) ??
      parseStrictFiniteTimingNumber(rootEl.getAttribute("data-composition-duration")) ??
      0)
    : 0;

  return {
    html,
    subCompositions,
    videos,
    audios,
    images,
    droppedMediaIds,
    ...(masterFxChain ? { masterFxChain } : {}),
    unresolvedCompositions,
    externalAssets,
    width,
    height,
    staticDuration,
    renderModeHints,
    hasShaderTransitions,
    usesThreeDTransforms,
    usesMixBlendMode,
    hasAncestorBackgroundImage,
  };
}

/**
 * Discover media elements from the browser DOM after JavaScript has run.
 * This catches videos/audios whose `src` is set dynamically via JS
 * (e.g. `document.getElementById("pip-video").src = URL`), which the
 * static regex parsers miss because the HTML has `src=""`. Clips are keyed
 * by `data-hf-render-id` when present — author ids collide across inlined
 * scenes, and this snapshot is the only identity those empty-src elements get.
 */
export interface BrowserMediaElement {
  id: string;
  tagName: "video" | "audio" | "image";
  src: string;
  start: number;
  end: number;
  duration: number;
  /** True when compilation inferred duration from the fallback source. */
  durationInferred: boolean;
  mediaStart: number;
  loop: boolean;
  hasAudio: boolean;
  volume: number;
  /** The `muted` attribute/property. Preview silences muted media; the mix must too. */
  muted: boolean;
}

export interface BrowserAudioVolumeAutomation {
  id: string;
  keyframes: AudioVolumeKeyframe[];
}

export async function discoverMediaFromBrowser(page: Page): Promise<BrowserMediaElement[]> {
  const elements = await page.evaluate(() => {
    const results: {
      id: string;
      tagName: "video" | "audio" | "image";
      src: string;
      start: number;
      endRaw: string | null;
      durationRaw: string | null;
      intrinsicDuration: number;
      durationInferred: boolean;
      playbackStartRaw: string | null;
      mediaStartRaw: string | null;
      loop: boolean;
      hasAudio: boolean;
      volume: number;
      muted: boolean;
    }[] = [];

    const autoImageIds = new Map<Element, string>();
    let autoImageId = 0;
    document.querySelectorAll("img[src]").forEach((image) => {
      if (!image.id) autoImageIds.set(image, `hf-img-${autoImageId++}`);
    });

    const mediaEls = new Set<Element>(
      document.querySelectorAll("video[data-start], audio[data-start], img[data-var-src]"),
    );
    // A variable-bound <picture><source> changes the owning image's currentSrc;
    // the <img> fallback itself does not necessarily carry data-var-src.
    document.querySelectorAll("picture source[data-var-src]").forEach((source) => {
      const image = source.closest("picture")?.querySelector("img");
      if (image) mediaEls.add(image);
    });
    mediaEls.forEach((el) => {
      const htmlEl = el as HTMLVideoElement | HTMLAudioElement | HTMLImageElement;
      const isImage = htmlEl.tagName.toLowerCase() === "img";
      const tagName: "video" | "audio" | "image" = isImage
        ? "image"
        : htmlEl.tagName.toLowerCase() === "video"
          ? "video"
          : "audio";
      // Render id is document-unique after inlining; author id is only unique
      // per composition file. Empty-src media is skipped by the static parse
      // and lives or dies on this snapshot — keying by author id collapses
      // colliding scenes onto one clip (residual of #3340).
      const id =
        htmlEl.getAttribute("data-hf-render-id") ||
        htmlEl.id ||
        (isImage ? autoImageIds.get(htmlEl) : undefined);
      if (!id) return;

      // currentSrc is authoritative for <video>/<audio><source> and responsive images.
      const ownSrc = htmlEl.getAttribute("src");
      const blankSrc =
        ownSrc !== null && ownSrc.trim() === "" && !htmlEl.querySelector("source[src]");
      const src = blankSrc ? "" : htmlEl.currentSrc || htmlEl.src || ownSrc || "";
      const start = parseFloat(htmlEl.getAttribute("data-start") || "0");
      const endRaw = htmlEl.getAttribute("data-end");
      const durationRaw = htmlEl.getAttribute("data-duration");
      const durationInferred = htmlEl.hasAttribute("data-hf-inferred-duration");
      const intrinsicDuration = isImage
        ? 0
        : (htmlEl as HTMLVideoElement | HTMLAudioElement).duration;
      const playbackStartRaw = htmlEl.getAttribute("data-playback-start");
      const mediaStartRaw = htmlEl.getAttribute("data-media-start");
      const loop = htmlEl.hasAttribute("loop");
      const hasAudio = htmlEl.getAttribute("data-has-audio") === "true";
      const volume = parseFloat(htmlEl.getAttribute("data-volume") || "1");
      const muted =
        !isImage &&
        (htmlEl.hasAttribute("muted") || (htmlEl as HTMLVideoElement | HTMLAudioElement).muted);

      results.push({
        id,
        tagName,
        src,
        start,
        endRaw,
        durationRaw,
        intrinsicDuration,
        durationInferred,
        playbackStartRaw,
        mediaStartRaw,
        loop,
        hasAudio,
        volume,
        muted,
      });
    });

    return results;
  });

  return elements.map(
    ({ endRaw, durationRaw, intrinsicDuration, playbackStartRaw, mediaStartRaw, ...element }) => ({
      ...element,
      end: parseStrictFiniteTimingNumber(endRaw) ?? 0,
      duration:
        element.durationInferred && Number.isFinite(intrinsicDuration) && intrinsicDuration > 0
          ? intrinsicDuration
          : (parseStrictFiniteTimingNumber(durationRaw) ?? 0),
      mediaStart: readMediaStart({
        getAttribute(name: string) {
          if (name === "data-playback-start") return playbackStartRaw;
          if (name === "data-media-start") return mediaStartRaw;
          return null;
        },
      }),
    }),
  );
}

export async function discoverAudioVolumeAutomationFromTimeline(
  page: Page,
  audioIds: string[],
  compositionDuration: number,
  sampleFps: number,
): Promise<BrowserAudioVolumeAutomation[]> {
  if (audioIds.length === 0 || compositionDuration <= 0) return [];

  const sampleStep = 1 / Math.min(60, Math.max(1, sampleFps));
  const rawWindows = await page.evaluate((ids: string[]) => {
    return ids.flatMap((id) => {
      const el =
        window.__hfMediaEl?.(id) ??
        document.getElementById(id) ??
        document.getElementById(id.replace(/-audio$/, ""));
      if (!(el instanceof HTMLAudioElement) && !(el instanceof HTMLVideoElement)) return [];
      return [
        {
          id,
          startRaw: el.dataset.start ?? null,
          endRaw: el.dataset.end ?? null,
          durationRaw: el.dataset.duration ?? null,
        },
      ];
    });
  }, audioIds);
  const clips = rawWindows.map(({ id, startRaw, endRaw, durationRaw }) => {
    const start = parseStrictFiniteTimingNumber(startRaw) ?? 0;
    const authoredDuration = parseStrictFiniteTimingNumber(durationRaw);
    const authoredEnd = parseStrictFiniteTimingNumber(endRaw);
    const end =
      authoredDuration != null && authoredDuration > 0
        ? start + authoredDuration
        : authoredEnd != null && authoredEnd > start
          ? authoredEnd
          : compositionDuration;
    return { id, start, end };
  });
  return page.evaluate(
    ({ clips, duration, step, maxGain }) => {
      const results: { id: string; keyframes: { time: number; volume: number }[] }[] = [];
      const clampGain = (value: number) =>
        Number.isFinite(value) ? Math.max(0, Math.min(maxGain, value)) : 1;
      // `HTMLMediaElement.volume` is spec-clamped to [0,1], so a clip authored
      // above unity — or a GSAP tween seeded from one — reads back as 0 dB and
      // the whole authored boost is lost from the mix. Shadow the accessor for
      // the probe so the authored value survives; the native setter still gets
      // the clamped value. Mirrors `withUnclampedVolume` in
      // packages/core/src/audioGain.ts, which the preview probe uses; this copy
      // exists only because the probe body is serialized into the page.
      //
      // Guarded because this body is also executed directly by tests that stand
      // in for a Page, where there is no DOM and no HTMLMediaElement.
      const volumeDescriptor =
        typeof HTMLMediaElement === "undefined"
          ? undefined
          : Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
      const nativeVolumeGet = volumeDescriptor?.get;
      const nativeVolumeSet = volumeDescriptor?.set;
      const withUnclampedVolume = <T>(el: HTMLMediaElement, probe: () => T): T => {
        if (!nativeVolumeGet || !nativeVolumeSet) return probe();
        let authored = Number(nativeVolumeGet.call(el));
        Object.defineProperty(el, "volume", {
          configurable: true,
          get: () => authored,
          set: (value: number) => {
            authored = Number(value);
            nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
          },
        });
        try {
          return probe();
        } finally {
          delete (el as unknown as Record<"volume", unknown>).volume;
          nativeVolumeSet.call(el, Math.max(0, Math.min(1, authored)));
        }
      };
      const timelines = (window as unknown as { __timelines?: Record<string, unknown> })
        .__timelines;
      if (!timelines) return results;

      const rootEl = document.querySelector("[data-composition-id]");
      const compId = rootEl?.getAttribute("data-composition-id");
      if (!compId) return results;

      const tl = timelines[compId] as
        | {
            totalTime?: (t: number, suppressEvents?: boolean) => unknown;
            seek?: (t: number, suppressEvents?: boolean) => unknown;
          }
        | undefined;
      if (!tl) return results;

      const seekTl = (t: number) => {
        if (typeof tl.totalTime === "function") {
          tl.totalTime(t, true);
        } else if (typeof tl.seek === "function") {
          tl.seek(t, true);
        }
      };

      for (const { id, start, end } of clips) {
        const el =
          window.__hfMediaEl?.(id) ??
          document.getElementById(id) ??
          document.getElementById(id.replace(/-audio$/, ""));
        if (!(el instanceof HTMLAudioElement) && !(el instanceof HTMLVideoElement)) continue;

        const sampleStart = Math.max(0, start);
        const sampleEnd = Math.min(duration, end);
        const initialVolumeAttr = Number.parseFloat(el.dataset.volume ?? "");

        const keyframes = withUnclampedVolume(el, () => {
          if (Number.isFinite(initialVolumeAttr)) {
            el.volume = clampGain(initialVolumeAttr);
          }

          const keyframes: { time: number; volume: number }[] = [];
          let previousSample: { time: number; volume: number } | undefined;
          for (let t = sampleStart; t <= sampleEnd + 0.000001; t = Math.min(sampleEnd, t + step)) {
            seekTl(t);
            const rawVolume = Number(el.volume);
            if (!Number.isFinite(rawVolume)) {
              if (t === sampleEnd) break;
              continue;
            }
            const volume = clampGain(rawVolume);
            const sample = {
              time: Number(t.toFixed(6)),
              volume: Number(volume.toFixed(6)),
            };
            const last = keyframes.at(-1);
            if (!last || Math.abs(last.volume - volume) > 0.0001) {
              // Retain the preceding real sample when compression omitted a flat
              // run. Continuous ramps already have that sample as their last
              // keyframe, so their interpolation remains unchanged.
              if (last && previousSample && previousSample.time > last.time) {
                keyframes.push(previousSample);
              }
              keyframes.push(sample);
            } else if (t === sampleEnd && sample.time > last.time) {
              keyframes.push(sample);
            }
            previousSample = sample;
            if (t === sampleEnd) break;
          }
          return keyframes;
        });

        const staticAttr = Number.parseFloat(el.dataset.volume ?? "");
        const staticVolume = Number.isFinite(staticAttr) ? clampGain(staticAttr) : 1;
        const hasAutomation = keyframes.some(
          (keyframe) => Math.abs(keyframe.volume - staticVolume) > 0.0001,
        );
        if (hasAutomation) {
          results.push({ id, keyframes });
        }
      }

      seekTl(0);
      return results;
    },
    { clips, duration: compositionDuration, step: sampleStep, maxGain: MAX_AUDIO_GAIN },
  );
}

export interface VideoVisibilityWindow {
  videoId: string;
  visibleStart: number;
  visibleEnd: number;
}

/**
 * Seek the GSAP timeline to discover when each video's parent scene is visible.
 * Only processes videos with the data-hf-auto-start sentinel (auto-injected timing).
 */
export async function discoverVideoVisibilityFromTimeline(
  page: Page,
  compositionDuration: number,
): Promise<VideoVisibilityWindow[]> {
  if (compositionDuration <= 0) return [];

  return page.evaluate((duration: number) => {
    const results: { videoId: string; visibleStart: number; visibleEnd: number }[] = [];
    const videos = document.querySelectorAll("video[data-hf-auto-start]");
    if (videos.length === 0) return results;

    const timelines = (window as unknown as { __timelines?: Record<string, unknown> }).__timelines;
    if (!timelines) return results;

    const rootEl = document.querySelector("[data-composition-id]");
    const compId = rootEl?.getAttribute("data-composition-id");
    if (!compId) return results;

    const tl = timelines[compId] as
      | {
          totalTime?: (t: number, suppressEvents?: boolean) => unknown;
          seek?: (t: number, suppressEvents?: boolean) => unknown;
        }
      | undefined;
    if (!tl) return results;

    const seekTl = (t: number) => {
      if (typeof tl.totalTime === "function") {
        tl.totalTime(t, true);
      } else if (typeof tl.seek === "function") {
        tl.seek(t, true);
      }
    };

    const SAMPLE_STEP = 0.1;
    const BINARY_PRECISION = 1 / 60;

    // Seek once per timestep and sample every video — seeking dominates and is
    // independent of which element we read.
    const entries: {
      id: string;
      sceneEl: Element;
      firstVisible: number | null;
      lastVisible: number | null;
    }[] = [];
    for (const videoEl of videos) {
      const id = videoEl.getAttribute?.("data-hf-render-id") || videoEl.id;
      if (!id) continue;
      entries.push({
        id,
        sceneEl: videoEl.closest(".scene") || videoEl,
        firstVisible: null,
        lastVisible: null,
      });
    }
    if (entries.length === 0) return results;

    for (let t = 0; t <= duration; t += SAMPLE_STEP) {
      seekTl(t);
      for (const entry of entries) {
        const opacity = parseFloat(window.getComputedStyle(entry.sceneEl).opacity);
        if (opacity > 0) {
          if (entry.firstVisible === null) entry.firstVisible = t;
          entry.lastVisible = t;
        }
      }
    }

    // Per-video boundary refinement (cheap: O(log(step)) seeks each).
    for (const entry of entries) {
      const { id, sceneEl, firstVisible, lastVisible } = entry;
      if (firstVisible === null || lastVisible === null) continue;

      // Binary search left boundary
      let lo = Math.max(0, firstVisible - SAMPLE_STEP);
      let hi = firstVisible;
      while (hi - lo > BINARY_PRECISION) {
        const mid = (lo + hi) / 2;
        seekTl(mid);
        const opacity = parseFloat(window.getComputedStyle(sceneEl).opacity);
        if (opacity > 0) hi = mid;
        else lo = mid;
      }
      const exactStart = hi;

      // Binary search right boundary
      lo = lastVisible;
      hi = Math.min(duration, lastVisible + SAMPLE_STEP);
      while (hi - lo > BINARY_PRECISION) {
        const mid = (lo + hi) / 2;
        seekTl(mid);
        const opacity = parseFloat(window.getComputedStyle(sceneEl).opacity);
        if (opacity > 0) lo = mid;
        else hi = mid;
      }
      const exactEnd = lo;

      results.push({
        videoId: id,
        visibleStart: Math.max(0, exactStart),
        visibleEnd: Math.min(duration, exactEnd),
      });
    }

    seekTl(0);
    return results;
  }, compositionDuration);
}

/**
 * Resolve composition durations via Puppeteer by querying window.__timelines.
 * The page must already have the interceptor loaded and timelines registered.
 */
export async function resolveCompositionDurations(
  page: Page,
  unresolved: UnresolvedElement[],
): Promise<ResolvedDuration[]> {
  if (unresolved.length === 0) return [];

  const ids = unresolved.map((el) => el.id);

  const results = await page.evaluate((compIds: string[]) => {
    const win = window as unknown as { __timelines?: Record<string, { duration(): number }> };
    const timelines = win.__timelines || {};
    const resolved: {
      id: string;
      duration: number;
      source: string;
      durationRaw?: string;
      compositionDurationRaw?: string;
    }[] = [];

    for (const id of compIds) {
      // Try window.__timelines[id].duration() first (GSAP timeline)
      const tl = timelines[id];
      let dur = 0;
      try {
        dur = typeof tl?.duration === "function" ? Number(tl.duration()) : 0;
      } catch {
        dur = 0;
      }
      if (dur > 0) {
        resolved.push({ id, duration: dur, source: "__timelines" });
        continue;
      }

      // Fallback: check for authored duration on the element itself
      const el = document.getElementById(id);
      if (el) {
        const durationRaw = el.getAttribute("data-duration");
        const compositionDurationRaw = el.getAttribute("data-composition-duration");
        if (durationRaw != null || compositionDurationRaw != null) {
          resolved.push({
            id,
            duration: 0,
            source: "data-duration",
            ...(durationRaw != null ? { durationRaw } : {}),
            ...(compositionDurationRaw != null ? { compositionDurationRaw } : {}),
          });
          continue;
        }
      }

      resolved.push({ id, duration: 0, source: "unresolved" });
    }

    return resolved;
  }, ids);

  const resolutions: ResolvedDuration[] = [];
  for (const r of results) {
    const duration =
      parseStrictFiniteTimingNumber(r.durationRaw) ??
      parseStrictFiniteTimingNumber(r.compositionDurationRaw) ??
      r.duration;
    if (duration != null && duration > 0) {
      resolutions.push({ id: r.id, duration });
    }
  }

  return resolutions;
}

/**
 * Re-compile after composition durations are resolved.
 * Injects durations into the HTML and re-parses sub-composition media with proper bounds.
 */
export async function recompileWithResolutions(
  compiled: CompiledComposition,
  resolutions: ResolvedDuration[],
  projectDir: string,
  downloadDir: string,
): Promise<CompiledComposition> {
  if (resolutions.length === 0) return compiled;

  const html = injectDurations(compiled.html, resolutions);

  // Re-resolve the sub-composition map against the updated HTML, but keep the
  // media list from the first pass. Resolving a composition's duration stamps a
  // `data-end` on its host, and re-collecting would newly clamp clips to it —
  // a retiming, not an identity fix. `compiled.videos` was already collected
  // from this same inlined document, so it is complete and correctly keyed.
  const { subCompositions } = await parseSubCompositions(html, projectDir, downloadDir);
  const { videos, audios, images } = compiled;

  const remaining = compiled.unresolvedCompositions.filter(
    (c) => !resolutions.some((r) => r.id === c.id),
  );

  return {
    ...compiled,
    html,
    subCompositions,
    videos,
    audios,
    images,
    unresolvedCompositions: remaining,
    renderModeHints: compiled.renderModeHints,
    hasShaderTransitions: compiled.hasShaderTransitions,
  };
}