fix(engine): prevent page background bleed on system Chrome macOS#1700
Closed
miga-heygen wants to merge 3 commits into
Closed
fix(engine): prevent page background bleed on system Chrome macOS#1700miga-heygen wants to merge 3 commits into
miga-heygen wants to merge 3 commits into
Conversation
) System Chrome's "new headless" mode on macOS includes window decorations (title bar + tab strip, ~85px) in the --window-size outer dimension, making the compositor surface shorter than the viewport set by page.setViewport(). The bottom gap fills with the page's canvas background color, producing a visible band in every rendered frame. Two-pronged fix: 1. Inflate --window-size height by 200px when not using chrome-headless-shell, ensuring the content area always exceeds the requested viewport. 2. Set Emulation.setDefaultBackgroundColorOverride to transparent on opaque capture sessions (defense-in-depth), so any residual clip-vs-surface mismatch produces transparent pixels instead of the page background. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…1699) Minimal 1920×1080 composition with body { background: #FAF9F5 } and a full-bleed gradient + a pink bar at the very bottom edge. On macOS with system Chrome (no headless-shell), the before state shows a ~85px beige band clipping the pink bar; the fix makes gradient + bar extend to the full 1080px edge. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #1699. On macOS, when the render falls back to system Google Chrome (no
chrome-headless-shellinstalled), every frame gets a solid horizontal band of the page's<body>background color across the bottom ~85px. Preview is fine; the band only appears in the rendered video.Root cause
System Chrome's "new headless" mode on macOS creates a virtual window whose
--window-sizesets the outer dimensions including title bar + tab strip (~85px). The compositor surface ends up shorter than the 1080px viewport set bypage.setViewport(). WhenPage.captureScreenshotclips to the full 1080px, the gap between the surface and the clip fills with the page's canvas background color (propagated frombody { background }), producing the band.chrome-headless-shellhas no window decorations, so the full--window-sizeis content area — which is why installing it fixes the issue.Fix
Two-pronged:
Root cause (
browserManager.ts): Inflate--window-sizeheight by 200px when not usingchrome-headless-shell. The generous buffer accounts for varying OS/Chrome decoration heights across macOS, Windows, and future Chrome versions.page.setViewport()still constrains the layout viewport to the exact composition dimensions — the extra window height just ensures the compositor surface is never shorter.Defense-in-depth (
screenshotService.ts+frameCapture.ts): SetEmulation.setDefaultBackgroundColorOverrideto transparent on opaque capture sessions (not just PNG/alpha). This is set once at session init (zero per-frame overhead). If any future edge case produces a clip-vs-surface mismatch, the gap composites to white (JPEG) or transparent (PNG) instead of the page's arbitrary background color.Test plan
buildChromeArgswindow-size height buffer (headless-shell exact, system Chrome inflated, default inflated)initOpaqueBackgroundOverride(verifies CDP call)Verification instructions (macOS)
chrome-headless-shellinstalled (hyperframes browser ensurereportsSource: system)<body>background (e.g.body { background: #FAF9F5 })npx hyperframes render .on this branch— Miga (https://claude.com/claude-code)