@hyperframes/producer 0.1.12 → 0.1.14

package/dist/index.js

@@ -99387,6 +99387,19 @@ function lintHyperframeHtml(html, options = {}) {
       )
     });
   }
+  const clipIds = /* @__PURE__ */ new Map();
+  const clipClasses = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const classAttr = readAttr(tag.raw, "class") || "";
+    const classes = classAttr.split(/\s+/).filter(Boolean);
+    if (!classes.includes("clip")) continue;
+    const id = readAttr(tag.raw, "id");
+    const info = { tag: tag.name, id: id || "", classes: classAttr };
+    if (id) clipIds.set(`#${id}`, info);
+    for (const cls of classes) {
+      if (cls !== "clip") clipClasses.set(`.${cls}`, info);
+    }
+  }
   const classUsage = countClassUsage(tags);
   for (const script of scripts) {
     const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
@@ -99429,24 +99442,39 @@ ${right2.raw}`)
         });
       }
     }
+    for (const win of gsapWindows) {
+      const sel = win.targetSelector;
+      const clipInfo = clipIds.get(sel) || clipClasses.get(sel);
+      if (!clipInfo) continue;
+      const elDesc = `<${clipInfo.tag}${clipInfo.id ? ` id="${clipInfo.id}"` : ""} class="${clipInfo.classes}">`;
+      pushFinding({
+        code: "gsap_animates_clip_element",
+        severity: "error",
+        message: `GSAP animation targets a clip element. Selector "${sel}" resolves to element ${elDesc}. The framework manages clip visibility \u2014 animate an inner wrapper instead.`,
+        selector: sel,
+        elementId: clipInfo.id || void 0,
+        fixHint: "Wrap content in a child <div> and target that with GSAP.",
+        snippet: truncateSnippet(win.raw)
+      });
+    }
     if (!localTimelineCompId || localTimelineCompId === rootCompositionId) {
       continue;
     }
-    for (const window3 of gsapWindows) {
-      if (!isSuspiciousGlobalSelector(window3.targetSelector)) {
+    for (const win of gsapWindows) {
+      if (!isSuspiciousGlobalSelector(win.targetSelector)) {
         continue;
       }
-      const className = getSingleClassSelector(window3.targetSelector);
+      const className = getSingleClassSelector(win.targetSelector);
       if (className && (classUsage.get(className) || 0) < 2) {
         continue;
       }
       pushFinding({
         code: "unscoped_gsap_selector",
         severity: "warning",
-        message: `Timeline "${localTimelineCompId}" uses unscoped selector "${window3.targetSelector}" that will target elements in ALL compositions when bundled, causing data loss (opacity, transforms, etc.).`,
-        selector: window3.targetSelector,
-        fixHint: `Scope the selector: \`[data-composition-id="${localTimelineCompId}"] ${window3.targetSelector}\` or use a unique id.`,
-        snippet: truncateSnippet(window3.raw)
+        message: `Timeline "${localTimelineCompId}" uses unscoped selector "${win.targetSelector}" that will target elements in ALL compositions when bundled, causing data loss (opacity, transforms, etc.).`,
+        selector: win.targetSelector,
+        fixHint: `Scope the selector: \`[data-composition-id="${localTimelineCompId}"] ${win.targetSelector}\` or use a unique id.`,
+        snippet: truncateSnippet(win.raw)
       });
     }
   }
@@ -99486,8 +99514,8 @@ ${right2.raw}`)
         if (!parentClosePattern.test(between)) {
           pushFinding({
             code: "video_nested_in_timed_element",
-            severity: "warning",
-            message: `<video> with data-start appears to be nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. This can break media sync.`,
+            severity: "error",
+            message: `<video> with data-start is nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. The framework cannot manage playback of nested media \u2014 video will be FROZEN in renders.`,
             elementId: readAttr(tag.raw, "id") || void 0,
             fixHint: "Move the <video> to be a direct child of the stage, or remove data-start from the wrapper div (use it as a non-timed visual container).",
             snippet: truncateSnippet(tag.raw)
@@ -99549,6 +99577,41 @@ ${right2.raw}`)
       });
     }
   }
