fix(browser): screenshot and inspect tabs that aren't on screen (#264)

## Summary

- `screenshot_tab` failed for any browser tab that wasn't the visible
pane. Hiding a tab detached its `WebContentsView` from the window, and a
parentless view has no compositor surface and reports a 0×0 viewport —
so `capturePage()` threw `UnknownVizError` (surfacing as `harness HTTP
500: capture failed`), or for a never-displayed tab produced an empty
image that the control server returned as **HTTP 200 with `data: ''`**,
which the MCP bridge reported as a bare "screenshot failed" with nothing
logged anywhere. `get_tab_clickables` shared the root cause: a 0×0
viewport makes a page look like it has no buttons.
- Hidden views are now **parked** in a lazily-created, never-shown
frameless window sized to fit them, so they keep laying out and
painting. Capture falls back to CDP `Page.captureScreenshot({
fromSurface: false })` when the on-screen surface is missing. Empty /
zero-size captures are now an error carrying a readable reason, never a
200.
- Separately: `create_browser_tab` didn't normalize a bare host, so
`example.com` failed with `ERR_INVALID_URL` despite the tool description
promising a scheme would be prepended. `navigate()` did normalize. Both
managers now share one `normalizeBrowserUrl` helper.

### Notes on the approach

Three alternatives were probed and rejected with evidence:

- **CDP `fromSurface: false` alone** — fails on a parentless view
("Unable to capture screenshot"), and hangs or crashes the process on a
never-attached 0×0 view. It needs the view parented, which is what the
park window provides.
- **`setBounds()` in `create()` alone** — a parentless view stays 0×0 no
matter what bounds you set.
- **Attaching the view "behind" the main renderer view** — impossible:
`win.contentView.children.length` is 0 for a `BrowserWindow`, so its
page isn't a child view and any added view composites *above* the UI.
The parked tab would visibly leak over the app.

The park window is `show: false`, `skipTaskbar: true`, frameless and
square-cornered (a title bar and rounded corners clip the region a
parked view can paint). A quit guard destroys it once no real window is
left, so it can't suppress `window-all-closed` on Linux/Windows.

## Test plan

Covered by tests:

- [x] `normalizeBrowserUrl` — bare host, explicit schemes
(`about:`/`file:`/`data:`), `host:port` vs scheme ambiguity, loopback →
`http`, whitespace, empty
- [x] `viewportCaptureError` / `encodedCaptureError` — 0×0 bounds,
NaN/negative, zero-size image, empty buffer
- [x] `/browser/screenshot` responses — 200 with data, 500 with the
verbatim reason, 500 for empty data, 500 for a vanished tab
- [x] `npm run typecheck`, `npx electron-vite build`, `npx vitest run`

Verified by hand in a running dev instance (real MCP HTTP path):

- [x] Reproduced the original `UnknownVizError` live, then confirmed the
fallback returns a real image
- [x] Bare host `example.com` → `https://example.com/`
- [x] Screenshot of a tab hidden by another tab taking the pane → fresh,
correct content
- [x] `get_tab_clickables` returns a real viewport and finds targets

Verified by hand against the real `BrowserManager` in an Electron
process, images inspected visually:

- [x] visible 900×600, parked-after-hide, never-displayed at 1280×800,
parked 1400×1000 fully painted (no black band), and a parked tab
navigated while hidden returning the *new* page
- [x] Park window stays `isVisible() === false`, host window keeps
focus, `destroyAll()` tears it down

Not verified by hand: the literal "switch the sidebar to another
worktree" gesture (can't drive the native UI) — the identical `hide()` →
detach path was induced by opening a second tab that displaces the
first.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: frenchie4111

src/main/browser-manager-playwright.test.ts

