feat(engine): default-on page-side compositing for SDR shader transitions

Page-side compositing is now enabled by default for SDR shader-transition
renders without video content. The 6.6× speedup applies automatically —
no flag needed.

Auto-disables when:
- HDR content detected
- Alpha output (WebM/MOV/PNG-sequence)
- Composition contains <video> elements (cloneNode loses playback state)
- beginFrame capture mode (Linux headless)

Use --no-page-side-compositing to force the Node-side layered path.

Changes:
- Engine config: enablePageSideCompositing defaults to true
- CLI: flag default flipped to true; --no-page-side-compositing disables
- Orchestrator: added composition.videos.length === 0 gate
- Docker: forwards --no-page-side-compositing when explicitly disabled
- Config tests updated for new default

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/cli/src/commands/render.ts

@@ -225,12 +225,11 @@ export default defineCommand({
     "page-side-compositing": {
       type: "boolean",
       description:
-        "EXPERIMENTAL. Run shader transitions on a page-side WebGL canvas " +
-        "inside Chrome instead of the Node-side layered blend. ~6× faster " +
-        "for SDR shader-transition renders on Mac. HDR/alpha content forces " +
-        "the existing path. Scenes with <video> or live <canvas> elements " +
-        "may render those elements as black during transition windows.",
-      default: false,
+        "Run shader transitions on a page-side WebGL canvas inside Chrome " +
+        "instead of the Node-side layered blend. ~6× faster for SDR " +
+        "shader-transition renders. HDR/alpha/video content auto-disables. " +
+        "Use --no-page-side-compositing to force the layered path.",
+      default: true,
     },
   },
   async run({ args }) {
@@ -304,13 +303,8 @@ export default defineCommand({
     }
 
     // ── 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";
+    if (args["page-side-compositing"] === false) {
+      process.env.HF_PAGE_SIDE_COMPOSITING = "false";
     }
 
     // ── Validate max-concurrent-renders ─────────────────────────────────
@@ -558,7 +552,7 @@ export default defineCommand({
         variables,
         entryFile,
         outputResolution,
-        pageSideCompositing: !!args["page-side-compositing"],
+        pageSideCompositing: args["page-side-compositing"] !== false,
         exitAfterComplete: true,
       });
     } else {

packages/cli/src/utils/dockerRunArgs.test.ts

@@ -278,16 +278,16 @@ describe("buildDockerRunArgs", () => {
     expect(args).not.toContain("--resolution");
   });
 
-  it("forwards --page-side-compositing when pageSideCompositing is true", () => {
+  it("forwards --no-page-side-compositing when pageSideCompositing is false", () => {
     const args = buildDockerRunArgs({
       ...FIXED_INPUT,
-      options: { ...BASE, pageSideCompositing: true },
+      options: { ...BASE, pageSideCompositing: false },
     });
-    expect(args).toContain("--page-side-compositing");
+    expect(args).toContain("--no-page-side-compositing");
   });
 
-  it("omits --page-side-compositing when pageSideCompositing is not set", () => {
+  it("omits --no-page-side-compositing when pageSideCompositing is not explicitly false", () => {
     const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
-    expect(args).not.toContain("--page-side-compositing");
+    expect(args).not.toContain("--no-page-side-compositing");
   });
 });

packages/cli/src/utils/dockerRunArgs.ts

@@ -81,6 +81,6 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
       : []),
     ...(options.entryFile ? ["--composition", options.entryFile] : []),
     ...(options.outputResolution ? ["--resolution", options.outputResolution] : []),
-    ...(options.pageSideCompositing ? ["--page-side-compositing"] : []),
+    ...(options.pageSideCompositing === false ? ["--no-page-side-compositing"] : []),
   ];
 }

packages/engine/src/config.test.ts

@@ -140,22 +140,15 @@ describe("resolveConfig", () => {
   });
 
   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");
+    it("defaults to 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("disabled when HF_PAGE_SIDE_COMPOSITING=false", () => {
+      setEnv("HF_PAGE_SIDE_COMPOSITING", "false");
+      const config = resolveConfig();
+      expect(config.enablePageSideCompositing).toBe(false);
     });
 
     it("explicit override wins over the env var", () => {

packages/engine/src/config.ts

@@ -177,7 +177,7 @@ export const DEFAULT_CONFIG: EngineConfig = {
   browserTimeout: 120_000,
   protocolTimeout: 300_000,
   forceScreenshot: false,
-  enablePageSideCompositing: false,
+  enablePageSideCompositing: true,
 
   enableChunkedEncode: false,
   chunkSizeFrames: 360,

packages/producer/src/services/renderOrchestrator.ts

@@ -1762,7 +1762,8 @@ export async function executeRenderJob(
       compiled.hasShaderTransitions &&
       !hasHdrContent &&
       !isPngSequence &&
-      !needsAlpha;
+      !needsAlpha &&
+      composition.videos.length === 0;
     if (usePageSideCompositingForTransitions) {
       fileServer.addPreHeadScript(HF_PAGE_SIDE_COMPOSITING_STUB);
       log.info(