@@ -1486,7 +1486,7 @@ async function constructCaptureSession(
 
   // Transparent-background setup is intentionally NOT done here. Chrome resets
   // the default-background-color override on navigation, and the
-  // `[data-composition-id]{background:transparent}` stylesheet that
+  // `html,body{background:transparent}` stylesheet that
   // `initTransparentBackground` injects must land in a real `document.head`.
   // See `initializeSession()` below — it calls `initTransparentBackground` for
   // PNG captures after `page.goto(...)` and the `window.__hf` readiness poll.
 
@@ -13,6 +13,7 @@ import {
   injectVideoFramesBatch,
   syncVideoFrameVisibility,
   shouldDefaultCaptureBeyondViewport,
+  initTransparentBackground,
   DOM_LAYER_MASK_STYLE_ID,
 } from "./screenshotService.js";
 
@@ -175,6 +176,70 @@ describe("pageContentExceedsCaptureHeight", () => {
   });
 });
 
+describe("initTransparentBackground", () => {
+  // evaluate() runs against a linkedom document in globalThis; the cached CDP stub skips createCDPSession().
+  function makeFakePageWithDom() {
+    const { document } = parseHTML("<html><body></body></html>");
+    const send = vi.fn().mockResolvedValue({});
+    const fakeSession = { send } as unknown as import("puppeteer-core").CDPSession;
+    const fakePage = {
+      evaluate: async (fn: (...args: never[]) => void, ...args: never[]) => fn(...args),
+    } as unknown as Page;
+    cdpSessionCache.set(fakePage, fakeSession);
+    const globals = globalThis as unknown as { document?: Document };
+    const previousDocument = globals.document;
+    globals.document = document;
+    return {
+      page: fakePage,
+      document,
+      send,
+      restore: () => {
+        globals.document = previousDocument;
+      },
+    };
+  }
+
+  it("clears only html/body when clearCompositionRoot is false — an authored composition-root background must survive", async () => {
+    const { page, document, send, restore } = makeFakePageWithDom();
+    try {
+      await initTransparentBackground(page, { clearCompositionRoot: false });
+      const style = document.getElementById("__hf_transparent_bg__");
+      expect(style?.textContent).toContain("html,body{");
+      expect(style?.textContent).not.toContain("[data-composition-id]");
+      expect(send).toHaveBeenCalledWith("Emulation.setDefaultBackgroundColorOverride", {
+        color: { r: 0, g: 0, b: 0, a: 0 },
+      });
+    } finally {
+      restore();
+    }
+  });
+
+  it("also clears the composition root when clearCompositionRoot is true (HDR layered DOM pass)", async () => {
+    const { page, document, restore } = makeFakePageWithDom();
+    try {
+      await initTransparentBackground(page, { clearCompositionRoot: true });
+      const style = document.getElementById("__hf_transparent_bg__");
+      expect(style?.textContent).toContain("[data-composition-id]");
+    } finally {
+      restore();
+    }
+  });
+
+  it("a later call replaces the earlier call's rule instead of no-op'ing on the existing style element", async () => {
+    const { page, document, restore } = makeFakePageWithDom();
+    try {
+      await initTransparentBackground(page, { clearCompositionRoot: false });
+      await initTransparentBackground(page, { clearCompositionRoot: true });
+      expect(document.querySelectorAll('style[id="__hf_transparent_bg__"]').length).toBe(1);
+      expect(document.getElementById("__hf_transparent_bg__")?.textContent).toContain(
+        "[data-composition-id]",
+      );
+    } finally {
+      restore();
+    }
+  });
+});
+
 describe("injectVideoFramesBatch replacement layout", () => {
   it("does not copy opposing inset constraints onto the injected frame image", async () => {
     const { window, document } = parseHTML(
 
@@ -279,43 +279,34 @@ export async function captureScreenshotWithAlpha(
 }
 
 /**
- * Set the page background to transparent once for a dedicated HDR DOM session.
- *
- * Call this once after session initialization. Then use captureAlphaPng() per
- * frame instead of captureScreenshotWithAlpha() to skip the per-frame CDP
- * background override round-trips.
- *
- * Only use on sessions that are exclusively dedicated to transparent capture
- * (e.g., the HDR two-pass DOM layer session) — the background will stay
- * transparent for the lifetime of the session.
- *
- * NOTE on the injected stylesheet: `Emulation.setDefaultBackgroundColorOverride`
- * only replaces the *default* page background. Compositions almost always set
- * `body { background: ... }` and `#root { background: ... }`, which paint over
- * the override and ruin alpha capture for layered HDR compositing — the
- * composition root's full-frame background paints across the entire viewport
- * and wipes out HDR content captured beneath it.
- *
- * We force `html`, `body`, and any element marked as a composition root
- * (`[data-composition-id]`) to transparent. In HDR layered compositing the HDR
- * video itself is the backdrop, so DOM layers must only contribute their
- * foreground UI pixels — never a page-spanning solid backdrop.
+ * Make the page transparent for alpha capture, then use captureAlphaPng() per frame. html/body always clear;
+ * [data-composition-id] roots (nested too) keep their background unless clearCompositionRoot (HDR layered pass).
+ * A repeat call rewrites the rule, so the last call wins.
  */
 const TRANSPARENT_BG_STYLE_ID = "__hf_transparent_bg__";
 
-export async function initTransparentBackground(page: Page): Promise<void> {
+export async function initTransparentBackground(
+  page: Page,
+  { clearCompositionRoot = false }: { clearCompositionRoot?: boolean } = {},
+): Promise<void> {
   const client = await getCdpSession(page);
   await client.send("Emulation.setDefaultBackgroundColorOverride", {
     color: { r: 0, g: 0, b: 0, a: 0 },
   });
-  await page.evaluate((styleId: string) => {
-    if (document.getElementById(styleId)) return;
-    const style = document.createElement("style");
-    style.id = styleId;
-    style.textContent =
-      "html,body,[data-composition-id]{background:transparent !important;background-color:transparent !important;background-image:none !important;}";
-    document.head.appendChild(style);
-  }, TRANSPARENT_BG_STYLE_ID);
+  await page.evaluate(
+    (styleId: string, clearCompositionRoot: boolean) => {
+      const selector = clearCompositionRoot ? "html,body,[data-composition-id]" : "html,body";
+      let style = document.getElementById(styleId);
+      if (!style) {
+        style = document.createElement("style");
+        style.id = styleId;
+        document.head.appendChild(style);
+      }
+      style.textContent = `${selector}{background:transparent !important;background-color:transparent !important;background-image:none !important;}`;
+    },
+    TRANSPARENT_BG_STYLE_ID,
+    clearCompositionRoot,
+  );
 }
 
 /**
 
@@ -128,7 +128,7 @@ export async function runHybridLayeredFrameLoop(input: HybridLoopInput): Promise
         cfg,
       );
       await initializeSession(s);
-      await initTransparentBackground(s.page);
+      await initTransparentBackground(s.page, { clearCompositionRoot: true });
       workerSessions.push(s);
     }
     const sessions: CaptureSession[] = [domSession, ...workerSessions];
 
@@ -222,7 +222,7 @@ export async function runCaptureHdrStage(
     await initializeSession(domSession);
     assertNotAborted();
     lastBrowserConsole = domSession.browserConsoleBuffer;
-    await initTransparentBackground(domSession.page);
+    await initTransparentBackground(domSession.page, { clearCompositionRoot: true });
 
     // ── Scene detection for shader transitions ──────────────────────────
     const transitionMeta: HdrTransitionMeta[] = await domSession.page.evaluate(() => {
 
@@ -31,6 +31,8 @@ import { createRenderJob, executeRenderJob } from "./services/renderOrchestrator
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const FIXTURE_DIR = resolve(moduleDir, "../tests/transparency-regression");
 const FIXTURE_SRC = join(FIXTURE_DIR, "src");
+const ROOT_BG_FIXTURE_DIR = resolve(moduleDir, "../tests/transparency-regression-root-bg");
+const ROOT_BG_FIXTURE_SRC = join(ROOT_BG_FIXTURE_DIR, "src");
 const SHADER_FIXTURE_DIR = resolve(moduleDir, "../tests/page-side-shader-compositor-render-compat");
 const SHADER_FIXTURE_SRC = join(SHADER_FIXTURE_DIR, "src");
 const SHADER_GOLDEN = join(SHADER_FIXTURE_DIR, "output", "output.mp4");
@@ -43,6 +45,10 @@ const TRANSPARENT_X = 10; // expected fully transparent
 const TRANSPARENT_Y = 10;
 const OPAQUE_X = 100; // inside the 50–150 red card
 const OPAQUE_Y = 100;
+// Root-bg fixture: same canvas and red card, but the composition root paints rgb(0,0,255) full-frame,
+// so (10,10) must decode opaque blue in alpha output.
+const ROOT_BG_X = 10;
+const ROOT_BG_Y = 10;
 
 function pixelOffset(x: number, y: number, width: number): number {
   return (y * width + x) * 4;
@@ -52,7 +58,7 @@ function assertAlphaPixel(
   png: { data: Uint8Array; width: number; height: number },
   x: number,
   y: number,
-  expectAlpha: "transparent" | "opaque-red",
+  expectAlpha: "transparent" | "opaque-red" | "opaque-blue",
   label: string,
 ): void {
   assert.equal(png.width, WIDTH, `${label}: width mismatch`);
@@ -68,23 +74,25 @@ function assertAlphaPixel(
       0,
       `${label}: pixel (${x},${y}) expected fully transparent (alpha=0), got rgba(${r},${g},${b},${a})`,
     );
-  } else {
-    assert.equal(
-      a,
-      255,
-      `${label}: pixel (${x},${y}) expected fully opaque (alpha=255), got rgba(${r},${g},${b},${a})`,
-    );
-    assert.ok(
-      typeof r === "number" && r >= 240,
-      `${label}: pixel (${x},${y}) expected red >= 240, got rgba(${r},${g},${b},${a})`,
-    );
-    assert.ok(
-      typeof g === "number" && g <= 30,
-      `${label}: pixel (${x},${y}) expected green <= 30, got rgba(${r},${g},${b},${a})`,
-    );
+    return;
+  }
+  assert.equal(
+    a,
+    255,
+    `${label}: pixel (${x},${y}) expected fully opaque (alpha=255), got rgba(${r},${g},${b},${a})`,
+  );
+  const expectRed = expectAlpha === "opaque-red";
+  const dominantName = expectRed ? "red" : "blue";
+  const dominantValue = expectRed ? r : b;
+  const otherChannels = expectRed ? { green: g, blue: b } : { red: r, green: g };
+  assert.ok(
+    typeof dominantValue === "number" && dominantValue >= 240,
+    `${label}: pixel (${x},${y}) expected ${dominantName} >= 240, got rgba(${r},${g},${b},${a})`,
+  );
+  for (const [name, value] of Object.entries(otherChannels)) {
     assert.ok(
-      typeof b === "number" && b <= 30,
-      `${label}: pixel (${x},${y}) expected blue <= 30, got rgba(${r},${g},${b},${a})`,
+      typeof value === "number" && value <= 30,
+      `${label}: pixel (${x},${y}) expected ${name} <= 30, got rgba(${r},${g},${b},${a})`,
     );
   }
 }
@@ -187,6 +195,30 @@ async function runWebmCheck(workRoot: string): Promise<void> {
   console.log("[webm] PASS — transparent + opaque-red pixels verified");
 }
 
+async function runRootBackgroundCheck(workRoot: string): Promise<void> {
+  console.log("\n[root-bg] rendering transparency-regression-root-bg …");
+  const outDir = join(workRoot, "root-bg");
+  mkdirSync(outDir, { recursive: true });
+  const outPath = join(outDir, "out.webm");
+
+  const job = createRenderJob({
+    fps: FPS,
+    quality: "draft",
+    format: "webm",
+  });
+
+  await executeRenderJob(job, ROOT_BG_FIXTURE_SRC, outPath);
+  assert.equal(job.status, "complete", `root-bg render did not complete: status=${job.status}`);
+  assert.ok(existsSync(outPath), `root-bg output not written to ${outPath}`);
+
+  const framePng = join(outDir, "frame-0.png");
+  await extractFirstFrameFromWebm(outPath, framePng);
+  const decoded = decodePng(readFileSync(framePng));
+  assertAlphaPixel(decoded, ROOT_BG_X, ROOT_BG_Y, "opaque-blue", "root-bg");
+  assertAlphaPixel(decoded, OPAQUE_X, OPAQUE_Y, "opaque-red", "root-bg");
+  console.log("[root-bg] PASS — composition root background preserved in alpha output");
+}
+
 async function runGifCheck(workRoot: string): Promise<void> {
   console.log("\n[gif] rendering transparency-regression …");
   const outDir = join(workRoot, "gif");
@@ -306,6 +338,9 @@ async function main(): Promise<void> {
   if (!existsSync(FIXTURE_SRC)) {
     throw new Error(`Fixture missing: ${FIXTURE_SRC}`);
   }
+  if (!existsSync(ROOT_BG_FIXTURE_SRC)) {
+    throw new Error(`Fixture missing: ${ROOT_BG_FIXTURE_SRC}`);
+  }
   if (!existsSync(SHADER_FIXTURE_SRC) || !existsSync(SHADER_GOLDEN)) {
     throw new Error(`Shader fixture or golden missing: ${SHADER_FIXTURE_DIR}`);
   }
@@ -315,6 +350,7 @@ async function main(): Promise<void> {
 
   try {
     await runWebmCheck(workRoot);
+    await runRootBackgroundCheck(workRoot);
     await runGifCheck(workRoot);
     await runGifShaderTransitionCheck(workRoot);
     await runPngSequenceCheck(workRoot);
 
@@ -93,6 +93,7 @@
     "three-boundary-deferred": "Was absent from the hand-written shard matrix, so it has never run in CI and its cost and pass state are unknown. Triage and either schedule it or record a real reason here.",
     "timed-descendant-visibility": "Was absent from the hand-written shard matrix, so it has never run in CI and its cost and pass state are unknown. Triage and either schedule it or record a real reason here.",
     "transparency-regression": "Not a harness fixture by design \u2014 its meta.json says it is exercised by `tsx src/transparency-test.ts`, which asserts a real alpha channel rather than comparing against a golden MP4.",
+    "transparency-regression-root-bg": "Not a harness fixture by design, same reason as its sibling `transparency-regression` \u2014 exercised by `tsx src/transparency-test.ts`, which asserts a real alpha channel rather than comparing against a golden MP4.",
     "video-hfid-no-id": "Was absent from the hand-written shard matrix, so it has never run in CI and its cost and pass state are unknown. Triage and either schedule it or record a real reason here.",
     "webgl-video-texture-render-compat": "Was absent from the hand-written shard matrix, so it has never run in CI and its cost and pass state are unknown. Triage and either schedule it or record a real reason here.",
     "wysiwyg-subcomp-css": "Rejected by the harness at load time (meta.json: maxAudioLagWindows must be >= 1), so it has never run despite looking scheduled-able. Fix the metadata, then schedule it."
 
@@ -0,0 +1,8 @@
+{
+  "name": "Transparency Regression — Composition Root Background",
+  "description": "Asserts that an author-painted background on the composition root itself (not html/body) survives into alpha-carrying output instead of being force-cleared. Exercised by `tsx src/transparency-test.ts`, NOT by the standard regression harness (which compares against a golden MP4).",
+  "tags": ["transparency", "alpha", "smoke"],
+  "renderConfig": {
+    "fps": 30
+  }
+}
@@ -0,0 +1,31 @@
+<!doctype html>
+<html>
+  <head>
+    <style>
+      /* Only the composition root paints a background; body stays unpainted. */
+      body {
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="transparency-regression-root-bg"
+      data-width="200"
+      data-height="200"
+      data-start="0"
+      data-duration="1"
+      data-no-timeline
+      style="position: absolute; inset: 0; background: rgb(0, 0, 255)"
+    >
+      <div
+        class="card"
+        style="position: absolute; left: 50px; top: 50px; width: 100px; height: 100px; background: rgb(255, 0, 0)"
+      ></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+    </script>
+  </body>
+</html>
Original file line number	Diff line number	Diff line change
`@@ -128,7 +128,7 @@ export async function runHybridLayeredFrameLoop(input: HybridLoopInput): Promise`
`128`	`128`	`cfg,`
`129`	`129`	`);`
`130`	`130`	`await initializeSession(s);`
`131`		`- await initTransparentBackground(s.page);`
	`131`	`+ await initTransparentBackground(s.page, { clearCompositionRoot: true });`
`132`	`132`	`workerSessions.push(s);`
`133`	`133`	`}`
`134`	`134`	`const sessions: CaptureSession[] = [domSession, ...workerSessions];`