From aeb4905a39ed1125dd07760f7402f75934230058 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 14:48:12 -0400
Subject: [PATCH 1/8] refactor(producer): extract HDR compositor from
 renderOrchestrator

Move ~700 LOC of HDR compositing primitives (countNonZeroAlpha,
countNonZeroRgb48, cropRgb48le, HdrVideoFrameSource,
closeHdrVideoFrameSource, blitHdrVideoLayer, HdrImageBuffer,
blitHdrImageLayer, CompositeTransfer, shouldUseLayeredComposite,
resolveCompositeTransfer, HdrCompositeContext, compositeHdrFrame,
HdrTransitionMeta, TransitionRange) into a dedicated
hdrCompositor.ts module.

Remove backward-compat re-exports from renderOrchestrator (hdrPerf,
captureCost, shared) and rewire all import sites to the
authoritative source modules.
---
 .../producer/src/services/hdrCompositor.ts    | 703 +++++++++++++++++
 .../src/services/render/perfSummary.ts        |   3 +-
 .../render/stages/captureHdrFrameShared.ts    |   5 +-
 .../render/stages/captureHdrHybridLoop.ts     |   8 +-
 .../render/stages/captureHdrResources.ts      |   8 +-
 .../render/stages/captureHdrSequentialLoop.ts |  10 +-
 .../services/render/stages/captureHdrStage.ts |   9 +-
 .../render/stages/extractVideosStage.ts       |   3 +-
 .../src/services/renderOrchestrator.test.ts   |   3 +-
 .../src/services/renderOrchestrator.ts        | 721 +-----------------
 10 files changed, 723 insertions(+), 750 deletions(-)
 create mode 100644 packages/producer/src/services/hdrCompositor.ts

