Function compileHtmlFile

packages/producer/src/services/htmlCompiler.ts:340–428

* Compile a single HTML file: static pass + ffprobe for unresolved media. * Returns compiled HTML and any unresolved composition elements that need browser resolution.

(
  html: string,
  baseDir: string,
  downloadDir: string,
  log?: ProducerLogger,
)

 * Returns compiled HTML and any unresolved composition elements that need browser resolution.
 */
async function compileHtmlFile(
  html: string,
  baseDir: string,
  downloadDir: string,
  log?: ProducerLogger,
): 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, baseDir, downloadDir, el.tagName).then(
        ({ duration }) => ({ id: el.id, duration }),
      ),
    ),
  );
  const resolutions: ResolvedDuration[] = resolvedResults.filter((r) => r.duration > 0);

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

  // Phase 2: Validate pre-resolved media — clamp data-duration to actual source duration (parallel ffprobe)
  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,
          baseDir,
          downloadDir,
          el.tagName,
        );
        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 > 0 && shouldClampMediaDuration(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 clips still get clamped (and
      // videos still hold the last frame); thread `log` through
      // parseSubCompositions to warn for them too.
      const kind = r.tagName === "audio" ? "Audio" : "Video";
      log?.warn(
        `[compile] ${kind} "${r.id}" (${r.src}) is ${r.maxDuration.toFixed(2)}s but its ` +
          `data-duration is ${r.duration.toFixed(2)}s — 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.`,