Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Promisecfg,);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.tsindex 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.tsindex 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/renderOrchestratorconst 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 transparentconst TRANSPARENT_Y = 10;const OPAQUE_X = 100; // inside the 50–150 red cardconst 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.jsonindex 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.jsonnew file mode 100644index 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.htmlnew file mode 100644index 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>