Harden preview automation reliability

[Quicksaver]

Summary

Hardens collaborative preview automation across the web host, MCP server, shared contracts, and Electron CDP controller so operations remain bounded and recoverable through cold tab startup, background-tab capture, renderer presentation races, and stalled debugger sessions.

New tabs acknowledge creation without waiting on cold renderer readiness, existing tabs retain stable visibility checks, and snapshots preserve semantic page data when raster capture is unavailable. Background snapshots keep inactive guests mounted and offscreen without changing the user's selected tab or focusing the native guest.

What Changed

• Bounded Electron automation operations, debugger-session initialization, screenshot capture, and recovery within caller deadlines; propagated caller timeouts into click, type, and wait operations and detached poisoned sessions without disrupting unrelated queued work.
• Made desktop debugger attachment lazy for the common system-color-scheme path and restored explicit color-scheme overrides through a separately bounded recovery path after detached DevTools closes.
• Added bounded compositor screenshots with hidden capturePage fallback, PNG validation and resizing, structured failure logging, and degraded semantic snapshots with screenshot: null.
• Kept inactive browser guests mounted at their requested viewport and offscreen, with reference-counted snapshot-only presentation leases that restore placement, honor operation deadlines, and never select or focus the background tab.
• Added deterministic background-capture staging when no prior panel rectangle exists, stable existing-tab presentation checks, selection reassertion across hydration races, and typed timeout diagnostics for host, visibility, overlay, and staging failures.
• Clamped remembered background-capture rectangles to the current renderer viewport so window resizes cannot leave a staged guest outside the compositor surface.
• Unified the renderer host and request consumer on one response-grace policy, preserved the real host budget in expired-deadline diagnostics, and propagated the remaining snapshot timeout through preload and IPC into the desktop control session.
• Kept a timed-out background snapshot's presentation lease until its already-started desktop capture settles, preventing response timeout cleanup from tearing down compositor staging underneath in-flight work.\n- Determined background capture from the selected right-panel browser surface as well as renderer visibility, preventing transient stale visibility from sending an inactive guest through foreground capture.\n- Bounded both compositor-frame staging waits and released the background lease when paused frame callbacks prevent desktop capture from starting, while preserving the lease for captures already in flight.
• Changed new preview tabs to acknowledge server-side creation immediately while their requested presentation and initial navigation continue, while reused tabs continue to wait for the readiness guarantees their existing targets should satisfy.
• Reserved response grace across the renderer and broker deadline boundary so stalled host operations return typed preview timeouts instead of generic execution failures, including for short caller-supplied deadlines.
• Updated snapshot contracts and MCP responses to make screenshots nullable and omit image content when unavailable while retaining semantic structured content.
• Standardized generated development URLs and Vite binding on 127.0.0.1 for composite, web, and desktop modes without leaking the generic HOST override into server-only runs.
• Made the pairing route react to later URL-fragment tokens in an already-mounted document, claim each token once, and remove the secret fragment after capture.
• Added focused regression coverage for desktop session deadlines and capture fallback, renderer staging and readiness, browser-surface state, pairing fragments, contracts, MCP snapshot responses, and development host configuration.
• Documented the branch-owned preview automation behavior, current limitation, primary files, focused test command, and development ports in BRANCH_DETAILS.md.

Why

Preview automation could fail with generic execution errors or timeouts during cold startup, after an offscreen guest stalled CDP initialization, or while a background tab lacked a presentable compositor surface. Screenshot failures could also discard otherwise usable semantic page state, and staging a native guest for capture could cover the T3 interface or change the user's active tab.

These changes make automation deadlines explicit end to end, recover control sessions after stalls, decouple new-tab creation from renderer readiness, and preserve useful semantic results even when raster evidence is temporarily unavailable.

Validation

• pnpm exec vp test run scripts/dev-runner.test.ts apps/desktop/src/preview/Manager.test.ts apps/server/src/mcp/McpHttpServer.test.ts apps/web/src/browser/browserSurfaceStore.test.ts apps/web/src/browser/hostedBrowserWebviewStyle.test.ts apps/web/src/components/auth/PairingRouteSurface.logic.test.ts apps/web/src/components/preview/previewAutomationOpenReadiness.test.ts apps/web/src/components/preview/previewAutomationPresentation.test.ts apps/web/src/components/preview/previewAutomationRequestConsumer.test.ts packages/contracts/src/ipc.test.ts packages/contracts/src/preview.test.ts passed with 11 files and 121 tests.
• Targeted lint and typechecks passed for @t3tools/web, @t3tools/desktop, and @t3tools/contracts.
• Integrated web verification authenticated an isolated app on ports 5744/13784, registered this worktree as a project, and reached its new-thread screen.
• git diff --check upstream/main...HEAD passed.

