Match transparent canvas backgrounds to the active theme (#2700)

Transparent inline canvases were composited against different surfaces:
the visible webview exposed Copse's active theme, while the hidden agent
mirror defaulted to white. A dark-theme canvas could therefore disagree
with its preview even though both loaded the same artifact bytes.

This change samples Copse's resolved body background (including UI tint)
and uses it as the hidden BrowserWindow's compositor backdrop. The
visible webview host explicitly uses the same base theme surface.
Artifact CSS remains authoritative, so an artifact that paints its own
background still overrides the default; a fully transparent sampled
color falls back to the resolved boot theme.

The focused Electron regression emits both a transparent artifact and
one with an explicit background. It checks the preview pixel against the
active tinted theme, checks the open canvas host against the app
surface, verifies the explicit artifact color wins, and saves the
transparent dark-theme state for review.

Validation:
- `pnpm test -- canvas-agent-mirror` — 11 passed
- `pnpm run build` — passed
- Typecheck, type-aware lint, formatting, demo-site consistency, and
dead-code analysis — passed after the final edits
- `pnpm run check:oracle` — 262 specs live, 15 invariants passed
- `pnpm run check:e2e-syntax` — 289 files parsed cleanly

The full `pnpm run check` could not complete its unit phase in this
command sandbox: unrelated watcher tests receive `EMFILE`, fixed `/tmp`
paths receive `EPERM`, and a later durable rerun stalled behind the
inaccessible orphaned test process. The focused local Electron spec also
stopped before Copse launched because Chromium could not create its
extension-unpack temp directory. CI should run
`tests/e2e/canvas-background-parity.e2e.ts` and publish the visual
evidence.

Co-Authored-By: Copse <noreply@copse.dev>
Copse-Models: acp:codex-acp#gpt-5.6-sol,
acp:claude-acp#claude-fable-5-1[1m]

---------

Co-authored-by: Jonathan Kingston <KingstonMailBox@gmail.com>

Author: jonathanKingston

src/main/index.ts

@@ -29,6 +29,7 @@ import {
 import { attachBrowserGuestContextMenu } from './windows/browser-context-menu.ts'
 import { applyAppIcon } from './app-icon.ts'
 import type { LLMMessage, StreamChunk } from '@shared/types'
+import { THEME_BACKGROUND } from '@shared/theme.ts'
 import {
   assertPrimaryMainWindow,
   beginMainWindowQuit,
@@ -37,6 +38,7 @@ import {
   getMainWindow,
   getRestorableMainWindowRecords,
 } from './windows/create-main-window.ts'
+import { readBootTheme } from './windows/boot-theme.ts'
 import { setShellOutputSink } from './services/exec/shell-output-context.ts'
 import { setSecretCipher } from './services/storage/secret-cipher.ts'
 import { createKeyringCipher, createMigratingCipher } from './services/storage/keyring-cipher.ts'
@@ -301,9 +303,39 @@ setCanvasArtefactSink((artefact) => {
   })
 })
 
+async function currentCanvasBackgroundColor(): Promise<string> {
+  const fallback = THEME_BACKGROUND[readBootTheme()]
+  const win = getMainWindow()
+  if (!win || win.isDestroyed()) return fallback
+  try {
+    const value: unknown = await win.webContents.executeJavaScript(
+      `(() => {
+        const canvas = document.createElement('canvas')
+        canvas.width = 1
+        canvas.height = 1
+        const context = canvas.getContext('2d')
+        if (!context) return ''
+        context.fillStyle = getComputedStyle(document.body).backgroundColor
+        context.fillRect(0, 0, 1, 1)
+        const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data
+        if (alpha === 0) return ''
+        return 'rgba(' + [red, green, blue, alpha / 255].join(', ') + ')'
+      })()`,
+      true,
+    )
+    return typeof value === 'string' && value.trim() ? value : fallback
+  } catch {
+    return fallback
+  }
+}
+
 // Load every artefact into the headless agent session as well, so the model can
 // snapshot and screenshot the canvas it just rendered instead of working blind.
-setCanvasArtefactMirror((artefact) => mirrorArtefactToAgent(artefact, getBrowserSession()))
+// The preview window is otherwise white by default, while the visible webview
+// exposes Copse's theme through a transparent artefact.
+setCanvasArtefactMirror(async (artefact) =>
+  mirrorArtefactToAgent(artefact, getBrowserSession(), await currentCanvasBackgroundColor()),
+)
 
 setContextEstimateRefreshSink(() => {
   const win = getMainWindow()

src/main/services/browser/session-manager.ts

@@ -47,6 +47,13 @@ export interface NavigateResult {
   url: string
 }
 
+export interface BrowserNavigateOptions {
+  newTab?: boolean | undefined
+  viewId?: string | undefined
+  /** Backdrop used when a page leaves its root transparent. */
+  backgroundColor?: string | undefined
+}
+
 export interface TabInfo {
   viewId: string
   title: string
@@ -69,7 +76,7 @@ export class BrowserSessionManager {
   private lastActiveId: string | null = null
   private counter = 0
 
-  private createTab(): Tab {
+  private createTab(backgroundColor?: string): Tab {
     if (this.tabs.length >= MAX_TABS) {
       throw new Error(`browser tab limit reached (${String(MAX_TABS)}); close a tab first`)
     }
@@ -79,6 +86,7 @@ export class BrowserSessionManager {
       show: false,
       width: DEFAULT_WIDTH,
       height: DEFAULT_HEIGHT,
+      ...(backgroundColor ? { backgroundColor } : {}),
       webPreferences: {
         // Dedicated agent browser profile, isolated from the user's interactive
         // browser pane, so automation never inherits the user's logged-in
@@ -116,12 +124,10 @@ export class BrowserSessionManager {
     return this.createTab()
   }
 
-  async navigate(
-    url: string,
-    opts?: { newTab?: boolean | undefined; viewId?: string | undefined },
-  ): Promise<NavigateResult> {
-    const tab = opts?.newTab ? this.createTab() : this.resolveTab(opts?.viewId)
+  async navigate(url: string, opts?: BrowserNavigateOptions): Promise<NavigateResult> {
+    const tab = opts?.newTab ? this.createTab(opts.backgroundColor) : this.resolveTab(opts?.viewId)
     this.lastActiveId = tab.id
+    if (opts?.backgroundColor) tab.window.setBackgroundColor(opts.backgroundColor)
     try {
       await tab.window.webContents.loadURL(url)
     } catch (err) {

src/main/services/canvas-agent-mirror.test.ts

@@ -10,7 +10,13 @@ function artefact(overrides: Partial<CanvasArtefact> = {}): CanvasArtefact {
 
 interface Call {
   url: string
-  opts?: { newTab?: boolean | undefined; viewId?: string | undefined } | undefined
+  opts?:
+    | {
+        newTab?: boolean | undefined
+        viewId?: string | undefined
+        backgroundColor?: string | undefined
+      }
+    | undefined
 }
 
 function session(
@@ -45,15 +51,28 @@ describe('mirrorArtefactToAgent', () => {
     assert.match(s.calls[0].url, /^data:text\/html;charset=utf-8;base64,/)
   })
 
+  it('uses the live canvas background when capturing transparent artefacts', async () => {
+    const s = session()
+    await mirrorArtefactToAgent(artefact(), s, 'rgb(17, 29, 23)')
+
+    assert.deepEqual(s.calls[0]?.opts, {
+      newTab: true,
+      backgroundColor: 'rgb(17, 29, 23)',
+    })
+  })
+
   it('reuses the tab for a re-render of the same title', async () => {
     const s = session()
-    await mirrorArtefactToAgent(artefact(), s)
-    await mirrorArtefactToAgent(artefact({ body: '<h1>v2</h1>' }), s)
+    await mirrorArtefactToAgent(artefact(), s, 'rgb(17, 29, 23)')
+    await mirrorArtefactToAgent(artefact({ body: '<h1>v2</h1>' }), s, 'rgb(17, 29, 23)')
 
     assert.equal(s.calls.length, 2)
     const [v1, v2] = s.calls
     assert.ok(v1 && v2)
-    assert.deepEqual(v2.opts, { viewId: 'tab-1' })
+    assert.deepEqual(v2.opts, {
+      viewId: 'tab-1',
+      backgroundColor: 'rgb(17, 29, 23)',
+    })
     assert.notEqual(v1.url, v2.url)
   })
 

src/main/services/canvas-agent-mirror.ts

@@ -19,11 +19,14 @@
 import type { CanvasArtefact } from '@shared/types/canvas.ts'
 import { artefactUrl } from '@shared/canvas/artefact.ts'
 
+interface CanvasMirrorNavigateOptions {
+  newTab?: boolean | undefined
+  viewId?: string | undefined
+  backgroundColor?: string | undefined
+}
+
 export interface CanvasMirrorSession {
-  navigate(
-    url: string,
-    opts?: { newTab?: boolean | undefined; viewId?: string | undefined },
-  ): Promise<{ viewId: string }>
+  navigate(url: string, opts?: CanvasMirrorNavigateOptions): Promise<{ viewId: string }>
   /** A small PNG `data:` URL of the tab, or null when capture is unavailable. */
   capturePreview(viewId: string): Promise<string | null>
 }
@@ -54,6 +57,7 @@ export function resetCanvasAgentMirrorForTest(): void {
 export async function mirrorArtefactToAgent(
   artefact: CanvasArtefact,
   session: CanvasMirrorSession,
+  backgroundColor?: string,
 ): Promise<string | null> {
   // `text/uri-list` is supplied by an MCP server and may name any external
   // origin. Navigating it here would bypass the approval that guards
@@ -69,10 +73,12 @@ export async function mirrorArtefactToAgent(
   }
   const key = artefactKey(artefact.threadId, artefact.title)
   const known = viewIdByArtefact.get(key)
+  const navigation: CanvasMirrorNavigateOptions = known ? { viewId: known } : { newTab: true }
+  if (backgroundColor) navigation.backgroundColor = backgroundColor
 
   let viewId: string
   try {
-    viewId = (await session.navigate(url, known ? { viewId: known } : { newTab: true })).viewId
+    viewId = (await session.navigate(url, navigation)).viewId
   } catch {
     // The remembered tab is gone — the agent closed it via `browser_tabs`, or
     // the session was torn down. Forget it and try once more in a fresh tab.
@@ -81,7 +87,9 @@ export async function mirrorArtefactToAgent(
     if (!known) return null
     viewIdByArtefact.delete(key)
     try {
-      viewId = (await session.navigate(url, { newTab: true })).viewId
+      const retry: CanvasMirrorNavigateOptions = { newTab: true }
+      if (backgroundColor) retry.backgroundColor = backgroundColor
+      viewId = (await session.navigate(url, retry)).viewId
     } catch {
       return null
     }

src/renderer/styles/global/layout.css

@@ -2052,6 +2052,9 @@
   flex-direction: column;
   min-height: 0;
   overflow: hidden;
+  /* Transparent canvas artefacts expose this surface. The headless mirror
+     captures against the resolved value of the same token. */
+  background: var(--bg-base);
   -webkit-app-region: no-drag;
   position: relative;
 }