@@ -127,9 +127,9 @@ describe('PlaywrightBrowserManager', () => {
       expect(url).toMatch(new RegExp(`^${baseUrl}/?$`))
 
       const shot = await m.capturePage(tabId)
-      expect(shot).not.toBeNull()
-      expect(shot!.format).toBe('jpeg')
-      expect(shot!.data.length).toBeGreaterThan(100)
+      expect(shot?.error).toBeUndefined()
+      expect(shot?.format).toBe('jpeg')
+      expect(shot?.data?.length ?? 0).toBeGreaterThan(100)
 
       const clickables = (await m.getClickables(tabId)) as
         | { items: Array<{ role: string; name: string; cx: number; cy: number }> }

src/main/browser-manager-playwright.ts

@@ -21,9 +21,10 @@
 
 import { createRequire } from 'module'
 import type { Browser, BrowserContext, Page } from 'playwright-core'
-import type { BrowserManagerLike, ConsoleLog } from './browser-manager-types'
+import type { BrowserManagerLike, CaptureResult, ConsoleLog } from './browser-manager-types'
 import type { Store } from './store'
 import { log } from './debug'
+import { normalizeBrowserUrl } from './browser-url'
 
 const CONSOLE_LOG_CAP = 200
 
@@ -311,7 +312,7 @@ export class PlaywrightBrowserManager implements BrowserManagerLike {
     if (this.hasTab(tabId)) return
     log('browser-playwright', `create tab=${tabId} wt=${worktreePath} url=${url}`)
     this.pendingTabIds.add(tabId)
-    const initialUrl = url && url.trim() ? url : 'about:blank'
+    const initialUrl = normalizeBrowserUrl(url) ?? 'about:blank'
     this.dispatchState(tabId, { url: initialUrl, loading: true })
     void this.createAsync(tabId, worktreePath, initialUrl).catch((err) => {
       const message = err instanceof Error ? err.message : String(err)
@@ -468,9 +469,8 @@ export class PlaywrightBrowserManager implements BrowserManagerLike {
   navigate(tabId: string, url: string): void {
     const inst = this.instances.get(tabId)
     if (!inst) return
-    const target = url.trim()
-    if (!target) return
-    const normalized = /^[a-z][a-z0-9+\-.]*:/i.test(target) ? target : `https://${target}`
+    const normalized = normalizeBrowserUrl(url)
+    if (!normalized) return
     this.dispatchState(tabId, { loading: true })
     inst.page.goto(normalized).catch((err) => {
       log(
@@ -619,25 +619,25 @@ export class PlaywrightBrowserManager implements BrowserManagerLike {
   async capturePage(
     tabId: string,
     opts?: { format?: 'jpeg' | 'png'; quality?: number }
-  ): Promise<{ data: string; format: 'jpeg' | 'png' } | null> {
+  ): Promise<CaptureResult | null> {
     const inst = this.instances.get(tabId)
     if (!inst) return null
     try {
       const format = opts?.format === 'png' ? 'png' : 'jpeg'
-      if (format === 'png') {
-        const buf = await inst.page.screenshot({ type: 'png' })
-        return { data: buf.toString('base64'), format: 'png' }
-      }
       const q = Math.max(1, Math.min(100, Math.round(opts?.quality ?? 70)))
-      const buf = await inst.page.screenshot({ type: 'jpeg', quality: q })
-      return { data: buf.toString('base64'), format: 'jpeg' }
+      const buf =
+        format === 'png'
+          ? await inst.page.screenshot({ type: 'png' })
+          : await inst.page.screenshot({ type: 'jpeg', quality: q })
+      if (buf.length < 1) {
+        log('browser-playwright', `capturePage produced no image tab=${tabId}`)
+        return { error: 'capture encoded to 0 bytes' }
+      }
+      return { data: buf.toString('base64'), format }
     } catch (err) {
-      log(
-        'browser-playwright',
-        `capturePage failed tab=${tabId}`,
-        err instanceof Error ? err.message : err
-      )
-      return null
+      const message = err instanceof Error ? err.message : String(err)
+      log('browser-playwright', `capturePage failed tab=${tabId}`, message)
+      return { error: `capture failed: ${message}` }
     }
   }
 

src/main/browser-manager-types.ts

@@ -17,6 +17,12 @@ export interface ConsoleLog {
   message: string
 }
 
+/** Success carries the encoded image; failure carries a reason the caller can
+ * surface verbatim. `null` from capturePage still means "no such tab". */
+export type CaptureResult =
+  | { data: string; format: 'jpeg' | 'png'; error?: undefined }
+  | { error: string; data?: undefined; format?: undefined }
+
 export interface BrowserManagerLike {
   setStore(store: Store): void
   hasTab(tabId: string): boolean
@@ -54,6 +60,6 @@ export interface BrowserManagerLike {
   capturePage(
     tabId: string,
     opts?: { format?: 'jpeg' | 'png'; quality?: number }
-  ): Promise<{ data: string; format: 'jpeg' | 'png' } | null>
+  ): Promise<CaptureResult | null>
   getDom(tabId: string): Promise<string | null>
 }