Skip to content

Write HTML. Render video. Built for agents.

fix(engine): preserve composition root background in alpha exports (#3976)

miga-heygend7285e414b36
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index dac4eaf3be..64c644d02f 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -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.
diff --git a/packages/engine/src/services/screenshotService.test.ts b/packages/engine/src/services/screenshotService.test.ts
index b2546013c1..4ff0b360e7 100644
--- a/packages/engine/src/services/screenshotService.test.ts
+++ b/packages/engine/src/services/screenshotService.test.ts
@@ -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(
diff --git a/packages/engine/src/services/screenshotService.ts b/packages/engine/src/services/screenshotService.ts
index 61d9168371..3618c773dd 100644
--- a/packages/engine/src/services/screenshotService.ts
+++ b/packages/engine/src/services/screenshotService.ts
@@ -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,
+ );
}
/**
diff --git a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
index 099b3bf1be..04bacae20d 100644
--- a/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
+++ b/packages/producer/src/services/render/stages/captureHdrHybridLoop.ts
@@ -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];
diff --git a/packages/producer/src/services/render/stages/captureHdrStage.ts b/packages/producer/src/services/render/stages/captureHdrStage.ts
index 8b1d0a60f7..e63f389047 100644
--- a/packages/producer/src/services/render/stages/captureHdrStage.ts
+++ b/packages/producer/src/services/render/stages/captureHdrStage.ts
@@ -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(() => {
diff --git a/packages/producer/src/transparency-test.ts b/packages/producer/src/transparency-test.ts
index e686f53bd6..8b8d76eacb 100644
--- a/packages/producer/src/transparency-test.ts
+++ b/packages/producer/src/transparency-test.ts
@@ -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);
diff --git a/packages/producer/tests/shard-schedule.json b/packages/producer/tests/shard-schedule.json
index b6beb922ad..b33adbe59f 100644
--- a/packages/producer/tests/shard-schedule.json
+++ b/packages/producer/tests/shard-schedule.json
@@ -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."
diff --git a/packages/producer/tests/transparency-regression-root-bg/meta.json b/packages/producer/tests/transparency-regression-root-bg/meta.json
new file mode 100644
index 0000000000..ff0b499e26
--- /dev/null
+++ b/packages/producer/tests/transparency-regression-root-bg/meta.json
@@ -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
+ }
+}
diff --git a/packages/producer/tests/transparency-regression-root-bg/src/index.html b/packages/producer/tests/transparency-regression-root-bg/src/index.html
new file mode 100644
index 0000000000..b09bc3c634
--- /dev/null
+++ b/packages/producer/tests/transparency-regression-root-bg/src/index.html
@@ -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>