@hyperframes/engine 0.5.0-alpha.8 → 0.5.0

package/src/services/browserManager.ts

@@ -234,16 +234,48 @@ export async function releaseBrowser(
   await browser.close().catch(() => {});
 }
 
+export function forceReleaseBrowser(browser: Browser): void {
+  if (pooledBrowser && pooledBrowser === browser) {
+    pooledBrowserRefCount = 0;
+    pooledBrowser = null;
+  }
+  const proc = (
+    browser as unknown as {
+      process?: () => { kill: (signal?: NodeJS.Signals) => boolean; killed?: boolean } | null;
+    }
+  ).process?.();
+  if (proc && !proc.killed) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+  try {
+    browser.disconnect();
+  } catch {
+    // Best-effort cleanup.
+  }
+}
+
 export interface BuildChromeArgsOptions {
   width: number;
   height: number;
   captureMode?: CaptureMode;
+  platform?: NodeJS.Platform;
 }
 
+const CANVAS_DRAW_ELEMENT_FEATURE_FLAG = "--enable-features=CanvasDrawElement";
+
 export function buildChromeArgs(
   options: BuildChromeArgsOptions,
-  config?: Partial<Pick<EngineConfig, "disableGpu" | "chromePath">>,
+  config?: Partial<Pick<EngineConfig, "browserGpuMode" | "disableGpu" | "chromePath">>,
 ): string[] {
+  const platform = options.platform ?? process.platform;
+  const gpuDisabled = config?.disableGpu ?? DEFAULT_CONFIG.disableGpu;
+  const browserGpuMode = gpuDisabled
+    ? "software"
+    : (config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode);
   // Chrome flags tuned for headless rendering performance. The set below is a
   // fairly standard "headless-for-capture" configuration — similar profiles
   // appear in Puppeteer's defaults, Playwright, Remotion, and Chrome's own
@@ -252,10 +284,10 @@ export function buildChromeArgs(
     "--no-sandbox",
     "--disable-setuid-sandbox",
     "--disable-dev-shm-usage",
+    CANVAS_DRAW_ELEMENT_FEATURE_FLAG,
     "--enable-webgl",
     "--ignore-gpu-blocklist",
-    "--use-gl=angle",
-    "--use-angle=swiftshader",
+    ...getBrowserGpuArgs(browserGpuMode, platform),
     "--font-render-hinting=none",
     "--force-color-profile=srgb",
     `--window-size=${options.width},${options.height}`,
@@ -301,9 +333,28 @@ export function buildChromeArgs(
     );
   }
 
-  const gpuDisabled = config?.disableGpu ?? DEFAULT_CONFIG.disableGpu;
   if (gpuDisabled) {
     chromeArgs.push("--disable-gpu");
   }
   return chromeArgs;
 }
+
+function getBrowserGpuArgs(
+  mode: EngineConfig["browserGpuMode"],
+  platform: NodeJS.Platform,
+): string[] {
+  if (mode === "software") {
+    return ["--use-gl=angle", "--use-angle=swiftshader"];
+  }
+
+  switch (platform) {
+    case "darwin":
+      return ["--use-gl=angle", "--use-angle=metal", "--enable-gpu-rasterization"];
+    case "win32":
+      return ["--use-gl=angle", "--use-angle=d3d11", "--enable-gpu-rasterization"];
+    case "linux":
+      return ["--use-gl=egl", "--enable-gpu-rasterization"];
+    default:
+      return ["--enable-gpu-rasterization"];
+  }
+}

package/src/services/chunkEncoder.ts

@@ -139,12 +139,43 @@ export function buildEncoderArgs(
           else args.push("-global_quality", String(quality));
           break;
       }
