@hyperframes/engine 0.4.6 → 0.4.8

package/src/services/hdrCapture.ts

@@ -0,0 +1,354 @@
+/// <reference types="@webgpu/types" />
+/**
+ * HDR Capture Service
+ *
+ * Captures HDR video frames via WebGPU float16 readback.
+ *
+ * The pipeline:
+ * 1. FFmpeg extracts raw HDR pixels (rgba64le) from video sources
+ * 2. Node converts HLG/PQ signal → linear light → float16
+ * 3. writeTexture uploads float16 data to WebGPU rgba16float texture
+ * 4. (Optional) WebGPU shader applies GSAP CSS transform
+ * 5. readback extracts float16 RGBA via base64 transfer
+ * 6. Node converts linear float16 → PQ signal → pipe to FFmpeg H.265
+ *
+ * Requirements:
+ * - Headed Chrome (not headless) — WebGPU unavailable in headless mode
+ * - GPU access (Metal on macOS, Vulkan+NVIDIA on Linux)
+ *
+ * Performance: ~6 fps at 1080x1920 via base64 transfer.
+ */
+
+import type { Page, Browser, PuppeteerNode } from "puppeteer-core";
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
+
+const PQ_M1 = 0.1593017578125;
+const PQ_M2 = 78.84375;
+const PQ_C1 = 0.8359375;
+const PQ_C2 = 18.8515625;
+const PQ_C3 = 18.6875;
+const PQ_MAX_NITS = 10000.0;
+const SDR_NITS = 203.0;
+
+function linearToPQ(L: number): number {
+  const Lp = Math.max(0, (L * SDR_NITS) / PQ_MAX_NITS);
+  const Lm1 = Math.pow(Lp, PQ_M1);
+  return Math.pow((PQ_C1 + PQ_C2 * Lm1) / (1.0 + PQ_C3 * Lm1), PQ_M2);
+}
+
+function float16Decode(h: number): number {
+  const sign = (h >> 15) & 1;
+  const exp = (h >> 10) & 0x1f;
+  const frac = h & 0x3ff;
+  if (exp === 0) return (sign ? -1 : 1) * Math.pow(2, -14) * (frac / 1024);
+  if (exp === 31) return frac ? NaN : sign ? -Infinity : Infinity;
+  return (sign ? -1 : 1) * Math.pow(2, exp - 15) * (1 + frac / 1024);
+}
+
+// ── Browser-side interface ────────────────────────────────────────────────────
+
+interface HdrCaptureRuntime {
+  uploadAndReadback(float16Base64: string): Promise<{ base64: string; bytesPerRow: number }>;
+}
+
+// ── Initialization ────────────────────────────────────────────────────────────
+
+/**
+ * Inject the WebGPU HDR readback runtime into the page.
+ *
+ * Creates an rgba16float render texture that accepts writeTexture uploads
+ * and provides readback via base64 transfer.
+ */
+export async function initHdrReadback(page: Page, width: number, height: number): Promise<boolean> {
+  return page.evaluate(
+    async (w: number, h: number): Promise<boolean> => {
+      if (!navigator.gpu) return false;
+
+      const adapter = await navigator.gpu.requestAdapter();
+      if (!adapter) return false;
+
+      const device = await adapter.requestDevice();
+
+      const bytesPerPixel = 8; // rgba16float = 4 channels × 2 bytes
+      const bytesPerRow = Math.ceil((w * bytesPerPixel) / 256) * 256;
+
+      // Render texture — includes COPY_DST for writeTexture uploads
+      const renderTexture = device.createTexture({
+        size: [w, h],
+        format: "rgba16float",
+        usage:
+          GPUTextureUsage.RENDER_ATTACHMENT |
+          GPUTextureUsage.COPY_SRC |
+          GPUTextureUsage.COPY_DST |
+          GPUTextureUsage.TEXTURE_BINDING,
+      });
+
+      const readBuffer = device.createBuffer({
+        size: bytesPerRow * h,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+      });
+
+      const captureRuntime = {
+        device,
+        renderTexture,
+        readBuffer,
+        bytesPerRow,
+        width: w,
+        height: h,
+
+        /**
+         * Upload pre-converted float16 RGBA data and read it back.
+         * The float16 data must be row-aligned to bytesPerRow.
+         *
+         * Input: base64-encoded Uint16Array (float16 RGBA, row-padded)
+         * Output: base64-encoded readback of the same texture
+         */
+        async uploadAndReadback(
+          float16Base64: string,
+        ): Promise<{ base64: string; bytesPerRow: number }> {
+          // Decode base64 → Uint8Array
+          const binary = atob(float16Base64);
+          const bytes = new Uint8Array(binary.length);
+          for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+
+          // Upload to texture
+          device.queue.writeTexture(
+            { texture: renderTexture },
+            bytes.buffer,
+            { bytesPerRow, rowsPerImage: h },
+            [w, h],
+          );
+
+          // Readback
+          const encoder = device.createCommandEncoder();
+          encoder.copyTextureToBuffer(
+            { texture: renderTexture },
+            { buffer: readBuffer, bytesPerRow },
+            [w, h],
+          );
+          device.queue.submit([encoder.finish()]);
+
+          await readBuffer.mapAsync(GPUMapMode.READ);
+          const readBytes = new Uint8Array(readBuffer.getMappedRange().slice(0));
+          readBuffer.unmap();
+
+          // Base64 encode in chunks
+          let b64 = "";
+          const chunkSize = 32768;
+          for (let i = 0; i < readBytes.length; i += chunkSize) {
+            const slice = readBytes.subarray(i, Math.min(i + chunkSize, readBytes.length));
+            b64 += String.fromCharCode(...slice);
+          }
+
+          return { base64: btoa(b64), bytesPerRow };
+        },
+      };
+
+      (window as unknown as Record<string, unknown>).__hfHdrCapture = captureRuntime;
+      return true;
+    },
+    width,
+    height,
+  );
+}
+
+// ── HDR frame conversion ──────────────────────────────────────────────────────
+
+/**
+ * Convert raw rgba64le pixels (from FFmpeg) to a base64 string for FFmpeg encoding.
+ *
+ * For HLG sources: the pixel values are already HLG-encoded. We pass them through
+ * as-is (normalized to 16-bit) and tag the output as HLG. No OETF conversion needed —
+ * the HLG signal values ARE the correct encoding. Converting to linear and back to
+ * PQ produces worse results because every viewer's PQ→display tone-mapping differs
+ * from its HLG→display tone-mapping.
+ *
+ * The WebGPU round-trip is skipped for pass-through — the pixels go directly from
+ * FFmpeg extraction to FFmpeg encoding. WebGPU is only needed when transforms
+ * (scale, rotate, opacity from GSAP) must be applied to the HDR pixels.
+ */
+export function convertHdrFrameToRgb48le(
+  rawRgba64le: Buffer,
+  width: number,
+  height: number,
+): Buffer {
+  const input = new Uint16Array(
+    rawRgba64le.buffer,
+    rawRgba64le.byteOffset,
+    rawRgba64le.byteLength / 2,
+  );
+
+  // Convert RGBA → RGB (drop alpha) for rgb48le output
+  const output = Buffer.alloc(width * height * 6);
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const srcIdx = (y * width + x) * 4;
+      const dstIdx = (y * width + x) * 6;
+      output.writeUInt16LE(input[srcIdx] ?? 0, dstIdx);
+      output.writeUInt16LE(input[srcIdx + 1] ?? 0, dstIdx + 2);
+      output.writeUInt16LE(input[srcIdx + 2] ?? 0, dstIdx + 4);
+    }
+  }
+
+  return output;
+}
+
+// ── Frame upload + readback ───────────────────────────────────────────────────
+
+/**
+ * Upload a float16 frame to WebGPU and read it back.
+ * Call after converting with convertHdrFrameToFloat16Base64.
+ */
+export async function uploadAndReadbackHdrFrame(
+  page: Page,
+  float16Base64: string,
+): Promise<{ rawBuffer: Buffer; bytesPerRow: number }> {
+  const result = await page.evaluate(
+    async (b64: string): Promise<{ base64: string; bytesPerRow: number }> => {
+      const hdr = (window as unknown as Record<string, unknown>).__hfHdrCapture as
+        | HdrCaptureRuntime
+        | undefined;
+      if (!hdr) throw new Error("HDR capture not initialized");
+      return hdr.uploadAndReadback(b64);
+    },
+    float16Base64,
+  );
+
+  return {
+    rawBuffer: Buffer.from(result.base64, "base64"),
+    bytesPerRow: result.bytesPerRow,
+  };
+}
+
+// ── PQ conversion ─────────────────────────────────────────────────────────────
+
+/**
+ * Convert float16 RGBA readback to PQ-encoded rgb48le for FFmpeg.
+ */
+export function float16ToPqRgb(
+  rawBuffer: Buffer,
+  bytesPerRow: number,
+  width: number,
+  height: number,
+): Buffer {
+  const data = new Uint16Array(rawBuffer.buffer, rawBuffer.byteOffset, rawBuffer.byteLength / 2);
+  const channelsPerRow = bytesPerRow / 2;
+  const output = Buffer.alloc(width * height * 6);
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const srcIdx = y * channelsPerRow + x * 4;
+      const r = float16Decode(data[srcIdx] ?? 0);
+      const g = float16Decode(data[srcIdx + 1] ?? 0);
+      const b = float16Decode(data[srcIdx + 2] ?? 0);
+
+      const dstIdx = (y * width + x) * 6;
+      output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(r)) * 65535), dstIdx);
+      output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(g)) * 65535), dstIdx + 2);
+      output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(b)) * 65535), dstIdx + 4);
+    }
+  }
+
+  return output;
+}
+
+// ── Chrome launch ─────────────────────────────────────────────────────────────
+
+function resolveHeadedChromePath(): string | undefined {
+  const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
+  if (!existsSync(baseDir)) return undefined;
+  const versions = readdirSync(baseDir).sort().reverse();
+  for (const version of versions) {
+    const candidates = [
+      join(
+        baseDir,
+        version,
+        "chrome-mac-arm64",
+        "Google Chrome for Testing.app",
+        "Contents",
+        "MacOS",
+        "Google Chrome for Testing",
+      ),
+      join(
+        baseDir,
+        version,
+        "chrome-mac-x64",
+        "Google Chrome for Testing.app",
+        "Contents",
+        "MacOS",
+        "Google Chrome for Testing",
+      ),
+      join(baseDir, version, "chrome-linux64", "chrome"),
+      join(baseDir, version, "chrome-win64", "chrome.exe"),
+    ];
+    for (const binary of candidates) {
+      if (existsSync(binary)) return binary;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Launch a headed Chrome browser with WebGPU enabled.
+ */
+export async function launchHdrBrowser(
+  width: number,
+  height: number,
+): Promise<{ browser: Browser; page: Page }> {
+  let ppt: PuppeteerNode | undefined;
+  try {
+    const mod = await import("puppeteer" as string);
+    ppt = mod.default;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+      throw err;
+    }
+    const mod = await import("puppeteer-core");
+    ppt = mod.default;
+  }
+  if (!ppt) throw new Error("Neither puppeteer nor puppeteer-core found");
+
+  const chromePath = resolveHeadedChromePath();
+  if (!chromePath) {
+    throw new Error(
+      "[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable",
+    );
+  }
+
+  const browser = await ppt.launch({
+    headless: false,
+    executablePath: chromePath,
+    args: buildHdrChromeArgs(width, height),
+  });
+
+  const page = await browser.newPage();
+  await page.setViewport({ width, height });
+
+  return { browser, page };
+}
+
+export function buildHdrChromeArgs(width: number, height: number): string[] {
+  return [
+    "--enable-unsafe-webgpu",
+    "--no-sandbox",
+    "--disable-setuid-sandbox",
+    "--window-position=-10000,-10000",
+    `--window-size=${width},${height}`,
+    "--disable-background-timer-throttling",
+    "--disable-backgrounding-occluded-windows",
+    "--disable-renderer-backgrounding",
+    "--disable-background-media-suspend",
+    "--disable-extensions",
+    "--disable-component-update",
+    "--disable-default-apps",
+    "--disable-sync",
+    "--no-zygote",
+    "--force-gpu-mem-available-mb=4096",
+  ];
+}

package/src/services/screenshotService.ts

@@ -133,6 +133,233 @@ export async function pageScreenshotCapture(page: Page, options: CaptureOptions)
   return Buffer.from(result.data, "base64");
 }
 
+/**
+ * Capture a screenshot with transparent background (PNG + alpha channel).
+ *
+ * Used in the two-pass HDR compositing pipeline — captures DOM content
+ * (text, graphics, SDR overlays) with transparency where the background shows,
+ * so it can be overlaid on top of native HDR video frames in FFmpeg.
+ *
+ * Sets and restores the background color override on every call. For sessions
+ * that capture many frames, prefer calling initTransparentBackground() once
+ * at session init, then captureAlphaPng() per frame to avoid the 2× CDP
+ * round-trip overhead.
+ */
+export async function captureScreenshotWithAlpha(
+  page: Page,
+  width: number,
+  height: number,
+): Promise<Buffer> {
+  const client = await getCdpSession(page);
+  // Force transparent background so the screenshot has a real alpha channel
+  await client.send("Emulation.setDefaultBackgroundColorOverride", {
+    color: { r: 0, g: 0, b: 0, a: 0 },
+  });
+  try {
+    const result = await client.send("Page.captureScreenshot", {
+      format: "png",
+      fromSurface: true,
+      captureBeyondViewport: false,
+      optimizeForSpeed: false, // `true` uses a zero-alpha-aware fast path that crushes real alpha values — observed empirically, CDP docs don't spell it out
+      clip: { x: 0, y: 0, width, height, scale: 1 },
+    });
+    return Buffer.from(result.data, "base64");
+  } finally {
+    // Restore opaque background even if captureScreenshot throws, otherwise
+    // subsequent opaque captures keep a transparent background.
+    await client.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {});
+  }
+}
+
+/**
+ * Set the page background to transparent once for a dedicated HDR DOM session.
+ *
+ * Call this once after session initialization. Then use captureAlphaPng() per
+ * frame instead of captureScreenshotWithAlpha() to skip the per-frame CDP
+ * background override round-trips.
+ *
+ * Only use on sessions that are exclusively dedicated to transparent capture
+ * (e.g., the HDR two-pass DOM layer session) — the background will stay
+ * transparent for the lifetime of the session.
+ *
+ * NOTE on the injected stylesheet: `Emulation.setDefaultBackgroundColorOverride`
+ * only replaces the *default* page background. Compositions almost always set
+ * `body { background: ... }` and `#root { background: ... }`, which paint over
+ * the override and ruin alpha capture for layered HDR compositing — the
+ * composition root's full-frame background paints across the entire viewport
+ * and wipes out HDR content captured beneath it.
+ *
+ * We force `html`, `body`, and any element marked as a composition root
+ * (`[data-composition-id]`) to transparent. In HDR layered compositing the HDR
+ * video itself is the backdrop, so DOM layers must only contribute their
+ * foreground UI pixels — never a page-spanning solid backdrop.
+ */
+export const TRANSPARENT_BG_STYLE_ID = "__hf_transparent_bg__";
+
+export async function initTransparentBackground(page: Page): Promise<void> {
+  const client = await getCdpSession(page);
+  await client.send("Emulation.setDefaultBackgroundColorOverride", {
+    color: { r: 0, g: 0, b: 0, a: 0 },
+  });
+  await page.evaluate((styleId: string) => {
+    if (document.getElementById(styleId)) return;
+    const style = document.createElement("style");
+    style.id = styleId;
+    style.textContent =
+      "html,body,[data-composition-id]{background:transparent !important;background-color:transparent !important;background-image:none !important;}";
+    document.head.appendChild(style);
+  }, TRANSPARENT_BG_STYLE_ID);
+}
+
+/**
+ * Capture a transparent-background PNG screenshot without setting the
+ * background color override. Requires initTransparentBackground() to have
+ * been called once on this session.
+ *
+ * Faster than captureScreenshotWithAlpha() for per-frame use in the HDR
+ * two-pass compositing loop.
+ */
+export async function captureAlphaPng(page: Page, width: number, height: number): Promise<Buffer> {
+  const client = await getCdpSession(page);
+  const result = await client.send("Page.captureScreenshot", {
+    format: "png",
+    fromSurface: true,
+    captureBeyondViewport: false,
+    optimizeForSpeed: false, // must be false to preserve alpha
+    clip: { x: 0, y: 0, width, height, scale: 1 },
+  });
+  return Buffer.from(result.data, "base64");
+}
+
+/**
+ * Stylesheet ID used by applyDomLayerMask / removeDomLayerMask. Exposed so
+ * tests can assert presence/absence of the mask between captures.
+ */
+export const DOM_LAYER_MASK_STYLE_ID = "__hf_dom_layer_mask__";
+
+/**
+ * Mask the DOM so a single layer screenshot captures ONLY the layer's pixels.
+ *
+ * The HDR layered compositor walks z-ordered layers and blits each one over a
+ * shared canvas. DOM layers are full-page screenshots — a naive screenshot
+ * captures every painted pixel on the page, which means root background +
+ * static overlays + sibling-scene content all overwrite previously composited
+ * HDR content beneath. The mask narrows each screenshot to the elements that
+ * actually belong to this layer.
+ *
+ * Strategy:
+ *
+ * 1. Inject a stylesheet that hides every body descendant
+ *    (`body * { visibility: hidden !important }`) and re-shows the layer's
+ *    elements (and their descendants and their injected `__render_frame_*`
+ *    siblings) via `visibility: visible !important`. CSS `visibility: visible`
+ *    on a descendant overrides an ancestor's `visibility: hidden`, so deep
+ *    layer elements remain visible even though intermediate parents are
+ *    hidden by the mass-hide rule.
+ * 2. Inline-hide each `extraHideId` (and its `__render_frame_*` sibling) with
+ *    `visibility: hidden !important`. Inline `!important` beats stylesheet
+ *    `!important`, so this overrides the show rule for elements that fall
+ *    under a show selector but should NOT paint — typically other-layer
+ *    elements that are descendants of a container layer (for example HDR
+ *    videos and other-layer SDR videos are descendants of `#root` when we
+ *    capture the root DOM layer).
+ *
+ * Only `visibility` is set on extraHideIds — never `opacity`. CSS opacity is
+ * multiplicative through the descendant chain and a descendant cannot escape
+ * an ancestor's `opacity: 0`. If `#root` is in `extraHideIds` and we set
+ * `opacity: 0` on it, every descendant — including `#vid-5-b` and its
+ * `__render_frame_vid-5-b__` IMG — becomes invisible even with
+ * `visibility: visible !important`. `visibility` does NOT have this problem:
+ * a descendant with `visibility: visible` overrides an ancestor's
+ * `visibility: hidden`.
+ *
+ * Layout is preserved (visibility doesn't trigger reflow), so border-radius
+ * clipping, overflow:hidden, and absolute positioning continue to apply to
+ * the visible layer elements. Opacity is also preserved — an ancestor at
+ * `opacity: 0` (e.g. an inactive scene during a transition) still
+ * propagates to its descendants, which is the desired behavior during
+ * cross-scene blends.
+ *
+ * Idempotent across calls: an existing mask stylesheet is removed before a
+ * new one is installed, so consecutive `applyDomLayerMask` invocations leave
+ * exactly one stylesheet attached.
+ */
+export async function applyDomLayerMask(
+  page: Page,
+  showIds: string[],
+  extraHideIds: string[],
+): Promise<void> {
+  await page.evaluate(
+    (args: { show: string[]; hide: string[]; styleId: string }) => {
+      const existing = document.getElementById(args.styleId);
+      if (existing) existing.remove();
+
+      const showSelectors: string[] = [];
+      for (const id of args.show) {
+        const escaped = CSS.escape(id);
+        showSelectors.push(`#${escaped}`, `#${escaped} *`);
+        const renderEscaped = CSS.escape(`__render_frame_${id}__`);
+        showSelectors.push(`#${renderEscaped}`, `#${renderEscaped} *`);
+      }
+
+      const massHideRule = "body *{visibility:hidden !important;}";
+      const showRule =
+        showSelectors.length === 0
+          ? ""
+          : `${showSelectors.join(",")}{visibility:visible !important;}`;
+
+      const style = document.createElement("style");
+      style.id = args.styleId;
+      style.textContent = `${massHideRule}\n${showRule}`;
+      document.head.appendChild(style);
+
+      for (const id of args.hide) {
+        const el = document.getElementById(id);
+        if (el) {
+          el.style.setProperty("visibility", "hidden", "important");
+        }
+        const img = document.getElementById(`__render_frame_${id}__`);
+        if (img) {
+          img.style.setProperty("visibility", "hidden", "important");
+        }
+      }
+    },
+    { show: showIds, hide: extraHideIds, styleId: DOM_LAYER_MASK_STYLE_ID },
+  );
+}
+
+/**
+ * Tear down the mask installed by applyDomLayerMask.
+ *
+ * Removes the mask stylesheet and clears the inline `visibility` properties
+ * set on `extraHideIds` (and their `__render_frame_*` siblings).
+ *
+ * IMPORTANT: We do NOT strip inline `opacity` here. applyDomLayerMask only
+ * ever sets `visibility` (never `opacity`), so any inline opacity present on
+ * a wrapper was put there by user animation code (typically GSAP) and must
+ * survive across per-layer captures. GSAP's seek with suppress-events does
+ * not re-apply tweens when the timeline is already at the target time, so if
+ * we strip opacity here and then seek to the same time for the next layer,
+ * GSAP won't put it back and the wrapper will render fully opaque.
+ */
+export async function removeDomLayerMask(page: Page, extraHideIds: string[]): Promise<void> {
+  await page.evaluate(
+    (args: { hide: string[]; styleId: string }) => {
+      const style = document.getElementById(args.styleId);
+      if (style) style.remove();
+      for (const id of args.hide) {
+        const el = document.getElementById(id);
+        if (el) {
+          el.style.removeProperty("visibility");
+        }
+        const img = document.getElementById(`__render_frame_${id}__`);
+        if (img) img.style.removeProperty("visibility");
+      }
+    },
+    { hide: extraHideIds, styleId: DOM_LAYER_MASK_STYLE_ID },
+  );
+}
+
 export async function injectVideoFramesBatch(
   page: Page,
   updates: Array<{ videoId: string; dataUri: string }>,
@@ -148,6 +375,16 @@ export async function injectVideoFramesBatch(
         let img = video.nextElementSibling as HTMLImageElement | null;
         const isNewImage = !img || !img.classList.contains("__render_frame__");
         const computedStyle = window.getComputedStyle(video);
+        // GSAP seeks re-apply tween values during an active tween, but do not
+        // re-apply tweens that have already completed. After an opacity fade-in
+        // finishes, GSAP's last set value is overwritten on subsequent frames
+        // by the `opacity: 0 !important` we apply at the bottom of this
+        // function to hide the native <video>. That leaves `computedOpacity`
+        // stuck at 0 even though the user's intent is opacity 1 (the tween's
+        // end state). The `|| 1` fallback treats computedOpacity === 0 as a
+        // hidden-native-video artifact and recovers opacity 1, matching the
+        // final on-screen state for the vast majority of compositions.
+        // For active tweens in the [0,1] exclusive range this is a no-op.
         const computedOpacity = parseFloat(computedStyle.opacity) || 1;
         const sourceIsStatic = !computedStyle.position || computedStyle.position === "static";
 
@@ -160,16 +397,11 @@ export async function injectVideoFramesBatch(
         }
         if (!img) continue;
 
-        if (!sourceIsStatic) {
-          img.style.position = computedStyle.position;
-          img.style.width = computedStyle.width;
-          img.style.height = computedStyle.height;
-          img.style.top = computedStyle.top;
-          img.style.left = computedStyle.left;
-          img.style.right = computedStyle.right;
-          img.style.bottom = computedStyle.bottom;
-          img.style.inset = computedStyle.inset;
-        } else {
+        // Always use absolute positioning so the <img> overlays the <video>
+        // instead of flowing below it. With position:relative, both elements
+        // stack vertically — the <img> lands below the video and gets clipped
+        // by any overflow:hidden ancestor (e.g., border-radius wrappers).
+        {
           const videoRect = video.getBoundingClientRect();
           const offsetLeft = Number.isFinite(video.offsetLeft) ? video.offsetLeft : 0;
           const offsetTop = Number.isFinite(video.offsetTop) ? video.offsetTop : 0;
@@ -189,6 +421,14 @@ export async function injectVideoFramesBatch(
         img.style.zIndex = computedStyle.zIndex;
 
         for (const property of visualProperties) {
+          // Opacity is handled explicitly via `computedOpacity` below — copying
+          // via the generic loop would race against the opacity:0 hide applied
+          // to the <video> at the end of this function. GSAP may animate
+          // opacity either on a wrapper (the <img> inherits via the stacking
+          // context) or directly on the <video> (we must copy it to the <img>
+          // since they are siblings). Reading computedStyle.opacity before
+          // hiding the <video> handles both cases correctly.
+          if (property === "opacity") continue;
           if (
             sourceIsStatic &&
             (property === "top" ||
@@ -235,14 +475,28 @@ export async function syncVideoFrameVisibility(
     const active = new Set(ids);
     const videos = Array.from(document.querySelectorAll("video[data-start]")) as HTMLVideoElement[];
     for (const video of videos) {
-      if (active.has(video.id)) continue;
-      video.style.removeProperty("display");
-      video.style.setProperty("visibility", "hidden", "important");
-      video.style.setProperty("opacity", "0", "important");
-      video.style.setProperty("pointer-events", "none", "important");
       const img = video.nextElementSibling as HTMLElement | null;
-      if (img && img.classList.contains("__render_frame__")) {
-        img.style.visibility = "hidden";
+      const hasImg = img && img.classList.contains("__render_frame__");
+      if (active.has(video.id)) {
+        // Active video: show injected <img>, hide native <video>.
+        // Do NOT clobber inline opacity here — GSAP-controlled opacity must
+        // survive until injectVideoFramesBatch reads it via getComputedStyle.
+        // visibility:hidden alone hides the native element without affecting
+        // its computed opacity.
+        video.style.setProperty("visibility", "hidden", "important");
+        video.style.setProperty("pointer-events", "none", "important");
+        if (hasImg) {
+          img.style.visibility = "visible";
+        }
+      } else {
+        // Inactive video: hide both
+        video.style.removeProperty("display");
+        video.style.setProperty("visibility", "hidden", "important");
+        video.style.setProperty("opacity", "0", "important");
+        video.style.setProperty("pointer-events", "none", "important");
+        if (hasImg) {
+          img.style.visibility = "hidden";
+        }
       }
     }
   }, activeVideoIds);