diff --git a/packages/producer/src/services/hdrCompositor.ts b/packages/producer/src/services/hdrCompositor.ts
new file mode 100644
index 0000000000..35c2bc9320
--- /dev/null
+++ b/packages/producer/src/services/hdrCompositor.ts
@@ -0,0 +1,703 @@
+// fallow-ignore-file complexity code-duplication
+/**
+ * HDR Compositor — pixel-level compositing primitives for the HDR
+ * layered render path.
+ *
+ * Extracted from `renderOrchestrator.ts` so the ~600 LOC of HDR-specific
+ * buffer manipulation, video/image blit logic, and per-frame compositor
+ * live in a focused module that can be tested and evolved independently.
+ *
+ * Consumers: `captureHdrStage.ts`, `captureHdrSequentialLoop.ts`,
+ * `captureHdrHybridLoop.ts`, `captureHdrFrameShared.ts`,
+ * `captureHdrResources.ts`.
+ */
+
+import { readSync, closeSync } from "fs";
+import { join } from "path";
+import {
+  type CaptureSession,
+  type BeforeCaptureHook,
+  type HdrTransfer,
+  type ElementStackingInfo,
+  type HfTransitionMeta,
+  captureAlphaPng,
+  applyDomLayerMask,
+  removeDomLayerMask,
+  decodePng,
+  blitRgba8OverRgb48le,
+  blitRgb48leRegion,
+  groupIntoLayers,
+  blitRgb48leAffine,
+  parseTransformMatrix,
+  convertTransfer,
+} from "@hyperframes/engine";
+import type { ProducerLogger } from "../logger.js";
+import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
+import { writeFileExclusiveSync } from "./render/shared.js";
+import { type HdrPerfCollector, addHdrTiming } from "./render/hdrPerf.js";
+
+// ─── Diagnostic helpers ────────────────────────────────────────────────────
+
+// Diagnostic helpers used by the HDR layered compositor when KEEP_TEMP=1
+// is set. They are pure (capture no state), so we keep them at module scope
+// to avoid re-creating closures per frame and to make them callable from
+// any future composite path that needs to log non-zero pixel counts.
+function countNonZeroAlpha(rgba: Uint8Array): number {
+  let n = 0;
+  for (let p = 3; p < rgba.length; p += 4) {
+    if (rgba[p] !== 0) n++;
+  }
+  return n;
+}
+
+function countNonZeroRgb48(buf: Uint8Array): number {
+  let n = 0;
+  for (let p = 0; p < buf.length; p += 6) {
+    if (
+      buf[p] !== 0 ||
+      buf[p + 1] !== 0 ||
+      buf[p + 2] !== 0 ||
+      buf[p + 3] !== 0 ||
+      buf[p + 4] !== 0 ||
+      buf[p + 5] !== 0
+    )
+      n++;
+  }
+  return n;
+}
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/**
+ * Metadata for a shader transition between two scenes, extracted from
+ * `window.__hf.transitions`. Re-exported from the engine so the producer
+ * shares the contract with composition runtime code.
+ */
+export type HdrTransitionMeta = HfTransitionMeta;
+
+/** Pre-computed frame range for an active transition. */
+export interface TransitionRange extends HdrTransitionMeta {
+  startFrame: number;
+  endFrame: number;
+}
+
+// ─── Video frame source ────────────────────────────────────────────────────
+
+/**
+ * Crop an rgb48le buffer to a sub-region. Returns a new Buffer containing
+ * only the cropped pixels.
+ */
+function cropRgb48le(
+  src: Buffer,
+  srcW: number,
+  srcH: number,
+  cropX: number,
+  cropY: number,
+  cropW: number,
+  cropH: number,
+): Buffer {
+  const BPP = 6;
+  const dst = Buffer.alloc(cropW * cropH * BPP);
+  for (let row = 0; row < cropH; row++) {
+    const srcRow = cropY + row;
+    if (srcRow < 0 || srcRow >= srcH) continue;
+    const srcOff = (srcRow * srcW + cropX) * BPP;
+    const dstOff = row * cropW * BPP;
+    const copyLen = Math.min(cropW, srcW - cropX) * BPP;
+    if (copyLen > 0) src.copy(dst, dstOff, srcOff, srcOff + copyLen);
+  }
+  return dst;
+}
+
+/**
+ * Blit a single HDR video layer onto an rgb48le canvas.
+ *
+ * Shared between the normal-frame compositing path (compositeToBuffer)
+ * and the transition dual-scene compositing loop to avoid duplicating
+ * the frame lookup, raw read, transfer, transform, and blit logic.
+ */
+export interface HdrVideoFrameSource {
+  dir: string;
+  rawPath: string;
+  fd: number;
+  width: number;
+  height: number;
+  frameSize: number;
+  frameCount: number;
+  scratch: Buffer;
+}
+
+export function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: ProducerLogger): void {
+  try {
+    closeSync(source.fd);
+  } catch (err) {
+    log?.warn("Failed to close HDR raw frame file", {
+      rawPath: source.rawPath,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+export function blitHdrVideoLayer(
+  canvas: Buffer,
+  el: ElementStackingInfo,
+  time: number,
+  fps: number,
+  hdrVideoFrameSources: Map<string, HdrVideoFrameSource>,
+  hdrStartTimes: Map<string, number>,
+  width: number,
+  height: number,
+  log?: ProducerLogger,
+  sourceTransfer?: HdrTransfer,
+  targetTransfer?: HdrTransfer,
+  hdrPerf?: HdrPerfCollector,
+): void {
+  const frameSource = hdrVideoFrameSources.get(el.id);
+  const startTime = hdrStartTimes.get(el.id);
+  if (!frameSource || startTime === undefined || el.opacity <= 0) {
+    return;
+  }
+
+  // Frame index within the video. Clamp to the extracted raw frame count so
+  // a composition that outlives the source clip freezes on the last frame,
+  // matching Chrome's <video> behavior.
+  const videoFrameIndex = Math.round((time - startTime) * fps) + 1;
+  if (videoFrameIndex < 1) return;
+  const effectiveIndex = Math.min(videoFrameIndex, frameSource.frameCount);
+  if (effectiveIndex < 1) return;
+  const frameOffset = (effectiveIndex - 1) * frameSource.frameSize;
+
+  try {
+    if (hdrPerf) hdrPerf.hdrVideoLayerBlits += 1;
+    let timingStart = Date.now();
+    const bytesRead = readSync(
+      frameSource.fd,
+      frameSource.scratch,
+      0,
+      frameSource.frameSize,
+      frameOffset,
+    );
+    if (bytesRead !== frameSource.frameSize) return;
+    const hdrRgb = frameSource.scratch;
+    const srcW = frameSource.width;
+    const srcH = frameSource.height;
+    addHdrTiming(hdrPerf, "hdrVideoReadDecodeMs", timingStart);
+
+    // Convert between HDR transfer functions if source doesn't match output
+    if (sourceTransfer && targetTransfer && sourceTransfer !== targetTransfer) {
+      timingStart = Date.now();
+      convertTransfer(hdrRgb, sourceTransfer, targetTransfer);
+      addHdrTiming(hdrPerf, "hdrVideoTransferMs", timingStart);
+    }
+
+    const viewportMatrix = parseTransformMatrix(el.transform);
+
+    // Pass border-radius for rounded-corner masking (only when non-zero)
+    const br = el.borderRadius;
+    const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
+    const borderRadiusParam = hasBorderRadius ? br : undefined;
+
+    // Apply ancestor overflow:hidden clip rect by constraining the blit
+    // bounds. For the no-transform (region) path, we crop the source
+    // image and adjust the destination position. For the affine path,
+    // clip rect support is not yet implemented (would require per-pixel
+    // scissor in the affine blit); log a warning and skip clipping.
+    let blitX = el.x;
+    let blitY = el.y;
+    let blitSrcX = 0;
+    let blitSrcY = 0;
+    let blitW = srcW;
+    let blitH = srcH;
+    let clipped = false;
+
+    if (el.clipRect) {
+      const cr = el.clipRect;
+      const cx1 = Math.max(blitX, cr.x);
+      const cy1 = Math.max(blitY, cr.y);
+      const cx2 = Math.min(blitX + blitW, cr.x + cr.width);
+      const cy2 = Math.min(blitY + blitH, cr.y + cr.height);
+      if (cx2 <= cx1 || cy2 <= cy1) return; // fully clipped
+      blitSrcX = cx1 - blitX;
+      blitSrcY = cy1 - blitY;
+      blitW = cx2 - cx1;
+      blitH = cy2 - cy1;
+      blitX = cx1;
+      blitY = cy1;
+      clipped = true;
+    }
+
+    // Detect translation-only matrix (no scale/rotation) — route through the
+    // region path which supports clip rects. Chrome reports a viewport matrix
+    // for all HDR elements, even untransformed ones or those with only layout
+    // translation (e.g. `left: 960px` → `matrix(1,0,0,1,960,0)`). The region
+    // blit handles translation via el.x/el.y, so we only need the affine path
+    // for actual scale/rotation transforms.
+    // parseTransformMatrix returns a 6-element array or null — length check unnecessary.
+    const isTranslationOnly = !!(
+      viewportMatrix &&
+      Math.abs(viewportMatrix[0]! - 1) < 0.001 &&
+      Math.abs(viewportMatrix[1]!) < 0.001 &&
+      Math.abs(viewportMatrix[2]!) < 0.001 &&
+      Math.abs(viewportMatrix[3]! - 1) < 0.001
+    );
+
+    timingStart = Date.now();
+    if (viewportMatrix && !isTranslationOnly) {
+      if (clipped && log) {
+        log.debug(
+          `HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
+        );
+      }
+      blitRgb48leAffine(
+        canvas,
+        hdrRgb,
+        viewportMatrix,
+        srcW,
+        srcH,
+        width,
+        height,
+        el.opacity < 0.999 ? el.opacity : undefined,
+        borderRadiusParam,
+      );
+    } else if (clipped) {
+      // Crop the source buffer to the clipped region before blitting
+      const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
+      blitRgb48leRegion(
+        canvas,
+        croppedBuf,
+        blitX,
+        blitY,
+        blitW,
+        blitH,
+        width,
+        height,
+        el.opacity < 0.999 ? el.opacity : undefined,
+        borderRadiusParam,
+      );
+    } else {
+      blitRgb48leRegion(
+        canvas,
+        hdrRgb,
+        el.x,
+        el.y,
+        srcW,
+        srcH,
+        width,
+        height,
+        el.opacity < 0.999 ? el.opacity : undefined,
+        borderRadiusParam,
+      );
+    }
+    addHdrTiming(hdrPerf, "hdrVideoBlitMs", timingStart);
+  } catch (err) {
+    if (log) {
+      log.debug(`HDR blit failed for ${el.id}`, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+// ─── Image buffer ──────────────────────────────────────────────────────────
+
+/**
+ * Pre-decoded HDR image buffer with its native pixel dimensions.
+ *
+ * Static images decode exactly once at setup time and are blitted on every
+ * visible frame, unlike video frames which are read fresh per timestamp.
+ */
+export interface HdrImageBuffer {
+  data: Buffer;
+  width: number;
+  height: number;
+}
+
+/**
+ * Blit a single HDR image layer onto an rgb48le canvas.
+ *
+ * Image-equivalent of `blitHdrVideoLayer` — the buffer is pre-decoded and
+ * static, so there's no time-based frame lookup or per-frame PNG read.
+ */
+export function blitHdrImageLayer(
+  canvas: Buffer,
+  el: ElementStackingInfo,
+  hdrImageBuffers: Map<string, HdrImageBuffer>,
+  hdrImageTransferCache: HdrImageTransferCache,
+  width: number,
+  height: number,
+  log?: ProducerLogger,
+  sourceTransfer?: HdrTransfer,
+  targetTransfer?: HdrTransfer,
+  hdrPerf?: HdrPerfCollector,
+): void {
+  const buf = hdrImageBuffers.get(el.id);
+  if (!buf || el.opacity <= 0) {
+    return;
+  }
+  if (el.clipRect && log) {
+    log.debug(`HDR clip rect on image element ${el.id} — clip not yet supported for images`);
+  }
+
+  try {
+    if (hdrPerf) hdrPerf.hdrImageLayerBlits += 1;
+    // The cache returns `buf.data` unchanged when no conversion is needed,
+    // and otherwise returns a per-(imageId, targetTransfer) buffer that was
+    // converted exactly once and reused across every subsequent frame.
+    let timingStart = Date.now();
+    const hdrRgb =
+      sourceTransfer && targetTransfer
+        ? hdrImageTransferCache.getConverted(el.id, sourceTransfer, targetTransfer, buf.data)
+        : buf.data;
+    addHdrTiming(hdrPerf, "hdrImageTransferMs", timingStart);
+
+    const viewportMatrix = parseTransformMatrix(el.transform);
+
+    const br = el.borderRadius;
+    const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
+    const borderRadiusParam = hasBorderRadius ? br : undefined;
+
+    timingStart = Date.now();
+    if (viewportMatrix) {
+      blitRgb48leAffine(
+        canvas,
+        hdrRgb,
+        viewportMatrix,
+        buf.width,
+        buf.height,
+        width,
+        height,
+        el.opacity < 0.999 ? el.opacity : undefined,
+        borderRadiusParam,
+      );
+    } else {
+      blitRgb48leRegion(
+        canvas,
+        hdrRgb,
+        el.x,
+        el.y,
+        buf.width,
+        buf.height,
+        width,
+        height,
+        el.opacity < 0.999 ? el.opacity : undefined,
+        borderRadiusParam,
+      );
+    }
+    addHdrTiming(hdrPerf, "hdrImageBlitMs", timingStart);
+  } catch (err) {
+    if (log) {
+      log.debug(`HDR image blit failed for ${el.id}`, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+// ─── Composite transfer + strategy ─────────────────────────────────────────
+
+/**
+ * Dependencies passed to `compositeHdrFrame`.
+ *
+ * Every field except the per-frame arguments is captured once when the HDR
+ * render path opens its `try { ... }` block and reused across every frame —
+ * extracting them into an explicit struct lets the helper live at module
+ * scope (no closure-over-renderJob) and keeps the per-call signature small.
+ */
+export type CompositeTransfer = HdrTransfer | "srgb";
+
+export function shouldUseLayeredComposite(options: {
+  hasHdrContent: boolean;
+  hasShaderTransitions: boolean;
+  isPngSequence: boolean;
+}): boolean {
+  return options.hasHdrContent || (options.hasShaderTransitions && !options.isPngSequence);
+}
+
+export function resolveCompositeTransfer(
+  hasHdrContent: boolean,
+  effectiveHdr: { transfer: HdrTransfer } | undefined,
+): CompositeTransfer {
+  return hasHdrContent && effectiveHdr ? effectiveHdr.transfer : "srgb";
+}
+
+export interface HdrCompositeContext {
+  log: ProducerLogger;
+  domSession: CaptureSession;
+  beforeCaptureHook: BeforeCaptureHook | null;
+  width: number;
+  height: number;
+  fps: number;
+  compositeTransfer: CompositeTransfer;
+  nativeHdrImageIds: Set<string>;
+  hdrImageBuffers: Map<string, HdrImageBuffer>;
+  hdrImageTransferCache: HdrImageTransferCache;
+  hdrVideoFrameSources: Map<string, HdrVideoFrameSource>;
+  hdrVideoStartTimes: Map<string, number>;
+  imageTransfers: Map<string, HdrTransfer>;
+  videoTransfers: Map<string, HdrTransfer>;
+  debugDumpEnabled: boolean;
+  debugDumpDir: string | null;
+  hdrPerf?: HdrPerfCollector;
+}
+
+// ─── Per-frame compositor ──────────────────────────────────────────────────
+
+/**
+ * Composite a single HDR frame into a pre-allocated `rgb48le` canvas.
+ *
+ * Bottom-to-top z-order: HDR layers are blitted directly from cached image
+ * buffers / extracted video frames; DOM layers are screenshotted with a
+ * mass-hide mask (so each layer paints only its own elements) and then
+ * blended into the canvas via `blitRgba8OverRgb48le` in the active HDR
+ * transfer space.
+ *
+ * The `elementFilter` parameter exists so the transition path can composite
+ * each scene independently; pass `undefined` for whole-stack rendering.
+ *
+ * @param ctx - Long-lived dependencies (logger, browser session, dimensions,
+ *              HDR layer maps). Captured once per render — see
+ *              {@link HdrCompositeContext}.
+ * @param canvas - Pre-allocated `width * height * 6` byte buffer. Caller must
+ *                 zero-fill before every frame (this helper does not).
+ * @param time - Seek time in seconds.
+ * @param fullStacking - Stacking info for ALL elements at this time. Even when
+ *                       filtering, every other element id is needed to build
+ *                       the DOM-layer hide-list.
+ * @param elementFilter - When set, only elements whose id is in the set are
+ *                        composited.
+ * @param debugFrameIndex - Frame index used to label per-layer diagnostic
+ *                          dumps. Pass `-1` to disable per-layer dumps even
+ *                          when `KEEP_TEMP=1` (e.g. for warmup frames).
+ */
+export async function compositeHdrFrame(
+  ctx: HdrCompositeContext,
+  canvas: Buffer,
+  time: number,
+  fullStacking: ElementStackingInfo[],
+  elementFilter?: Set<string>,
+  debugFrameIndex: number = -1,
+): Promise<void> {
+  const {
+    log,
+    domSession,
+    beforeCaptureHook,
+    width,
+    height,
+    fps,
+    compositeTransfer,
+    nativeHdrImageIds,
+    hdrImageBuffers,
+    hdrImageTransferCache,
+    hdrVideoFrameSources,
+    hdrVideoStartTimes,
+    imageTransfers,
+    videoTransfers,
+    debugDumpEnabled,
+    debugDumpDir,
+    hdrPerf,
+  } = ctx;
+
+  const filteredStacking = elementFilter
+    ? fullStacking.filter((e) => elementFilter.has(e.id))
+    : fullStacking;
+
+  // Zero-opacity elements stay in the stacking for correct hide-list
+  // generation (their <img> replacements must be hidden from sibling
+  // screenshots). The actual blit is skipped in the compositing loop below.
+  const layers = groupIntoLayers(filteredStacking);
+
+  const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
+  if (shouldLog) {
+    log.info("[diag] compositeToBuffer plan", {
+      frame: debugFrameIndex,
+      time: time.toFixed(3),
+      filterSize: elementFilter?.size,
+      fullStackingCount: fullStacking.length,
+      filteredCount: filteredStacking.length,
+      layerCount: layers.length,
+      layers: layers.map((l) =>
+        l.type === "hdr"
+          ? {
+              type: "hdr",
+              id: l.element.id,
+              z: l.element.zIndex,
+              visible: l.element.visible,
+              opacity: l.element.opacity,
+              bounds: `${Math.round(l.element.x)},${Math.round(l.element.y)} ${Math.round(l.element.width)}x${Math.round(l.element.height)}`,
+            }
+          : { type: "dom", ids: l.elementIds },
+      ),
+    });
+  }
+
+  for (const [layerIdx, layer] of layers.entries()) {
+    if (layer.type === "hdr") {
+      // Skip zero-opacity HDR elements — their parent scene may have faded out.
+      if (layer.element.opacity <= 0) continue;
+      const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
+      const isHdrImage = nativeHdrImageIds.has(layer.element.id);
+      const hdrTargetTransfer = compositeTransfer === "srgb" ? undefined : compositeTransfer;
+      if (isHdrImage) {
+        blitHdrImageLayer(
+          canvas,
+          layer.element,
+          hdrImageBuffers,
+          hdrImageTransferCache,
+          width,
+          height,
+          log,
+          imageTransfers.get(layer.element.id),
+          hdrTargetTransfer,
+          hdrPerf,
+        );
+      } else {
+        blitHdrVideoLayer(
+          canvas,
+          layer.element,
+          time,
+          fps,
+          hdrVideoFrameSources,
+          hdrVideoStartTimes,
+          width,
+          height,
+          log,
+          videoTransfers.get(layer.element.id),
+          hdrTargetTransfer,
+          hdrPerf,
+        );
+      }
+      if (shouldLog) {
+        const after = countNonZeroRgb48(canvas);
+        if (isHdrImage) {
+          const buf = hdrImageBuffers.get(layer.element.id);
+          log.info("[diag] hdr layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            id: layer.element.id,
+            kind: "image",
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            bufferDecoded: !!buf,
+            bufferDims: buf ? `${buf.width}x${buf.height}` : null,
+          });
+        } else {
+          const frameSource = hdrVideoFrameSources.get(layer.element.id);
+          const startTime = hdrVideoStartTimes.get(layer.element.id) ?? 0;
+          const localTime = time - startTime;
+          const frameNum = Math.floor(localTime * fps) + 1;
+          log.info("[diag] hdr layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            id: layer.element.id,
+            kind: "video",
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            startTime,
+            localTime: localTime.toFixed(3),
+            hdrFrameNum: frameNum,
+            rawPath: frameSource?.rawPath ?? null,
+            frameCount: frameSource?.frameCount ?? null,
+          });
+        }
+      }
+    } else {
+      // DOM layer: capture only elements in this layer.
+      //
+      // Each layer gets a fresh seek + inject cycle to guarantee correct
+      // visibility state — avoids fragile interactions between the frame
+      // injector, applyDomLayerMask, removeDomLayerMask, and GSAP re-seek.
+      //
+      // The mask:
+      //   - mass-hides every body descendant via stylesheet
+      //   - re-shows the layer's elements (and their descendants and
+      //     their injected `__render_frame_*` siblings) so deep-nested
+      //     content stays visible even though intermediate ancestors
+      //     are hidden
+      //   - inline-hides every other data-start element so they don't
+      //     paint when they happen to be descendants of a layer element
+      //     (most importantly: HDR videos and other-layer SDR videos
+      //     that live inside `#root` when capturing the root DOM layer)
+      //
+      // Without the mask, every DOM screenshot captures the full page
+      // (root background, sibling scenes' static content, the painted
+      // border/box-shadow of cards, etc.) and the resulting opaque
+      // pixels overwrite previously composited HDR content beneath.
+      const allElementIds = fullStacking.map((e) => e.id);
+      const layerIds = new Set(layer.elementIds);
+      const hideIds = allElementIds.filter((id) => !layerIds.has(id));
+      if (hdrPerf) hdrPerf.domLayerCaptures += 1;
+
+      // 1. Seek GSAP to restore all animated properties from clean state
+      let timingStart = Date.now();
+      await domSession.page.evaluate((t: number) => {
+        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+      }, time);
+      addHdrTiming(hdrPerf, "domLayerSeekMs", timingStart);
+
+      // 2. Run frame injector to set correct SDR video visibility
+      if (beforeCaptureHook) {
+        timingStart = Date.now();
+        await beforeCaptureHook(domSession.page, time);
+        addHdrTiming(hdrPerf, "domLayerInjectMs", timingStart);
+      }
+
+      // 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
+      timingStart = Date.now();
+      await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
+      addHdrTiming(hdrPerf, "domMaskApplyMs", timingStart);
+
+      // 4. Screenshot
+      timingStart = Date.now();
+      const domPng = await captureAlphaPng(domSession.page, width, height);
+      addHdrTiming(hdrPerf, "domScreenshotMs", timingStart);
+
+      // 5. Tear down the mask
+      timingStart = Date.now();
+      await removeDomLayerMask(domSession.page, hideIds);
+      addHdrTiming(hdrPerf, "domMaskRemoveMs", timingStart);
+
+      try {
+        timingStart = Date.now();
+        const { data: domRgba } = decodePng(domPng);
+        addHdrTiming(hdrPerf, "domPngDecodeMs", timingStart);
+        const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
+        const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
+        timingStart = Date.now();
+        blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer);
+        addHdrTiming(hdrPerf, "domBlitMs", timingStart);
+        if (shouldLog && debugDumpDir) {
+          const after = countNonZeroRgb48(canvas);
+          const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
+          const dumpPath = join(debugDumpDir, dumpName);
+          writeFileExclusiveSync(dumpPath, domPng);
+          log.info("[diag] dom layer blit", {
+            frame: debugFrameIndex,
+            layerIdx,
+            layerIds: layer.elementIds,
+            hideCount: hideIds.length,
+            pngBytes: domPng.length,
+            alphaPixels,
+            pixelsAdded: after - before,
+            totalNonZero: after,
+            dumpPath,
+          });
+        }
+      } catch (err) {
+        log.warn("DOM layer decode/blit failed; skipping overlay", {
+          layerIds: layer.elementIds,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  if (shouldLog && debugDumpDir) {
+    const finalNonZero = countNonZeroRgb48(canvas);
+    log.info("[diag] compositeToBuffer end", {
+      frame: debugFrameIndex,
+      finalNonZeroPixels: finalNonZero,
+      totalPixels: width * height,
+      coverage: ((finalNonZero / (width * height)) * 100).toFixed(1) + "%",
+    });
+  }
+}
diff --git a/packages/producer/src/services/render/perfSummary.ts b/packages/producer/src/services/render/perfSummary.ts
index b736cf4509..cce8e69710 100644
--- a/packages/producer/src/services/render/perfSummary.ts
+++ b/packages/producer/src/services/render/perfSummary.ts
@@ -4,10 +4,9 @@
  */
 
 import { fpsToNumber } from "@hyperframes/core";
+import type { CaptureCalibrationSample, CaptureCostEstimate } from "./captureCost.js";
 import type {
   CaptureAttemptSummary,
-  CaptureCalibrationSample,
-  CaptureCostEstimate,
   HdrDiagnostics,
   RenderJob,
   RenderPerfSummary,
diff --git a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
index 8c2b923cf9..a6fa7dc38a 100644
--- a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
+++ b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
@@ -23,14 +23,13 @@ import {
 import type { ProducerLogger } from "../../../logger.js";
 import {
   type HdrCompositeContext,
-  type HdrPerfCollector,
   type HdrVideoFrameSource,
   type TransitionRange,
-  addHdrTiming,
   blitHdrImageLayer,
   blitHdrVideoLayer,
   closeHdrVideoFrameSource,
-} from "../../renderOrchestrator.js";
+} from "../../hdrCompositor.js";
+import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
 
 // ─── Hybrid path gating + partitioning ─────────────────────────────────────
 
diff --git a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
index 7b0fbaeea1..d78a03d367 100644
--- a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
@@ -38,13 +38,11 @@ import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
 import {
   type HdrCompositeContext,
-  type HdrPerfCollector,
-  type ProgressCallback,
-  type RenderJob,
   type TransitionRange,
-  addHdrTiming,
   compositeHdrFrame,
-} from "../../renderOrchestrator.js";
+} from "../../hdrCompositor.js";
+import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
+import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import { writeFileExclusiveSync } from "../shared.js";
 import {
   type ShaderTransitionWorkerPool,
diff --git a/packages/producer/src/services/render/stages/captureHdrResources.ts b/packages/producer/src/services/render/stages/captureHdrResources.ts
index c50b736541..76129dd5fb 100644
--- a/packages/producer/src/services/render/stages/captureHdrResources.ts
+++ b/packages/producer/src/services/render/stages/captureHdrResources.ts
@@ -36,12 +36,8 @@ import {
 } from "@hyperframes/engine";
 import { fpsToFfmpegArg } from "@hyperframes/core";
 import type { ProducerLogger } from "../../../logger.js";
-import type {
-  HdrDiagnostics,
-  HdrImageBuffer,
-  HdrVideoFrameSource,
-  RenderJob,
-} from "../../renderOrchestrator.js";
+import type { HdrImageBuffer, HdrVideoFrameSource } from "../../hdrCompositor.js";
+import type { HdrDiagnostics, RenderJob } from "../../renderOrchestrator.js";
 import type { CompositionMetadata } from "../shared.js";
 
 const NO_FOLLOW_FLAG = constants.O_NOFOLLOW ?? 0;
diff --git a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
index 883cd29452..5360bd980d 100644
--- a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
@@ -23,13 +23,11 @@ import {
 import type { ProducerLogger } from "../../../logger.js";
 import {
   type HdrCompositeContext,
-  type HdrPerfCollector,
-  type ProgressCallback,
-  type RenderJob,
   type TransitionRange,
-  addHdrTiming,
   compositeHdrFrame,
-} from "../../renderOrchestrator.js";
+} from "../../hdrCompositor.js";
+import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
+import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import { writeFileExclusiveSync } from "../shared.js";
 import {
   captureSceneIntoBuffer,
@@ -57,7 +55,7 @@ export interface SequentialLoopInput {
   hdrTargetTransfer: "pq" | "hlg" | undefined;
   hdrVideoEndTimes: Map<string, number>;
   cleanedUpVideos: Set<string>;
-  hdrVideoFrameSources: Map<string, import("../../renderOrchestrator.js").HdrVideoFrameSource>;
+  hdrVideoFrameSources: Map<string, import("../../hdrCompositor.js").HdrVideoFrameSource>;
   debugDumpEnabled: boolean;
   debugDumpDir: string | null;
   assertNotAborted: () => void;
diff --git a/packages/producer/src/services/render/stages/captureHdrStage.ts b/packages/producer/src/services/render/stages/captureHdrStage.ts
index 215df1fc91..3c567abdee 100644
--- a/packages/producer/src/services/render/stages/captureHdrStage.ts
+++ b/packages/producer/src/services/render/stages/captureHdrStage.ts
@@ -57,17 +57,14 @@ import type { ProducerLogger } from "../../../logger.js";
 import { createHdrImageTransferCache } from "../../hdrImageTransferCache.js";
 import {
   type HdrCompositeContext,
-  type HdrDiagnostics,
-  type HdrPerfCollector,
   type HdrTransitionMeta,
   type HdrVideoFrameSource,
-  type ProgressCallback,
-  type RenderJob,
   type TransitionRange,
   closeHdrVideoFrameSource,
-  createHdrPerfCollector,
   resolveCompositeTransfer,
-} from "../../renderOrchestrator.js";
+} from "../../hdrCompositor.js";
+import { type HdrPerfCollector, createHdrPerfCollector } from "../hdrPerf.js";
+import type { HdrDiagnostics, ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import type { CompositionMetadata } from "../shared.js";
 import {
   decodeHdrImageBuffers,
diff --git a/packages/producer/src/services/render/stages/extractVideosStage.ts b/packages/producer/src/services/render/stages/extractVideosStage.ts
index 4aa3a52bd7..db08836ab5 100644
--- a/packages/producer/src/services/render/stages/extractVideosStage.ts
+++ b/packages/producer/src/services/render/stages/extractVideosStage.ts
@@ -48,10 +48,9 @@ import { fpsToNumber } from "@hyperframes/core";
 import {
   collectVideoMetadataHints,
   collectVideoReadinessSkipIds,
-  materializeExtractedFramesForCompiledDir,
   type RenderJob,
 } from "../../renderOrchestrator.js";
-import { type CompositionMetadata } from "../shared.js";
+import { materializeExtractedFramesForCompiledDir, type CompositionMetadata } from "../shared.js";
 import type { ProducerLogger } from "../../../logger.js";
 
 export interface ExtractVideosStageInput {
diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index 5c19b16f27..4e8d5d315c 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -13,10 +13,9 @@ import {
   findMissingFrameRanges,
   getNextRetryWorkerCount,
   isRecoverableParallelCaptureError,
-  resolveCompositeTransfer,
-  shouldUseLayeredComposite,
   shouldUseStreamingEncode,
 } from "./renderOrchestrator.js";
+import { resolveCompositeTransfer, shouldUseLayeredComposite } from "./hdrCompositor.js";
 import {
   createCaptureCalibrationConfig,
   estimateCaptureCostMultiplier,
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 31ff18d4f8..44e8d231e2 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -1,4 +1,4 @@
-// fallow-ignore-file unused-export unused-type circular-dependency code-duplication complexity
+// fallow-ignore-file unused-type circular-dependency code-duplication complexity
 /**
  * Render Orchestrator Service
  *
@@ -36,8 +36,6 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
-  readSync,
-  closeSync,
   readdirSync,
   rmSync,
   statSync,
@@ -52,7 +50,6 @@ import {
   resolveConfig,
   type ExtractionResult,
   type ExtractionPhaseBreakdown,
-  type HdrTransfer,
   closeCaptureSession,
   type CaptureOptions,
   type CaptureVideoMetadataHint,
@@ -65,18 +62,6 @@ import {
   mergeWorkerFrames,
   type ParallelProgress,
   type WorkerTask,
-  captureAlphaPng,
-  applyDomLayerMask,
-  removeDomLayerMask,
-  decodePng,
-  blitRgba8OverRgb48le,
-  blitRgb48leRegion,
-  groupIntoLayers,
-  blitRgb48leAffine,
-  parseTransformMatrix,
-  convertTransfer,
-  type ElementStackingInfo,
-  type HfTransitionMeta,
   getSystemTotalMb,
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
   assertConfiguredFfmpegBinariesExist,
@@ -91,13 +76,11 @@ import {
   VIRTUAL_TIME_SHIM,
 } from "./fileServer.js";
 import { defaultLogger, type ProducerLogger } from "../logger.js";
-import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
 import {
   createCompiledFrameSrcResolver,
   createMemorySampler,
   type MemorySampler,
   updateJobStatus,
-  writeFileExclusiveSync,
 } from "./render/shared.js";
 import { buildRenderErrorDetails, cleanupRenderResources, safeCleanup } from "./render/cleanup.js";
 import { normalizeErrorMessage } from "../utils/errorMessage.js";
@@ -118,7 +101,7 @@ import {
   type RenderExtractionObservability,
   type RenderObservabilitySummary,
 } from "./render/observability.js";
-import { type HdrPerfCollector, type HdrPerfSummary, addHdrTiming } from "./render/hdrPerf.js";
+import { type HdrPerfCollector, type HdrPerfSummary } from "./render/hdrPerf.js";
 import { runCompileStage } from "./render/stages/compileStage.js";
 import { runProbeStage } from "./render/stages/probeStage.js";
 import { runExtractVideosStage } from "./render/stages/extractVideosStage.js";
@@ -128,6 +111,7 @@ import { runCaptureStreamingStage } from "./render/stages/captureStreamingStage.
 import { runCaptureHdrStage } from "./render/stages/captureHdrStage.js";
 import { runEncodeStage } from "./render/stages/encodeStage.js";
 import { runAssembleStage } from "./render/stages/assembleStage.js";
+import { shouldUseLayeredComposite } from "./hdrCompositor.js";
 
 function sampleDirectoryBytes(dir: string): number {
   let total = 0;
@@ -182,47 +166,6 @@ function summarizeExtractionObservability(
   };
 }
 
-// Diagnostic helpers used by the HDR layered compositor when KEEP_TEMP=1
-// is set. They are pure (capture no state), so we keep them at module scope
-// to avoid re-creating closures per frame and to make them callable from
-// any future composite path that needs to log non-zero pixel counts.
-function countNonZeroAlpha(rgba: Uint8Array): number {
-  let n = 0;
-  for (let p = 3; p < rgba.length; p += 4) {
-    if (rgba[p] !== 0) n++;
-  }
-  return n;
-}
-
-function countNonZeroRgb48(buf: Uint8Array): number {
-  let n = 0;
-  for (let p = 0; p < buf.length; p += 6) {
-    if (
-      buf[p] !== 0 ||
-      buf[p + 1] !== 0 ||
-      buf[p + 2] !== 0 ||
-      buf[p + 3] !== 0 ||
-      buf[p + 4] !== 0 ||
-      buf[p + 5] !== 0
-    )
-      n++;
-  }
-  return n;
-}
-
-/**
- * Metadata for a shader transition between two scenes, extracted from
- * `window.__hf.transitions`. Re-exported from the engine so the producer
- * shares the contract with composition runtime code.
- */
-export type HdrTransitionMeta = HfTransitionMeta;
-
-/** Pre-computed frame range for an active transition. */
-export interface TransitionRange extends HdrTransitionMeta {
-  startFrame: number;
-  endFrame: number;
-}
-
 export type RenderStatus =
   | "queued"
   | "preprocessing"
@@ -379,36 +322,6 @@ export interface HdrDiagnostics {
   imageDecodeFailures: number;
 }
 
-// HDR-pipeline perf collector lives in `./render/hdrPerf.ts`. Re-exported
-// from this module so the existing `import { ... } from "./renderOrchestrator"`
-// callers keep working unchanged.
-export {
-  type HdrPerfCollector,
-  type HdrPerfSummary,
-  type HdrPerfTimingKey,
-  addHdrTiming,
-  createHdrPerfCollector,
-  finalizeHdrPerf,
-} from "./render/hdrPerf.js";
-
-// Capture-cost calibration helpers and constants live in `./render/captureCost.ts`.
-// Re-exported here for backwards compatibility with existing
-// `import { ... } from "./renderOrchestrator"` callers.
-export {
-  type CaptureCalibrationOutcome,
-  type CaptureCalibrationSample,
-  type CaptureCostEstimate,
-  createCaptureCalibrationConfig,
-  createFailedCaptureCalibrationEstimate,
-  estimateCaptureCostMultiplier,
-  estimateMeasuredCaptureCostMultiplier,
-  logCaptureCalibrationResult,
-  measureCaptureCostFromSession,
-  resolveRenderWorkerCount,
-  runCaptureCalibration,
-  selectCaptureCalibrationFrames,
-} from "./render/captureCost.js";
-
 export interface FrameRange {
   startFrame: number;
   endFrame: number;
@@ -501,15 +414,6 @@ function installDebugLogger(logPath: string, log: ProducerLogger = defaultLogger
   };
 }
 
-// Compile-output helpers (`createCompiledFrameSrcResolver`,
-// `materializeExtractedFramesForCompiledDir`) live in `./render/shared.ts`.
-// Re-exported from this module for backwards compatibility with existing
-// `import { ... } from "./renderOrchestrator"` call sites.
-export {
-  createCompiledFrameSrcResolver,
-  materializeExtractedFramesForCompiledDir,
-} from "./render/shared.js";
-
 export function collectVideoReadinessSkipIds(
   nativeHdrVideoIds: ReadonlySet<string>,
   extractedVideos: readonly ExtractedVideoReadinessInput[],
@@ -624,12 +528,6 @@ export function isRecoverableParallelCaptureError(error: unknown): boolean {
   );
 }
 
-// `shouldFallbackToScreenshotAfterCalibrationError` lives in
-// `./render/captureCost.ts` alongside the calibration runner. Re-exported
-// here for backwards compatibility with existing
-// `import { ... } from "./renderOrchestrator"` callers.
-export { shouldFallbackToScreenshotAfterCalibrationError } from "./render/captureCost.js";
-
 function countCapturedFrames(
   totalFrames: number,
   framesDir: string,
@@ -779,619 +677,6 @@ export async function executeDiskCaptureWithAdaptiveRetry(options: {
   }
 }
 
-/**
- * Crop an rgb48le buffer to a sub-region. Returns a new Buffer containing
- * only the cropped pixels.
- */
-function cropRgb48le(
-  src: Buffer,
-  srcW: number,
-  srcH: number,
-  cropX: number,
-  cropY: number,
-  cropW: number,
-  cropH: number,
-): Buffer {
-  const BPP = 6;
-  const dst = Buffer.alloc(cropW * cropH * BPP);
-  for (let row = 0; row < cropH; row++) {
-    const srcRow = cropY + row;
-    if (srcRow < 0 || srcRow >= srcH) continue;
-    const srcOff = (srcRow * srcW + cropX) * BPP;
-    const dstOff = row * cropW * BPP;
-    const copyLen = Math.min(cropW, srcW - cropX) * BPP;
-    if (copyLen > 0) src.copy(dst, dstOff, srcOff, srcOff + copyLen);
-  }
-  return dst;
-}
-
-/**
- * Blit a single HDR video layer onto an rgb48le canvas.
- *
- * Shared between the normal-frame compositing path (compositeToBuffer)
- * and the transition dual-scene compositing loop to avoid duplicating
- * the frame lookup, raw read, transfer, transform, and blit logic.
- */
-export interface HdrVideoFrameSource {
-  dir: string;
-  rawPath: string;
-  fd: number;
-  width: number;
-  height: number;
-  frameSize: number;
-  frameCount: number;
-  scratch: Buffer;
-}
-
-export function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: ProducerLogger): void {
-  try {
-    closeSync(source.fd);
-  } catch (err) {
-    log?.warn("Failed to close HDR raw frame file", {
-      rawPath: source.rawPath,
-      error: err instanceof Error ? err.message : String(err),
-    });
-  }
-}
-
-export function blitHdrVideoLayer(
-  canvas: Buffer,
-  el: ElementStackingInfo,
-  time: number,
-  fps: number,
-  hdrVideoFrameSources: Map<string, HdrVideoFrameSource>,
-  hdrStartTimes: Map<string, number>,
-  width: number,
-  height: number,
-  log?: ProducerLogger,
-  sourceTransfer?: HdrTransfer,
-  targetTransfer?: HdrTransfer,
-  hdrPerf?: HdrPerfCollector,
-): void {
-  const frameSource = hdrVideoFrameSources.get(el.id);
-  const startTime = hdrStartTimes.get(el.id);
-  if (!frameSource || startTime === undefined || el.opacity <= 0) {
-    return;
-  }
-
-  // Frame index within the video. Clamp to the extracted raw frame count so
-  // a composition that outlives the source clip freezes on the last frame,
-  // matching Chrome's <video> behavior.
-  const videoFrameIndex = Math.round((time - startTime) * fps) + 1;
-  if (videoFrameIndex < 1) return;
-  const effectiveIndex = Math.min(videoFrameIndex, frameSource.frameCount);
-  if (effectiveIndex < 1) return;
-  const frameOffset = (effectiveIndex - 1) * frameSource.frameSize;
-
-  try {
-    if (hdrPerf) hdrPerf.hdrVideoLayerBlits += 1;
-    let timingStart = Date.now();
-    const bytesRead = readSync(
-      frameSource.fd,
-      frameSource.scratch,
-      0,
-      frameSource.frameSize,
-      frameOffset,
-    );
-    if (bytesRead !== frameSource.frameSize) return;
-    const hdrRgb = frameSource.scratch;
-    const srcW = frameSource.width;
-    const srcH = frameSource.height;
-    addHdrTiming(hdrPerf, "hdrVideoReadDecodeMs", timingStart);
-
-    // Convert between HDR transfer functions if source doesn't match output
-    if (sourceTransfer && targetTransfer && sourceTransfer !== targetTransfer) {
-      timingStart = Date.now();
-      convertTransfer(hdrRgb, sourceTransfer, targetTransfer);
-      addHdrTiming(hdrPerf, "hdrVideoTransferMs", timingStart);
-    }
-
-    const viewportMatrix = parseTransformMatrix(el.transform);
-
-    // Pass border-radius for rounded-corner masking (only when non-zero)
-    const br = el.borderRadius;
-    const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
-    const borderRadiusParam = hasBorderRadius ? br : undefined;
-
-    // Apply ancestor overflow:hidden clip rect by constraining the blit
-    // bounds. For the no-transform (region) path, we crop the source
-    // image and adjust the destination position. For the affine path,
-    // clip rect support is not yet implemented (would require per-pixel
-    // scissor in the affine blit); log a warning and skip clipping.
-    let blitX = el.x;
-    let blitY = el.y;
-    let blitSrcX = 0;
-    let blitSrcY = 0;
-    let blitW = srcW;
-    let blitH = srcH;
-    let clipped = false;
-
-    if (el.clipRect) {
-      const cr = el.clipRect;
-      const cx1 = Math.max(blitX, cr.x);
-      const cy1 = Math.max(blitY, cr.y);
-      const cx2 = Math.min(blitX + blitW, cr.x + cr.width);
-      const cy2 = Math.min(blitY + blitH, cr.y + cr.height);
-      if (cx2 <= cx1 || cy2 <= cy1) return; // fully clipped
-      blitSrcX = cx1 - blitX;
-      blitSrcY = cy1 - blitY;
-      blitW = cx2 - cx1;
-      blitH = cy2 - cy1;
-      blitX = cx1;
-      blitY = cy1;
-      clipped = true;
-    }
-
-    // Detect translation-only matrix (no scale/rotation) — route through the
-    // region path which supports clip rects. Chrome reports a viewport matrix
-    // for all HDR elements, even untransformed ones or those with only layout
-    // translation (e.g. `left: 960px` → `matrix(1,0,0,1,960,0)`). The region
-    // blit handles translation via el.x/el.y, so we only need the affine path
-    // for actual scale/rotation transforms.
-    // parseTransformMatrix returns a 6-element array or null — length check unnecessary.
-    const isTranslationOnly = !!(
-      viewportMatrix &&
-      Math.abs(viewportMatrix[0]! - 1) < 0.001 &&
-      Math.abs(viewportMatrix[1]!) < 0.001 &&
-      Math.abs(viewportMatrix[2]!) < 0.001 &&
-      Math.abs(viewportMatrix[3]! - 1) < 0.001
-    );
-
-    timingStart = Date.now();
-    if (viewportMatrix && !isTranslationOnly) {
-      if (clipped && log) {
-        log.debug(
-          `HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
-        );
-      }
-      blitRgb48leAffine(
-        canvas,
-        hdrRgb,
-        viewportMatrix,
-        srcW,
-        srcH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else if (clipped) {
-      // Crop the source buffer to the clipped region before blitting
-      const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
-      blitRgb48leRegion(
-        canvas,
-        croppedBuf,
-        blitX,
-        blitY,
-        blitW,
-        blitH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else {
-      blitRgb48leRegion(
-        canvas,
-        hdrRgb,
-        el.x,
-        el.y,
-        srcW,
-        srcH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    }
-    addHdrTiming(hdrPerf, "hdrVideoBlitMs", timingStart);
-  } catch (err) {
-    if (log) {
-      log.debug(`HDR blit failed for ${el.id}`, {
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-}
-
-/**
- * Pre-decoded HDR image buffer with its native pixel dimensions.
- *
- * Static images decode exactly once at setup time and are blitted on every
- * visible frame, unlike video frames which are read fresh per timestamp.
- */
-export interface HdrImageBuffer {
-  data: Buffer;
-  width: number;
-  height: number;
-}
-
-/**
- * Blit a single HDR image layer onto an rgb48le canvas.
- *
- * Image-equivalent of `blitHdrVideoLayer` — the buffer is pre-decoded and
- * static, so there's no time-based frame lookup or per-frame PNG read.
- */
-export function blitHdrImageLayer(
-  canvas: Buffer,
-  el: ElementStackingInfo,
-  hdrImageBuffers: Map<string, HdrImageBuffer>,
-  hdrImageTransferCache: HdrImageTransferCache,
-  width: number,
-  height: number,
-  log?: ProducerLogger,
-  sourceTransfer?: HdrTransfer,
-  targetTransfer?: HdrTransfer,
-  hdrPerf?: HdrPerfCollector,
-): void {
-  const buf = hdrImageBuffers.get(el.id);
-  if (!buf || el.opacity <= 0) {
-    return;
-  }
-  if (el.clipRect && log) {
-    log.debug(`HDR clip rect on image element ${el.id} — clip not yet supported for images`);
-  }
-
-  try {
-    if (hdrPerf) hdrPerf.hdrImageLayerBlits += 1;
-    // The cache returns `buf.data` unchanged when no conversion is needed,
-    // and otherwise returns a per-(imageId, targetTransfer) buffer that was
-    // converted exactly once and reused across every subsequent frame.
-    let timingStart = Date.now();
-    const hdrRgb =
-      sourceTransfer && targetTransfer
-        ? hdrImageTransferCache.getConverted(el.id, sourceTransfer, targetTransfer, buf.data)
-        : buf.data;
-    addHdrTiming(hdrPerf, "hdrImageTransferMs", timingStart);
-
-    const viewportMatrix = parseTransformMatrix(el.transform);
-
-    const br = el.borderRadius;
-    const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
-    const borderRadiusParam = hasBorderRadius ? br : undefined;
-
-    timingStart = Date.now();
-    if (viewportMatrix) {
-      blitRgb48leAffine(
-        canvas,
-        hdrRgb,
-        viewportMatrix,
-        buf.width,
-        buf.height,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else {
-      blitRgb48leRegion(
-        canvas,
-        hdrRgb,
-        el.x,
-        el.y,
-        buf.width,
-        buf.height,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    }
-    addHdrTiming(hdrPerf, "hdrImageBlitMs", timingStart);
-  } catch (err) {
-    if (log) {
-      log.debug(`HDR image blit failed for ${el.id}`, {
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-}
-
-/**
- * Dependencies passed to `compositeHdrFrame`.
- *
- * Every field except the per-frame arguments is captured once when the HDR
- * render path opens its `try { ... }` block and reused across every frame —
- * extracting them into an explicit struct lets the helper live at module
- * scope (no closure-over-renderJob) and keeps the per-call signature small.
- */
-type CompositeTransfer = HdrTransfer | "srgb";
-
-export function shouldUseLayeredComposite(options: {
-  hasHdrContent: boolean;
-  hasShaderTransitions: boolean;
-  isPngSequence: boolean;
-}): boolean {
-  return options.hasHdrContent || (options.hasShaderTransitions && !options.isPngSequence);
-}
-
-export function resolveCompositeTransfer(
-  hasHdrContent: boolean,
-  effectiveHdr: { transfer: HdrTransfer } | undefined,
-): CompositeTransfer {
-  return hasHdrContent && effectiveHdr ? effectiveHdr.transfer : "srgb";
-}
-
-export interface HdrCompositeContext {
-  log: ProducerLogger;
-  domSession: CaptureSession;
-  beforeCaptureHook: BeforeCaptureHook | null;
-  width: number;
-  height: number;
-  fps: number;
-  compositeTransfer: CompositeTransfer;
-  nativeHdrImageIds: Set<string>;
-  hdrImageBuffers: Map<string, HdrImageBuffer>;
-  hdrImageTransferCache: HdrImageTransferCache;
-  hdrVideoFrameSources: Map<string, HdrVideoFrameSource>;
-  hdrVideoStartTimes: Map<string, number>;
-  imageTransfers: Map<string, HdrTransfer>;
-  videoTransfers: Map<string, HdrTransfer>;
-  debugDumpEnabled: boolean;
-  debugDumpDir: string | null;
-  hdrPerf?: HdrPerfCollector;
-}
-
-/**
- * Composite a single HDR frame into a pre-allocated `rgb48le` canvas.
- *
- * Bottom-to-top z-order: HDR layers are blitted directly from cached image
- * buffers / extracted video frames; DOM layers are screenshotted with a
- * mass-hide mask (so each layer paints only its own elements) and then
- * blended into the canvas via `blitRgba8OverRgb48le` in the active HDR
- * transfer space.
- *
- * The `elementFilter` parameter exists so the transition path can composite
- * each scene independently; pass `undefined` for whole-stack rendering.
- *
- * @param ctx - Long-lived dependencies (logger, browser session, dimensions,
- *              HDR layer maps). Captured once per render — see
- *              {@link HdrCompositeContext}.
- * @param canvas - Pre-allocated `width * height * 6` byte buffer. Caller must
- *                 zero-fill before every frame (this helper does not).
- * @param time - Seek time in seconds.
- * @param fullStacking - Stacking info for ALL elements at this time. Even when
- *                       filtering, every other element id is needed to build
- *                       the DOM-layer hide-list.
- * @param elementFilter - When set, only elements whose id is in the set are
- *                        composited.
- * @param debugFrameIndex - Frame index used to label per-layer diagnostic
- *                          dumps. Pass `-1` to disable per-layer dumps even
- *                          when `KEEP_TEMP=1` (e.g. for warmup frames).
- */
-export async function compositeHdrFrame(
-  ctx: HdrCompositeContext,
-  canvas: Buffer,
-  time: number,
-  fullStacking: ElementStackingInfo[],
-  elementFilter?: Set<string>,
-  debugFrameIndex: number = -1,
-): Promise<void> {
-  const {
-    log,
-    domSession,
-    beforeCaptureHook,
-    width,
-    height,
-    fps,
-    compositeTransfer,
-    nativeHdrImageIds,
-    hdrImageBuffers,
-    hdrImageTransferCache,
-    hdrVideoFrameSources,
-    hdrVideoStartTimes,
-    imageTransfers,
-    videoTransfers,
-    debugDumpEnabled,
-    debugDumpDir,
-    hdrPerf,
-  } = ctx;
-
-  const filteredStacking = elementFilter
-    ? fullStacking.filter((e) => elementFilter.has(e.id))
-    : fullStacking;
-
-  // Zero-opacity elements stay in the stacking for correct hide-list
-  // generation (their <img> replacements must be hidden from sibling
-  // screenshots). The actual blit is skipped in the compositing loop below.
-  const layers = groupIntoLayers(filteredStacking);
-
-  const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
-  if (shouldLog) {
-    log.info("[diag] compositeToBuffer plan", {
-      frame: debugFrameIndex,
-      time: time.toFixed(3),
-      filterSize: elementFilter?.size,
-      fullStackingCount: fullStacking.length,
-      filteredCount: filteredStacking.length,
-      layerCount: layers.length,
-      layers: layers.map((l) =>
-        l.type === "hdr"
-          ? {
-              type: "hdr",
-              id: l.element.id,
-              z: l.element.zIndex,
-              visible: l.element.visible,
-              opacity: l.element.opacity,
-              bounds: `${Math.round(l.element.x)},${Math.round(l.element.y)} ${Math.round(l.element.width)}x${Math.round(l.element.height)}`,
-            }
-          : { type: "dom", ids: l.elementIds },
-      ),
-    });
-  }
-
-  for (const [layerIdx, layer] of layers.entries()) {
-    if (layer.type === "hdr") {
-      // Skip zero-opacity HDR elements — their parent scene may have faded out.
-      if (layer.element.opacity <= 0) continue;
-      const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
-      const isHdrImage = nativeHdrImageIds.has(layer.element.id);
-      const hdrTargetTransfer = compositeTransfer === "srgb" ? undefined : compositeTransfer;
-      if (isHdrImage) {
-        blitHdrImageLayer(
-          canvas,
-          layer.element,
-          hdrImageBuffers,
-          hdrImageTransferCache,
-          width,
-          height,
-          log,
-          imageTransfers.get(layer.element.id),
-          hdrTargetTransfer,
-          hdrPerf,
-        );
-      } else {
-        blitHdrVideoLayer(
-          canvas,
-          layer.element,
-          time,
-          fps,
-          hdrVideoFrameSources,
-          hdrVideoStartTimes,
-          width,
-          height,
-          log,
-          videoTransfers.get(layer.element.id),
-          hdrTargetTransfer,
-          hdrPerf,
-        );
-      }
-      if (shouldLog) {
-        const after = countNonZeroRgb48(canvas);
-        if (isHdrImage) {
-          const buf = hdrImageBuffers.get(layer.element.id);
-          log.info("[diag] hdr layer blit", {
-            frame: debugFrameIndex,
-            layerIdx,
-            id: layer.element.id,
-            kind: "image",
-            pixelsAdded: after - before,
-            totalNonZero: after,
-            bufferDecoded: !!buf,
-            bufferDims: buf ? `${buf.width}x${buf.height}` : null,
-          });
-        } else {
-          const frameSource = hdrVideoFrameSources.get(layer.element.id);
-          const startTime = hdrVideoStartTimes.get(layer.element.id) ?? 0;
-          const localTime = time - startTime;
-          const frameNum = Math.floor(localTime * fps) + 1;
-          log.info("[diag] hdr layer blit", {
-            frame: debugFrameIndex,
-            layerIdx,
-            id: layer.element.id,
-            kind: "video",
-            pixelsAdded: after - before,
-            totalNonZero: after,
-            startTime,
-            localTime: localTime.toFixed(3),
-            hdrFrameNum: frameNum,
-            rawPath: frameSource?.rawPath ?? null,
-            frameCount: frameSource?.frameCount ?? null,
-          });
-        }
-      }
-    } else {
-      // DOM layer: capture only elements in this layer.
-      //
-      // Each layer gets a fresh seek + inject cycle to guarantee correct
-      // visibility state — avoids fragile interactions between the frame
-      // injector, applyDomLayerMask, removeDomLayerMask, and GSAP re-seek.
-      //
-      // The mask:
-      //   - mass-hides every body descendant via stylesheet
-      //   - re-shows the layer's elements (and their descendants and
-      //     their injected `__render_frame_*` siblings) so deep-nested
-      //     content stays visible even though intermediate ancestors
-      //     are hidden
-      //   - inline-hides every other data-start element so they don't
-      //     paint when they happen to be descendants of a layer element
-      //     (most importantly: HDR videos and other-layer SDR videos
-      //     that live inside `#root` when capturing the root DOM layer)
-      //
-      // Without the mask, every DOM screenshot captures the full page
-      // (root background, sibling scenes' static content, the painted
-      // border/box-shadow of cards, etc.) and the resulting opaque
-      // pixels overwrite previously composited HDR content beneath.
-      const allElementIds = fullStacking.map((e) => e.id);
-      const layerIds = new Set(layer.elementIds);
-      const hideIds = allElementIds.filter((id) => !layerIds.has(id));
-      if (hdrPerf) hdrPerf.domLayerCaptures += 1;
-
-      // 1. Seek GSAP to restore all animated properties from clean state
-      let timingStart = Date.now();
-      await domSession.page.evaluate((t: number) => {
-        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-      }, time);
-      addHdrTiming(hdrPerf, "domLayerSeekMs", timingStart);
-
-      // 2. Run frame injector to set correct SDR video visibility
-      if (beforeCaptureHook) {
-        timingStart = Date.now();
-        await beforeCaptureHook(domSession.page, time);
-        addHdrTiming(hdrPerf, "domLayerInjectMs", timingStart);
-      }
-
-      // 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
-      timingStart = Date.now();
-      await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
-      addHdrTiming(hdrPerf, "domMaskApplyMs", timingStart);
-
-      // 4. Screenshot
-      timingStart = Date.now();
-      const domPng = await captureAlphaPng(domSession.page, width, height);
-      addHdrTiming(hdrPerf, "domScreenshotMs", timingStart);
-
-      // 5. Tear down the mask
-      timingStart = Date.now();
-      await removeDomLayerMask(domSession.page, hideIds);
-      addHdrTiming(hdrPerf, "domMaskRemoveMs", timingStart);
-
-      try {
-        timingStart = Date.now();
-        const { data: domRgba } = decodePng(domPng);
-        addHdrTiming(hdrPerf, "domPngDecodeMs", timingStart);
-        const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
-        const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
-        timingStart = Date.now();
-        blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer);
-        addHdrTiming(hdrPerf, "domBlitMs", timingStart);
-        if (shouldLog && debugDumpDir) {
-          const after = countNonZeroRgb48(canvas);
-          const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
-          const dumpPath = join(debugDumpDir, dumpName);
-          writeFileExclusiveSync(dumpPath, domPng);
-          log.info("[diag] dom layer blit", {
-            frame: debugFrameIndex,
-            layerIdx,
-            layerIds: layer.elementIds,
-            hideCount: hideIds.length,
-            pngBytes: domPng.length,
-            alphaPixels,
-            pixelsAdded: after - before,
-            totalNonZero: after,
-            dumpPath,
-          });
-        }
-      } catch (err) {
-        log.warn("DOM layer decode/blit failed; skipping overlay", {
-          layerIds: layer.elementIds,
-          error: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-  }
-
-  if (shouldLog && debugDumpDir) {
-    const finalNonZero = countNonZeroRgb48(canvas);
-    log.info("[diag] compositeToBuffer end", {
-      frame: debugFrameIndex,
-      finalNonZeroPixels: finalNonZero,
-      totalPixels: width * height,
-      coverage: ((finalNonZero / (width * height)) * 100).toFixed(1) + "%",
-    });
-  }
-}
-
 export type RenderConfigInput = Omit<RenderConfig, "fps"> & { fps: FpsInput };
 
 export function createRenderJob(config: RenderConfigInput): RenderJob {

From aeba3d7ce32c367b5b3d2299c5ac551c16ef2cee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 14:49:47 -0400
Subject: [PATCH 2/8] refactor(producer): delete 4 re-export shim files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

screenshotService.ts, videoFrameExtractor.ts, videoFrameInjector.ts,
and streamingEncoder.ts existed solely to re-export symbols from
@hyperframes/engine. No internal consumer imported from them except
index.ts → videoFrameInjector, which now imports directly from engine.
---
 packages/producer/src/index.ts                  |  2 +-
 .../producer/src/services/screenshotService.ts  | 13 -------------
 .../producer/src/services/streamingEncoder.ts   | 12 ------------
 .../src/services/videoFrameExtractor.ts         | 17 -----------------
 .../producer/src/services/videoFrameInjector.ts |  5 -----
 5 files changed, 1 insertion(+), 48 deletions(-)
 delete mode 100644 packages/producer/src/services/screenshotService.ts
 delete mode 100644 packages/producer/src/services/streamingEncoder.ts
 delete mode 100644 packages/producer/src/services/videoFrameExtractor.ts
 delete mode 100644 packages/producer/src/services/videoFrameInjector.ts

diff --git a/packages/producer/src/index.ts b/packages/producer/src/index.ts
index bdf507d613..5db76efbaf 100644
--- a/packages/producer/src/index.ts
+++ b/packages/producer/src/index.ts
@@ -52,7 +52,7 @@ export {
 } from "./services/fileServer.js";
 
 // ── Video frame injection (Hyperframes-specific hook) ───────────────────────
-export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
+export { createVideoFrameInjector } from "@hyperframes/engine";
 
 // ── Configuration ───────────────────────────────────────────────────────────
 export { resolveConfig, DEFAULT_CONFIG, type ProducerConfig } from "./config.js";
diff --git a/packages/producer/src/services/screenshotService.ts b/packages/producer/src/services/screenshotService.ts
deleted file mode 100644
index a00cf3e2b9..0000000000
--- a/packages/producer/src/services/screenshotService.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/**
- * Re-exported from @hyperframes/engine.
- * @see engine/src/services/screenshotService.ts for implementation.
- */
-export {
-  beginFrameCapture,
-  pageScreenshotCapture,
-  getCdpSession,
-  injectVideoFramesBatch,
-  syncVideoFrameVisibility,
-  cdpSessionCache,
-  type BeginFrameResult,
-} from "@hyperframes/engine";
diff --git a/packages/producer/src/services/streamingEncoder.ts b/packages/producer/src/services/streamingEncoder.ts
deleted file mode 100644
index 653c0b135b..0000000000
--- a/packages/producer/src/services/streamingEncoder.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-/**
- * Re-exported from @hyperframes/engine.
- * @see engine/src/services/streamingEncoder.ts for implementation.
- */
-export {
-  spawnStreamingEncoder,
-  createFrameReorderBuffer,
-  type StreamingEncoder,
-  type StreamingEncoderOptions,
-  type StreamingEncoderResult,
-  type FrameReorderBuffer,
-} from "@hyperframes/engine";
diff --git a/packages/producer/src/services/videoFrameExtractor.ts b/packages/producer/src/services/videoFrameExtractor.ts
deleted file mode 100644
index 136c096fd8..0000000000
--- a/packages/producer/src/services/videoFrameExtractor.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-/**
- * Re-exported from @hyperframes/engine.
- * @see engine/src/services/videoFrameExtractor.ts for implementation.
- */
-export {
-  parseVideoElements,
-  extractVideoFramesRange,
-  extractAllVideoFrames,
-  getFrameAtTime,
-  createFrameLookupTable,
-  FrameLookupTable,
-  type VideoElement,
-  type ExtractedFrames,
-  type ExtractionOptions,
-  type ExtractionResult,
-  type ExtractionPhaseBreakdown,
-} from "@hyperframes/engine";
diff --git a/packages/producer/src/services/videoFrameInjector.ts b/packages/producer/src/services/videoFrameInjector.ts
deleted file mode 100644
index df9c367862..0000000000
--- a/packages/producer/src/services/videoFrameInjector.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-/**
- * Re-exported from @hyperframes/engine.
- * @see engine/src/services/videoFrameInjector.ts for implementation.
- */
-export { createVideoFrameInjector } from "@hyperframes/engine";

From 21d5139d6daf07dc7e2ca56d6ede034fe4fb3504 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 14:50:06 -0400
Subject: [PATCH 3/8] refactor(producer): delete unused PNG decode/blit worker
 pool

The pool (455 LOC) and worker (127 LOC) were built speculatively for
pipelining Chrome screenshots with PNG decode/blit but were never
wired into any capture path. Zero non-test source files imported them.

Also removed the esbuild entry point from producer/build.mjs, the
tsup entry point + alpha-blit alias from cli/tsup.config.ts, and
the PNG worker bootstrap from cli/src/cli.ts.
---
 packages/cli/src/cli.ts                       |  20 +-
 packages/cli/tsup.config.ts                   |  16 -
 packages/producer/build.mjs                   |   5 -
 .../src/services/pngDecodeBlitWorker.ts       | 122 -----
 .../services/pngDecodeBlitWorkerPool.test.ts  | 384 ---------------
 .../src/services/pngDecodeBlitWorkerPool.ts   | 455 ------------------
 6 files changed, 5 insertions(+), 997 deletions(-)
 delete mode 100644 packages/producer/src/services/pngDecodeBlitWorker.ts
 delete mode 100644 packages/producer/src/services/pngDecodeBlitWorkerPool.test.ts
 delete mode 100644 packages/producer/src/services/pngDecodeBlitWorkerPool.ts

diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 298ef88fa5..372d13bfdf 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -22,34 +22,24 @@ for (const stream of [process.stdout, process.stderr]) {
 }
 
 // ── Worker entry path bootstrap (must run before any producer/engine load) ──
-// The hf#677 worker_threads pools (`pngDecodeBlitWorkerPool`,
-// `shaderTransitionWorkerPool`) live in the producer package and try to
-// resolve their worker entry by probing for sibling `.js` files next to
+// The shaderTransitionWorkerPool lives in the producer package and resolves
+// its worker entry by probing for a sibling `.js` file next to
 // `import.meta.url`. When this CLI is bundled by tsup, the producer code is
 // inlined into `cli.js`, but `import.meta.url` resolves to the producer's
 // own dist path (NOT cli.js) on some module-graph layouts — so the sibling
-// probe lands in a directory that does not contain the bundled workers.
-// We emit the worker entries next to cli.js (see tsup.config.ts) and tell
-// the pools where to find them via the published env-var overrides. The
-// pools have an explicit `workerEntryPath` factory option as the canonical
-// API, but setting the env vars here covers every call site without having
-// to thread the path through the renderOrchestrator → captureHdrStage →
-// captureHdrHybridLoop chain.
+// probe lands in a directory that does not contain the bundled worker.
+// We emit the worker entry next to cli.js (see tsup.config.ts) and tell
+// the pool where to find it via the published env-var override.
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 
-// fallow-ignore-next-line complexity
 (() => {
   const here = dirname(fileURLToPath(import.meta.url));
   const shader = join(here, "shaderTransitionWorker.js");
-  const png = join(here, "pngDecodeBlitWorker.js");
   if (!process.env.HF_SHADER_WORKER_ENTRY && existsSync(shader)) {
     process.env.HF_SHADER_WORKER_ENTRY = shader;
   }
-  if (!process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY && existsSync(png)) {
-    process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY = png;
-  }
 })();
 
 // ── Fast-path exits ─────────────────────────────────────────────────────────
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index e220eacbdb..9208dc9e94 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -7,20 +7,8 @@ const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url),
 };
 
 export default defineConfig({
-  // hf#732 lever-4: emit BOTH the CLI bundle and the PNG decode + alpha-blit
-  // worker entry. The producer's `pngDecodeBlitWorkerPool` instantiates a
-  // Node `worker_threads` Worker via `new Worker(<path>)`, which is a
-  // filesystem load — it cannot share the parent module graph. The pool's
-  // path resolver probes for `pngDecodeBlitWorker.js` next to its own loaded
-  // module (which lives inside `dist/cli.js` after the producer is
-  // `noExternal`'d and bundled in). Without this entry the file would not
-  // exist at runtime and the pool would either crash or silently fall back
-  // to inline decode/blit, killing the perf gain.
   entry: {
     cli: "src/cli.ts",
-    pngDecodeBlitWorker: "../producer/src/services/pngDecodeBlitWorker.ts",
-    // hf#677/#732: shader-blend worker. Same `new Worker(<path>)`
-    // bundling rationale as `pngDecodeBlitWorker` above.
     shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
   },
   format: ["esm"],
@@ -96,10 +84,6 @@ var __dirname = __hf_dirname(__filename);`,
       "@hyperframes/aws-lambda/sdk": resolve(__dirname, "../aws-lambda/src/sdk/index.ts"),
       // Same for the GCP adapter's SDK subpath barrel.
       "@hyperframes/gcp-cloud-run/sdk": resolve(__dirname, "../gcp-cloud-run/src/sdk/index.ts"),
-      // hf#732 lever-4: alias for the PNG decode+blit worker's import.
-      // `alphaBlit.ts` is import-free (only zlib) so the worker survives
-      // the worker_thread loader boundary directly via this TS source.
-      "@hyperframes/engine/alpha-blit": resolve(__dirname, "../engine/src/utils/alphaBlit.ts"),
       // hf#677 follow-up: the shader-blend worker imports from
       // `@hyperframes/engine/shader-transitions` (subpath export) — a
       // standalone TS file with zero internal imports that survives the
diff --git a/packages/producer/build.mjs b/packages/producer/build.mjs
index 4721ef6858..22fceae09f 100644
--- a/packages/producer/build.mjs
+++ b/packages/producer/build.mjs
@@ -59,11 +59,6 @@ const sharedOpts = {
 await Promise.all([
   build({ ...sharedOpts, entryPoints: ["src/index.ts"], outfile: "dist/index.js" }),
   build({ ...sharedOpts, entryPoints: ["src/server.ts"], outfile: "dist/public-server.js" }),
-  build({
-    ...sharedOpts,
-    entryPoints: ["src/services/pngDecodeBlitWorker.ts"],
-    outfile: "dist/services/pngDecodeBlitWorker.js",
-  }),
   build({
     ...sharedOpts,
     entryPoints: ["src/services/shaderTransitionWorker.ts"],
diff --git a/packages/producer/src/services/pngDecodeBlitWorker.ts b/packages/producer/src/services/pngDecodeBlitWorker.ts
deleted file mode 100644
index 41250a449a..0000000000
--- a/packages/producer/src/services/pngDecodeBlitWorker.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-/**
- * Worker entry point for off-main-thread PNG decode + alpha blit. The
- * companion to `pngDecodeBlitWorkerPool.ts`. See that file for the rationale
- * (hf#732 lever-4: overlap Chrome's screenshot with Node's decode+blit).
- *
- * Lifecycle:
- *
- * 1. Pool constructor spawns N of these workers up front.
- * 2. Main thread posts `{ png, pngOffset, pngLength, dest, destOffset,
- *    destLength, width, height, transfer }` with `transferList: [png, dest]`.
- *    Both underlying ArrayBuffers are detached on the sender; the caller
- *    must NOT touch them until the worker replies.
- * 3. Worker wraps each ArrayBuffer as a Node Buffer view (zero-copy),
- *    runs `decodePng` to get an RGBA8 Uint8Array, then `blitRgba8OverRgb48le`
- *    to composite the decoded pixels onto the rgb48le `dest` buffer in
- *    the requested transfer space.
- * 4. Worker posts `{ ok, png, dest, decodeMs, blitMs }` back with
- *    `transferList: [png, dest]`. Both ArrayBuffers return to the main
- *    thread; the caller swaps `result.dest` into its render state.
- * 5. On decode/blit exception, worker posts `{ ok: false, error, png,
- *    dest }` — both ArrayBuffers still returned so the caller can release
- *    them.
- *
- * The worker holds no per-frame state. The intermediate RGBA8 decode
- * buffer is allocated per-call and dropped on the worker side.
- *
- * Import strategy: identical to `shaderTransitionWorker.ts` — use the
- * `./alpha-blit` subpath export of `@hyperframes/engine` rather than the
- * package root, because the root pulls in the full engine graph and the
- * tsx loader's `.js → .ts` rewrite does not survive the Worker boundary
- * under dev/test.
- */
-
-import { parentPort } from "node:worker_threads";
-import { decodePng, blitRgba8OverRgb48le } from "@hyperframes/engine/alpha-blit";
-
-interface DecodeBlitJobRequest {
-  png: ArrayBuffer;
-  pngOffset: number;
-  pngLength: number;
-  dest: ArrayBuffer;
-  destOffset: number;
-  destLength: number;
-  width: number;
-  height: number;
-  transfer: string;
-}
-
-interface DecodeBlitJobOk {
-  ok: true;
-  png: ArrayBuffer;
-  dest: ArrayBuffer;
-  decodeMs: number;
-  blitMs: number;
-}
-
-interface DecodeBlitJobErr {
-  ok: false;
-  error: string;
-  png: ArrayBuffer;
-  dest: ArrayBuffer;
-}
-
-export type DecodeBlitJobResult = DecodeBlitJobOk | DecodeBlitJobErr;
-
-if (!parentPort) {
-  // Defensive — this module is only meaningful inside a worker_thread.
-  // eslint-disable-next-line no-console
-  console.warn("[pngDecodeBlitWorker] no parentPort; module loaded on main thread");
-} else {
-  parentPort.on("message", (msg: DecodeBlitJobRequest) => {
-    const { png, pngOffset, pngLength, dest, destOffset, destLength, width, height, transfer } =
-      msg;
-    // Re-wrap the transferred ArrayBuffers as Node Buffer views. The
-    // dispatcher in the pool normalizes inputs to offset-0 ArrayBuffers
-    // before transfer (avoiding the 8KB shared-pool DataCloneError), so
-    // pngOffset / destOffset are 0 and pngLength / destLength match the
-    // backing ArrayBuffer byteLength in practice. We still honor the
-    // forwarded values so the worker is robust if the dispatcher ever
-    // changes (e.g. ships a slice over a larger transferred ArrayBuffer).
-    const pngBuf = Buffer.from(png, pngOffset, pngLength);
-    const destBuf = Buffer.from(dest, destOffset, destLength);
-
-    try {
-      const decodeStart = Date.now();
-      const { data: rgba } = decodePng(pngBuf);
-      const decodeMs = Date.now() - decodeStart;
-
-      const blitStart = Date.now();
-      // `blitRgba8OverRgb48le` accepts the CompositeTransfer string as a
-      // typed union. The pool's `transfer` field is `string` for transport
-      // simplicity; the actual values flow through unchanged from the
-      // orchestrator's HdrCompositeContext and the function validates at
-      // its own boundary.
-      blitRgba8OverRgb48le(
-        rgba,
-        destBuf,
-        width,
-        height,
-        transfer as Parameters<typeof blitRgba8OverRgb48le>[4],
-      );
-      const blitMs = Date.now() - blitStart;
-
-      const reply: DecodeBlitJobOk = {
-        ok: true,
-        png,
-        dest,
-        decodeMs,
-        blitMs,
-      };
-      parentPort!.postMessage(reply, [png, dest]);
-    } catch (err) {
-      const reply: DecodeBlitJobErr = {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-        png,
-        dest,
-      };
-      parentPort!.postMessage(reply, [png, dest]);
-    }
-  });
-}
diff --git a/packages/producer/src/services/pngDecodeBlitWorkerPool.test.ts b/packages/producer/src/services/pngDecodeBlitWorkerPool.test.ts
deleted file mode 100644
index 7bd67f98cd..0000000000
--- a/packages/producer/src/services/pngDecodeBlitWorkerPool.test.ts
+++ /dev/null
@@ -1,384 +0,0 @@
-/**
- * Tests for the hf#732 lever-4 PNG decode + alpha-blit worker pool. Like the
- * shader-blend pool tests next door, these are correctness-critical: a
- * regression either corrupts every composited DOM layer or leaks worker
- * handles. Tests pin three properties:
- *
- *   1. Byte-equivalence with the inline path. The worker calls the exact
- *      same `decodePng` + `blitRgba8OverRgb48le` the inline path uses, so
- *      the round-trip must reproduce the inline result to the last byte.
- *   2. Buffer-transfer correctness across the 8KB Node pool threshold.
- *      The pool's dispatcher must NOT throw `DataCloneError` for inputs
- *      that happen to live in the shared 8KB pool (small PNGs, etc.).
- *   3. Concurrent dispatch + pipelining. N concurrent `run` calls
- *      against a pool sized to N all complete with correct output. The
- *      pipelining test asserts that decode/blit of frame N overlaps the
- *      kickoff of frame N+1's "capture" (simulated by a deferred Promise),
- *      proving the pool isn't accidentally serializing.
- *
- * The pool's clean-shutdown path is also exercised so a test failure
- * doesn't leak handles into other tests.
- */
-
-import { afterEach, describe, expect, it } from "vitest";
-import { deflateSync } from "zlib";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-import { decodePng, blitRgba8OverRgb48le } from "@hyperframes/engine/alpha-blit";
-import {
-  createPngDecodeBlitWorkerPool,
-  type PngDecodeBlitWorkerPool,
-} from "./pngDecodeBlitWorkerPool.js";
-
-const W = 16;
-const H = 8;
-const RGB48_BYTES = W * H * 6;
-
-/**
- * Synthesize a minimal RGBA8 PNG with a uniform color. Skips CRC32
- * because `decodePng` does not verify checksums. Produces an output that's
- * intentionally tiny (well under 8KB) so the test exercises the
- * shared-pool-detection path in the dispatcher.
- */
-function makeUniformRgbaPng(
-  w: number,
-  h: number,
-  r: number,
-  g: number,
-  b: number,
-  a: number,
-): Buffer {
-  const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(w, 0);
-  ihdr.writeUInt32BE(h, 4);
-  ihdr[8] = 8; // 8-bit depth
-  ihdr[9] = 6; // RGBA
-  ihdr[10] = 0; // deflate
-  ihdr[11] = 0; // no filter
-  ihdr[12] = 0; // non-interlaced
-
-  const rows: Buffer[] = [];
-  for (let y = 0; y < h; y++) {
-    rows.push(Buffer.from([0])); // PNG row filter byte (None)
-    for (let x = 0; x < w; x++) {
-      rows.push(Buffer.from([r, g, b, a]));
-    }
-  }
-  const idatData = deflateSync(Buffer.concat(rows));
-
-  function chunk(type: string, data: Buffer): Buffer {
-    const len = Buffer.alloc(4);
-    len.writeUInt32BE(data.length, 0);
-    const typeBuf = Buffer.from(type, "ascii");
-    const crc = Buffer.alloc(4); // skipped by decoder
-    return Buffer.concat([len, typeBuf, data, crc]);
-  }
-
-  return Buffer.concat([
-    sig,
-    chunk("IHDR", ihdr),
-    chunk("IDAT", idatData),
-    chunk("IEND", Buffer.alloc(0)),
-  ]);
-}
-
-describe("PngDecodeBlitWorkerPool", () => {
-  const pools: PngDecodeBlitWorkerPool[] = [];
-
-  afterEach(async () => {
-    while (pools.length > 0) {
-      const p = pools.pop();
-      if (p) await p.terminate();
-    }
-  });
-
-  async function makePool(size: number): Promise<PngDecodeBlitWorkerPool> {
-    const p = await createPngDecodeBlitWorkerPool({ size });
-    pools.push(p);
-    return p;
-  }
-
-  it("produces byte-identical output to the inline decode+blit path", async () => {
-    const pool = await makePool(1);
-    const png = makeUniformRgbaPng(W, H, 255, 0, 0, 255);
-
-    // Pool path: blit onto a zero-filled rgb48le canvas.
-    const poolDest = Buffer.alloc(RGB48_BYTES);
-    const poolResult = await pool.run({
-      png: Buffer.from(png), // independent copy — the input may be detached
-      dest: poolDest,
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-
-    // Reference: inline decode+blit onto a separately allocated canvas.
-    const refDest = Buffer.alloc(RGB48_BYTES);
-    const { data: refRgba } = decodePng(png);
-    blitRgba8OverRgb48le(refRgba, refDest, W, H, "srgb");
-
-    expect(Buffer.compare(poolResult.dest, refDest)).toBe(0);
-  });
-
-  it("composites OVER existing rgb48le content (alpha blend semantics)", async () => {
-    const pool = await makePool(1);
-
-    // Half-transparent red over a green background.
-    const png = makeUniformRgbaPng(W, H, 255, 0, 0, 128);
-
-    const poolDest = Buffer.alloc(RGB48_BYTES);
-    for (let i = 0; i < W * H; i++) {
-      const off = i * 6;
-      poolDest.writeUInt16LE(0, off); // R
-      poolDest.writeUInt16LE(60000, off + 2); // G
-      poolDest.writeUInt16LE(0, off + 4); // B
-    }
-
-    const poolResult = await pool.run({
-      png: Buffer.from(png),
-      dest: poolDest,
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-
-    // Inline reference applies the same blend to its own copy of the
-    // green background.
-    const refDest = Buffer.alloc(RGB48_BYTES);
-    for (let i = 0; i < W * H; i++) {
-      const off = i * 6;
-      refDest.writeUInt16LE(0, off);
-      refDest.writeUInt16LE(60000, off + 2);
-      refDest.writeUInt16LE(0, off + 4);
-    }
-    const { data: refRgba } = decodePng(png);
-    blitRgba8OverRgb48le(refRgba, refDest, W, H, "srgb");
-
-    expect(Buffer.compare(poolResult.dest, refDest)).toBe(0);
-  });
-
-  it("survives small PNGs that would otherwise hit the Node 8KB shared pool", async () => {
-    // A 16×8 RGBA PNG compresses to a few hundred bytes — comfortably
-    // under the 8KB Buffer pool threshold. If the dispatcher fails to
-    // copy-out before postMessage, this throws DataCloneError.
-    const pool = await makePool(1);
-    const png = makeUniformRgbaPng(W, H, 50, 100, 200, 255);
-    expect(png.byteLength).toBeLessThan(8192);
-
-    const result = await pool.run({
-      png,
-      dest: Buffer.alloc(RGB48_BYTES),
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-    expect(result.dest.byteLength).toBe(RGB48_BYTES);
-  });
-
-  it("runs N concurrent decode+blit tasks against an N-wide pool", async () => {
-    const pool = await makePool(4);
-    const png = makeUniformRgbaPng(W, H, 200, 100, 50, 255);
-
-    const tasks = Array.from({ length: 4 }, () =>
-      pool.run({
-        png: Buffer.from(png),
-        dest: Buffer.alloc(RGB48_BYTES),
-        width: W,
-        height: H,
-        transfer: "srgb",
-      }),
-    );
-    const results = await Promise.all(tasks);
-
-    // All 4 results must match each other (same input) AND match the
-    // inline reference.
-    const refDest = Buffer.alloc(RGB48_BYTES);
-    const { data: refRgba } = decodePng(png);
-    blitRgba8OverRgb48le(refRgba, refDest, W, H, "srgb");
-    for (const r of results) {
-      expect(Buffer.compare(r.dest, refDest)).toBe(0);
-    }
-  });
-
-  it("permits frame N+1 capture to proceed while frame N decode+blit is in flight", async () => {
-    // Pipelining proof: kick off a "decode+blit" task that we can hold by
-    // virtue of the worker actually running, then concurrently kick off a
-    // simulated next-frame capture (a Promise that resolves immediately).
-    // The simulated capture must resolve BEFORE the decode+blit, proving
-    // the decode+blit isn't blocking the main thread.
-    const pool = await makePool(2);
-    const png = makeUniformRgbaPng(W, H, 50, 100, 200, 255);
-
-    // Sentinel timestamps to verify overlap.
-    const captureStarted: number[] = [];
-    const captureDone: number[] = [];
-    const decodeBlitStarted: number[] = [];
-    const decodeBlitDone: number[] = [];
-
-    decodeBlitStarted.push(Date.now());
-    const decodeBlitPromise = pool
-      .run({
-        png: Buffer.from(png),
-        dest: Buffer.alloc(RGB48_BYTES),
-        width: W,
-        height: H,
-        transfer: "srgb",
-      })
-      .then((r) => {
-        decodeBlitDone.push(Date.now());
-        return r;
-      });
-
-    // Simulated next-frame CDP capture — a microtask-y await that yields.
-    // On a non-pipelined (synchronous-inline) path this would have to wait
-    // for the decode+blit, but the pool dispatches to a worker thread so
-    // the main thread is free to start the next "capture" immediately.
-    captureStarted.push(Date.now());
-    await new Promise((resolve) => setImmediate(resolve));
-    captureDone.push(Date.now());
-
-    await decodeBlitPromise;
-
-    expect(captureDone[0]).toBeDefined();
-    expect(decodeBlitDone[0]).toBeDefined();
-    // The simulated capture must have completed before the decode+blit —
-    // proof that the pool is NOT blocking the main thread.
-    expect(captureDone[0]!).toBeLessThanOrEqual(decodeBlitDone[0]!);
-  });
-
-  it("spawns from an explicit workerEntryPath, bypassing the import.meta.url resolver", async () => {
-    // Regression for the hf#677 bundled-CLI bug: when the pool is inlined
-    // into a separate bundle (e.g. cli.js), `import.meta.url` resolves to
-    // the bundle's path rather than the bundled worker's emitted path, and
-    // the sibling-probe fallback computes a path the worker file does not
-    // live at. The explicit `workerEntryPath` plumbed by the call site
-    // bypasses the heuristic entirely.
-    const here = dirname(fileURLToPath(import.meta.url));
-    const explicitPath = resolve(here, "pngDecodeBlitWorker.ts");
-    const pool = await createPngDecodeBlitWorkerPool({
-      size: 1,
-      workerEntryPath: explicitPath,
-    });
-    pools.push(pool);
-
-    const png = makeUniformRgbaPng(W, H, 64, 128, 192, 255);
-    const dest = Buffer.alloc(RGB48_BYTES);
-    const result = await pool.run({
-      png: Buffer.from(png),
-      dest,
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-
-    // Compare to inline reference to confirm the explicit-path spawn actually
-    // ran real work (not just spawned and crashed silently).
-    const refDest = Buffer.alloc(RGB48_BYTES);
-    const { data: refRgba } = decodePng(png);
-    blitRgba8OverRgb48le(refRgba, refDest, W, H, "srgb");
-    expect(Buffer.compare(result.dest, refDest)).toBe(0);
-  });
-
-  it("terminates cleanly even with queued tasks", async () => {
-    const pool = await makePool(1);
-    const png = makeUniformRgbaPng(W, H, 1, 2, 3, 255);
-
-    // Two tasks: the first dispatches, the second queues.
-    const p1 = pool.run({
-      png: Buffer.from(png),
-      dest: Buffer.alloc(RGB48_BYTES),
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-    const p2 = pool.run({
-      png: Buffer.from(png),
-      dest: Buffer.alloc(RGB48_BYTES),
-      width: W,
-      height: H,
-      transfer: "srgb",
-    });
-
-    await pool.terminate();
-    pools.pop(); // already terminated; don't try to re-terminate in afterEach
-
-    // Both must settle (resolve or reject). The first MAY resolve if the
-    // worker finished before terminate() raced in; the second MUST reject
-    // because it never got to dispatch.
-    const r1 = await p1.catch((e: unknown) => e);
-    const r2 = await p2.catch((e: unknown) => e);
-    if (r2 instanceof Error) {
-      expect(r2.message).toMatch(/terminated/);
-    } else {
-      // If both raced to resolve before terminate, that's also acceptable
-      // — but only the second one is guaranteed-rejected. Accept either
-      // shape; the goal of the test is "no leaked handles, no unhandled
-      // rejection".
-      expect(r2).toBeDefined();
-    }
-    // r1 is "either resolved with a result OR rejected with terminated";
-    // both are acceptable.
-    expect(r1).toBeDefined();
-  });
-
-  describe("crash recovery", () => {
-    const CRASH_WORKER = resolve(
-      dirname(fileURLToPath(import.meta.url)),
-      "__fixtures__",
-      "crashOnMessageWorker.mjs",
-    );
-
-    async function makeCrashPool(size: number): Promise<PngDecodeBlitWorkerPool> {
-      const p = await createPngDecodeBlitWorkerPool({ size, workerEntryPath: CRASH_WORKER });
-      pools.push(p);
-      return p;
-    }
-
-    function blitReq(): Parameters<PngDecodeBlitWorkerPool["run"]>[0] {
-      return {
-        png: Buffer.from([0]),
-        dest: Buffer.alloc(RGB48_BYTES),
-        width: W,
-        height: H,
-        transfer: "srgb",
-      };
-    }
-
-    function settledWithin(p: Promise<unknown>, ms = 3000): Promise<string> {
-      return Promise.race([
-        p.then(
-          () => "resolved",
-          () => "rejected",
-        ),
-        new Promise<string>((r) => setTimeout(() => r("hung"), ms)),
-      ]);
-    }
-
-    it("rejects the in-flight task when its only worker crashes, then fails subsequent runs fast", async () => {
-      const pool = await makeCrashPool(1);
-      expect(await settledWithin(pool.run(blitReq()))).toBe("rejected");
-      // Dead slot must be excluded; a later run fails fast rather than hanging
-      // on a postMessage to the terminated worker.
-      expect(await settledWithin(pool.run(blitReq()))).toBe("rejected");
-    });
-
-    it("rejects a queued task on crash instead of leaving it to hang", async () => {
-      const pool = await makeCrashPool(1);
-      const inFlight = settledWithin(pool.run(blitReq()));
-      const queued = settledWithin(pool.run(blitReq()));
-      expect(await inFlight).toBe("rejected");
-      expect(await queued).toBe("rejected");
-    });
-
-    it("never wedges the pool when slots die", async () => {
-      const pool = await makeCrashPool(2);
-      const results = await Promise.all([
-        settledWithin(pool.run(blitReq())),
-        settledWithin(pool.run(blitReq())),
-        settledWithin(pool.run(blitReq())),
-      ]);
-      expect(results).not.toContain("hung");
-    });
-  });
-});
diff --git a/packages/producer/src/services/pngDecodeBlitWorkerPool.ts b/packages/producer/src/services/pngDecodeBlitWorkerPool.ts
deleted file mode 100644
index 05fedaf1f7..0000000000
--- a/packages/producer/src/services/pngDecodeBlitWorkerPool.ts
+++ /dev/null
@@ -1,455 +0,0 @@
-/**
- * Pool of Node `worker_threads` Workers for off-main-thread PNG decode +
- * rgba8-over-rgb48le blit. The hf#732 lever-4 follow-up: capture (Chrome
- * compositor) and decode+blit (Node CPU) were previously serialized per
- * frame inside `captureTransitionFrame` / `compositeHdrFrame`. Each frame
- * waited ~30 ms (decode) + ~50 ms (blit) on the Node main thread before the
- * next CDP screenshot could begin. With the decode+blit on a worker pool,
- * the calling thread can kick off the next CDP capture immediately and the
- * decode+blit overlaps Chrome's screenshot work.
- *
- * Why a SEPARATE pool from `shaderTransitionWorkerPool`:
- *
- *   - Different work shapes: shader-blend reads 2× rgb48le, writes 1×
- *     rgb48le. Decode+blit reads 1× PNG bytes (variable size, often
- *     ~250 KB for 854×480 with sparse DOM content), allocates a temporary
- *     RGBA8 buffer, and writes 1× rgb48le (over an existing destination).
- *   - Different concurrency profile: shader-blend fires once per
- *     transition frame; decode+blit fires once per DOM layer per frame
- *     (typically 3-6× per normal frame, 2× per transition frame). The
- *     pools have very different dispatch rates and queuing characteristics.
- *   - Sizing them independently lets us tune each to its bottleneck without
- *     starving the other.
- *
- * API:
- *
- *   const pool = await createPngDecodeBlitWorkerPool({ size, log });
- *   const result = await pool.run({
- *     png: pngBuffer,             // alpha-channel PNG from CDP (zero-copy in)
- *     dest: rgb48leDestBuffer,    // rgb48le canvas to blend onto (zero-copy in)
- *     width, height,
- *     transfer: "srgb" | "pq" | "hlg" | etc.,
- *   });
- *   // result.dest is the SAME memory as the input `dest`, but re-attached
- *   // to the main thread. The input Buffer is detached on dispatch — the
- *   // caller must use `result.dest` for any subsequent reads/writes.
- *   await pool.terminate();
- *
- * Buffer transfer contract:
- *
- *   The PNG bytes are transferred IN with `transferList: [png.buffer]` so
- *   we don't copy them across the worker boundary. The `dest` rgb48le
- *   ArrayBuffer is also transferred IN (and back OUT) so the blit happens
- *   in place on the same memory the caller pre-allocated. After `run`
- *   resolves, the caller MUST swap its Buffer reference to `result.dest`
- *   — the original Buffer's underlying ArrayBuffer is detached on dispatch.
- *
- *   The intermediate RGBA8 decode buffer is allocated INSIDE the worker
- *   and dropped on the worker side — there is no main-thread allocation
- *   for it. The PNG ArrayBuffer is transferred back too so the caller can
- *   release it.
- */
-
-import { Worker } from "node:worker_threads";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { dirname, join } from "node:path";
-import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
-import { cpus } from "node:os";
-
-interface PoolLogger {
-  info?: (msg: string, meta?: Record<string, unknown>) => void;
-  warn?: (msg: string, meta?: Record<string, unknown>) => void;
-  error?: (msg: string, meta?: Record<string, unknown>) => void;
-}
-
-export interface PngDecodeBlitPoolOptions {
-  /** Number of worker threads. Clamped to [1, cpus().length]. */
-  size: number;
-  /** Optional logger; falls back to no-op. */
-  log?: PoolLogger;
-  /**
-   * Absolute filesystem path to the worker entry module. When provided, the
-   * pool spawns workers from this exact path and skips the fallback
-   * `import.meta.url`-based resolver entirely. Required by callers that
-   * bundle the worker via a separate build (e.g. the CLI's tsup bundle):
-   * `import.meta.url` inside the bundled pool resolves to the bundle's own
-   * location, NOT the bundled worker entry's location, so the heuristic
-   * resolver below cannot find the worker. Path extension determines the
-   * loader behaviour (`.ts` → tsx/esm loader is appended to execArgv).
-   */
-  workerEntryPath?: string;
-}
-
-export interface PngDecodeBlitRequest {
-  /** PNG bytes captured from CDP (Page.captureScreenshot). */
-  png: Buffer;
-  /**
-   * Pre-allocated rgb48le destination canvas (width*height*6 bytes). The
-   * blit composites the decoded RGBA8 image OVER this buffer's existing
-   * contents in `transfer` space.
-   */
-  dest: Buffer;
-  width: number;
-  height: number;
-  /**
-   * Composite color space tag matching the engine's `CompositeTransfer`
-   * union. Passed through to `blitRgba8OverRgb48le` in the worker.
-   */
-  transfer: string;
-}
-
-export interface PngDecodeBlitResult {
-  /**
-   * Re-attached destination buffer holding the composited rgb48le pixels.
-   * Same memory as the request's `dest`, viewed through a fresh Buffer.
-   */
-  dest: Buffer;
-  /** Per-worker timing: decode duration in ms (excluding postMessage latency). */
-  decodeMs: number;
-  /** Per-worker timing: blit duration in ms. */
-  blitMs: number;
-}
-
-interface PendingTask {
-  req: PngDecodeBlitRequest;
-  resolve: (r: PngDecodeBlitResult) => void;
-  reject: (err: Error) => void;
-  enqueuedAtMs?: number;
-  traceId?: number;
-}
-
-interface WorkerSlot {
-  worker: Worker;
-  busy: boolean;
-  current: PendingTask | null;
-  /**
-   * Set once the worker has crashed (`error`) or exited unexpectedly. A dead
-   * slot must never be dispatched to again: `postMessage` to a terminated
-   * Worker is a silent no-op (no throw, no reply), so a task routed to it
-   * would hang forever. The pool does not respawn mid-render, so a dead slot
-   * stays dead until teardown.
-   */
-  dead: boolean;
-}
-
-interface WorkerReply {
-  ok: boolean;
-  error?: string;
-  png: ArrayBuffer;
-  dest: ArrayBuffer;
-  decodeMs?: number;
-  blitMs?: number;
-}
-
-export interface PngDecodeBlitWorkerPool {
-  readonly size: number;
-  run(req: PngDecodeBlitRequest): Promise<PngDecodeBlitResult>;
-  terminate(): Promise<void>;
-}
-
-/**
- * Resolve the path to the compiled worker module.
- *
- * Resolution order (first match wins):
- *   1. Explicit `workerEntryPath` factory option — callers that bundle the
- *      worker via a separate build pipeline (e.g. the CLI's tsup bundle that
- *      emits `pngDecodeBlitWorker.js` next to `cli.js`) must use this. The
- *      bundled-CLI case is the *only* one where the fallback below cannot
- *      find the worker: `import.meta.url` inside the inlined pool resolves
- *      to the bundle path, not the worker's emitted path, so the sibling
- *      probe lands in the wrong directory.
- *   2. `HF_PNG_DECODE_BLIT_WORKER_ENTRY` env var — test/dev infra override.
- *   3. Same-directory `.js` sibling — works when both pool source and
- *      worker source compile into the same `dist/services/` directory
- *      (in-tree dev builds and the colocated tsc emit).
- *   4. Same-directory `.ts` sibling — vitest/bun raw-TS execution path.
- */
-function resolveWorkerEntry(explicit: string | undefined): { path: string; isTs: boolean } {
-  if (explicit && explicit.length > 0) {
-    return { path: explicit, isTs: explicit.endsWith(".ts") };
-  }
-  const override = process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY;
-  if (override && override.length > 0) {
-    const isTs = override.endsWith(".ts");
-    return { path: override, isTs };
-  }
-  const moduleDir = dirname(fileURLToPath(import.meta.url));
-  const jsPath = join(moduleDir, "pngDecodeBlitWorker.js");
-  if (existsSync(jsPath)) return { path: jsPath, isTs: false };
-  const tsPath = join(moduleDir, "pngDecodeBlitWorker.ts");
-  return { path: tsPath, isTs: true };
-}
-
-/**
- * Mirror of `shaderTransitionWorkerPool.buildExecArgv`. Worker threads
- * inherit the parent's loader only if the relevant flag is present on
- * `process.execArgv`; under vitest the tsx loader is NOT exposed there, so
- * we append `--import tsx/esm` when the resolved entry is `.ts` and no
- * loader is detected. Best-effort: silently no-ops if `tsx/esm` can't be
- * resolved (prod bundle).
- */
-function buildExecArgv(entryIsTs: boolean): string[] {
-  const inherited = [...process.execArgv];
-  if (!entryIsTs) return inherited;
-  const hasLoader = inherited.some(
-    (a) => a.includes("tsx/esm") || a.includes("ts-node/esm") || a.includes("--import"),
-  );
-  if (hasLoader) return inherited;
-  try {
-    const require = createRequire(import.meta.url);
-    const tsxEsm = require.resolve("tsx/esm");
-    inherited.push("--import", pathToFileURL(tsxEsm).href);
-  } catch {
-    // tsx not installed (prod) — leave execArgv as-is.
-  }
-  return inherited;
-}
-
-export async function createPngDecodeBlitWorkerPool(
-  opts: PngDecodeBlitPoolOptions,
-): Promise<PngDecodeBlitWorkerPool> {
-  const cpuCount = Math.max(1, cpus().length);
-  const size = Math.max(1, Math.min(opts.size, cpuCount));
-  const log = opts.log ?? {};
-  const { path: entry, isTs: entryIsTs } = resolveWorkerEntry(opts.workerEntryPath);
-
-  const slots: WorkerSlot[] = [];
-  const queue: PendingTask[] = [];
-  let terminated = false;
-
-  const traceEnabled = process.env.HF_PNG_DECODE_BLIT_POOL_TRACE === "1";
-  let nextTaskId = 0;
-
-  const execArgv = buildExecArgv(entryIsTs);
-
-  // When every worker has died there is no live thread left to drain the
-  // queue, so any waiting tasks would hang forever. Reject them instead.
-  const failQueueIfNoLiveSlots = (): void => {
-    if (slots.some((s) => !s.dead)) return;
-    while (queue.length > 0) {
-      const t = queue.shift();
-      if (t) t.reject(new Error("png-decode-blit pool has no live workers; task abandoned"));
-    }
-  };
-
-  const dispatchNext = (slot: WorkerSlot): void => {
-    if (terminated || slot.busy || slot.dead) return;
-    const task = queue.shift();
-    if (!task) return;
-    slot.busy = true;
-    slot.current = task;
-    if (traceEnabled) {
-      const slotIdx = slots.indexOf(slot);
-      const waitMs = task.enqueuedAtMs ? Date.now() - task.enqueuedAtMs : 0;
-      const busyCount = slots.filter((s) => s.busy).length;
-      log.info?.("[pngDecodeBlitPool] dispatch", {
-        task: task.traceId,
-        slot: slotIdx,
-        waitMs,
-        busyCount,
-        queueDepth: queue.length,
-      });
-    }
-    const { png, dest, width, height, transfer } = task.req;
-    // Transfer the PNG bytes (input) and the rgb48le dest (in-place blit
-    // target) across the worker boundary. Both are detached on the main
-    // thread until the reply re-attaches them.
-    //
-    // Node `Buffer.alloc(N)` allocates a dedicated ArrayBuffer for buffers
-    // above 8KB (the pool threshold); below that, Buffers are slices over
-    // a shared 8KB pool ArrayBuffer. `postMessage` with `transferList`
-    // REJECTS the shared pool with `DataCloneError: Cannot transfer
-    // object of unsupported type`. The rgb48le `dest` buffers in the
-    // hybrid path are always > 8KB (854×480×6 ≈ 2.4MB) so they're fine,
-    // but PNG inputs (variable size, typically 30-300KB but can be < 8KB
-    // for empty layers) AND any small upstream Buffers can hit the pool.
-    //
-    // Safety net: if the underlying ArrayBuffer is larger than the Buffer
-    // view OR if the Buffer view doesn't cover the ArrayBuffer exactly,
-    // we copy into a fresh dedicated ArrayBuffer before transfer. Cost is
-    // one allocation + memcpy of the PNG bytes — small versus the
-    // postMessage round-trip we're already paying.
-    const pngBackingFitsExactly = png.byteOffset === 0 && png.byteLength === png.buffer.byteLength;
-    const pngSource: Buffer = pngBackingFitsExactly ? png : Buffer.from(png); // Buffer.from(Buffer) copies into a new pool slot
-    // For very small PNGs, `Buffer.from(buf)` may still land in the pool.
-    // Force a dedicated ArrayBuffer with `Uint8Array.slice().buffer`.
-    let abPng: ArrayBuffer;
-    let pngOffset: number;
-    let pngLength: number;
-    if (pngSource.byteOffset === 0 && pngSource.byteLength === pngSource.buffer.byteLength) {
-      abPng = pngSource.buffer as ArrayBuffer;
-      pngOffset = 0;
-      pngLength = pngSource.byteLength;
-    } else {
-      const copied = new Uint8Array(pngSource.byteLength);
-      copied.set(pngSource);
-      abPng = copied.buffer;
-      pngOffset = 0;
-      pngLength = copied.byteLength;
-    }
-    // The rgb48le `dest` should always have a dedicated ArrayBuffer
-    // (`Buffer.alloc` above the 8KB pool threshold gives one). Defensive
-    // path mirrors the PNG handling for symmetry.
-    let abDest: ArrayBuffer;
-    let destOffset: number;
-    let destLength: number;
-    if (dest.byteOffset === 0 && dest.byteLength === dest.buffer.byteLength) {
-      abDest = dest.buffer as ArrayBuffer;
-      destOffset = 0;
-      destLength = dest.byteLength;
-    } else {
-      // Should never happen for hybrid-path canvases. Take the
-      // copy-and-transfer path so we don't crash; but log so we surface
-      // any future allocator change that violates the invariant.
-      log.warn?.("[pngDecodeBlitPool] dest buffer is a slice over a larger ArrayBuffer; copying", {
-        offset: dest.byteOffset,
-        length: dest.byteLength,
-        backingSize: dest.buffer.byteLength,
-      });
-      const copied = new Uint8Array(dest.byteLength);
-      copied.set(dest);
-      abDest = copied.buffer;
-      destOffset = 0;
-      destLength = copied.byteLength;
-    }
-    try {
-      slot.worker.postMessage(
-        {
-          png: abPng,
-          pngOffset,
-          pngLength,
-          dest: abDest,
-          destOffset,
-          destLength,
-          width,
-          height,
-          transfer,
-        },
-        [abPng, abDest],
-      );
-    } catch (err) {
-      slot.busy = false;
-      slot.current = null;
-      task.reject(err instanceof Error ? err : new Error(String(err)));
-    }
-  };
-
-  const onWorkerMessage = (slot: WorkerSlot, reply: WorkerReply): void => {
-    const task = slot.current;
-    slot.current = null;
-    slot.busy = false;
-    if (!task) {
-      dispatchNext(slot);
-      return;
-    }
-    if (!reply.ok) {
-      task.reject(new Error(reply.error ?? "png-decode-blit worker failed"));
-    } else {
-      // Re-attach the dest ArrayBuffer as a Node Buffer view. We wrap the
-      // full reply.dest (offset=0, length=byteLength) because the
-      // dispatch path normalizes to offset-0 ArrayBuffers (either the
-      // caller's original or a fresh copy we made on the dispatch side).
-      // The blit work happened over the full ArrayBuffer in the worker;
-      // returning a view that matches that is the correct semantics.
-      task.resolve({
-        dest: Buffer.from(reply.dest, 0, reply.dest.byteLength),
-        decodeMs: reply.decodeMs ?? 0,
-        blitMs: reply.blitMs ?? 0,
-      });
-    }
-    dispatchNext(slot);
-  };
-
-  const onWorkerError = (slot: WorkerSlot, err: Error): void => {
-    const task = slot.current;
-    slot.current = null;
-    slot.busy = false;
-    // Mark dead before rejecting and before draining the queue so this slot is
-    // excluded from future dispatch; postMessage to its terminated worker would
-    // be a silent no-op and any task routed here would hang.
-    slot.dead = true;
-    if (task) {
-      task.reject(
-        new Error(`png-decode-blit worker crashed mid-task: ${err.message}; dest buffer lost`),
-      );
-    }
-    log.warn?.("[pngDecodeBlitWorkerPool] worker errored", { err: err.message });
-    failQueueIfNoLiveSlots();
-  };
-
-  const onWorkerExit = (slot: WorkerSlot, code: number): void => {
-    if (terminated) return;
-    slot.dead = true;
-    if (slot.current) {
-      slot.current.reject(new Error(`png-decode-blit worker exited (code=${code}) mid-task`));
-      slot.current = null;
-      slot.busy = false;
-    }
-    log.warn?.("[pngDecodeBlitWorkerPool] worker exited unexpectedly", { code });
-    failQueueIfNoLiveSlots();
-  };
-
-  try {
-    for (let i = 0; i < size; i++) {
-      const worker = new Worker(entry, { execArgv });
-      const slot: WorkerSlot = { worker, busy: false, current: null, dead: false };
-      worker.on("message", (msg: WorkerReply) => onWorkerMessage(slot, msg));
-      worker.on("error", (err: unknown) =>
-        onWorkerError(slot, err instanceof Error ? err : new Error(String(err))),
-      );
-      worker.on("exit", (code) => onWorkerExit(slot, code));
-      slots.push(slot);
-    }
-  } catch (err) {
-    terminated = true;
-    await Promise.all(slots.map((s) => s.worker.terminate().catch(() => undefined)));
-    throw err;
-  }
-
-  log.info?.("[pngDecodeBlitWorkerPool] spawned", { size, entry });
-
-  return {
-    size,
-    async run(req: PngDecodeBlitRequest): Promise<PngDecodeBlitResult> {
-      if (terminated) {
-        throw new Error("png-decode-blit pool already terminated");
-      }
-      return new Promise<PngDecodeBlitResult>((resolve, reject) => {
-        const task: PendingTask = traceEnabled
-          ? { req, resolve, reject, enqueuedAtMs: Date.now(), traceId: ++nextTaskId }
-          : { req, resolve, reject };
-        const idle = slots.find((s) => !s.busy && !s.dead);
-        if (idle) {
-          queue.unshift(task);
-          dispatchNext(idle);
-        } else if (slots.some((s) => !s.dead)) {
-          // A live worker is busy; it drains the queue when it completes.
-          queue.push(task);
-        } else {
-          // Every worker has died — don't hang waiting for a dispatch that
-          // can never happen.
-          reject(new Error("png-decode-blit pool has no live workers"));
-        }
-      });
-    },
-    async terminate(): Promise<void> {
-      if (terminated) return;
-      terminated = true;
-      while (queue.length > 0) {
-        const t = queue.shift();
-        if (t) t.reject(new Error("png-decode-blit pool terminated before task ran"));
-      }
-      for (const slot of slots) {
-        const t = slot.current;
-        if (t) {
-          slot.current = null;
-          slot.busy = false;
-          t.reject(new Error("png-decode-blit pool terminated mid-task"));
-        }
-      }
-      await Promise.all(slots.map((s) => s.worker.terminate().catch(() => undefined)));
-      log.info?.("[pngDecodeBlitWorkerPool] terminated", { size });
-    },
-  };
-}

From 4df981b317e98f017d45bce9669e8e808ec61b3f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 14:54:22 -0400
Subject: [PATCH 4/8] refactor(producer): centralize frame filename
 construction

Replace 4 inline padStart(6) template literals with shared helpers:
- formatCaptureFrameName(index, ext): zero-based, for internal capture
- formatExportFrameName(index, ext): zero-based input, one-based output
  for user-facing png-sequence export
---
 .../src/services/distributed/assemble.ts      |  3 +-
 .../src/services/render/stages/encodeStage.ts |  3 +-
 .../src/services/renderOrchestrator.ts        |  5 +--
 packages/producer/src/utils/paths.test.ts     | 31 ++++++++++++++++++-
 packages/producer/src/utils/paths.ts          |  8 +++++
 5 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/packages/producer/src/services/distributed/assemble.ts b/packages/producer/src/services/distributed/assemble.ts
index 214cfc451c..ec6eb98f1d 100644
--- a/packages/producer/src/services/distributed/assemble.ts
+++ b/packages/producer/src/services/distributed/assemble.ts
@@ -37,6 +37,7 @@ import { dirname, join } from "node:path";
 import { applyFaststart, muxVideoWithAudio, runFfmpeg } from "@hyperframes/engine";
 import { fpsToFfmpegArg } from "@hyperframes/core";
 import { defaultLogger, type ProducerLogger } from "../../logger.js";
+import { formatExportFrameName } from "../../utils/paths.js";
 import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
 import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
 import type { DistributedFormat } from "./shared.js";
@@ -397,7 +398,7 @@ function mergePngFrameDirs(
       throw new Error(`[assemble] png-sequence chunk has no frames: ${chunkDir}`);
     }
     for (const frame of frames) {
-      const dst = join(outputPath, `frame_${String(globalIdx + 1).padStart(6, "0")}.png`);
+      const dst = join(outputPath, formatExportFrameName(globalIdx, "png"));
       cpSync(join(chunkDir, frame), dst);
       globalIdx += 1;
     }
diff --git a/packages/producer/src/services/render/stages/encodeStage.ts b/packages/producer/src/services/render/stages/encodeStage.ts
index 0ac575b0db..4c4ae8278f 100644
--- a/packages/producer/src/services/render/stages/encodeStage.ts
+++ b/packages/producer/src/services/render/stages/encodeStage.ts
@@ -42,6 +42,7 @@ import {
 } from "@hyperframes/engine";
 import type { Fps } from "@hyperframes/core";
 import type { ProducerLogger } from "../../../logger.js";
+import { formatExportFrameName } from "../../../utils/paths.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import {
   buildGifPalettegenArgs,
@@ -236,7 +237,7 @@ export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeSta
       );
     }
     captured.forEach((name, i) => {
-      const dst = join(outputPath, `frame_${String(i + 1).padStart(6, "0")}.png`);
+      const dst = join(outputPath, formatExportFrameName(i, "png"));
       copyFileSync(join(framesDir, name), dst);
     });
     if (hasAudio && audioOutputPath && existsSync(audioOutputPath)) {
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 44e8d231e2..e6b99b10f6 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -84,6 +84,7 @@ import {
 } from "./render/shared.js";
 import { buildRenderErrorDetails, cleanupRenderResources, safeCleanup } from "./render/cleanup.js";
 import { normalizeErrorMessage } from "../utils/errorMessage.js";
+import { formatCaptureFrameName } from "../utils/paths.js";
 import { resolveEffectiveHdrMode } from "./render/hdrMode.js";
 import { buildRenderPerfSummary } from "./render/perfSummary.js";
 import { getCaptureStageBrowserConsole } from "./render/captureStageError.js";
@@ -467,7 +468,7 @@ export function findMissingFrameRanges(
   let rangeStart: number | null = null;
 
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
-    const framePath = join(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    const framePath = join(framesDir, formatCaptureFrameName(frameIndex, frameExt));
     const missing = !existsSync(framePath);
     if (missing && rangeStart === null) {
       rangeStart = frameIndex;
@@ -535,7 +536,7 @@ function countCapturedFrames(
 ): number {
   let captured = 0;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
-    const framePath = join(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    const framePath = join(framesDir, formatCaptureFrameName(frameIndex, frameExt));
     if (existsSync(framePath)) captured++;
   }
   return captured;
diff --git a/packages/producer/src/utils/paths.test.ts b/packages/producer/src/utils/paths.test.ts
index 336938c6e0..abbffb0001 100644
--- a/packages/producer/src/utils/paths.test.ts
+++ b/packages/producer/src/utils/paths.test.ts
@@ -14,7 +14,12 @@
 import { describe, expect, it } from "vitest";
 import { resolve, win32 } from "node:path";
 
-import { isPathInside, toExternalAssetKey } from "./paths.js";
+import {
+  isPathInside,
+  toExternalAssetKey,
+  formatCaptureFrameName,
+  formatExportFrameName,
+} from "./paths.js";
 
 describe("isPathInside", () => {
   it("returns true when child is directly inside parent", () => {
@@ -133,3 +138,27 @@ describe("toExternalAssetKey", () => {
     expect(/^[A-Za-z]:/.test(key)).toBe(false);
   });
 });
+
+describe("formatCaptureFrameName", () => {
+  it("returns zero-padded filename for zero-based index", () => {
+    expect(formatCaptureFrameName(0, "jpg")).toBe("frame_000000.jpg");
+  });
+
+  it("pads to 6 digits for large indices", () => {
+    expect(formatCaptureFrameName(999999, "png")).toBe("frame_999999.png");
+  });
+
+  it("handles mid-range indices", () => {
+    expect(formatCaptureFrameName(42, "jpg")).toBe("frame_000042.jpg");
+  });
+});
+
+describe("formatExportFrameName", () => {
+  it("returns one-based filename from zero-based input", () => {
+    expect(formatExportFrameName(0, "png")).toBe("frame_000001.png");
+  });
+
+  it("increments index by 1", () => {
+    expect(formatExportFrameName(4, "png")).toBe("frame_000005.png");
+  });
+});
diff --git a/packages/producer/src/utils/paths.ts b/packages/producer/src/utils/paths.ts
index be93fd5ad1..ebf8688ca0 100644
--- a/packages/producer/src/utils/paths.ts
+++ b/packages/producer/src/utils/paths.ts
@@ -109,6 +109,14 @@ export function toExternalAssetKey(absPath: string): string {
   return "hf-ext/" + normalised;
 }
 
+export function formatCaptureFrameName(index: number, ext: string): string {
+  return `frame_${String(index).padStart(6, "0")}.${ext}`;
+}
+
+export function formatExportFrameName(index: number, ext: string): string {
+  return `frame_${String(index + 1).padStart(6, "0")}.${ext}`;
+}
+
 export function resolveRenderPaths(
   projectDir: string,
   outputPath: string | null | undefined,

From 0d7923c9645c5e6a0b7428405acdae3dde330bd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 14:55:34 -0400
Subject: [PATCH 5/8] perf(producer): hoist allElementIds out of compositing
 loop

Move fullStacking.map() from inside the per-layer iteration to before
the loop, computing the element ID list once per frame instead of once
per DOM layer per frame.
---
 packages/producer/src/services/hdrCompositor.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/producer/src/services/hdrCompositor.ts b/packages/producer/src/services/hdrCompositor.ts
index 35c2bc9320..a364bc4d01 100644
--- a/packages/producer/src/services/hdrCompositor.ts
+++ b/packages/producer/src/services/hdrCompositor.ts
@@ -505,6 +505,7 @@ export async function compositeHdrFrame(
   // generation (their <img> replacements must be hidden from sibling
   // screenshots). The actual blit is skipped in the compositing loop below.
   const layers = groupIntoLayers(filteredStacking);
+  const allElementIds = fullStacking.map((e) => e.id);
 
   const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
   if (shouldLog) {
@@ -622,7 +623,6 @@ export async function compositeHdrFrame(
       // (root background, sibling scenes' static content, the painted
       // border/box-shadow of cards, etc.) and the resulting opaque
       // pixels overwrite previously composited HDR content beneath.
-      const allElementIds = fullStacking.map((e) => e.id);
       const layerIds = new Set(layer.elementIds);
       const hideIds = allElementIds.filter((id) => !layerIds.has(id));
       if (hdrPerf) hdrPerf.domLayerCaptures += 1;

From f2694ac2066775f3bca09c4eca2bddcfe60d4c65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 15:00:30 -0400
Subject: [PATCH 6/8] refactor(producer): consolidate HDR timing
 instrumentation

---
 .../producer/src/services/hdrCompositor.ts    | 217 +++++++++---------
 .../producer/src/services/render/hdrPerf.ts   |  24 ++
 .../render/stages/captureHdrFrameShared.ts    |  66 +++---
 .../render/stages/captureHdrHybridLoop.ts     |  30 +--
 .../render/stages/captureHdrSequentialLoop.ts |  59 ++---
 5 files changed, 205 insertions(+), 191 deletions(-)

diff --git a/packages/producer/src/services/hdrCompositor.ts b/packages/producer/src/services/hdrCompositor.ts
index a364bc4d01..4659dde380 100644
--- a/packages/producer/src/services/hdrCompositor.ts
+++ b/packages/producer/src/services/hdrCompositor.ts
@@ -34,7 +34,7 @@ import {
 import type { ProducerLogger } from "../logger.js";
 import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
 import { writeFileExclusiveSync } from "./render/shared.js";
-import { type HdrPerfCollector, addHdrTiming } from "./render/hdrPerf.js";
+import { type HdrPerfCollector, timeHdrPhase, timeHdrPhaseAsync } from "./render/hdrPerf.js";
 
 // ─── Diagnostic helpers ────────────────────────────────────────────────────
 
@@ -169,25 +169,19 @@ export function blitHdrVideoLayer(
 
   try {
     if (hdrPerf) hdrPerf.hdrVideoLayerBlits += 1;
-    let timingStart = Date.now();
-    const bytesRead = readSync(
-      frameSource.fd,
-      frameSource.scratch,
-      0,
-      frameSource.frameSize,
-      frameOffset,
+    const bytesRead = timeHdrPhase(hdrPerf, "hdrVideoReadDecodeMs", () =>
+      readSync(frameSource.fd, frameSource.scratch, 0, frameSource.frameSize, frameOffset),
     );
     if (bytesRead !== frameSource.frameSize) return;
     const hdrRgb = frameSource.scratch;
     const srcW = frameSource.width;
     const srcH = frameSource.height;
-    addHdrTiming(hdrPerf, "hdrVideoReadDecodeMs", timingStart);
 
     // Convert between HDR transfer functions if source doesn't match output
     if (sourceTransfer && targetTransfer && sourceTransfer !== targetTransfer) {
-      timingStart = Date.now();
-      convertTransfer(hdrRgb, sourceTransfer, targetTransfer);
-      addHdrTiming(hdrPerf, "hdrVideoTransferMs", timingStart);
+      timeHdrPhase(hdrPerf, "hdrVideoTransferMs", () =>
+        convertTransfer(hdrRgb, sourceTransfer, targetTransfer),
+      );
     }
 
     const viewportMatrix = parseTransformMatrix(el.transform);
@@ -241,54 +235,54 @@ export function blitHdrVideoLayer(
       Math.abs(viewportMatrix[3]! - 1) < 0.001
     );
 
-    timingStart = Date.now();
-    if (viewportMatrix && !isTranslationOnly) {
-      if (clipped && log) {
-        log.debug(
-          `HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
+    timeHdrPhase(hdrPerf, "hdrVideoBlitMs", () => {
+      if (viewportMatrix && !isTranslationOnly) {
+        if (clipped && log) {
+          log.debug(
+            `HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
+          );
+        }
+        blitRgb48leAffine(
+          canvas,
+          hdrRgb,
+          viewportMatrix,
+          srcW,
+          srcH,
+          width,
+          height,
+          el.opacity < 0.999 ? el.opacity : undefined,
+          borderRadiusParam,
+        );
+      } else if (clipped) {
+        // Crop the source buffer to the clipped region before blitting
+        const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
+        blitRgb48leRegion(
+          canvas,
+          croppedBuf,
+          blitX,
+          blitY,
+          blitW,
+          blitH,
+          width,
+          height,
+          el.opacity < 0.999 ? el.opacity : undefined,
+          borderRadiusParam,
+        );
+      } else {
+        blitRgb48leRegion(
+          canvas,
+          hdrRgb,
+          el.x,
+          el.y,
+          srcW,
+          srcH,
+          width,
+          height,
+          el.opacity < 0.999 ? el.opacity : undefined,
+          borderRadiusParam,
         );
       }
-      blitRgb48leAffine(
-        canvas,
-        hdrRgb,
-        viewportMatrix,
-        srcW,
-        srcH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else if (clipped) {
-      // Crop the source buffer to the clipped region before blitting
-      const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
-      blitRgb48leRegion(
-        canvas,
-        croppedBuf,
-        blitX,
-        blitY,
-        blitW,
-        blitH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else {
-      blitRgb48leRegion(
-        canvas,
-        hdrRgb,
-        el.x,
-        el.y,
-        srcW,
-        srcH,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    }
-    addHdrTiming(hdrPerf, "hdrVideoBlitMs", timingStart);
+    });
   } catch (err) {
     if (log) {
       log.debug(`HDR blit failed for ${el.id}`, {
@@ -343,12 +337,11 @@ export function blitHdrImageLayer(
     // The cache returns `buf.data` unchanged when no conversion is needed,
     // and otherwise returns a per-(imageId, targetTransfer) buffer that was
     // converted exactly once and reused across every subsequent frame.
-    let timingStart = Date.now();
-    const hdrRgb =
+    const hdrRgb = timeHdrPhase(hdrPerf, "hdrImageTransferMs", () =>
       sourceTransfer && targetTransfer
         ? hdrImageTransferCache.getConverted(el.id, sourceTransfer, targetTransfer, buf.data)
-        : buf.data;
-    addHdrTiming(hdrPerf, "hdrImageTransferMs", timingStart);
+        : buf.data,
+    );
 
     const viewportMatrix = parseTransformMatrix(el.transform);
 
@@ -356,34 +349,34 @@ export function blitHdrImageLayer(
     const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
     const borderRadiusParam = hasBorderRadius ? br : undefined;
 
-    timingStart = Date.now();
-    if (viewportMatrix) {
-      blitRgb48leAffine(
-        canvas,
-        hdrRgb,
-        viewportMatrix,
-        buf.width,
-        buf.height,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    } else {
-      blitRgb48leRegion(
-        canvas,
-        hdrRgb,
-        el.x,
-        el.y,
-        buf.width,
-        buf.height,
-        width,
-        height,
-        el.opacity < 0.999 ? el.opacity : undefined,
-        borderRadiusParam,
-      );
-    }
-    addHdrTiming(hdrPerf, "hdrImageBlitMs", timingStart);
+    timeHdrPhase(hdrPerf, "hdrImageBlitMs", () => {
+      if (viewportMatrix) {
+        blitRgb48leAffine(
+          canvas,
+          hdrRgb,
+          viewportMatrix,
+          buf.width,
+          buf.height,
+          width,
+          height,
+          el.opacity < 0.999 ? el.opacity : undefined,
+          borderRadiusParam,
+        );
+      } else {
+        blitRgb48leRegion(
+          canvas,
+          hdrRgb,
+          el.x,
+          el.y,
+          buf.width,
+          buf.height,
+          width,
+          height,
+          el.opacity < 0.999 ? el.opacity : undefined,
+          borderRadiusParam,
+        );
+      }
+    });
   } catch (err) {
     if (log) {
       log.debug(`HDR image blit failed for ${el.id}`, {
@@ -628,43 +621,41 @@ export async function compositeHdrFrame(
       if (hdrPerf) hdrPerf.domLayerCaptures += 1;
 
       // 1. Seek GSAP to restore all animated properties from clean state
-      let timingStart = Date.now();
-      await domSession.page.evaluate((t: number) => {
-        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-      }, time);
-      addHdrTiming(hdrPerf, "domLayerSeekMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "domLayerSeekMs", () =>
+        domSession.page.evaluate((t: number) => {
+          if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+        }, time),
+      );
 
       // 2. Run frame injector to set correct SDR video visibility
       if (beforeCaptureHook) {
-        timingStart = Date.now();
-        await beforeCaptureHook(domSession.page, time);
-        addHdrTiming(hdrPerf, "domLayerInjectMs", timingStart);
+        await timeHdrPhaseAsync(hdrPerf, "domLayerInjectMs", () =>
+          beforeCaptureHook(domSession.page, time),
+        );
       }
 
       // 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
-      timingStart = Date.now();
-      await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
-      addHdrTiming(hdrPerf, "domMaskApplyMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "domMaskApplyMs", () =>
+        applyDomLayerMask(domSession.page, layer.elementIds, hideIds),
+      );
 
       // 4. Screenshot
-      timingStart = Date.now();
-      const domPng = await captureAlphaPng(domSession.page, width, height);
-      addHdrTiming(hdrPerf, "domScreenshotMs", timingStart);
+      const domPng = await timeHdrPhaseAsync(hdrPerf, "domScreenshotMs", () =>
+        captureAlphaPng(domSession.page, width, height),
+      );
 
       // 5. Tear down the mask
-      timingStart = Date.now();
-      await removeDomLayerMask(domSession.page, hideIds);
-      addHdrTiming(hdrPerf, "domMaskRemoveMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "domMaskRemoveMs", () =>
+        removeDomLayerMask(domSession.page, hideIds),
+      );
 
       try {
-        timingStart = Date.now();
-        const { data: domRgba } = decodePng(domPng);
-        addHdrTiming(hdrPerf, "domPngDecodeMs", timingStart);
+        const { data: domRgba } = timeHdrPhase(hdrPerf, "domPngDecodeMs", () => decodePng(domPng));
         const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
         const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
-        timingStart = Date.now();
-        blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer);
-        addHdrTiming(hdrPerf, "domBlitMs", timingStart);
+        timeHdrPhase(hdrPerf, "domBlitMs", () =>
+          blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer),
+        );
         if (shouldLog && debugDumpDir) {
           const after = countNonZeroRgb48(canvas);
           const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
diff --git a/packages/producer/src/services/render/hdrPerf.ts b/packages/producer/src/services/render/hdrPerf.ts
index c033fad5c3..0f23c9bc81 100644
--- a/packages/producer/src/services/render/hdrPerf.ts
+++ b/packages/producer/src/services/render/hdrPerf.ts
@@ -90,6 +90,30 @@ export function addHdrTiming(
   perf.timings[key] += Date.now() - startMs;
 }
 
+export function timeHdrPhase<T>(
+  perf: HdrPerfCollector | undefined,
+  key: HdrPerfTimingKey,
+  fn: () => T,
+): T {
+  if (!perf) return fn();
+  const start = Date.now();
+  const result = fn();
+  addHdrTiming(perf, key, start);
+  return result;
+}
+
+export async function timeHdrPhaseAsync<T>(
+  perf: HdrPerfCollector | undefined,
+  key: HdrPerfTimingKey,
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (!perf) return fn();
+  const start = Date.now();
+  const result = await fn();
+  addHdrTiming(perf, key, start);
+  return result;
+}
+
 function averageTiming(totalMs: number, count: number): number {
   return count > 0 ? Math.round((totalMs / count) * 100) / 100 : 0;
 }
diff --git a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
index a6fa7dc38a..a6c0458677 100644
--- a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
+++ b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
@@ -29,7 +29,7 @@ import {
   blitHdrVideoLayer,
   closeHdrVideoFrameSource,
 } from "../../hdrCompositor.js";
-import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
+import { type HdrPerfCollector, timeHdrPhase, timeHdrPhaseAsync } from "../hdrPerf.js";
 
 // ─── Hybrid path gating + partitioning ─────────────────────────────────────
 
@@ -141,15 +141,15 @@ export async function captureSceneIntoBuffer(a: CaptureSceneArgs): Promise<void>
     log,
     frameIdx,
   } = a;
-  let timingStart = Date.now();
-  await session.page.evaluate((t: number) => {
-    if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-  }, time);
-  addHdrTiming(hdrPerf, "domLayerSeekMs", timingStart);
+  await timeHdrPhaseAsync(hdrPerf, "domLayerSeekMs", () =>
+    session.page.evaluate((t: number) => {
+      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+    }, time),
+  );
   if (beforeCaptureHook) {
-    timingStart = Date.now();
-    await beforeCaptureHook(session.page, time);
-    addHdrTiming(hdrPerf, "domLayerInjectMs", timingStart);
+    await timeHdrPhaseAsync(hdrPerf, "domLayerInjectMs", () =>
+      beforeCaptureHook(session.page, time),
+    );
   }
   for (const el of stackingInfo) {
     if (!el.isHdr || !sceneIds.has(el.id)) continue;
@@ -188,22 +188,20 @@ export async function captureSceneIntoBuffer(a: CaptureSceneArgs): Promise<void>
     .map((e) => e.id)
     .filter((id) => !sceneIds.has(id) || nativeHdrIds.has(id));
   if (hdrPerf) hdrPerf.domLayerCaptures += 1;
-  timingStart = Date.now();
-  await applyDomLayerMask(session.page, showIds, hideIds);
-  addHdrTiming(hdrPerf, "domMaskApplyMs", timingStart);
-  timingStart = Date.now();
-  const domPng = await captureAlphaPng(session.page, width, height);
-  addHdrTiming(hdrPerf, "domScreenshotMs", timingStart);
-  timingStart = Date.now();
-  await removeDomLayerMask(session.page, hideIds);
-  addHdrTiming(hdrPerf, "domMaskRemoveMs", timingStart);
+  await timeHdrPhaseAsync(hdrPerf, "domMaskApplyMs", () =>
+    applyDomLayerMask(session.page, showIds, hideIds),
+  );
+  const domPng = await timeHdrPhaseAsync(hdrPerf, "domScreenshotMs", () =>
+    captureAlphaPng(session.page, width, height),
+  );
+  await timeHdrPhaseAsync(hdrPerf, "domMaskRemoveMs", () =>
+    removeDomLayerMask(session.page, hideIds),
+  );
   try {
-    timingStart = Date.now();
-    const { data: domRgba } = decodePng(domPng);
-    addHdrTiming(hdrPerf, "domPngDecodeMs", timingStart);
-    timingStart = Date.now();
-    blitRgba8OverRgb48le(domRgba, sceneBuf, width, height, compositeTransfer);
-    addHdrTiming(hdrPerf, "domBlitMs", timingStart);
+    const { data: domRgba } = timeHdrPhase(hdrPerf, "domPngDecodeMs", () => decodePng(domPng));
+    timeHdrPhase(hdrPerf, "domBlitMs", () =>
+      blitRgba8OverRgb48le(domRgba, sceneBuf, width, height, compositeTransfer),
+    );
   } catch (err) {
     log.warn("DOM layer decode/blit failed; skipping overlay for transition scene", {
       frameIndex: frameIdx,
@@ -258,19 +256,17 @@ export async function captureTransitionFrameOnWorker(
     hdrPerf.frames += 1;
     hdrPerf.transitionFrames += 1;
   }
-  let timingStart = Date.now();
-  await session.page.evaluate((t: number) => {
-    if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-  }, time);
-  addHdrTiming(hdrPerf, "frameSeekMs", timingStart);
+  await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
+    session.page.evaluate((t: number) => {
+      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+    }, time),
+  );
   if (beforeCaptureHook) {
-    timingStart = Date.now();
-    await beforeCaptureHook(session.page, time);
-    addHdrTiming(hdrPerf, "frameInjectMs", timingStart);
+    await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () => beforeCaptureHook(session.page, time));
   }
-  timingStart = Date.now();
-  const stackingInfo = await queryElementStacking(session.page, nativeHdrIds);
-  addHdrTiming(hdrPerf, "stackingQueryMs", timingStart);
+  const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
+    queryElementStacking(session.page, nativeHdrIds),
+  );
   const sceneAIds = new Set(sceneElements[transition.fromScene] ?? []);
   const sceneBIds = new Set(sceneElements[transition.toScene] ?? []);
   buffers.bufferA.fill(0);
diff --git a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
index d78a03d367..5479cd2356 100644
--- a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
@@ -41,7 +41,7 @@ import {
   type TransitionRange,
   compositeHdrFrame,
 } from "../../hdrCompositor.js";
-import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
+import { type HdrPerfCollector, addHdrTiming, timeHdrPhaseAsync } from "../hdrPerf.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import { writeFileExclusiveSync } from "../shared.js";
 import {
@@ -306,25 +306,25 @@ export async function runHybridLayeredFrameLoop(input: HybridLoopInput): Promise
           });
         } else {
           const beforeCaptureHook = session.onBeforeCapture;
-          let timingStart = Date.now();
-          await session.page.evaluate((t: number) => {
-            if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-          }, time);
-          addHdrTiming(hdrPerf, "frameSeekMs", timingStart);
+          await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
+            session.page.evaluate((t: number) => {
+              if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+            }, time),
+          );
           if (beforeCaptureHook) {
-            timingStart = Date.now();
-            await beforeCaptureHook(session.page, time);
-            addHdrTiming(hdrPerf, "frameInjectMs", timingStart);
+            await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () =>
+              beforeCaptureHook(session.page, time),
+            );
           }
-          timingStart = Date.now();
-          const stackingInfo = await queryElementStacking(session.page, nativeHdrIds);
-          addHdrTiming(hdrPerf, "stackingQueryMs", timingStart);
+          const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
+            queryElementStacking(session.page, nativeHdrIds),
+          );
           canvas.fill(0);
           // Rebind ctx to this worker's session for per-layer captures
           const wctx: HdrCompositeContext = { ...hdrCompositeCtx, domSession: session };
-          timingStart = Date.now();
-          await compositeHdrFrame(wctx, canvas, time, stackingInfo, undefined, i);
-          addHdrTiming(hdrPerf, "normalCompositeMs", timingStart);
+          await timeHdrPhaseAsync(hdrPerf, "normalCompositeMs", () =>
+            compositeHdrFrame(wctx, canvas, time, stackingInfo, undefined, i),
+          );
           if (debugDumpEnabled && debugDumpDir && i % 30 === 0) {
             writeFileExclusiveSync(
               join(debugDumpDir, `frame_${String(i).padStart(4, "0")}_final_rgb48le.bin`),
diff --git a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
index 5360bd980d..11141c2051 100644
--- a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
@@ -26,7 +26,12 @@ import {
   type TransitionRange,
   compositeHdrFrame,
 } from "../../hdrCompositor.js";
-import { type HdrPerfCollector, addHdrTiming } from "../hdrPerf.js";
+import {
+  type HdrPerfCollector,
+  addHdrTiming,
+  timeHdrPhase,
+  timeHdrPhaseAsync,
+} from "../hdrPerf.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import { writeFileExclusiveSync } from "../shared.js";
 import {
@@ -104,20 +109,20 @@ export async function runSequentialLayeredFrameLoop(input: SequentialLoopInput):
     const time = (i * job.config.fps.den) / job.config.fps.num;
     if (hdrPerf) hdrPerf.frames += 1;
 
-    let timingStart = Date.now();
-    await domSession.page.evaluate((t: number) => {
-      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-    }, time);
-    addHdrTiming(hdrPerf, "frameSeekMs", timingStart);
+    await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
+      domSession.page.evaluate((t: number) => {
+        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+      }, time),
+    );
 
     if (beforeCaptureHook) {
-      timingStart = Date.now();
-      await beforeCaptureHook(domSession.page, time);
-      addHdrTiming(hdrPerf, "frameInjectMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () =>
+        beforeCaptureHook(domSession.page, time),
+      );
     }
-    timingStart = Date.now();
-    const stackingInfo = await queryElementStacking(domSession.page, nativeHdrIds);
-    addHdrTiming(hdrPerf, "stackingQueryMs", timingStart);
+    const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
+      queryElementStacking(domSession.page, nativeHdrIds),
+    );
     const activeTransition = transitionRanges.find((t) => i >= t.startFrame && i <= t.endFrame);
 
     if (i % 30 === 0 && (log.isLevelEnabled?.("debug") ?? true)) {
@@ -141,10 +146,10 @@ export async function runSequentialLayeredFrameLoop(input: SequentialLoopInput):
             (activeTransition.endFrame - activeTransition.startFrame);
       const sceneAIds = new Set(sceneElements[activeTransition.fromScene] ?? []);
       const sceneBIds = new Set(sceneElements[activeTransition.toScene] ?? []);
-      timingStart = Date.now();
-      transitionBuffers.bufferA.fill(0);
-      transitionBuffers.bufferB.fill(0);
-      addHdrTiming(hdrPerf, "canvasClearMs", timingStart);
+      timeHdrPhase(hdrPerf, "canvasClearMs", () => {
+        transitionBuffers.bufferA.fill(0);
+        transitionBuffers.bufferB.fill(0);
+      });
 
       for (const [sceneBuf, sceneIds] of [
         [transitionBuffers.bufferA, sceneAIds],
@@ -187,26 +192,24 @@ export async function runSequentialLayeredFrameLoop(input: SequentialLoopInput):
         progress,
       );
       addHdrTiming(hdrPerf, "transitionCompositeMs", transitionTimingStart);
-      timingStart = Date.now();
-      ensureFrameWritten(await hdrEncoder.writeFrame(transitionBuffers.output), i);
-      addHdrTiming(hdrPerf, "encoderWriteMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "encoderWriteMs", async () =>
+        ensureFrameWritten(await hdrEncoder.writeFrame(transitionBuffers.output), i),
+      );
     } else {
       if (hdrPerf) hdrPerf.normalFrames += 1;
-      timingStart = Date.now();
-      normalCanvas.fill(0);
-      addHdrTiming(hdrPerf, "canvasClearMs", timingStart);
-      timingStart = Date.now();
-      await compositeHdrFrame(hdrCompositeCtx, normalCanvas, time, stackingInfo, undefined, i);
-      addHdrTiming(hdrPerf, "normalCompositeMs", timingStart);
+      timeHdrPhase(hdrPerf, "canvasClearMs", () => normalCanvas.fill(0));
+      await timeHdrPhaseAsync(hdrPerf, "normalCompositeMs", () =>
+        compositeHdrFrame(hdrCompositeCtx, normalCanvas, time, stackingInfo, undefined, i),
+      );
       if (debugDumpEnabled && debugDumpDir && i % 30 === 0) {
         writeFileExclusiveSync(
           join(debugDumpDir, `frame_${String(i).padStart(4, "0")}_final_rgb48le.bin`),
           normalCanvas,
         );
       }
-      timingStart = Date.now();
-      ensureFrameWritten(await hdrEncoder.writeFrame(normalCanvas), i);
-      addHdrTiming(hdrPerf, "encoderWriteMs", timingStart);
+      await timeHdrPhaseAsync(hdrPerf, "encoderWriteMs", async () =>
+        ensureFrameWritten(await hdrEncoder.writeFrame(normalCanvas), i),
+      );
     }
 
     cleanupEndedHdrVideos({

From c15988709f5767a1c21806b5edeefcf0049211e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 15:46:39 -0400
Subject: [PATCH 7/8] refactor(producer): remove typecasts and deduplicate HDR
 capture patterns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Extract seekInjectAndQueryStacking() and seekAndInject() helpers to
  deduplicate the seek+inject+query pattern across sequential loop,
  hybrid loop, and per-scene transition capture (3 call sites → 1 helper)
- Fix sceneBuf as Buffer casts by properly typing the scene-capture
  arrays as [Buffer, Set<string>][] instead of using as const + cast
- Replace as NonNullable<> cast on outputFormat with as const fallback
- Add explanatory comments on inherent linkedom DOM casts
---
 .../render/stages/captureHdrFrameShared.ts    | 97 ++++++++++++++-----
 .../render/stages/captureHdrHybridLoop.ts     | 24 ++---
 .../render/stages/captureHdrSequentialLoop.ts | 31 +++---
 .../src/services/renderOrchestrator.ts        |  9 +-
 4 files changed, 106 insertions(+), 55 deletions(-)

diff --git a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
index a6c0458677..484c11f286 100644
--- a/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
+++ b/packages/producer/src/services/render/stages/captureHdrFrameShared.ts
@@ -11,6 +11,7 @@
 
 import { rmSync } from "node:fs";
 import {
+  type BeforeCaptureHook,
   type CaptureSession,
   type ElementStackingInfo,
   applyDomLayerMask,
@@ -29,7 +30,12 @@ import {
   blitHdrVideoLayer,
   closeHdrVideoFrameSource,
 } from "../../hdrCompositor.js";
-import { type HdrPerfCollector, timeHdrPhase, timeHdrPhaseAsync } from "../hdrPerf.js";
+import {
+  type HdrPerfCollector,
+  type HdrPerfTimingKey,
+  timeHdrPhase,
+  timeHdrPhaseAsync,
+} from "../hdrPerf.js";
 
 // ─── Hybrid path gating + partitioning ─────────────────────────────────────
 
@@ -101,6 +107,53 @@ export interface LayeredTransitionBuffers {
   output: Buffer;
 }
 
+// ─── Seek + inject + stacking query (shared across all three loop paths) ──
+
+/**
+ * Seek the page to `time` and run the optional before-capture hook.
+ * Used by `captureSceneIntoBuffer` which receives stacking info from
+ * its caller, and by `seekInjectAndQueryStacking` which appends a
+ * stacking query.
+ */
+async function seekAndInject(
+  page: CaptureSession["page"],
+  time: number,
+  beforeCaptureHook: BeforeCaptureHook | null,
+  hdrPerf: HdrPerfCollector | undefined,
+  seekKey: HdrPerfTimingKey,
+  injectKey: HdrPerfTimingKey,
+): Promise<void> {
+  await timeHdrPhaseAsync(hdrPerf, seekKey, () =>
+    page.evaluate((t: number) => {
+      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
+    }, time),
+  );
+  if (beforeCaptureHook) {
+    await timeHdrPhaseAsync(hdrPerf, injectKey, () => beforeCaptureHook(page, time));
+  }
+}
+
+/**
+ * Seek the page to `time`, run the optional before-capture hook, then
+ * query element stacking order. Each phase is individually timed via the
+ * caller-provided perf keys so the sequential loop, hybrid worker, and
+ * per-scene transition capture each emit the correct telemetry label
+ * (`frameSeekMs` vs. `domLayerSeekMs`, etc.).
+ */
+export async function seekInjectAndQueryStacking(
+  page: CaptureSession["page"],
+  time: number,
+  beforeCaptureHook: BeforeCaptureHook | null,
+  nativeHdrIds: Set<string>,
+  hdrPerf: HdrPerfCollector | undefined,
+  seekKey: HdrPerfTimingKey,
+  injectKey: HdrPerfTimingKey,
+  stackingKey: HdrPerfTimingKey,
+): Promise<ElementStackingInfo[]> {
+  await seekAndInject(page, time, beforeCaptureHook, hdrPerf, seekKey, injectKey);
+  return timeHdrPhaseAsync(hdrPerf, stackingKey, () => queryElementStacking(page, nativeHdrIds));
+}
+
 // ─── Per-scene capture (shared by sequential transition + hybrid worker) ──
 
 export interface CaptureSceneArgs {
@@ -141,16 +194,14 @@ export async function captureSceneIntoBuffer(a: CaptureSceneArgs): Promise<void>
     log,
     frameIdx,
   } = a;
-  await timeHdrPhaseAsync(hdrPerf, "domLayerSeekMs", () =>
-    session.page.evaluate((t: number) => {
-      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-    }, time),
+  await seekAndInject(
+    session.page,
+    time,
+    beforeCaptureHook,
+    hdrPerf,
+    "domLayerSeekMs",
+    "domLayerInjectMs",
   );
-  if (beforeCaptureHook) {
-    await timeHdrPhaseAsync(hdrPerf, "domLayerInjectMs", () =>
-      beforeCaptureHook(session.page, time),
-    );
-  }
   for (const el of stackingInfo) {
     if (!el.isHdr || !sceneIds.has(el.id)) continue;
     if (nativeHdrImageIds.has(el.id)) {
@@ -256,28 +307,28 @@ export async function captureTransitionFrameOnWorker(
     hdrPerf.frames += 1;
     hdrPerf.transitionFrames += 1;
   }
-  await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
-    session.page.evaluate((t: number) => {
-      if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-    }, time),
-  );
-  if (beforeCaptureHook) {
-    await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () => beforeCaptureHook(session.page, time));
-  }
-  const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
-    queryElementStacking(session.page, nativeHdrIds),
+  const stackingInfo = await seekInjectAndQueryStacking(
+    session.page,
+    time,
+    beforeCaptureHook,
+    nativeHdrIds,
+    hdrPerf,
+    "frameSeekMs",
+    "frameInjectMs",
+    "stackingQueryMs",
   );
   const sceneAIds = new Set(sceneElements[transition.fromScene] ?? []);
   const sceneBIds = new Set(sceneElements[transition.toScene] ?? []);
   buffers.bufferA.fill(0);
   buffers.bufferB.fill(0);
-  for (const [sceneBuf, sceneIds] of [
+  const sceneCaptures: [Buffer, Set<string>][] = [
     [buffers.bufferA, sceneAIds],
     [buffers.bufferB, sceneBIds],
-  ] as const) {
+  ];
+  for (const [sceneBuf, sceneIds] of sceneCaptures) {
     await captureSceneIntoBuffer({
       session,
-      sceneBuf: sceneBuf as Buffer,
+      sceneBuf,
       sceneIds,
       stackingInfo,
       time,
diff --git a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
index 5479cd2356..90e056cb32 100644
--- a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
@@ -32,7 +32,6 @@ import {
   crossfade,
   initTransparentBackground,
   initializeSession,
-  queryElementStacking,
 } from "@hyperframes/engine";
 import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
@@ -54,6 +53,7 @@ import {
   distributeLayeredHybridFrameRanges,
   ensureFrameWritten,
   partitionTransitionFrames,
+  seekInjectAndQueryStacking,
 } from "./captureHdrFrameShared.js";
 import { updateJobStatus } from "../shared.js";
 
@@ -305,19 +305,15 @@ export async function runHybridLayeredFrameLoop(input: HybridLoopInput): Promise
             throw err instanceof Error ? err : new Error(String(err));
           });
         } else {
-          const beforeCaptureHook = session.onBeforeCapture;
-          await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
-            session.page.evaluate((t: number) => {
-              if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-            }, time),
-          );
-          if (beforeCaptureHook) {
-            await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () =>
-              beforeCaptureHook(session.page, time),
-            );
-          }
-          const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
-            queryElementStacking(session.page, nativeHdrIds),
+          const stackingInfo = await seekInjectAndQueryStacking(
+            session.page,
+            time,
+            session.onBeforeCapture,
+            nativeHdrIds,
+            hdrPerf,
+            "frameSeekMs",
+            "frameInjectMs",
+            "stackingQueryMs",
           );
           canvas.fill(0);
           // Rebind ctx to this worker's session for per-layer captures
diff --git a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
index 11141c2051..5928378378 100644
--- a/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrSequentialLoop.ts
@@ -18,7 +18,6 @@ import {
   type TransitionFn,
   TRANSITIONS,
   crossfade,
-  queryElementStacking,
 } from "@hyperframes/engine";
 import type { ProducerLogger } from "../../../logger.js";
 import {
@@ -39,6 +38,7 @@ import {
   cleanupEndedHdrVideos,
   ensureFrameWritten,
   type LayeredTransitionBuffers,
+  seekInjectAndQueryStacking,
 } from "./captureHdrFrameShared.js";
 import { updateJobStatus } from "../shared.js";
 
@@ -109,19 +109,15 @@ export async function runSequentialLayeredFrameLoop(input: SequentialLoopInput):
     const time = (i * job.config.fps.den) / job.config.fps.num;
     if (hdrPerf) hdrPerf.frames += 1;
 
-    await timeHdrPhaseAsync(hdrPerf, "frameSeekMs", () =>
-      domSession.page.evaluate((t: number) => {
-        if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
-      }, time),
-    );
-
-    if (beforeCaptureHook) {
-      await timeHdrPhaseAsync(hdrPerf, "frameInjectMs", () =>
-        beforeCaptureHook(domSession.page, time),
-      );
-    }
-    const stackingInfo = await timeHdrPhaseAsync(hdrPerf, "stackingQueryMs", () =>
-      queryElementStacking(domSession.page, nativeHdrIds),
+    const stackingInfo = await seekInjectAndQueryStacking(
+      domSession.page,
+      time,
+      beforeCaptureHook,
+      nativeHdrIds,
+      hdrPerf,
+      "frameSeekMs",
+      "frameInjectMs",
+      "stackingQueryMs",
     );
     const activeTransition = transitionRanges.find((t) => i >= t.startFrame && i <= t.endFrame);
 
@@ -151,14 +147,15 @@ export async function runSequentialLayeredFrameLoop(input: SequentialLoopInput):
         transitionBuffers.bufferB.fill(0);
       });
 
-      for (const [sceneBuf, sceneIds] of [
+      const sceneCaptures: [Buffer, Set<string>][] = [
         [transitionBuffers.bufferA, sceneAIds],
         [transitionBuffers.bufferB, sceneBIds],
-      ] as const) {
+      ];
+      for (const [sceneBuf, sceneIds] of sceneCaptures) {
         assertNotAborted();
         await captureSceneIntoBuffer({
           session: domSession,
-          sceneBuf: sceneBuf as Buffer,
+          sceneBuf,
           sceneIds,
           stackingInfo,
           time,
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index e6b99b10f6..984d4c532f 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -696,6 +696,8 @@ function normalizeCompositionSrcPath(srcPath: string): string {
 }
 
 function createStandaloneEntryRenderClone(root: Element, host: Element): Element {
+  // linkedom's cloneNode returns `any` (not `Node`), so the Element cast
+  // is needed to access setAttribute/appendChild without losing type safety.
   const hostClone = host.cloneNode(true) as Element;
   hostClone.setAttribute("data-start", "0");
 
@@ -741,6 +743,9 @@ export function extractStandaloneEntryFromIndex(
   const body = document.querySelector("body");
   if (!body) return null;
 
+  // linkedom's querySelectorAll returns `any` on Document and `NodeList` on
+  // the ParentNode mixin. Neither types the elements as `Element`, so the
+  // cast is required to call getAttribute / hasAttribute without `any`.
   const hosts = Array.from(document.querySelectorAll("[data-composition-src]")) as Element[];
   const host = hosts.find(
     (candidate) =>
@@ -749,6 +754,8 @@ export function extractStandaloneEntryFromIndex(
   );
   if (!host) return null;
 
+  // linkedom's `children` is typed as `NodeList` (not `HTMLCollection<Element>`),
+  // so the Element[] cast is needed.
   const root =
     (Array.from(body.children) as Element[]).find((candidate) =>
       candidate.hasAttribute("data-composition-id"),
@@ -807,7 +814,7 @@ export async function executeRenderJob(
     log,
     renderJobId: job.id,
   });
-  const outputFormat = (job.config.format ?? "mp4") as NonNullable<RenderConfig["format"]>;
+  const outputFormat = job.config.format ?? ("mp4" as const);
   const isWebm = outputFormat === "webm";
   const isMov = outputFormat === "mov";
   const isPngSequence = outputFormat === "png-sequence";

From 1d249d3047de4fc739b45487efe17cdee47a1652 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 13 Jun 2026 15:57:51 -0400
Subject: [PATCH 8/8] refactor(producer): name constants, type matrix, extract
 opacity helper

- Replace magic 0.001/0.999 with TRANSFORM_IDENTITY_EPSILON and
  OPAQUE_ALPHA_THRESHOLD; replace BPP=6 with RGB48_BYTES_PER_PIXEL
- Add AffineMatrix tuple type + isAffineMatrix guard, eliminating
  all 4 non-null assertions on matrix indices
- Extract resolveBlitOpacity() to replace 5 identical ternaries
- Narrow fallow-ignore-file to line-level complexity suppressions
---
 .../producer/src/services/hdrCompositor.ts    | 78 ++++++++++---------
 1 file changed, 41 insertions(+), 37 deletions(-)

diff --git a/packages/producer/src/services/hdrCompositor.ts b/packages/producer/src/services/hdrCompositor.ts
index 4659dde380..f188bd8cd5 100644
--- a/packages/producer/src/services/hdrCompositor.ts
+++ b/packages/producer/src/services/hdrCompositor.ts
@@ -1,4 +1,3 @@
-// fallow-ignore-file complexity code-duplication
 /**
  * HDR Compositor — pixel-level compositing primitives for the HDR
  * layered render path.
@@ -66,6 +65,22 @@ function countNonZeroRgb48(buf: Uint8Array): number {
   return n;
 }
 
+// ─── Constants ────────────────────────────────────────────────────────────
+
+const TRANSFORM_IDENTITY_EPSILON = 0.001;
+const OPAQUE_ALPHA_THRESHOLD = 0.999;
+const RGB48_BYTES_PER_PIXEL = 6;
+
+type AffineMatrix = [number, number, number, number, number, number];
+
+function isAffineMatrix(m: number[]): m is AffineMatrix {
+  return m.length === 6;
+}
+
+function resolveBlitOpacity(opacity: number): number | undefined {
+  return opacity < OPAQUE_ALPHA_THRESHOLD ? opacity : undefined;
+}
+
 // ─── Types ─────────────────────────────────────────────────────────────────
 
 /**
@@ -96,14 +111,13 @@ function cropRgb48le(
   cropW: number,
   cropH: number,
 ): Buffer {
-  const BPP = 6;
-  const dst = Buffer.alloc(cropW * cropH * BPP);
+  const dst = Buffer.alloc(cropW * cropH * RGB48_BYTES_PER_PIXEL);
   for (let row = 0; row < cropH; row++) {
     const srcRow = cropY + row;
     if (srcRow < 0 || srcRow >= srcH) continue;
-    const srcOff = (srcRow * srcW + cropX) * BPP;
-    const dstOff = row * cropW * BPP;
-    const copyLen = Math.min(cropW, srcW - cropX) * BPP;
+    const srcOff = (srcRow * srcW + cropX) * RGB48_BYTES_PER_PIXEL;
+    const dstOff = row * cropW * RGB48_BYTES_PER_PIXEL;
+    const copyLen = Math.min(cropW, srcW - cropX) * RGB48_BYTES_PER_PIXEL;
     if (copyLen > 0) src.copy(dst, dstOff, srcOff, srcOff + copyLen);
   }
   return dst;
@@ -138,6 +152,7 @@ export function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: Prod
   }
 }
 
+// fallow-ignore-next-line complexity
 export function blitHdrVideoLayer(
   canvas: Buffer,
   el: ElementStackingInfo,
@@ -184,18 +199,13 @@ export function blitHdrVideoLayer(
       );
     }
 
-    const viewportMatrix = parseTransformMatrix(el.transform);
+    const rawMatrix = parseTransformMatrix(el.transform);
+    const matrix = rawMatrix && isAffineMatrix(rawMatrix) ? rawMatrix : null;
 
-    // Pass border-radius for rounded-corner masking (only when non-zero)
     const br = el.borderRadius;
     const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
     const borderRadiusParam = hasBorderRadius ? br : undefined;
 
-    // Apply ancestor overflow:hidden clip rect by constraining the blit
-    // bounds. For the no-transform (region) path, we crop the source
-    // image and adjust the destination position. For the affine path,
-    // clip rect support is not yet implemented (would require per-pixel
-    // scissor in the affine blit); log a warning and skip clipping.
     let blitX = el.x;
     let blitY = el.y;
     let blitSrcX = 0;
@@ -210,7 +220,7 @@ export function blitHdrVideoLayer(
       const cy1 = Math.max(blitY, cr.y);
       const cx2 = Math.min(blitX + blitW, cr.x + cr.width);
       const cy2 = Math.min(blitY + blitH, cr.y + cr.height);
-      if (cx2 <= cx1 || cy2 <= cy1) return; // fully clipped
+      if (cx2 <= cx1 || cy2 <= cy1) return;
       blitSrcX = cx1 - blitX;
       blitSrcY = cy1 - blitY;
       blitW = cx2 - cx1;
@@ -220,23 +230,16 @@ export function blitHdrVideoLayer(
       clipped = true;
     }
 
-    // Detect translation-only matrix (no scale/rotation) — route through the
-    // region path which supports clip rects. Chrome reports a viewport matrix
-    // for all HDR elements, even untransformed ones or those with only layout
-    // translation (e.g. `left: 960px` → `matrix(1,0,0,1,960,0)`). The region
-    // blit handles translation via el.x/el.y, so we only need the affine path
-    // for actual scale/rotation transforms.
-    // parseTransformMatrix returns a 6-element array or null — length check unnecessary.
     const isTranslationOnly = !!(
-      viewportMatrix &&
-      Math.abs(viewportMatrix[0]! - 1) < 0.001 &&
-      Math.abs(viewportMatrix[1]!) < 0.001 &&
-      Math.abs(viewportMatrix[2]!) < 0.001 &&
-      Math.abs(viewportMatrix[3]! - 1) < 0.001
+      matrix &&
+      Math.abs(matrix[0] - 1) < TRANSFORM_IDENTITY_EPSILON &&
+      Math.abs(matrix[1]) < TRANSFORM_IDENTITY_EPSILON &&
+      Math.abs(matrix[2]) < TRANSFORM_IDENTITY_EPSILON &&
+      Math.abs(matrix[3] - 1) < TRANSFORM_IDENTITY_EPSILON
     );
 
     timeHdrPhase(hdrPerf, "hdrVideoBlitMs", () => {
-      if (viewportMatrix && !isTranslationOnly) {
+      if (matrix && !isTranslationOnly) {
         if (clipped && log) {
           log.debug(
             `HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
@@ -245,16 +248,15 @@ export function blitHdrVideoLayer(
         blitRgb48leAffine(
           canvas,
           hdrRgb,
-          viewportMatrix,
+          matrix,
           srcW,
           srcH,
           width,
           height,
-          el.opacity < 0.999 ? el.opacity : undefined,
+          resolveBlitOpacity(el.opacity),
           borderRadiusParam,
         );
       } else if (clipped) {
-        // Crop the source buffer to the clipped region before blitting
         const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
         blitRgb48leRegion(
           canvas,
@@ -265,7 +267,7 @@ export function blitHdrVideoLayer(
           blitH,
           width,
           height,
-          el.opacity < 0.999 ? el.opacity : undefined,
+          resolveBlitOpacity(el.opacity),
           borderRadiusParam,
         );
       } else {
@@ -278,7 +280,7 @@ export function blitHdrVideoLayer(
           srcH,
           width,
           height,
-          el.opacity < 0.999 ? el.opacity : undefined,
+          resolveBlitOpacity(el.opacity),
           borderRadiusParam,
         );
       }
@@ -343,23 +345,24 @@ export function blitHdrImageLayer(
         : buf.data,
     );
 
-    const viewportMatrix = parseTransformMatrix(el.transform);
+    const rawMatrix = parseTransformMatrix(el.transform);
+    const matrix = rawMatrix && isAffineMatrix(rawMatrix) ? rawMatrix : null;
 
     const br = el.borderRadius;
     const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
     const borderRadiusParam = hasBorderRadius ? br : undefined;
 
     timeHdrPhase(hdrPerf, "hdrImageBlitMs", () => {
-      if (viewportMatrix) {
+      if (matrix) {
         blitRgb48leAffine(
           canvas,
           hdrRgb,
-          viewportMatrix,
+          matrix,
           buf.width,
           buf.height,
           width,
           height,
-          el.opacity < 0.999 ? el.opacity : undefined,
+          resolveBlitOpacity(el.opacity),
           borderRadiusParam,
         );
       } else {
@@ -372,7 +375,7 @@ export function blitHdrImageLayer(
           buf.height,
           width,
           height,
-          el.opacity < 0.999 ? el.opacity : undefined,
+          resolveBlitOpacity(el.opacity),
           borderRadiusParam,
         );
       }
@@ -462,6 +465,7 @@ export interface HdrCompositeContext {
  *                          dumps. Pass `-1` to disable per-layer dumps even
  *                          when `KEEP_TEMP=1` (e.g. for warmup frames).
  */
+// fallow-ignore-next-line complexity
 export async function compositeHdrFrame(
   ctx: HdrCompositeContext,
   canvas: Buffer,