perf(engine): page-side compositing for shader transitions (opt-in spike)

Add an opt-in `--page-side-compositing` flag (CLI) backed by a new engine
config field `enablePageSideCompositing` and env var `HF_PAGE_SIDE_COMPOSITING`.
When set, SDR shader-transition compositions skip the Node-side layered blend
(the hf#677 chain) and instead run the shader inside Chrome via a page-side
WebGL canvas; the engine then captures ONE opaque RGB frame per output frame
via the existing streaming capture path.

This is the strongest non-beginFrame perf lever for Mac users, who cannot
take the beginFrame `~5×` path (Chromium structural limit, crbug.com/40656275).
Stacks on top of the hf#677 1.95× baseline.

Default OFF — existing fixture pins (byte-exact MP4 output) are preserved.
Opt-in path is intentionally PSNR-pinned, not byte-equal (WebGL is f32; Node
is f64). HDR content forces the existing layered path regardless.

Implementation:
- engine: new `EngineConfig.enablePageSideCompositing` (default false).
- producer/fileServer: new `HF_PAGE_SIDE_COMPOSITING_STUB` early-page script
  injected into the served HTML head when the flag is on.
- producer/renderOrchestrator: when the flag + no HDR + no png-sequence,
  route SDR transitions through the streaming path instead of the layered
  HDR stage.
- shader-transitions: new `engineModePageComposite.ts` installs a fullscreen
  WebGL compositor overlay and wraps `window.__hf.seek` so each seek inside
  a transition window captures both scenes via the Chromium
  `drawElementImage` API to GL textures, runs the fragment shader, and
  displays the composited result on the overlay canvas. The engine takes
  one screenshot per frame and sees the composited overlay.
- cli: new `--page-side-compositing` flag sets `HF_PAGE_SIDE_COMPOSITING=true`
  before producer load.
- scripts/page-side-compositing-smoke: bundled-CLI smoke that renders a
  representative fixture with and without the flag, validates the canary
  strings are in the shipped bundles, and writes a wall-time pair.

Determinism trade documented in the engine config doc-comment. The smoke
script enforces the bundled-CLI validation discipline from prior perf work
(see internal feedback note `validate_bundled_cli_not_dev_path`).

Runtime requirement: Chromium's `CanvasDrawElement` feature (already
enabled by the engine's `--enable-features=CanvasDrawElement` launch flag).
When the runtime feature is unavailable, the page-side installer logs a
warning and falls back to opacity-flip mode — the engine still takes the
streaming path; the transition window degrades to a hard scene swap. Vance
will validate on Mac Chrome where the feature is supported.

Co-Authored-By: Vai <vai@heygen.com>

Author: vanceingalls

packages/cli/src/commands/render.ts

@@ -222,6 +222,16 @@ export default defineCommand({
       description:
         "Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; the scale must be an integer multiple. Not yet supported with --hdr.",
     },
+    "page-side-compositing": {
+      type: "boolean",
+      description:
+        "EXPERIMENTAL (opt-in spike). Run shader transitions on a page-side " +
+        "WebGL canvas inside Chrome instead of the Node-side layered blend. " +
+        "Mac-viable lever to push past the hf#677 1.95× baseline on shader-" +
+        "transition renders. SDR only; HDR content forces the existing path. " +
+        "Pin a PSNR-based correctness check, not byte-equality, when using this.",
+      default: false,
+    },
   },
   async run({ args }) {
     // ── Resolve project ────────────────────────────────────────────────────
@@ -293,6 +303,16 @@ export default defineCommand({
       workers = parsed;
     }
 
+    // ── Wire opt-in: page-side compositing ───────────────────────────────
+    // EXPERIMENTAL — the engine reads HF_PAGE_SIDE_COMPOSITING via
+    // `resolveConfig()` (engine `EngineConfig.enablePageSideCompositing`).
+    // Set the env var BEFORE `loadProducer()` runs so producer's first call
+    // to `resolveConfig()` picks it up. Same pattern as
+    // PRODUCER_HEADLESS_SHELL_PATH below.
+    if (args["page-side-compositing"]) {
+      process.env.HF_PAGE_SIDE_COMPOSITING = "true";
+    }
+
     // ── Validate max-concurrent-renders ─────────────────────────────────
     if (args["max-concurrent-renders"] != null) {
       const parsed = parseInt(args["max-concurrent-renders"], 10);

packages/engine/src/config.test.ts

@@ -138,4 +138,30 @@ describe("resolveConfig", () => {
     const config = resolveConfig();
     expect(config.frameDataUriCacheLimit).toBe(32);
   });
+
+  describe("enablePageSideCompositing (HF_PAGE_SIDE_COMPOSITING)", () => {
+    it("defaults to false", () => {
+      const config = resolveConfig();
+      expect(config.enablePageSideCompositing).toBe(false);
+    });
+
+    it("flips to true when HF_PAGE_SIDE_COMPOSITING=true", () => {
+      setEnv("HF_PAGE_SIDE_COMPOSITING", "true");
+      const config = resolveConfig();
+      expect(config.enablePageSideCompositing).toBe(true);
+    });
+
+    it("ignores any non-'true' value", () => {
+      setEnv("HF_PAGE_SIDE_COMPOSITING", "1");
+      expect(resolveConfig().enablePageSideCompositing).toBe(false);
+      setEnv("HF_PAGE_SIDE_COMPOSITING", "yes");
+      expect(resolveConfig().enablePageSideCompositing).toBe(false);
+    });
+
+    it("explicit override wins over the env var", () => {
+      setEnv("HF_PAGE_SIDE_COMPOSITING", "true");
+      const config = resolveConfig({ enablePageSideCompositing: false });
+      expect(config.enablePageSideCompositing).toBe(false);
+    });
+  });
 });

packages/engine/src/config.ts

@@ -48,6 +48,35 @@ export interface EngineConfig {
   expectedChromiumMajor?: number;
   /** Force screenshot capture mode (skip BeginFrame even on Linux). */
   forceScreenshot: boolean;
+  /**
+   * Opt-in: page-side shader-transition compositing.
+   *
+   * When `true`, shader transitions for SDR compositions run their blend
+   * inside Chrome via WebGL on a page-side compositor canvas instead of
+   * Node-side per-pixel blending (the hf#677 layered pipeline). The engine
+   * then captures ONE opaque RGB frame per output frame via the streaming
+   * capture path, skipping per-scene transparent screenshots and the
+   * Node-side shader-blend worker pool entirely.
+   *
+   * The feature stacks on top of the hf#677 chain — it does not undo it.
+   * When this flag is OFF (the default), behaviour is byte-identical to the
+   * current path. When ON and the composition has no shader transitions or
+   * has HDR content (which forces the layered path regardless), this flag
+   * is a no-op.
+   *
+   * Mac viability: Chrome on Mac accelerates page-side WebGL canvases via
+   * Metal/CoreAnimation natively. This is the lever for Mac users who
+   * cannot use `--enable-begin-frame-control` (Chromium structural limit,
+   * crbug.com/40656275).
+   *
+   * Determinism: page-side WebGL is f32, not f64. Byte-equality fixture
+   * pins are NOT compatible with this path; the new path's correctness
+   * pin is PSNR-based. Default OFF preserves the existing pins for the
+   * hf#677 chain.
+   *
+   * Env fallback: `HF_PAGE_SIDE_COMPOSITING=true`.
+   */
+  enablePageSideCompositing: boolean;
 
   // ── Encoding ─────────────────────────────────────────────────────────
   enableChunkedEncode: boolean;
@@ -148,6 +177,7 @@ export const DEFAULT_CONFIG: EngineConfig = {
   browserTimeout: 120_000,
   protocolTimeout: 300_000,
   forceScreenshot: false,
+  enablePageSideCompositing: false,
 
   enableChunkedEncode: false,
   chunkSizeFrames: 360,
@@ -221,6 +251,10 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
       : undefined,
 
     forceScreenshot: envBool("PRODUCER_FORCE_SCREENSHOT", DEFAULT_CONFIG.forceScreenshot),
+    enablePageSideCompositing: envBool(
+      "HF_PAGE_SIDE_COMPOSITING",
+      DEFAULT_CONFIG.enablePageSideCompositing,
+    ),
 
     enableChunkedEncode: envBool(
       "PRODUCER_ENABLE_CHUNKED_ENCODE",

packages/producer/src/services/fileServer.ts

@@ -428,6 +428,29 @@ const HF_EARLY_STUB = `(function() {
   if (!window.__hf) window.__hf = {};
 })();`;
 
+/**
+ * Page-side compositing opt-in flag stub.
+ *
+ * When the engine is launched with `enablePageSideCompositing: true`, the
+ * orchestrator injects this stub into the very top of every served HTML
+ * page. The flag is read by `@hyperframes/shader-transitions`' engine-mode
+ * `init()` to switch from the default opacity-flip mode (which leaves
+ * shader blending to the Node side via the hf#677 layered pipeline) to a
+ * page-side WebGL compositor that runs the shader inside Chrome and
+ * exposes a single opaque RGB frame for the engine to capture.
+ *
+ * Sentinel ONLY — no logic here. The compositor itself ships inside
+ * `@hyperframes/shader-transitions` and is loaded by the composition's
+ * regular script bundle.
+ *
+ * Default OFF: when the flag is not set, behavior is byte-identical to
+ * the existing layered path.
+ */
+export const HF_PAGE_SIDE_COMPOSITING_STUB = `(function() {
+  if (typeof window === "undefined") return;
+  window.__HF_PAGE_SIDE_COMPOSITING__ = true;
+})();`;
+
 /**
  * Bridge script: maps window.__player (Hyperframe runtime) → window.__hf (engine protocol).
  * Injected after RENDER_MODE_SCRIPT so the engine's frameCapture can find window.__hf.

packages/producer/src/services/renderOrchestrator.ts

@@ -78,7 +78,12 @@ import {
 import { join, dirname, resolve } from "path";
 import { randomUUID } from "crypto";
 import { fileURLToPath } from "url";
-import { createFileServer, type FileServerHandle, VIRTUAL_TIME_SHIM } from "./fileServer.js";
+import {
+  createFileServer,
+  type FileServerHandle,
+  HF_PAGE_SIDE_COMPOSITING_STUB,
+  VIRTUAL_TIME_SHIM,
+} from "./fileServer.js";
 import { defaultLogger, type ProducerLogger } from "../logger.js";
 import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
 import {
@@ -1620,11 +1625,18 @@ export async function executeRenderJob(
 
     // Start file server (may already be running from duration discovery)
     if (!fileServer) {
+      // Inject the page-side compositing opt-in flag stub BEFORE the virtual
+      // time shim when the engine config opts in. The shim itself does not
+      // depend on the flag; ordering is arbitrary but stable.
+      const preHeadScripts: string[] = [VIRTUAL_TIME_SHIM];
+      if (cfg.enablePageSideCompositing) {
+        preHeadScripts.unshift(HF_PAGE_SIDE_COMPOSITING_STUB);
+      }
       fileServer = await createFileServer({
         projectDir,
         compiledDir: join(workDir, "compiled"),
         port: 0,
-        preHeadScripts: [VIRTUAL_TIME_SHIM],
+        preHeadScripts,
       });
       assertNotAborted();
     }
@@ -1742,11 +1754,32 @@ export async function executeRenderJob(
     // issues (orange shift) with no quality benefit.
     const nativeHdrIds = new Set([...nativeHdrVideoIds, ...nativeHdrImageIds]);
     const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
-    const useLayeredComposite = shouldUseLayeredComposite({
-      hasHdrContent,
-      hasShaderTransitions: compiled.hasShaderTransitions,
-      isPngSequence,
-    });
+    // Page-side compositing opt-in: when the engine is configured to run the
+    // shader blend inside Chrome via a page-side WebGL canvas, the layered
+    // Node-side composite path is unnecessary for SDR shader transitions.
+    // The streaming path takes ONE opaque RGB screenshot per output frame —
+    // exactly the single capture the page-side compositor produces. HDR
+    // content still forces the layered path (HDR layers need per-layer
+    // alpha + native HDR raw frame compositing in Node; that's out of scope
+    // for this opt-in).
+    const usePageSideCompositingForTransitions =
+      cfg.enablePageSideCompositing &&
+      compiled.hasShaderTransitions &&
+      !hasHdrContent &&
+      !isPngSequence;
+    if (usePageSideCompositingForTransitions) {
+      log.info(
+        "[Render] Page-side compositing enabled — bypassing Node-side layered " +
+          "shader-blend path. Engine will capture one opaque RGB frame per output frame.",
+      );
+    }
+    const useLayeredComposite =
+      !usePageSideCompositingForTransitions &&
+      shouldUseLayeredComposite({
+        hasHdrContent,
+        hasShaderTransitions: compiled.hasShaderTransitions,
+        isPngSequence,
+      });
     const encoderHdr = hasHdrContent ? effectiveHdr : undefined;
     // png-sequence has no encoder, but the rest of the orchestrator still
     // reads `preset.quality` for `effectiveQuality` and `preset.codec` for

packages/shader-transitions/src/engineModePageComposite.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  isPageSideCompositingSupported,
+  PAGE_COMPOSITOR_BUILD_CANARY,
+  PAGE_COMPOSITOR_CANVAS_ID,
+} from "./engineModePageComposite.js";
+
+describe("isPageSideCompositingSupported", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns false outside the browser (no window)", () => {
+    vi.stubGlobal("window", undefined);
+    expect(isPageSideCompositingSupported()).toBe(false);
+  });
+
+  it("returns false outside the browser (no document)", () => {
+    vi.stubGlobal("window", {});
+    vi.stubGlobal("document", undefined);
+    expect(isPageSideCompositingSupported()).toBe(false);
+  });
+
+  it("returns true when drawElementImage is exposed", () => {
+    vi.stubGlobal("window", {});
+    vi.stubGlobal("document", {
+      createElement: () => ({
+        setAttribute: () => undefined,
+        layoutSubtree: true,
+        getContext: () => ({ drawElementImage: () => undefined }),
+      }),
+    });
+    expect(isPageSideCompositingSupported()).toBe(true);
+  });
+
+  it("returns false when drawElementImage is missing", () => {
+    vi.stubGlobal("window", {});
+    vi.stubGlobal("document", {
+      createElement: () => ({
+        setAttribute: () => undefined,
+        layoutSubtree: true,
+        getContext: () => ({}),
+      }),
+    });
+    expect(isPageSideCompositingSupported()).toBe(false);
+  });
+});
+
+describe("page-side compositor exported constants", () => {
+  // These constants are load-bearing for the bundled-CLI smoke: the
+  // validation script greps the shipped bundle for the canary to confirm
+  // the page-side path is in the production tsup output, not just the
+  // source tree.
+  it("exports a stable canary string used by the bundled-CLI smoke", () => {
+    expect(PAGE_COMPOSITOR_BUILD_CANARY).toBe("__hf_page_compositor_v1__");
+  });
+
+  it("exports a stable canvas id", () => {
+    expect(PAGE_COMPOSITOR_CANVAS_ID).toBe("__hf-page-side-compositor");
+  });
+});