@hyperframes/engine 0.6.0-alpha.1 → 0.6.0-alpha.10

package/src/services/browserManager.ts

@@ -136,6 +136,119 @@ async function probeBeginFrameSupport(browser: Browser): Promise<boolean> {
   }
 }
 
+/**
+ * Cached *in-flight or resolved* probe Promise for `resolveBrowserGpuMode("auto", ...)`.
+ *
+ * Caching the Promise (rather than the resolved value) deduplicates concurrent
+ * callers — the parallel coordinator runs N workers via `Promise.all`, so a
+ * `--workers 4` render against a no-GPU host would otherwise fire 4
+ * simultaneous probe Chromes. The first call assigns the Promise and every
+ * other concurrent caller awaits the same one, paying the ~240 ms probe cost
+ * exactly once per process lifetime.
+ *
+ * Exported for tests; production callers go through `resolveBrowserGpuMode`.
+ */
+export let _autoBrowserGpuModeCache: Promise<"software" | "hardware"> | undefined;
+
+/** Test-only: reset the cached probe result. */
+export function _resetAutoBrowserGpuModeCacheForTests(): void {
+  _autoBrowserGpuModeCache = undefined;
+}
+
+/**
+ * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
+ *
+ * For `"software"` / `"hardware"` this is a pure pass-through. For `"auto"`
+ * it launches a tiny Chrome with the platform's hardware GPU args, runs a
+ * one-shot WebGL availability probe, and falls back to `"software"` if
+ * hardware-mode WebGL is unavailable. The Promise is cached for the process
+ * lifetime, so concurrent callers (parallel workers) share the same probe.
+ *
+ * Any failure (Chrome launch error, navigation timeout, missing canvas API,
+ * etc.) is treated as a `"software"` fallback. The render path with
+ * SwiftShader always works, so a misclassification toward software is the
+ * safe failure mode; misclassifying toward hardware would error on the real
+ * render.
+ */
+export function resolveBrowserGpuMode(
+  mode: EngineConfig["browserGpuMode"],
+  options: {
+    chromePath?: string;
+    browserTimeout?: number;
+    platform?: NodeJS.Platform;
+  } = {},
+): Promise<"software" | "hardware"> {
+  if (mode !== "auto") return Promise.resolve(mode);
+  if (_autoBrowserGpuModeCache) return _autoBrowserGpuModeCache;
+
+  _autoBrowserGpuModeCache = (async () => {
+    const platform = options.platform ?? process.platform;
+    const browserTimeout = options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
+    const executablePath = options.chromePath ?? resolveHeadlessShellPath({});
+
+    const probeArgs = [
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+      "--disable-dev-shm-usage",
+      "--enable-webgl",
+      "--ignore-gpu-blocklist",
+      ...getBrowserGpuArgs("hardware", platform),
+    ];
+
+    const ppt = await getPuppeteer().catch(() => null);
+    if (!ppt) {
+      logResolvedBrowserGpuMode("software", "puppeteer unavailable");
+      return "software" as const;
+    }
+
+    let probeBrowser: Browser | undefined;
+    try {
+      probeBrowser = await ppt.launch({
+        headless: true,
+        args: probeArgs,
+        defaultViewport: { width: 64, height: 64 },
+        executablePath,
+        timeout: browserTimeout,
+      });
+      const page = await probeBrowser.newPage();
+      const hasWebGL = await page.evaluate(() => {
+        try {
+          const c = document.createElement("canvas");
+          const gl =
+            c.getContext("webgl") ||
+            (c.getContext("experimental-webgl") as RenderingContext | null);
+          return gl !== null;
+        } catch {
+          return false;
+        }
+      });
+      const resolved = hasWebGL ? ("hardware" as const) : ("software" as const);
+      logResolvedBrowserGpuMode(resolved, hasWebGL ? "WebGL probe succeeded" : "WebGL unavailable");
+      return resolved;
+    } catch (err) {
+      logResolvedBrowserGpuMode(
+        "software",
+        `probe failed (${err instanceof Error ? err.message : String(err)})`,
+      );
+      return "software" as const;
+    } finally {
+      await probeBrowser?.close().catch(() => {});
+    }
+  })();
+
+  return _autoBrowserGpuModeCache;
+}
+
+/**
+ * Single observability surface for the auto-detect outcome. Logged exactly
+ * once per process (the probe runs once); without this line, a regression
+ * to "always software even with a GPU present" would be invisible in
+ * production. Goes to stderr to stay out of stdout pipelines.
+ */
+function logResolvedBrowserGpuMode(resolved: "hardware" | "software", reason: string): void {
+  console.error(`[hyperframes] browserGpuMode auto → ${resolved} (${reason})`);
+}
+
 export async function acquireBrowser(
   chromeArgs: string[],
   config?: Partial<
@@ -265,6 +378,8 @@ export interface BuildChromeArgsOptions {
   platform?: NodeJS.Platform;
 }
 
+const CANVAS_DRAW_ELEMENT_FEATURE_FLAG = "--enable-features=CanvasDrawElement";
+
 export function buildChromeArgs(
   options: BuildChromeArgsOptions,
   config?: Partial<Pick<EngineConfig, "browserGpuMode" | "disableGpu" | "chromePath">>,
@@ -282,6 +397,7 @@ export function buildChromeArgs(
     "--no-sandbox",
     "--disable-setuid-sandbox",
     "--disable-dev-shm-usage",
+    CANVAS_DRAW_ELEMENT_FEATURE_FLAG,
     "--enable-webgl",
     "--ignore-gpu-blocklist",
     ...getBrowserGpuArgs(browserGpuMode, platform),
@@ -341,7 +457,20 @@ function getBrowserGpuArgs(
   platform: NodeJS.Platform,
 ): string[] {
   if (mode === "software") {
-    return ["--use-gl=angle", "--use-angle=swiftshader"];
+    // Chrome 120+ deprecated implicit SwiftShader fallback; the explicit
+    // path (--use-angle=swiftshader) keeps working but Chrome emits a
+    // deprecation warning unless --enable-unsafe-swiftshader is also set.
+    // Despite the name, this is exactly the behaviour Chrome had before;
+    // the flag exists to make CPU rasterisation an explicit opt-in rather
+    // than an implicit fallback for end users on the open web.
+    return ["--use-gl=angle", "--use-angle=swiftshader", "--enable-unsafe-swiftshader"];
+  }
+
+  if (mode === "auto") {
+    // Should not reach here — `resolveBrowserGpuMode` collapses "auto" to
+    // "software" or "hardware" before args are built. Be defensive: software
+    // is the always-safe fallback.
+    return ["--use-gl=angle", "--use-angle=swiftshader", "--enable-unsafe-swiftshader"];
   }
 
   switch (platform) {

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/frameCapture.ts

@@ -18,6 +18,7 @@ import {
   releaseBrowser,
   forceReleaseBrowser,
   buildChromeArgs,
+  resolveBrowserGpuMode,
   resolveHeadlessShellPath,
   type CaptureMode,
 } from "./browserManager.js";
@@ -113,11 +114,22 @@ export async function createCaptureSession(
   const headlessShell = resolveHeadlessShellPath(config);
   const isLinux = process.platform === "linux";
   const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
+  // BeginFrame's screenshot does not honor a viewport `deviceScaleFactor`
+  // (the captured surface is sized by the OS window in CSS pixels regardless
+  // of `Emulation.setDeviceMetricsOverride`'s DPR). When supersampling we
+  // need explicit clip+scale on `Page.captureScreenshot`, so fall back to
+  // the screenshot path for any DPR > 1.
+  const supersampling = (options.deviceScaleFactor ?? 1) > 1;
   const preMode: CaptureMode =
-    headlessShell && isLinux && !forceScreenshot ? "beginframe" : "screenshot";
+    headlessShell && isLinux && !forceScreenshot && !supersampling ? "beginframe" : "screenshot";
+  const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
+  const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
+    chromePath: headlessShell ?? undefined,
+    browserTimeout: config?.browserTimeout,
+  });
   const chromeArgs = buildChromeArgs(
     { width: options.width, height: options.height, captureMode: preMode },
-    config,
+    { ...config, browserGpuMode: resolvedGpuMode },
   );
 
   const { browser, captureMode } = await acquireBrowser(chromeArgs, config);
@@ -388,8 +400,14 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
     await applyVideoMetadataHints(page, session.options.videoMetadataHints);
 
-    // Wait for all video elements to have loaded metadata (dimensions + duration)
-    // Without this, frame 0 captures videos at their 300x150 default size.
+    // 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. videoMetadataHints
     // supply intrinsic dimensions for skipped videos whose layout depends on
@@ -397,12 +415,12 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     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.`,
       );
     }
 
@@ -484,16 +502,13 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   await applyVideoMetadataHints(page, session.options.videoMetadataHints);
 
-  // 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 and
-  // videoMetadataHints are paired.
+  // 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));

package/src/services/screenshotService.test.ts

@@ -0,0 +1,92 @@
+// @vitest-environment node
+import { describe, it, expect, vi } from "vitest";
+import { type Page } from "puppeteer-core";
+import { pageScreenshotCapture, cdpSessionCache } from "./screenshotService.js";
+
+// Stub a Page + CDPSession just enough that pageScreenshotCapture can call
+// `client.send("Page.captureScreenshot", ...)` and we can inspect the args.
+function makeFakePageWithCdp(send: (method: string, params: object) => Promise<{ data: string }>) {
+  const fakeSession = { send } as unknown as import("puppeteer-core").CDPSession;
+  // Stub a Page object — the WeakMap cache is the only Page-thing used in the
+  // path under test, so we can pre-seed it and skip page.createCDPSession().
+  const fakePage = {} as Page;
+  cdpSessionCache.set(fakePage, fakeSession);
+  return fakePage;
+}
+
+describe("pageScreenshotCapture supersample plumbing", () => {
+  // Minimal 1×1 transparent PNG, base64. The function returns Buffer.from(data, "base64")
+  // and we never inspect the bytes — only the params we pass to client.send.
+  const ONE_PIXEL_PNG_B64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII=";
+
+  it("omits `clip` when deviceScaleFactor is undefined (default 1)", async () => {
+    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
+    const page = makeFakePageWithCdp(send);
+
+    await pageScreenshotCapture(page, {
+      width: 1920,
+      height: 1080,
+      fps: 30,
+      format: "jpeg",
+      quality: 80,
+    });
+
+    expect(send).toHaveBeenCalledWith(
+      "Page.captureScreenshot",
+      expect.not.objectContaining({ clip: expect.anything() }),
+    );
+  });
+
+  it("omits `clip` when deviceScaleFactor is exactly 1", async () => {
+    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
+    const page = makeFakePageWithCdp(send);
+
+    await pageScreenshotCapture(page, {
+      width: 1920,
+      height: 1080,
+      fps: 30,
+      format: "jpeg",
+      deviceScaleFactor: 1,
+    });
+
+    const params = send.mock.calls[0]?.[1] as { clip?: unknown };
+    expect(params.clip).toBeUndefined();
+  });
+
+  it("passes `clip` with `scale = dpr` when deviceScaleFactor > 1 (the supersample contract)", async () => {
+    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
+    const page = makeFakePageWithCdp(send);
+
+    await pageScreenshotCapture(page, {
+      width: 1920,
+      height: 1080,
+      fps: 30,
+      format: "jpeg",
+      deviceScaleFactor: 2,
+    });
+
+    expect(send).toHaveBeenCalledWith(
+      "Page.captureScreenshot",
+      expect.objectContaining({
+        clip: { x: 0, y: 0, width: 1920, height: 1080, scale: 2 },
+      }),
+    );
+  });
+
+  it("propagates a non-2 supersample factor (e.g. 720p → 4K = 3×)", async () => {
+    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
+    const page = makeFakePageWithCdp(send);
+
+    await pageScreenshotCapture(page, {
+      width: 1280,
+      height: 720,
+      fps: 30,
+      format: "jpeg",
+      deviceScaleFactor: 3,
+    });
+
+    const params = send.mock.calls[0]?.[1] as { clip?: { scale: number } };
+    expect(params.clip?.scale).toBe(3);
+  });
+});

package/src/services/screenshotService.ts

@@ -129,12 +129,20 @@ export async function beginFrameCapture(
 export async function pageScreenshotCapture(page: Page, options: CaptureOptions): Promise<Buffer> {
   const client = await getCdpSession(page);
   const isPng = options.format === "png";
+  const dpr = options.deviceScaleFactor ?? 1;
+  // When supersampling, pass an explicit clip with `scale` so Chrome emits a
+  // screenshot at device-pixel dimensions (`width × height × dpr`). Without
+  // this, `Page.captureScreenshot` returns at CSS dimensions regardless of
+  // the viewport's deviceScaleFactor.
+  const clip =
+    dpr > 1 ? { x: 0, y: 0, width: options.width, height: options.height, scale: dpr } : undefined;
   const result = await client.send("Page.captureScreenshot", {
     format: isPng ? "png" : "jpeg",
     quality: isPng ? undefined : (options.quality ?? 80),
     fromSurface: true,
     captureBeyondViewport: false,
     optimizeForSpeed: !isPng,
+    ...(clip ? { clip } : {}),
   });
   return Buffer.from(result.data, "base64");
 }

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;
 }
@@ -364,6 +389,9 @@ export async function spawnStreamingEncoder(
     exitPromiseResolve?.();
   });
 
+  ffmpeg.stdin?.on("error", () => {});
+  ffmpeg.stdout?.on("error", () => {});
+
   // Handle abort signal
   const onAbort = () => {
     if (exitStatus === "running") {

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>');