+
+      // Same B-frame story as the SW branch below — nvenc emits B-frames
+      // by default (qsv via b_strategy, vaapi too), and the negative-DTS
+      // freeze hits the same downstream players. The unconditional
+      // `-avoid_negative_ts make_zero` near the bottom of this function
+      // covers the mux level, but we belt-and-suspenders the encoder too
+      // so even tools that consume the chunk file directly (without going
+      // through our mux step) play correctly. videotoolbox doesn't accept
+      // `-bf` so it's skipped — videotoolbox h264 also doesn't emit
+      // negative DTS in practice on macOS Sonoma+.
+      if (
+        codec === "h264" &&
+        (gpuEncoder === "nvenc" || gpuEncoder === "qsv" || gpuEncoder === "vaapi")
+      ) {
+        args.push("-bf", "0");
+        if (gpuEncoder === "qsv") {
+          args.push("-b_strategy", "0");
+        }
+      }
     } else {
       const encoderName = codec === "h264" ? "libx264" : "libx265";
       args.push("-c:v", encoderName, "-preset", preset);
       if (bitrate) args.push("-b:v", bitrate);
       else args.push("-crf", String(quality));
 
+      // Disable B-frames. Standard h264 with B-frames produces negative DTS
+      // at the start of the stream (the first B-frame's decode order is
+      // "before" the first I-frame's presentation time). VS Code's video
+      // preview, several browser <video> pipelines, and some HW decoders
+      // freeze on the first frame when DTS is negative, so audio plays alone.
+      // -bf 0 makes PTS == DTS at every frame, eliminating the issue at the
+      // source. Quality cost is ~5–10% larger files at the same CRF — a
+      // worthwhile trade for "the file plays everywhere".
+      if (codec === "h264") {
+        args.push("-bf", "0");
+      }
+
       // Encoder-specific params: anti-banding + color space tagging.
       // aq-mode=3 redistributes bits to dark flat areas (gradients).
       // For HDR x265 paths we additionally embed BT.2020 + transfer + HDR static
@@ -239,6 +270,8 @@ export function buildEncoderArgs(
     args.push("-pix_fmt", pixelFormat);
   }
 
+  args.push("-avoid_negative_ts", "make_zero");
+
   args.push("-y", outputPath);
   return args;
 }
@@ -510,6 +543,9 @@ export async function muxVideoWithAudio(
   } else {
     args.push("-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart");
   }
+  // PTS bases can diverge during mux and reintroduce negative DTS. See
+  // buildEncoderArgs for the full reasoning on why that breaks playback.
+  args.push("-avoid_negative_ts", "make_zero");
   args.push("-shortest", "-y", outputPath);
 
   const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;

package/src/services/fileServer.ts

@@ -10,6 +10,7 @@ import { Hono } from "hono";
 import { serve } from "@hono/node-server";
 import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, extname } from "node:path";
+import { injectScriptsIntoHtml } from "@hyperframes/core/compiler";
 
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
@@ -34,74 +35,6 @@ const MIME_TYPES: Record<string, string> = {
   ".otf": "font/otf",
 };
 
