@hyperframes/producer 0.4.4 → 0.4.6

package/dist/public-server.js

@@ -57866,7 +57866,7 @@ var require_util2 = __commonJS({
         }
         path12 = url.path;
       }
-      var isAbsolute2 = exports.isAbsolute(path12);
+      var isAbsolute3 = exports.isAbsolute(path12);
       var parts = path12.split(/\/+/);
       for (var part, up = 0, i = parts.length - 1; i >= 0; i--) {
         part = parts[i];
@@ -57886,7 +57886,7 @@ var require_util2 = __commonJS({
       }
       path12 = parts.join("/");
       if (path12 === "") {
-        path12 = isAbsolute2 ? "/" : ".";
+        path12 = isAbsolute3 ? "/" : ".";
       }
       if (url) {
         url.path = path12;
@@ -57931,7 +57931,7 @@ var require_util2 = __commonJS({
     exports.isAbsolute = function(aPath) {
       return aPath.charAt(0) === "/" || urlRegexp.test(aPath);
     };
-    function relative2(aRoot, aPath) {
+    function relative3(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
       }
@@ -57950,7 +57950,7 @@ var require_util2 = __commonJS({
       }
       return Array(level + 1).join("../") + aPath.substr(aRoot.length + 1);
     }
-    exports.relative = relative2;
+    exports.relative = relative3;
     var supportsNullProto = (function() {
       var obj = /* @__PURE__ */ Object.create(null);
       return !("__proto__" in obj);
@@ -95503,10 +95503,10 @@ function compareDocumentPosition(nodeA, nodeB) {
 function uniqueSort(nodes) {
   nodes = nodes.filter((node, i, arr) => !arr.includes(node, i + 1));
   nodes.sort((a, b) => {
-    const relative2 = compareDocumentPosition(a, b);
-    if (relative2 & DocumentPosition.PRECEDING) {
+    const relative3 = compareDocumentPosition(a, b);
+    if (relative3 & DocumentPosition.PRECEDING) {
       return -1;
-    } else if (relative2 & DocumentPosition.FOLLOWING) {
+    } else if (relative3 & DocumentPosition.FOLLOWING) {
       return 1;
     }
     return 0;
@@ -103860,6 +103860,15 @@ function isFontResourceError(type, text, locationUrl) {
     `${locationUrl} ${text}`
   );
 }
+async function pollPageExpression(page, expression, timeoutMs, intervalMs = 100) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ready = Boolean(await page.evaluate(expression));
+    if (ready) return true;
+    await new Promise((resolve13) => setTimeout(resolve13, intervalMs));
+  }
+  return Boolean(await page.evaluate(expression));
+}
 async function initializeSession(session) {
   const { page, serverUrl } = session;
   page.on("console", (msg) => {
@@ -103889,14 +103898,26 @@ async function initializeSession(session) {
   if (session.captureMode === "screenshot") {
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 6e4 });
     const pageReadyTimeout2 = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
-    await page.waitForFunction(
+    const pageReady2 = await pollPageExpression(
+      page,
       `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`,
-      { timeout: pageReadyTimeout2 }
+      pageReadyTimeout2
     );
-    await page.waitForFunction(
+    if (!pageReady2) {
+      throw new Error(
+        `[FrameCapture] window.__hf not ready after ${pageReadyTimeout2}ms. Page must expose window.__hf = { duration, seek }.`
+      );
+    }
+    const videosReady = await pollPageExpression(
+      page,
       `document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
-      { timeout: pageReadyTimeout2 }
+      pageReadyTimeout2
     );
+    if (!videosReady) {
+      throw new Error(
+        `[FrameCapture] video metadata not ready after ${pageReadyTimeout2}ms. Video elements must load metadata before capture starts.`
+      );
+    }
     await page.evaluate(`document.fonts?.ready`);
     session.isInitialized = true;
     return;
@@ -105931,7 +105952,7 @@ async function mergeWorkerFrames(workDir, tasks, outputDir) {
 }
 
 // src/services/renderOrchestrator.ts
-import { join as join14, dirname as dirname10, resolve as resolve9 } from "path";
+import { join as join15, dirname as dirname10, resolve as resolve10 } from "path";
 import { randomUUID } from "crypto";
 import { freemem as freemem2 } from "os";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -106036,6 +106057,102 @@ var MIME_TYPES = {
   ".ttf": "font/ttf",
   ".otf": "font/otf"
 };
+var VIRTUAL_TIME_SHIM = String.raw`(function() {
+  if (window.__HF_VIRTUAL_TIME__) return;
+
+  var virtualNowMs = 0;
+  var rafId = 1;
+  var rafQueue = [];
+  var OriginalDate = Date;
+  var originalSetTimeout = window.setTimeout.bind(window);
+  var originalClearTimeout = window.clearTimeout.bind(window);
+  var originalSetInterval = window.setInterval.bind(window);
+  var originalClearInterval = window.clearInterval.bind(window);
+  var originalRequestAnimationFrame = window.requestAnimationFrame
+    ? window.requestAnimationFrame.bind(window)
+    : null;
+  var originalCancelAnimationFrame = window.cancelAnimationFrame
+    ? window.cancelAnimationFrame.bind(window)
+    : null;
+
+  function flushAnimationFrame() {
+    if (!rafQueue.length) return;
+    var current = rafQueue.slice();
+    rafQueue.length = 0;
+    for (var i = 0; i < current.length; i++) {
+      var entry = current[i];
+      if (entry.cancelled) continue;
+      try {
+        entry.callback(virtualNowMs);
+      } catch {}
+    }
+  }
+
+  function VirtualDate() {
+    var args = Array.prototype.slice.call(arguments);
+    if (!(this instanceof VirtualDate)) {
+      return OriginalDate.apply(null, args.length ? args : [virtualNowMs]);
+    }
+    var instance = args.length ? new (Function.prototype.bind.apply(OriginalDate, [null].concat(args)))() : new OriginalDate(virtualNowMs);
+    Object.setPrototypeOf(instance, VirtualDate.prototype);
+    return instance;
+  }
+
+  VirtualDate.prototype = OriginalDate.prototype;
+  Object.setPrototypeOf(VirtualDate, OriginalDate);
+  VirtualDate.now = function() { return virtualNowMs; };
+  VirtualDate.parse = OriginalDate.parse.bind(OriginalDate);
+  VirtualDate.UTC = OriginalDate.UTC.bind(OriginalDate);
+
+  try {
+    Object.defineProperty(window, "Date", {
+      configurable: true,
+      writable: true,
+      value: VirtualDate,
+    });
+  } catch {}
+
+  if (window.performance && typeof window.performance.now === "function") {
+    try {
+      Object.defineProperty(window.performance, "now", {
+        configurable: true,
+        value: function() { return virtualNowMs; },
+      });
+    } catch {}
+  }
+
+  window.requestAnimationFrame = function(callback) {
+    if (typeof callback !== "function") return 0;
+    var entry = { id: rafId++, callback: callback, cancelled: false };
+    rafQueue.push(entry);
+    return entry.id;
+  };
+  window.cancelAnimationFrame = function(id) {
+    for (var i = 0; i < rafQueue.length; i++) {
+      if (rafQueue[i].id === id) {
+        rafQueue[i].cancelled = true;
+      }
+    }
+  };
+
+  window.__HF_VIRTUAL_TIME__ = {
+    originalSetTimeout: originalSetTimeout,
+    originalClearTimeout: originalClearTimeout,
+    originalSetInterval: originalSetInterval,
+    originalClearInterval: originalClearInterval,
+    originalRequestAnimationFrame: originalRequestAnimationFrame,
+    originalCancelAnimationFrame: originalCancelAnimationFrame,
+    seekToTime: function(nextTimeMs) {
+      var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+      virtualNowMs = safeTimeMs;
+      flushAnimationFrame();
+      return virtualNowMs;
+    },
+    getTime: function() {
+      return virtualNowMs;
+    },
+  };
+})();`;
 var RENDER_SEEK_MODE = process.env.PRODUCER_RUNTIME_RENDER_SEEK_MODE === "strict-boundary" ? "strict-boundary" : "preview-phase";
 var RENDER_SEEK_DIAGNOSTICS = process.env.PRODUCER_DEBUG_SEEK_DIAGNOSTICS === "true";
 var RENDER_SEEK_STEP = Math.max(
@@ -106047,6 +106164,10 @@ var RENDER_SEEK_OFFSET_FRACTION = Math.max(
   Math.min(0.95, Number(process.env.PRODUCER_RUNTIME_RENDER_SEEK_OFFSET_FRACTION || 0.5))
 );
 var RENDER_MODE_SCRIPT = `(function() {
+  var __realSetTimeout =
+    window.__HF_VIRTUAL_TIME__ && typeof window.__HF_VIRTUAL_TIME__.originalSetTimeout === "function"
+      ? window.__HF_VIRTUAL_TIME__.originalSetTimeout
+      : window.setTimeout.bind(window);
   var __seekMode = ${JSON.stringify(RENDER_SEEK_MODE)};
   var __seekDiagnostics = ${RENDER_SEEK_DIAGNOSTICS ? "true" : "false"};
   var __seekStep = ${RENDER_SEEK_STEP};
@@ -106140,23 +106261,56 @@ var RENDER_MODE_SCRIPT = `(function() {
         window.__renderReady = true;
         return;
       }
-      setTimeout(waitForPlayer, 50);
+      __realSetTimeout(waitForPlayer, 50);
       return;
     }
     if (installMediaFallbackPlayer()) {
       return;
     }
-    setTimeout(waitForPlayer, 50);
+    __realSetTimeout(waitForPlayer, 50);
   }
   waitForPlayer();
 })();`;
 var HF_BRIDGE_SCRIPT = `(function() {
+  var __realSetInterval =
+    window.__HF_VIRTUAL_TIME__ && typeof window.__HF_VIRTUAL_TIME__.originalSetInterval === "function"
+      ? window.__HF_VIRTUAL_TIME__.originalSetInterval
+      : window.setInterval.bind(window);
+  var __realClearInterval =
+    window.__HF_VIRTUAL_TIME__ && typeof window.__HF_VIRTUAL_TIME__.originalClearInterval === "function"
+      ? window.__HF_VIRTUAL_TIME__.originalClearInterval
+      : window.clearInterval.bind(window);
   function getDeclaredDuration() {
     var root = document.querySelector('[data-composition-id]');
     if (!root) return 0;
     var d = Number(root.getAttribute('data-duration'));
     return Number.isFinite(d) && d > 0 ? d : 0;
   }
+  function seekSameOriginChildFrames(frameWindow, nextTimeMs) {
+    var frames;
+    try {
+      frames = frameWindow.frames;
+    } catch (_error) {
+      return;
+    }
+    if (!frames || typeof frames.length !== "number") return;
+    for (var i = 0; i < frames.length; i++) {
+      var childWindow = null;
+      try {
+        childWindow = frames[i];
+        if (!childWindow || childWindow === frameWindow) continue;
+        if (
+          childWindow.__HF_VIRTUAL_TIME__ &&
+          typeof childWindow.__HF_VIRTUAL_TIME__.seekToTime === "function"
+        ) {
+          childWindow.__HF_VIRTUAL_TIME__.seekToTime(nextTimeMs);
+        }
+      } catch (_error) {
+        continue;
+      }
+      seekSameOriginChildFrames(childWindow, nextTimeMs);
+    }
+  }
   function bridge() {
     var p = window.__player;
     if (!p || typeof p.renderSeek !== "function" || typeof p.getDuration !== "function") {
@@ -106167,13 +106321,20 @@ var HF_BRIDGE_SCRIPT = `(function() {
         var d = p.getDuration();
         return d > 0 ? d : getDeclaredDuration();
       },
-      seek: function(t) { p.renderSeek(t); },
+      seek: function(t) {
+        p.renderSeek(t);
+        var nextTimeMs = (Math.max(0, Number(t) || 0)) * 1000;
+        if (window.__HF_VIRTUAL_TIME__ && typeof window.__HF_VIRTUAL_TIME__.seekToTime === "function") {
+          window.__HF_VIRTUAL_TIME__.seekToTime(nextTimeMs);
+        }
+        seekSameOriginChildFrames(window, nextTimeMs);
+      },
     };
     return true;
   }
   if (bridge()) return;
-  var iv = setInterval(function() {
-    if (bridge()) clearInterval(iv);
+  var iv = __realSetInterval(function() {
+    if (bridge()) __realClearInterval(iv);
   }, 50);
 })();`;
 function stripEmbeddedRuntimeScripts(html) {
@@ -106235,8 +106396,22 @@ function injectScriptsIntoHtml(html, headScripts, bodyScripts, stripEmbedded) {
   }
   return html;
 }
+function injectScriptsAtHeadStart(html, scripts) {
+  if (scripts.length === 0) return html;
+  const headTags = scripts.map((src) => `<script>${src}</script>`).join("\n");
+  if (html.includes("<head")) {
+    return html.replace(/<head\b[^>]*>/i, (match2) => `${match2}
+${headTags}`);
+  }
+  if (html.includes("<body")) {
+    return html.replace("<body", () => `${headTags}
+<body`);
+  }
+  return headTags + "\n" + html;
+}
 function createFileServer2(options) {
   const { projectDir, compiledDir, port = 0, stripEmbeddedRuntime = true } = options;
+  const preHeadScripts = options.preHeadScripts ?? [];
   const headScripts = options.headScripts ?? [getVerifiedHyperframeRuntimeSource()];
   const bodyScripts = options.bodyScripts ?? [RENDER_MODE_SCRIPT, HF_BRIDGE_SCRIPT];
   const app = new Hono2();
@@ -106260,7 +106435,11 @@ function createFileServer2(options) {
     if (ext === ".html") {
       const rawHtml = readFileSync6(filePath, "utf-8");
       const isIndex = relativePath === "index.html";
-      const html = isIndex ? injectScriptsIntoHtml(rawHtml, headScripts, bodyScripts, stripEmbeddedRuntime) : rawHtml;
+      let html = rawHtml;
+      if (preHeadScripts.length > 0) {
+        html = injectScriptsAtHeadStart(html, preHeadScripts);
+      }
+      html = isIndex ? injectScriptsIntoHtml(html, headScripts, bodyScripts, stripEmbeddedRuntime) : html;
       return c.text(html, 200, { "Content-Type": contentType });
     }
     const content = readFileSync6(filePath);
@@ -106291,13 +106470,41 @@ function createFileServer2(options) {
 
 // src/services/htmlCompiler.ts
 import { readFileSync as readFileSync8, existsSync as existsSync14, mkdirSync as mkdirSync9 } from "fs";
-import { join as join13, dirname as dirname9, resolve as resolve8 } from "path";
+import { join as join14, dirname as dirname9, resolve as resolve9 } from "path";
 import postcss from "postcss";
 
+// src/utils/paths.ts
+import { resolve as resolve8, basename as basename2, join as join12, relative as relative2, isAbsolute as isAbsolute2 } from "node:path";
+var DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? resolve8(new URL(import.meta.url).pathname, "../../..", "renders");
+function isPathInside(childPath, parentPath) {
+  const absChild = resolve8(childPath);
+  const absParent = resolve8(parentPath);
+  if (absChild === absParent) return true;
+  const rel = relative2(absParent, absChild);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function toExternalAssetKey(absPath) {
+  if (absPath.startsWith("hf-ext/")) return absPath;
+  let normalised = absPath.replace(/\\/g, "/");
+  normalised = normalised.replace(/^\/\/\?\/UNC\//i, "//");
+  normalised = normalised.replace(/^\/\/\?\//, "");
+  normalised = normalised.replace(/^\/\/([^/]+)\//, "unc/$1/");
+  normalised = normalised.replace(/^\/+/, "");
+  normalised = normalised.replace(/^([A-Za-z]):\/?/, "$1/");
+  return "hf-ext/" + normalised;
+}
+function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS_DIR) {
+  const absoluteProjectDir = resolve8(projectDir);
+  const projectName = basename2(absoluteProjectDir);
+  const resolvedOutputPath = outputPath ?? join12(rendersDir, `${projectName}.mp4`);
+  const absoluteOutputPath = resolve8(resolvedOutputPath);
+  return { absoluteProjectDir, absoluteOutputPath };
+}
+
 // src/services/deterministicFonts.ts
 import { existsSync as existsSync13, mkdirSync as mkdirSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 
 // src/services/fontData.generated.ts
 var EMBEDDED_FONT_DATA = /* @__PURE__ */ new Map([
@@ -106575,20 +106782,20 @@ function warnUnresolvedFonts(unresolved) {
   Docs: https://hyperframes.heygen.com/docs/fonts`
   );
 }
-var GOOGLE_FONTS_CACHE_DIR = join12(homedir2(), ".cache", "hyperframes", "fonts");
+var GOOGLE_FONTS_CACHE_DIR = join13(homedir2(), ".cache", "hyperframes", "fonts");
 var WOFF2_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 function fontSlug(familyName) {
   return familyName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
 function fontCacheDir(slug) {
-  const dir = join12(GOOGLE_FONTS_CACHE_DIR, slug);
+  const dir = join13(GOOGLE_FONTS_CACHE_DIR, slug);
   if (!existsSync13(dir)) {
     mkdirSync8(dir, { recursive: true });
   }
   return dir;
 }
 function cachedWoff2Path(slug, weight, style) {
-  return join12(fontCacheDir(slug), `${weight}-${style}.woff2`);
+  return join13(fontCacheDir(slug), `${weight}-${style}.woff2`);
 }
 async function fetchGoogleFont(familyName) {
   const slug = fontSlug(familyName);
@@ -106680,6 +106887,37 @@ function dedupeElementsById(elements) {
   }
   return Array.from(deduped.values());
 }
+var INLINE_SCRIPT_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+function stripJsComments(source2) {
+  return source2.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+}
+function detectRenderModeHints(html) {
+  const reasons = [];
+  const { document: document2 } = parseHTML(html);
+  if (document2.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;
+  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(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
+  };
+}
 async function resolveMediaDuration(src, mediaStart, baseDir, downloadDir, tagName19) {
   let filePath = src;
   if (isHttpUrl(src)) {
@@ -106690,7 +106928,7 @@ async function resolveMediaDuration(src, mediaStart, baseDir, downloadDir, tagNa
       return { duration: 0, resolvedPath: src };
     }
   } else if (!filePath.startsWith("/")) {
-    filePath = join13(baseDir, filePath);
+    filePath = join14(baseDir, filePath);
   }
   if (!existsSync14(filePath)) {
     return { duration: 0, resolvedPath: filePath };
@@ -106756,7 +106994,7 @@ async function parseSubCompositions(html, projectDir, downloadDir, parentOffset
     const elEnd = elEndRaw ? parseFloat(elEndRaw) : Infinity;
     const absoluteStart = parentOffset + elStart;
     const absoluteEnd = Math.min(parentEnd, isFinite(elEnd) ? parentOffset + elEnd : Infinity);
-    const filePath = resolve8(projectDir, srcPath);
+    const filePath = resolve9(projectDir, srcPath);
     if (visited.has(filePath)) {
       continue;
     }
@@ -106956,7 +107194,7 @@ function inlineSubCompositions(html, subCompositions, projectDir) {
     if (!srcPath) continue;
     let compHtml = subCompositions.get(srcPath) || null;
     if (!compHtml) {
-      const filePath = resolve8(projectDir, srcPath);
+      const filePath = resolve9(projectDir, srcPath);
       if (existsSync14(filePath)) {
         compHtml = readFileSync8(filePath, "utf-8");
       }
@@ -107169,7 +107407,7 @@ ${safeText}
   return result;
 }
 function collectExternalAssets(html, projectDir) {
-  const absProjectDir = resolve8(projectDir);
+  const absProjectDir = resolve9(projectDir);
   const externalAssets = /* @__PURE__ */ new Map();
   const CSS_URL_RE2 = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
   function processPath(rawPath) {
@@ -107177,12 +107415,12 @@ function collectExternalAssets(html, projectDir) {
     if (!trimmed || trimmed.startsWith("/") || trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("//") || trimmed.startsWith("data:") || trimmed.startsWith("#")) {
       return null;
     }
-    const absPath = resolve8(absProjectDir, trimmed);
-    if (absPath.startsWith(absProjectDir + "/") || absPath === absProjectDir) {
+    const absPath = resolve9(absProjectDir, trimmed);
+    if (isPathInside(absPath, absProjectDir)) {
       return null;
     }
     if (!existsSync14(absPath)) return null;
-    const safeKey = "hf-ext/" + absPath.replace(/^\//, "");
+    const safeKey = toExternalAssetKey(absPath);
     externalAssets.set(safeKey, absPath);
     return safeKey;
   }
@@ -107243,6 +107481,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     /(<(?:video|audio)\b[^>]*?)\s+preload\s*=\s*["']none["']/gi,
     "$1"
   );
+  const renderModeHints = detectRenderModeHints(sanitizedHtml);
   const coalescedHtml = await injectDeterministicFontFaces(
     coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml))
   );
@@ -107254,7 +107493,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
   const audios = dedupeElementsById([...mainAudios, ...subAudios]);
   for (const video of videos) {
     if (isHttpUrl(video.src)) continue;
-    const videoPath = resolve8(projectDir, video.src);
+    const videoPath = resolve9(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`;
     Promise.all([analyzeKeyframeIntervals(videoPath), extractVideoMetadata(videoPath)]).then(([analysis, metadata]) => {
       if (analysis.isProblematic) {
@@ -107286,7 +107525,8 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     externalAssets,
     width,
     height,
-    staticDuration
+    staticDuration,
+    renderModeHints
   };
 }
 async function discoverMediaFromBrowser(page) {
@@ -107380,7 +107620,8 @@ async function recompileWithResolutions(compiled, resolutions, projectDir, downl
     subCompositions,
     videos,
     audios,
-    unresolvedCompositions: remaining
+    unresolvedCompositions: remaining,
+    renderModeHints: compiled.renderModeHints
   };
 }
 
@@ -107481,17 +107722,17 @@ function installDebugLogger(logPath, log = defaultLogger) {
   };
 }
 function writeCompiledArtifacts(compiled, workDir, includeSummary) {
-  const compileDir = join14(workDir, "compiled");
+  const compileDir = join15(workDir, "compiled");
   mkdirSync10(compileDir, { recursive: true });
-  writeFileSync4(join14(compileDir, "index.html"), compiled.html, "utf-8");
+  writeFileSync4(join15(compileDir, "index.html"), compiled.html, "utf-8");
   for (const [srcPath, html] of compiled.subCompositions) {
-    const outPath = join14(compileDir, srcPath);
+    const outPath = join15(compileDir, srcPath);
     mkdirSync10(dirname10(outPath), { recursive: true });
     writeFileSync4(outPath, html, "utf-8");
   }
   for (const [relativePath, absolutePath] of compiled.externalAssets) {
-    const outPath = resolve9(join14(compileDir, relativePath));
-    if (!outPath.startsWith(compileDir + "/")) {
+    const outPath = resolve10(join15(compileDir, relativePath));
+    if (!isPathInside(outPath, compileDir)) {
       console.warn(`[Render] Skipping external asset with unsafe path: ${relativePath}`);
       continue;
     }
@@ -107517,11 +107758,20 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
         end: a.end,
         mediaStart: a.mediaStart
       })),
-      subCompositions: Array.from(compiled.subCompositions.keys())
+      subCompositions: Array.from(compiled.subCompositions.keys()),
+      renderModeHints: compiled.renderModeHints
     };
-    writeFileSync4(join14(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+    writeFileSync4(join15(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   }
 }
+function applyRenderModeHints(cfg, compiled, log = defaultLogger) {
+  if (cfg.forceScreenshot || !compiled.renderModeHints.recommendScreenshot) return;
+  cfg.forceScreenshot = true;
+  log.warn("Auto-selected screenshot capture mode for render compatibility", {
+    reasonCodes: compiled.renderModeHints.reasons.map((reason) => reason.code),
+    reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
+  });
+}
 function createRenderJob(config2) {
   return {
     id: randomUUID(),
@@ -107563,9 +107813,9 @@ function extractStandaloneEntryFromIndex(indexHtml, entryFile) {
 }
 async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSignal) {
   const moduleDir = dirname10(fileURLToPath3(import.meta.url));
-  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve9(process.env.PRODUCER_RENDERS_DIR, "..") : resolve9(moduleDir, "../..");
-  const debugDir = join14(producerRoot, ".debug");
-  const workDir = job.config.debug ? join14(debugDir, job.id) : join14(dirname10(outputPath), `work-${job.id}`);
+  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve10(process.env.PRODUCER_RENDERS_DIR, "..") : resolve10(moduleDir, "../..");
+  const debugDir = join15(producerRoot, ".debug");
+  const workDir = job.config.debug ? join15(debugDir, job.id) : join15(dirname10(outputPath), `work-${job.id}`);
   const pipelineStart = Date.now();
   const log = job.config.logger ?? defaultLogger;
   let fileServer = null;
@@ -107573,7 +107823,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
   let lastBrowserConsole = [];
   let restoreLogger = null;
   const perfStages = {};
-  const perfOutputPath = join14(workDir, "perf-summary.json");
+  const perfOutputPath = join15(workDir, "perf-summary.json");
   const cfg = { ...job.config.producerConfig ?? resolveConfig() };
   const outputFormat = job.config.format ?? "mp4";
   const isWebm = outputFormat === "webm";
@@ -107595,19 +107845,19 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     assertNotAborted();
     if (!existsSync15(workDir)) mkdirSync10(workDir, { recursive: true });
     if (job.config.debug) {
-      const logPath = join14(workDir, "render.log");
+      const logPath = join15(workDir, "render.log");
       restoreLogger = installDebugLogger(logPath, log);
     }
     const entryFile = job.config.entryFile || "index.html";
-    let htmlPath = join14(projectDir, entryFile);
+    let htmlPath = join15(projectDir, entryFile);
     if (!existsSync15(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
     const rawEntry = readFileSync9(htmlPath, "utf-8");
     if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {
-      const wrapperPath = join14(workDir, "standalone-entry.html");
-      const projectIndexPath = join14(projectDir, "index.html");
+      const wrapperPath = join15(workDir, "standalone-entry.html");
+      const projectIndexPath = join15(projectDir, "index.html");
       if (!existsSync15(projectIndexPath)) {
         throw new Error(
           `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
@@ -107631,9 +107881,10 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const stage1Start = Date.now();
     updateJobStatus(job, "preprocessing", "Compiling composition", 5, onProgress);
     const compileStart = Date.now();
-    let compiled = await compileForRender(projectDir, htmlPath, join14(workDir, "downloads"));
+    let compiled = await compileForRender(projectDir, htmlPath, join15(workDir, "downloads"));
     assertNotAborted();
     perfStages.compileOnlyMs = Date.now() - compileStart;
+    applyRenderModeHints(cfg, compiled, log);
     writeCompiledArtifacts(compiled, workDir, Boolean(job.config.debug));
     log.info("Compiled composition metadata", {
       entryFile,
@@ -107641,7 +107892,8 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       width: compiled.width,
       height: compiled.height,
       videoCount: compiled.videos.length,
-      audioCount: compiled.audios.length
+      audioCount: compiled.audios.length,
+      renderModeHints: compiled.renderModeHints
     });
     const composition = {
       duration: compiled.staticDuration,
@@ -107660,8 +107912,9 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         reasons.push(`${compiled.unresolvedCompositions.length} unresolved composition(s)`);
       fileServer = await createFileServer2({
         projectDir,
-        compiledDir: join14(workDir, "compiled"),
-        port: 0
+        compiledDir: join15(workDir, "compiled"),
+        port: 0,
+        preHeadScripts: [VIRTUAL_TIME_SHIM]
       });
       assertNotAborted();
       const captureOpts = {
@@ -107673,7 +107926,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       };
       probeSession = await createCaptureSession(
         fileServer.url,
-        join14(workDir, "probe"),
+        join15(workDir, "probe"),
         captureOpts,
         null,
         cfg
@@ -107705,7 +107958,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             compiled,
             resolutions,
             projectDir,
-            join14(workDir, "downloads")
+            join15(workDir, "downloads")
           );
           assertNotAborted();
           composition.videos = compiled.videos;
@@ -107840,12 +108093,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const stage2Start = Date.now();
     updateJobStatus(job, "preprocessing", "Extracting video frames", 10, onProgress);
     let frameLookup = null;
-    const compiledDir = join14(workDir, "compiled");
+    const compiledDir = join15(workDir, "compiled");
     if (composition.videos.length > 0) {
       const extractionResult = await extractAllVideoFrames(
         composition.videos,
         projectDir,
-        { fps: job.config.fps, outputDir: join14(workDir, "video-frames") },
+        { fps: job.config.fps, outputDir: join15(workDir, "video-frames") },
         abortSignal,
         void 0,
         compiledDir
@@ -107879,13 +108132,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     }
     const stage3Start = Date.now();
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress);
-    const audioOutputPath = join14(workDir, "audio.aac");
+    const audioOutputPath = join15(workDir, "audio.aac");
     let hasAudio = false;
     if (composition.audios.length > 0) {
       const audioResult = await processCompositionAudio(
         composition.audios,
         projectDir,
-        join14(workDir, "audio-work"),
+        join15(workDir, "audio-work"),
         audioOutputPath,
         job.duration,
         abortSignal,
@@ -107903,12 +108156,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     if (!fileServer) {
       fileServer = await createFileServer2({
         projectDir,
-        compiledDir: join14(workDir, "compiled"),
-        port: 0
+        compiledDir: join15(workDir, "compiled"),
+        port: 0,
+        preHeadScripts: [VIRTUAL_TIME_SHIM]
       });
       assertNotAborted();
     }
-    const framesDir = join14(workDir, "captured-frames");
+    const framesDir = join15(workDir, "captured-frames");
     if (!existsSync15(framesDir)) mkdirSync10(framesDir, { recursive: true });
     const captureOptions = {
       width,
@@ -107920,7 +108174,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const workerCount = calculateOptimalWorkers(job.totalFrames, job.config.workers, cfg);
     const FORMAT_EXT = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
     const videoExt = FORMAT_EXT[outputFormat] ?? ".mp4";
-    const videoOnlyPath = join14(workDir, `video-only${videoExt}`);
+    const videoOnlyPath = join15(workDir, `video-only${videoExt}`);
     const preset = getEncoderPreset(job.config.quality, outputFormat);
     const effectiveQuality = job.config.crf ?? preset.quality;
     const effectiveBitrate = job.config.videoBitrate;
@@ -108196,7 +108450,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     }
     if (job.config.debug) {
       if (existsSync15(outputPath)) {
-        const debugOutput = join14(workDir, `output${videoExt}`);
+        const debugOutput = join15(workDir, `output${videoExt}`);
         copyFileSync2(outputPath, debugOutput);
       }
     } else {
@@ -108291,7 +108545,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
 
 // src/services/hyperframeLint.ts
 import { existsSync as existsSync16, readFileSync as readFileSync10, statSync as statSync6 } from "node:fs";
-import { resolve as resolve10, join as join15 } from "node:path";
+import { resolve as resolve11, join as join16 } from "node:path";
 function isStringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -108318,7 +108572,7 @@ function pickEntryFile(files, preferredEntryFile) {
   return null;
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
-  const absProjectDir = resolve10(projectDir);
+  const absProjectDir = resolve11(projectDir);
   if (!existsSync16(absProjectDir) || !statSync6(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
@@ -108326,7 +108580,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     (value) => typeof value === "string" && value.trim().length > 0
   );
   for (const entryFile of entryCandidates) {
-    const absoluteEntryPath = resolve10(absProjectDir, entryFile);
+    const absoluteEntryPath = resolve11(absProjectDir, entryFile);
     if (!absoluteEntryPath.startsWith(absProjectDir)) {
       return { error: `Entry file must stay inside project directory: ${entryFile}` };
     }
@@ -108339,7 +108593,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     }
   }
   return {
-    error: `No HTML entry file found in project directory: ${join15(absProjectDir, preferredEntryFile || "index.html")}`
+    error: `No HTML entry file found in project directory: ${join16(absProjectDir, preferredEntryFile || "index.html")}`
   };
 }
 function prepareHyperframeLintBody(body) {
@@ -108379,17 +108633,6 @@ function runHyperframeLint(prepared) {
   return lintHyperframeHtml(prepared.html, { filePath: prepared.entryFile });
 }
 
-// src/utils/paths.ts
-import { resolve as resolve11, basename as basename2, join as join16 } from "node:path";
-var DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? resolve11(new URL(import.meta.url).pathname, "../../..", "renders");
-function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS_DIR) {
-  const absoluteProjectDir = resolve11(projectDir);
-  const projectName = basename2(absoluteProjectDir);
-  const resolvedOutputPath = outputPath ?? join16(rendersDir, `${projectName}.mp4`);
-  const absoluteOutputPath = resolve11(resolvedOutputPath);
-  return { absoluteProjectDir, absoluteOutputPath };
-}
-
 // src/utils/semaphore.ts
 var Semaphore = class {
   constructor(maxConcurrent) {