Proof

No additional proof artifacts are included; the focused automated coverage exercises the affected deadline, capture, presentation, pairing, and contract behavior.

---

Note

High Risk
Wide behavioral change across CDP lifecycle, snapshot contracts (screenshot nullable), open/readiness semantics, and timeout propagation; integrators and agents must handle null screenshots and new timeout surfaces.

Overview
Preview automation is hardened across Electron, the web renderer, MCP, and contracts so operations stay within deadlines, recover from stalled CDP sessions, and still return useful semantic snapshots when raster capture fails.

Desktop (PreviewManager) wraps control sessions in caller-aware timeouts (with response grace), lazy-attaches debuggers on register, detaches poisoned sessions on timeout without breaking queued work, and routes snapshots through CDP Page.captureScreenshot with bounded capturePage fallback. Screenshots are validated/resized; failures yield screenshot: null while page state, AX tree, and diagnostics still return. Click/type/wait propagate timeoutMs; DevTools close triggers bounded color-scheme restore.

Web host adds reference-counted background capture leases (offscreen staging, compositor-frame wait, no tab focus), open policies that acknowledge new tabs immediately vs waiting for stable visibility on reused tabs, host response budgets with typed timeout errors, and pairing that reacts to hashchange with one-shot token claims.

Contracts/MCP make snapshot screenshot nullable; MCP omits image content when absent. Snapshot IPC gains optional background and timeoutMs (defaults preserve legacy behavior).

Dev runner standardizes loopback URLs and Vite HOST on 127.0.0.1 for composite/web/desktop modes. BRANCH_DETAILS.md documents expected behavior and test command.

^{Reviewed by Cursor Bugbot for commit bfe907c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Harden preview automation reliability with per-operation timeouts and background capture support

• All automation operations (snapshot, click, type, waitFor) now run under host-side and desktop-side time budgets, rejecting with typed timeout errors (PreviewAutomationHostDeadlineExceededError, PreviewAutomationTimeoutError) instead of hanging indefinitely.
• Snapshot capture switches to CDP-based screenshots with fallback to capturePage; the screenshot field in PreviewAutomationSnapshot is now nullable when capture fails.
• Adds background capture mode for snapshots: an inactive webview is staged at a clamped rect with near-transparent opacity and no pointer events, tracked via a reference-counted lease in browserSurfaceStore.
• PreviewAutomationHosts uses a structured open-wait policy (resolvePreviewAutomationOpenWaitPolicy) to acknowledge new tabs immediately and conditionally wait for overlay/visibility on reused tabs.
• CDP control session restoration is now time-bounded and auto-recovers when DevTools are closed with a non-system color scheme.
• PairingRouteSurface replaces ref-based one-shot auto-submit with Set-based deduplication and adds a hashchange listener to handle tokens arriving after mount.
• Dev runner now uses a loopback host constant for VITE_HTTP_URL, VITE_WS_URL, and VITE_DEV_SERVER_URL across all dev modes.
• Risk: PreviewAutomationSnapshot.screenshot is now null-able — consumers that assumed a non-null screenshot must handle the null case.

^{Macroscope summarized bfe907c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 05ced50f-4d73-4ce0-bfc4-09f89870205a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 01debc6. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant runtime behavior changes including bounded automation timeouts, CDP session recovery, background tab screenshot staging, and a schema change making screenshots nullable. The cross-cutting nature and new failure recovery mechanisms warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[Quicksaver]

Follow-up to Macroscope’s approvability summary: all five inline findings were addressed in 27d0818, each thread now has a concrete resolution reply, and all review threads are resolved. The feature-focused suite passes with 11 files and 119 tests; targeted lint and affected-package typechecks also pass.

[Quicksaver]

Follow-up to Macroscope's approvability summary: the two later inline findings were addressed in bfe907c and both threads are resolved. Background capture now follows selected panel state, paused compositor-frame waits release staging before desktop capture begins, and the feature-focused suite passes with 11 files and 121 tests.