-function stripEmbeddedRuntimeScripts(html: string): string {
-  if (!html) return html;
-  const scriptRe = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
-  const runtimeSrcMarkers = [
-    "hyperframe.runtime.iife.js",
-    "hyperframes-runtime.modular.inline.js",
-    "data-hyperframes-preview-runtime",
-  ];
-  const runtimeInlineMarkers = [
-    "__hyperframeRuntimeBootstrapped",
-    "__hyperframeRuntime",
-    "__hyperframeRuntimeTeardown",
-    "window.__player =",
-    "window.__playerReady",
-    "window.__renderReady",
-  ];
-
-  const shouldStrip = (block: string): boolean => {
-    const lowered = block.toLowerCase();
-    for (const marker of runtimeSrcMarkers) {
-      if (lowered.includes(marker.toLowerCase())) {
-        return true;
-      }
-    }
-    for (const marker of runtimeInlineMarkers) {
-      if (block.includes(marker)) {
-        return true;
-      }
-    }
-    return false;
-  };
-
-  return html.replace(scriptRe, (block) => (shouldStrip(block) ? "" : block));
-}
-
-function injectScriptsIntoHtml(
-  html: string,
-  headScripts: string[],
-  bodyScripts: string[],
-  stripEmbedded: boolean,
-): string {
-  if (stripEmbedded) {
-    html = stripEmbeddedRuntimeScripts(html);
-  }
-
-  if (headScripts.length > 0) {
-    const headTags = headScripts.map((src) => `<script>${src}</script>`).join("\n");
-    if (html.includes("</head>")) {
-      html = html.replace("</head>", () => `${headTags}\n</head>`);
-    } else if (html.includes("<body")) {
-      html = html.replace("<body", () => `${headTags}\n<body`);
-    } else {
-      html = headTags + "\n" + html;
-    }
-  }
-
-  if (bodyScripts.length > 0) {
-    const bodyTags = bodyScripts.map((src) => `<script>${src}</script>`).join("\n");
-    if (html.includes("</body>")) {
-      html = html.replace("</body>", () => `${bodyTags}\n</body>`);
-    } else {
-      html = html + "\n" + bodyTags;
-    }
-  }
-
-  return html;
-}
-
 export interface FileServerOptions {
   projectDir: string;
   compiledDir?: string;

package/src/services/frameCapture.ts

@@ -16,6 +16,7 @@ import { quantizeTimeToFrame } from "@hyperframes/core";
 import {
   acquireBrowser,
   releaseBrowser,
+  forceReleaseBrowser,
   buildChromeArgs,
   resolveHeadlessShellPath,
   type CaptureMode,
@@ -29,6 +30,7 @@ import {
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 import type {
   CaptureOptions,
+  CaptureVideoMetadataHint,
   CaptureResult,
   CaptureBufferResult,
   CapturePerfSummary,
@@ -73,6 +75,26 @@ export interface CaptureSession {
 // Circular buffer for browser console messages dumped on render failure diagnostics.
 // Complex compositions produce 100+ messages; 50 was too small to capture relevant errors.
 const BROWSER_CONSOLE_BUFFER_SIZE = 200;
+const CAPTURE_SESSION_CLOSE_TIMEOUT_MS = 5_000;
+
+async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boolean> {
+  let timedOut = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([
+    promise.then(
+      () => undefined,
+      () => undefined,
+    ),
+    new Promise<void>((resolve) => {
+      timer = setTimeout(() => {
+        timedOut = true;
+        resolve();
+      }, CAPTURE_SESSION_CLOSE_TIMEOUT_MS);
+    }),
+  ]);
+  if (timer) clearTimeout(timer);
+  return !timedOut;
+}
 
 export async function createCaptureSession(
   serverUrl: string,
@@ -133,6 +155,22 @@ export async function createCaptureSession(
       w.__name = <T>(fn: T, _name: string): T => fn;
     }
   });
+  // Inject render-time variable overrides before any page script runs, so the
+  // runtime helper `getVariables()` returns the merged result on its first
+  // call. Pass the JSON string and parse inside the page so we don't require
+  // any JSON-incompatible value to round-trip through Puppeteer's serializer.
+  if (options.variables && Object.keys(options.variables).length > 0) {
+    const variablesJson = JSON.stringify(options.variables);
+    await page.evaluateOnNewDocument((json: string) => {
+      type WindowWithVariables = Window & { __hfVariables?: Record<string, unknown> };
+      try {
+        (window as WindowWithVariables).__hfVariables = JSON.parse(json);
+      } catch {
+        // The CLI validated the JSON before this point — a parse failure here
+        // means the page swapped JSON.parse, which is the page's problem.
+      }
+    }, variablesJson);
+  }
   const browserVersion = await browser.version();
   const expectedMajor = config?.expectedChromiumMajor;
   if (Number.isFinite(expectedMajor)) {
@@ -221,6 +259,64 @@ async function pollPageExpression(
   return Boolean(await page.evaluate(expression));
 }
 
+async function applyVideoMetadataHints(
+  page: Page,
+  hints: readonly CaptureVideoMetadataHint[] | undefined,
+): Promise<void> {
+  if (!hints || hints.length === 0) return;
+
+  await page.evaluate(
+    (metadataHints: CaptureVideoMetadataHint[]) => {
+      for (const hint of metadataHints) {
+        if (
+          !hint.id ||
+          !Number.isFinite(hint.width) ||
+          !Number.isFinite(hint.height) ||
+          hint.width <= 0 ||
+          hint.height <= 0
+        ) {
+          continue;
+        }
+
+        const video = document.getElementById(hint.id) as HTMLVideoElement | null;
+        if (!video) continue;
+
+        if (!video.hasAttribute("width")) video.setAttribute("width", String(hint.width));
+        if (!video.hasAttribute("height")) video.setAttribute("height", String(hint.height));
+
+        const computed = window.getComputedStyle(video);
+        if (
+          !video.style.aspectRatio &&
+          (!computed.aspectRatio || computed.aspectRatio === "auto")
+        ) {
+          video.style.aspectRatio = `${hint.width} / ${hint.height}`;
+        }
+      }
+    },
+    [...hints],
+  );
+}
+
+async function waitForOptionalTailwindReady(page: Page, timeoutMs: number): Promise<void> {
+  const hasTailwindReady = await page.evaluate(
+    `(() => { const ready = window.__tailwindReady; return !!ready && typeof ready.then === "function"; })()`,
+  );
+  if (!hasTailwindReady) return;
+
+  const ready = await Promise.race([
+    page.evaluate(
+      `Promise.resolve(window.__tailwindReady).then(() => true, () => false)`,
+    ) as Promise<boolean>,
+    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), timeoutMs)),
+  ]);
+
+  if (!ready) {
+    throw new Error(
+      `[FrameCapture] window.__tailwindReady not resolved after ${timeoutMs}ms. Tailwind browser runtime must finish before frame capture starts.`,
+    );
+  }
+}
+
 export async function initializeSession(session: CaptureSession): Promise<void> {
   const { page, serverUrl } = session;
 
@@ -290,24 +386,34 @@ export async function initializeSession(session: CaptureSession): Promise<void>
       );
     }
 
-    // Wait for all video elements to have loaded metadata (dimensions + duration)
-    // Without this, frame 0 captures videos at their 300x150 default size.
+    await applyVideoMetadataHints(page, session.options.videoMetadataHints);
+
+    // Wait for all video elements to have decoded their CURRENT frame, not
+    // just metadata. readyState >= 2 (HAVE_CURRENT_DATA) means a frame is
+    // actually rasterized and ready to paint — at >= 1 (HAVE_METADATA) we
+    // only know the dimensions, and the first <video> screenshot can come
+    // back as a black/blank rectangle. This bites compositions with two
+    // <video> elements of different codecs (h264 mp4 + VP9 webm) where the
+    // faster decoder lets the readiness check pass while the slower one
+    // hasn't painted, producing a black "first frame" for the slower clip.
     // skipReadinessVideoIds excludes natively-extracted videos (e.g. HDR HEVC
-    // sources) whose frames come from ffmpeg out-of-band — Chromium may not be
-    // able to decode them at all (e.g. HEVC on Linux headless-shell).
+    // sources) whose frames come from ffmpeg out-of-band. videoMetadataHints
+    // supply intrinsic dimensions for skipped videos whose layout depends on
+    // aspect ratio, while Chromium may still fail to decode/load metadata.
     const skipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
     const videosReady = await pollPageExpression(
       page,
-      `(() => { const skip = new Set(${skipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
+      `(() => { const skip = new Set(${skipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 2); })()`,
       pageReadyTimeout,
     );
     if (!videosReady) {
       throw new Error(
-        `[FrameCapture] video metadata not ready after ${pageReadyTimeout}ms. Video elements must load metadata before capture starts.`,
+        `[FrameCapture] video first frame not decoded after ${pageReadyTimeout}ms. Video elements must reach readyState >= 2 (HAVE_CURRENT_DATA) before capture starts.`,
       );
     }
 
     await page.evaluate(`document.fonts?.ready`);
+    await waitForOptionalTailwindReady(page, pageReadyTimeout);
 
     // For PNG captures, force the page background fully transparent so the
     // captured screenshots carry a real alpha channel. Must run AFTER
@@ -382,15 +488,15 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     );
   }
 
-  // Wait for all video elements to have loaded metadata (dimensions + duration).
-  // Without this, frame 0 captures videos at their 300x150 default size.
-  // See screenshot-mode comment above for why skipReadinessVideoIds exists.
+  await applyVideoMetadataHints(page, session.options.videoMetadataHints);
+
+  // Same readyState contract as the screenshot path above (>= 2 / HAVE_CURRENT_DATA).
   const beginframeSkipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
   const videoDeadline =
     Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout);
   while (Date.now() < videoDeadline) {
     const videosReady = await page.evaluate(
-      `(() => { const skip = new Set(${beginframeSkipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
+      `(() => { const skip = new Set(${beginframeSkipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 2); })()`,
     );
     if (videosReady) break;
     await new Promise((r) => setTimeout(r, 100));
@@ -398,6 +504,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   // Font check (no rAF dependency — uses fonts.ready API directly)
   await page.evaluate(`document.fonts?.ready`);
+  await waitForOptionalTailwindReady(page, pageReadyTimeout);
 
   // Stop warmup
   warmupRunning = false;
@@ -607,11 +714,22 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void
   // but browserReleased=false → second call no-ops on page and retries browser.
   // This matches the orchestrator's intent for HDR cleanup.
   if (!session.pageReleased && session.page) {
-    await session.page.close().catch(() => {});
+    const pageClosed = await waitForCloseWithTimeout(session.page.close());
+    if (!pageClosed) {
+      console.warn("[FrameCapture] Timed out closing page; forcing browser process shutdown");
+      forceReleaseBrowser(session.browser);
+      session.browserReleased = true;
+    }
     session.pageReleased = true;
   }
   if (!session.browserReleased && session.browser) {
-    await releaseBrowser(session.browser, session.config);
+    const browserClosed = await waitForCloseWithTimeout(
+      releaseBrowser(session.browser, session.config),
+    );
+    if (!browserClosed) {
+      console.warn("[FrameCapture] Timed out closing browser; forcing browser process shutdown");
+      forceReleaseBrowser(session.browser);
+    }
     session.browserReleased = true;
   }
   session.isInitialized = false;

package/src/services/screenshotService.ts

@@ -446,13 +446,15 @@ export async function injectVideoFramesBatch(
           }
         }
         img.decoding = "sync";
-        img.src = item.dataUri;
-        pendingDecodes.push(
-          img
-            .decode()
-            .catch(() => undefined)
-            .then(() => undefined),
-        );
+        if (img.getAttribute("src") !== item.dataUri) {
+          img.src = item.dataUri;
+          pendingDecodes.push(
+            img
+              .decode()
+              .catch(() => undefined)
+              .then(() => undefined),
+          );
+        }
         img.style.opacity = String(computedOpacity);
         img.style.visibility = "visible";
         // Hide the native <video> with visibility only — never clobber inline

package/src/services/streamingEncoder.ts

@@ -221,12 +221,33 @@ export function buildStreamingArgs(
           else args.push("-global_quality", String(quality));
           break;
       }
+
+      // Mirror SW branch: GPU h264 paths emit B-frames by default (nvenc, qsv,
+      // vaapi) and produce the same negative-DTS freeze for downstream players.
+      // See chunkEncoder.buildEncoderArgs for the full explanation.
+      if (
+        codec === "h264" &&
+        (gpuEncoder === "nvenc" || gpuEncoder === "qsv" || gpuEncoder === "vaapi")
+      ) {
+        args.push("-bf", "0");
+        if (gpuEncoder === "qsv") {
+          args.push("-b_strategy", "0");
+        }
+      }
     } else {
       const encoderName = codec === "h264" ? "libx264" : "libx265";
       args.push("-c:v", encoderName, "-preset", preset);
       if (bitrate) args.push("-b:v", bitrate);
       else args.push("-crf", String(quality));
 
+      // Mirrors chunkEncoder: disable B-frames for h264 so PTS == DTS, no
+      // negative DTS at stream start. Without this, files freeze on the
+      // first frame in VS Code preview, several browsers, and some HW
+      // decoders. See chunkEncoder.buildEncoderArgs for the full reasoning.
+      if (codec === "h264") {
+        args.push("-bf", "0");
+      }
+
       // Encoder-specific params: anti-banding + color space tagging.
       // For HDR, getHdrEncoderColorParams also emits the SMPTE ST 2086
       // mastering-display and CTA-861.3 MaxCLL/MaxFALL SEI messages —
@@ -313,6 +334,10 @@ export function buildStreamingArgs(
     args.push("-pix_fmt", pixelFormat);
   }
 
+  // Belt-and-suspenders against negative DTS at stream start. See chunkEncoder
+  // for the full explanation; same playback compatibility class.
+  args.push("-avoid_negative_ts", "make_zero");
+
   args.push("-y", outputPath);
   return args;
 }

package/src/services/videoFrameExtractor.test.ts

@@ -1,5 +1,13 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -9,6 +17,9 @@ import {
   parseImageElements,
   extractAllVideoFrames,
   createFrameLookupTable,
+  resolveProjectRelativeSrc,
+  codecMayHaveAlpha,
+  decoderForCodec,
   type VideoElement,
   type ExtractedFrames,
 } from "./videoFrameExtractor.js";
@@ -23,6 +34,111 @@ import { runFfmpeg } from "../utils/runFfmpeg.js";
 // synthesized VFR fixture.
 const HAS_FFMPEG = spawnSync("ffmpeg", ["-version"]).status === 0;
 
+// Codec-based alpha defaulting replaces tag-based detection (the
+// alpha_mode/ALPHA_MODE case bug — see ffprobe.test.ts for the regression
+// pin on that). The extractor uses these helpers for two decisions:
+//   1. whether to force the alpha-aware decoder (libvpx-vp9 for VP9, libvpx
+//      for VP8)
+//   2. whether to default the cached frame format to PNG (with alpha) vs JPG
+// The "default to capable" trade is small file-size growth on opaque VP9
+// content for correctness on alpha-having content even when the sidecar tag
+// is missing or muxed with the wrong case.
+describe("codec alpha capability", () => {
+  it("flags VP9, VP8, and ProRes as alpha-capable", () => {
+    expect(codecMayHaveAlpha("vp9")).toBe(true);
+    expect(codecMayHaveAlpha("VP9")).toBe(true);
+    expect(codecMayHaveAlpha("vp8")).toBe(true);
+    expect(codecMayHaveAlpha("prores")).toBe(true);
+  });
+
+  it("does not flag h264 / h265 / mpeg4 (no alpha in their bitstreams)", () => {
+    expect(codecMayHaveAlpha("h264")).toBe(false);
+    expect(codecMayHaveAlpha("h265")).toBe(false);
+    expect(codecMayHaveAlpha("hevc")).toBe(false);
+    expect(codecMayHaveAlpha("mpeg4")).toBe(false);
+  });
+
+  it("treats undefined / empty input as non-alpha", () => {
+    expect(codecMayHaveAlpha(undefined)).toBe(false);
+    expect(codecMayHaveAlpha("")).toBe(false);
+  });
+
+  it("returns the alpha-aware decoder name for VP9 and VP8", () => {
+    expect(decoderForCodec("vp9")).toBe("libvpx-vp9");
+    expect(decoderForCodec("VP9")).toBe("libvpx-vp9");
+    expect(decoderForCodec("vp8")).toBe("libvpx");
+  });
+});
+
+// Regression: a long-standing footgun where `<video src="../assets/foo">`
+// inside a sub-composition silently dropped the video from extraction. The
+// browser's URL resolver clamps `..` at the served origin's root (so the
+// page renders fine in the studio), but `path.join(projectDir, "../assets/foo")`
+// normalizes to <parentOfProjectDir>/assets/foo, which doesn't exist —
+// extraction skipped, no frame injection, rendered output shows the video's
+// first decoded frame for the whole clip duration. The resolver now mirrors
+// browser semantics by clamping any traversal that escapes the project root.
+describe("resolveProjectRelativeSrc — sub-composition path clamping", () => {
+  let tmp: string;
+
+  beforeAll(() => {
+    tmp = mkdtempSync(join(tmpdir(), "hf-resolver-"));
+    mkdirSync(join(tmp, "project", "assets"), { recursive: true });
+    writeFileSync(join(tmp, "project", "assets", "foo.mp4"), "");
+  });
+  afterAll(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns the literal join when the file exists at projectDir/src", () => {
+    const projectDir = join(tmp, "project");
+    expect(resolveProjectRelativeSrc("assets/foo.mp4", projectDir)).toBe(
+      join(projectDir, "assets/foo.mp4"),
+    );
+  });
+
+  it("clamps a leading `../` so `../assets/foo.mp4` resolves to assets/foo.mp4", () => {
+    const projectDir = join(tmp, "project");
+    expect(resolveProjectRelativeSrc("../assets/foo.mp4", projectDir)).toBe(
+      join(projectDir, "assets/foo.mp4"),
+    );
+  });
+
+  it("clamps multiple leading `../../../` segments", () => {
+    const projectDir = join(tmp, "project");
+    expect(resolveProjectRelativeSrc("../../../assets/foo.mp4", projectDir)).toBe(
+      join(projectDir, "assets/foo.mp4"),
+    );
+  });
+
+  it("clamps mid-path traversal that escapes baseDir (not just leading `..`)", () => {
+    // `assets/../../foo.mp4` collapses past projectDir via path.join — this
+    // case used to silently escape; the resolver now strips embedded `..`
+    // segments and re-anchors at the project root.
+    const projectDir = join(tmp, "project");
+    expect(resolveProjectRelativeSrc("assets/../../assets/foo.mp4", projectDir)).toBe(
+      join(projectDir, "assets/foo.mp4"),
+    );
+  });
+
+  it("returns the (non-existent) base-dir path on miss so callers get a stable error message", () => {
+    const projectDir = join(tmp, "project");
+    expect(resolveProjectRelativeSrc("../assets/missing.mp4", projectDir)).toBe(
+      join(projectDir, "../assets/missing.mp4"),
+    );
+  });
+
+  it("prefers compiled-dir over base-dir when the file exists in both", () => {
+    const projectDir = join(tmp, "project");
+    const compiledDir = join(tmp, "compiled");
+    mkdirSync(join(compiledDir, "assets"), { recursive: true });
+    writeFileSync(join(compiledDir, "assets", "foo.mp4"), "");
+    expect(resolveProjectRelativeSrc("assets/foo.mp4", projectDir, compiledDir)).toBe(
+      join(compiledDir, "assets/foo.mp4"),
+    );
+  });
+});
+
 describe("parseVideoElements", () => {
   it("parses videos without an id or data-start attribute", () => {
     const videos = parseVideoElements('<video src="clip.mp4"></video>');