+  for (const tag of tags) {
+    if (tag.name !== "video" && tag.name !== "audio") continue;
+    const hasDataStart = readAttr(tag.raw, "data-start");
+    const hasId = readAttr(tag.raw, "id");
+    const hasSrc = readAttr(tag.raw, "src");
+    if (hasDataStart && !hasId) {
+      pushFinding({
+        code: "media_missing_id",
+        severity: "error",
+        message: `<${tag.name}> has data-start but no id attribute. The renderer requires id to discover media elements \u2014 this ${tag.name === "audio" ? "audio will be SILENT" : "video will be FROZEN"} in renders.`,
+        fixHint: `Add a unique id attribute: <${tag.name} id="my-${tag.name}" ...>`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+    if (hasDataStart && hasId && !hasSrc) {
+      pushFinding({
+        code: "media_missing_src",
+        severity: "error",
+        message: `<${tag.name} id="${hasId}"> has data-start but no src attribute. The renderer cannot load this media.`,
+        elementId: hasId,
+        fixHint: `Add a src attribute to the <${tag.name}> element directly. If using <source> children, the renderer still requires src on the parent element.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+    if (readAttr(tag.raw, "preload") === "none") {
+      pushFinding({
+        code: "media_preload_none",
+        severity: "warning",
+        message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has preload="none" which prevents the renderer from loading this media. The compiler strips it for renders, but preview may also have issues.`,
+        elementId: hasId || void 0,
+        fixHint: `Remove preload="none" or change to preload="auto". The framework manages media loading.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+  }
   for (const tag of tags) {
     if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
     if (!readAttr(tag.raw, "data-start")) continue;
@@ -99664,12 +99727,83 @@ ${right2.raw}`)
       }
     }
   }
+  for (const script of scripts) {
+    const content = script.content;
+    const hasExitTween = /\.to\s*\([^,]+,\s*\{[^}]*opacity\s*:\s*0/.test(content);
+    const hasHardKill = /\.set\s*\([^,]+,\s*\{[^}]*(?:visibility\s*:\s*["']hidden["']|opacity\s*:\s*0)/.test(content);
+    const hasCaptionLoop = /forEach|\.forEach\s*\(/.test(content) && /createElement|caption|group|cg-/.test(content);
+    if (hasCaptionLoop && hasExitTween && !hasHardKill) {
+      pushFinding({
+        code: "caption_exit_missing_hard_kill",
+        severity: "warning",
+        message: "Caption exit animations (tl.to with opacity: 0) detected without a hard tl.set kill. Exit tweens can fail when karaoke word-level tweens conflict, leaving captions stuck on screen.",
+        fixHint: 'Add `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end)` after every exit tl.to animation as a deterministic kill.'
+      });
+    }
+  }
+  for (const style of styles) {
+    const content = style.content;
+    const captionBlocks = content.matchAll(
+      /(\.caption[-_]?(?:group|container|text|line|word)|#caption[-_]?container)\s*\{([^}]+)\}/gi
+    );
+    for (const [, selector, body] of captionBlocks) {
+      if (!body) continue;
+      const hasNowrap = /white-space\s*:\s*nowrap/i.test(body);
+      const hasMaxWidth = /max-width/i.test(body);
+      if (hasNowrap && !hasMaxWidth) {
+        pushFinding({
+          code: "caption_text_overflow_risk",
+          severity: "warning",
+          selector: (selector ?? "").trim(),
+          message: `Caption selector "${(selector ?? "").trim()}" has white-space: nowrap but no max-width. Long phrases will clip off-screen.`,
+          fixHint: "Add max-width: 1600px (landscape) or max-width: 900px (portrait) and overflow: hidden."
+        });
+      }
+    }
+  }
+  for (const style of styles) {
+    const content = style.content;
+    const captionBlocks = content.matchAll(
+      /(\.caption[-_]?(?:group|container|text|line)|#caption[-_]?container)\s*\{([^}]+)\}/gi
+    );
+    for (const [, selector, body] of captionBlocks) {
+      if (!body) continue;
+      if (/position\s*:\s*relative/i.test(body)) {
+        pushFinding({
+          code: "caption_container_relative_position",
+          severity: "warning",
+          selector: (selector ?? "").trim(),
+          message: `Caption selector "${(selector ?? "").trim()}" uses position: relative which causes overflow and breaks caption stacking.`,
+          fixHint: "Use position: absolute for all caption elements."
+        });
+      }
+    }
+  }
+  {
+    const externalScriptRe = /<script\b[^>]*\bsrc=["'](https?:\/\/[^"']+)["'][^>]*>/gi;
+    let match2;
+    const seen2 = /* @__PURE__ */ new Set();
+    while ((match2 = externalScriptRe.exec(source2)) !== null) {
+      const src = match2[1] ?? "";
+      if (seen2.has(src)) continue;
+      seen2.add(src);
+      pushFinding({
+        code: "external_script_dependency",
+        severity: "info",
+        message: `This composition loads an external script from \`${src}\`. The HyperFrames bundler automatically hoists CDN scripts from sub-compositions into the parent document. In unbundled runtime mode, \`loadExternalCompositions\` re-injects them. If you're using a custom pipeline that bypasses both, you'll need to include this script manually.`,
+        fixHint: "No action needed when using `hyperframes dev` or `hyperframes render`. If using a custom pipeline, add this script tag to your root composition or HTML page.",
+        snippet: truncateSnippet(match2[0] ?? "")
+      });
+    }
+  }
   const errorCount = findings.filter((finding) => finding.severity === "error").length;
-  const warningCount = findings.length - errorCount;
+  const warningCount = findings.filter((finding) => finding.severity === "warning").length;
+  const infoCount = findings.filter((finding) => finding.severity === "info").length;
   return {
     ok: errorCount === 0,
     errorCount,
     warningCount,
+    infoCount,
     findings
   };
 }
@@ -99988,6 +100122,14 @@ function quantizeTimeToFrame(timeSeconds, fps) {
   return frameIndex / safeFps;
 }
 
+// ../../node_modules/.bun/@chenglou+pretext@0.0.3/node_modules/@chenglou/pretext/dist/analysis.js
+var arabicScriptRe = new RegExp("\\p{Script=Arabic}", "u");
+var combiningMarkRe = new RegExp("\\p{M}", "u");
+var decimalDigitRe = new RegExp("\\p{Nd}", "u");
+
+// ../../node_modules/.bun/@chenglou+pretext@0.0.3/node_modules/@chenglou/pretext/dist/measurement.js
+var emojiPresentationRe = new RegExp("\\p{Emoji_Presentation}", "u");
+
 // ../engine/src/services/screenshotService.ts
 var cdpSessionCache = /* @__PURE__ */ new WeakMap();
 async function getCdpSession(page) {
@@ -101105,6 +101247,42 @@ import { join as join7 } from "path";
 
 // ../engine/src/utils/ffprobe.ts
 import { spawn as spawn7 } from "child_process";
+function runFfprobe(args) {
+  return new Promise((resolve12, reject) => {
+    const proc = spawn7("ffprobe", args);
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
+      } else {
+        resolve12(stdout);
+      }
+    });
+    proc.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+function parseProbeJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch (e) {
+    throw new Error(
+      `[FFmpeg] Failed to parse ffprobe output: ${e instanceof Error ? e.message : e}`
+    );
+  }
+}
 var videoMetadataCache = /* @__PURE__ */ new Map();
 var audioMetadataCache = /* @__PURE__ */ new Map();
 function parseFrameRate(frameRateStr) {
@@ -101119,11 +101297,9 @@ function parseFrameRate(frameRateStr) {
 }
 async function extractVideoMetadata(filePath) {
   const cached = videoMetadataCache.get(filePath);
-  if (cached) {
-    return cached;
-  }
-  const probePromise = new Promise((resolve12, reject) => {
-    const args = [
+  if (cached) return cached;
+  const probePromise = (async () => {
+    const stdout = await runFfprobe([
       "-v",
       "quiet",
       "-print_format",
@@ -101131,56 +101307,24 @@ async function extractVideoMetadata(filePath) {
       "-show_format",
       "-show_streams",
       filePath
-    ];
-    const ffprobe = spawn7("ffprobe", args);
-    let stdout = "";
-    let stderr = "";
-    ffprobe.stdout.on("data", (data) => {
-      stdout += data.toString();
-    });
-    ffprobe.stderr.on("data", (data) => {
-      stderr += data.toString();
-    });
-    ffprobe.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
-        return;
-      }
-      try {
-        const output2 = JSON.parse(stdout);
-        const videoStream = output2.streams.find((s) => s.codec_type === "video");
-        if (!videoStream) {
-          reject(new Error("[FFmpeg] No video stream found"));
-          return;
-        }
-        const hasAudio = output2.streams.some((s) => s.codec_type === "audio");
-        const fps = parseFrameRate(videoStream.avg_frame_rate) || parseFrameRate(videoStream.r_frame_rate);
-        const durationSeconds = output2.format.duration ? parseFloat(output2.format.duration) : 0;
-        const metadata = {
-          durationSeconds,
-          width: videoStream.width || 0,
-          height: videoStream.height || 0,
-          fps,
-          videoCodec: videoStream.codec_name || "unknown",
-          hasAudio
-        };
-        resolve12(metadata);
-      } catch (parseError) {
-        reject(
-          new Error(
-            `[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`
-          )
-        );
-      }
-    });
-    ffprobe.on("error", (err) => {
-      if (err.code === "ENOENT") {
-        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
-      } else {
-        reject(err);
-      }
-    });
-  });
+    ]);
+    const output2 = parseProbeJson(stdout);
+    const videoStream = output2.streams.find((s) => s.codec_type === "video");
+    if (!videoStream) throw new Error("[FFmpeg] No video stream found");
+    const rFps = parseFrameRate(videoStream.r_frame_rate);
+    const avgFps = parseFrameRate(videoStream.avg_frame_rate);
+    const fps = avgFps || rFps;
+    const isVFR = rFps > 0 && avgFps > 0 && Math.abs(rFps - avgFps) / Math.max(rFps, avgFps) > 0.1;
+    return {
+      durationSeconds: output2.format.duration ? parseFloat(output2.format.duration) : 0,
+      width: videoStream.width || 0,
+      height: videoStream.height || 0,
+      fps,
+      videoCodec: videoStream.codec_name || "unknown",
+      hasAudio: output2.streams.some((s) => s.codec_type === "audio"),
+      isVFR
+    };
+  })();
   videoMetadataCache.set(filePath, probePromise);
   probePromise.catch(() => {
     if (videoMetadataCache.get(filePath) === probePromise) {
@@ -101191,11 +101335,9 @@ async function extractVideoMetadata(filePath) {
 }
 async function extractAudioMetadata(filePath) {
   const cached = audioMetadataCache.get(filePath);
-  if (cached) {
-    return cached;
-  }
-  const probePromise = new Promise((resolve12, reject) => {
-    const args = [
+  if (cached) return cached;
+  const probePromise = (async () => {
+    const stdout = await runFfprobe([
       "-v",
       "quiet",
       "-print_format",
@@ -101203,53 +101345,19 @@ async function extractAudioMetadata(filePath) {
       "-show_format",
       "-show_streams",
       filePath
-    ];
-    const ffprobe = spawn7("ffprobe", args);
-    let stdout = "";
-    let stderr = "";
-    ffprobe.stdout.on("data", (data) => {
-      stdout += data.toString();
-    });
-    ffprobe.stderr.on("data", (data) => {
-      stderr += data.toString();
-    });
-    ffprobe.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
-        return;
-      }
-      try {
-        const output2 = JSON.parse(stdout);
-        const audioStream = output2.streams.find((s) => s.codec_type === "audio");
-        if (!audioStream) {
-          reject(new Error("[FFmpeg] No audio stream found"));
-          return;
-        }
-        const durationSeconds = output2.format.duration ? parseFloat(output2.format.duration) : 0;
-        const metadata = {
-          durationSeconds,
-          sampleRate: audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100,
-          channels: audioStream.channels || 2,
-          audioCodec: audioStream.codec_name || "unknown",
-          bitrate: output2.format.bit_rate ? parseInt(output2.format.bit_rate) : void 0
-        };
-        resolve12(metadata);
-      } catch (parseError) {
-        reject(
-          new Error(
-            `[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`
-          )
-        );
-      }
-    });
-    ffprobe.on("error", (err) => {
-      if (err.code === "ENOENT") {
-        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
-      } else {
-        reject(err);
-      }
-    });
-  });
+    ]);
+    const output2 = parseProbeJson(stdout);
+    const audioStream = output2.streams.find((s) => s.codec_type === "audio");
+    if (!audioStream) throw new Error("[FFmpeg] No audio stream found");
+    const durationSeconds = output2.format.duration ? parseFloat(output2.format.duration) : 0;
+    return {
+      durationSeconds,
+      sampleRate: audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100,
+      channels: audioStream.channels || 2,
+      audioCodec: audioStream.codec_name || "unknown",
+      bitrate: output2.format.bit_rate ? parseInt(output2.format.bit_rate) : void 0
+    };
+  })();
   audioMetadataCache.set(filePath, probePromise);
   probePromise.catch(() => {
     if (audioMetadataCache.get(filePath) === probePromise) {
@@ -101258,6 +101366,57 @@ async function extractAudioMetadata(filePath) {
   });
   return probePromise;
 }
+var keyframeCache = /* @__PURE__ */ new Map();
+async function analyzeKeyframeIntervals(filePath) {
+  const cached = keyframeCache.get(filePath);
+  if (cached) return cached;
+  const promise = analyzeKeyframeIntervalsUncached(filePath);
+  keyframeCache.set(filePath, promise);
+  promise.catch(() => {
+    if (keyframeCache.get(filePath) === promise) {
+      keyframeCache.delete(filePath);
+    }
+  });
+  return promise;
+}
+async function analyzeKeyframeIntervalsUncached(filePath) {
+  const stdout = await runFfprobe([
+    "-v",
+    "quiet",
+    "-select_streams",
+    "v:0",
+    "-skip_frame",
+    "nokey",
+    "-show_entries",
+    "frame=pts_time",
+    "-of",
+    "csv=p=0",
+    filePath
+  ]);
+  const timestamps = stdout.split("\n").map((line) => parseFloat(line.trim())).filter((t) => Number.isFinite(t));
+  if (timestamps.length < 2) {
+    return {
+      avgIntervalSeconds: 0,
+      maxIntervalSeconds: 0,
+      keyframeCount: timestamps.length,
+      isProblematic: false
+    };
+  }
+  let maxInterval = 0;
+  let totalInterval = 0;
+  for (let i = 1; i < timestamps.length; i++) {
+    const interval = (timestamps[i] ?? 0) - (timestamps[i - 1] ?? 0);
+    totalInterval += interval;
+    if (interval > maxInterval) maxInterval = interval;
+  }
+  const avgInterval = totalInterval / (timestamps.length - 1);
+  return {
+    avgIntervalSeconds: Math.round(avgInterval * 100) / 100,
+    maxIntervalSeconds: Math.round(maxInterval * 100) / 100,
+    keyframeCount: timestamps.length,
+    isProblematic: maxInterval > 2
+  };
+}
 
 // ../engine/src/utils/urlDownloader.ts
 import { createWriteStream as createWriteStream2, existsSync as existsSync7, mkdirSync as mkdirSync4 } from "fs";
@@ -101329,20 +101488,38 @@ function isHttpUrl(path12) {
 function parseVideoElements(html) {
   const videos = [];
   const { document: document2 } = parseHTML(html);
-  const videoEls = document2.querySelectorAll("video[id][src]");
+  const videoEls = Array.from(
+    /* @__PURE__ */ new Set([
+      ...Array.from(document2.querySelectorAll("video[id][src]")),
+      ...Array.from(document2.querySelectorAll("video[src][data-start]"))
+    ])
+  );
+  videoEls.forEach((el, i) => {
+    if (!el.id) el.id = `hf-video-${i}`;
+  });
   for (const el of videoEls) {
     const id = el.getAttribute("id");
     const src = el.getAttribute("src");
     if (!id || !src) continue;
     const startAttr = el.getAttribute("data-start");
     const endAttr = el.getAttribute("data-end");
+    const durationAttr = el.getAttribute("data-duration");
     const mediaStartAttr = el.getAttribute("data-media-start");
     const hasAudioAttr = el.getAttribute("data-has-audio");
+    const start = startAttr ? parseFloat(startAttr) : 0;
+    let end = 0;
+    if (endAttr) {
+      end = parseFloat(endAttr);
+    } else if (durationAttr) {
+      end = start + parseFloat(durationAttr);
+    } else {
+      end = Infinity;
+    }
     videos.push({
       id,
       src,
-      start: startAttr ? parseFloat(startAttr) : 0,
-      end: endAttr ? parseFloat(endAttr) : 0,
+      start,
+      end,
       mediaStart: mediaStartAttr ? parseFloat(mediaStartAttr) : 0,
       hasAudio: hasAudioAttr === "true"
     });
@@ -101452,7 +101629,7 @@ async function extractAllVideoFrames(videos, baseDir, options, signal, config2)
           return { error: { videoId: video.id, error: `Video file not found: ${videoPath}` } };
         }
         let videoDuration = video.end - video.start;
-        if (videoDuration <= 0) {
+        if (!Number.isFinite(videoDuration) || videoDuration <= 0) {
           const metadata = await extractVideoMetadata(videoPath);
           const sourceDuration = metadata.durationSeconds - video.mediaStart;
           videoDuration = sourceDuration > 0 ? sourceDuration : metadata.durationSeconds;
@@ -102962,7 +103139,7 @@ var Context = class {
    * @param layout - The layout to set.
    * @returns The layout function.
    */
-  setLayout = (layout) => this.#layout = layout;
+  setLayout = (layout2) => this.#layout = layout2;
   /**
    * Gets the current layout for the response.
    *
@@ -105446,6 +105623,7 @@ async function compileHtmlFile(html, baseDir, downloadDir) {
   if (clampList.length > 0) {
     compiledHtml = clampDurations(compiledHtml, clampList);
   }
+  compiledHtml = compiledHtml.replace(/(<video\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
 async function parseSubCompositions(html, projectDir, downloadDir, parentOffset = 0, parentEnd = Infinity, visited = /* @__PURE__ */ new Set()) {
@@ -105798,13 +105976,51 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
   } = await parseSubCompositions(compiledHtml, projectDir, downloadDir);
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions(fullHtml, subCompositions, projectDir);
+  const sanitizedHtml = inlinedHtml.replace(
+    /(<(?:video|audio)\b[^>]*?)\s+preload\s*=\s*["']none["']/gi,
+    "$1"
+  );
   const html = injectDeterministicFontFaces(
-    coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(inlinedHtml))
+    coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml))
   );
   const mainVideos = parseVideoElements(html);
   const mainAudios = parseAudioElements(html);
   const videos = dedupeElementsById([...subVideos, ...mainVideos]);
   const audios = dedupeElementsById([...subAudios, ...mainAudios]);
+  for (const video of videos) {
+    if (isHttpUrl(video.src)) continue;
+    const videoPath = resolve7(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) {
+        console.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) {
+        console.warn(
+          `[Compiler] WARNING: Video "${video.id}" is variable frame rate (VFR). Screen recordings and phone videos are often VFR, which causes stuttering and frame skipping in renders. Re-encode with: ${reencode}`
+        );
+      }
+    }).catch(() => {
+    });
+  }
+  const autoIdVideos = videos.filter((v) => v.id.startsWith("hf-video-"));
+  let htmlWithIds = html;
+  if (autoIdVideos.length > 0) {
+    const { document: idDoc } = parseHTML(html);
+    let changed = false;
+    for (const v of autoIdVideos) {
+      const el = idDoc.querySelector(`video[src="${v.src}"]:not([id])`);
+      if (el) {
+        el.id = v.id;
+        changed = true;
+      }
+    }
+    if (changed) {
+      htmlWithIds = idDoc.documentElement?.outerHTML ?? html;
+    }
+  }
   const { document: document2 } = parseHTML(html);
   const rootEl = document2.querySelector("[data-composition-id]");
   const width = rootEl ? parseInt(rootEl.getAttribute("data-width") || "1080", 10) : 1080;
@@ -105813,7 +106029,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     rootEl.getAttribute("data-duration") || rootEl.getAttribute("data-composition-duration") || "0"
   ) : 0;
   return {
-    html,
+    html: htmlWithIds,
     subCompositions,
     videos,
     audios,
@@ -106719,6 +106935,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     }
     const errorMessage = error instanceof Error ? error.message : String(error);
     const errorStack = error instanceof Error ? error.stack : void 0;
+    const isTimeoutError = errorMessage.includes("Waiting failed") || errorMessage.includes("timeout exceeded") || errorMessage.includes("Navigation timeout");
+    const wasParallel = job.config.workers !== 1;
+    if (isTimeoutError && wasParallel) {
+      log.warn(
+        `Parallel capture timed out with ${job.config.workers ?? "auto"} workers. Video-heavy compositions often need sequential capture. Retry with --workers 1`
+      );
+    }
     job.error = errorMessage;
     updateJobStatus(job, "failed", `Failed: ${errorMessage}`, job.progress, onProgress);
     const elapsed = Date.now() - pipelineStart;