fix(preview): keep snapshots slim unless the agent asks

[gbarros-dev]

preview_snapshot always collected the accessibility tree, console, and network, while preview_wait_for could match sidebar chrome instead of page content.

Snapshots are now slim by default and accept explicit include slices for AX, console, and network. Waits default to the main landmark, remain aware of visible overlays and shadow roots, and can opt into document-wide matching.

The rebased control-session path preserves Electron's pinned debugger reference, finalizes failed acquisitions in the action timeline, and retries against the current webview when a guest is replaced during session setup.

Verified with:

• vp test run apps/desktop/src/preview/Manager.test.ts apps/desktop/src/ipc/methods/preview.test.ts packages/contracts/src/preview.test.ts apps/server/src/mcp/toolkits/preview/tools.test.ts apps/server/src/mcp/toolkits/preview/handlers.test.ts (124 tests)
• targeted typechecks for desktop, contracts, server, and web
• targeted lint and formatting checks for all changed files
• git diff --check

Split out of closed #7127.

Originally implemented with Grok 4.6 through Grok CLI. Rebased and updated with GPT-5.6 Sol through Codex desktop.

Note

Make preview automation snapshots slim by default with optional diagnostic includes

• Snapshots now default to page metadata, main-content text, interactive elements, action timeline, and screenshot; ax, console, and network data are only collected when explicitly requested through the new include parameter
• waitFor text and locator matching defaults to the main landmark instead of the whole document, with an optional document scope; overlay and portal roots are also searched by default
• withControlSession retries up to three times when guest WebContents swaps during acquisition, and action finalization is idempotent so both the inner execution and outer acquisition path finalize safely
• Adds a CDP Page.captureScreenshot fallback when Electron capturePage fails, decoding returned PNG data
• Risk: accessibilityTree is now optional in PreviewAutomationSnapshot in previewAutomation.ts — consumers that assumed it was always present must handle its absence. Control sessions no longer unconditionally enable Accessibility, Network, and Log domains; only requested domains are activated.

^{Macroscope summarized 2ad661c.}

---

Note

Medium Risk
Changes core preview automation (CDP session lifecycle, default wait scope, optional accessibility tree) and may break callers that assumed full snapshots or document-wide text/locator waits.

Overview
Preview automation snapshots are slim by default unless callers pass include with ax, console, and/or network. Contracts, desktop IPC/preload, web automation host, and the MCP preview_snapshot tool all accept the new input; heavier CDP domains are enabled only when requested, and console/network capture is gated on those domains.

Control-session handling is more resilient: debugger diagnostic enablement is tracked per session, withControlSession re-resolves the live webview (with retries after guest swaps), and failed acquisitions finalize the action timeline instead of leaving stuck “running” entries.

Snapshot and wait behavior is tuned for agents: visible text and default wait_for search favor the main landmark (with optional scope: "document"), locators respect overlays/shadow DOM and ignore hidden dialog triggers, interactive harvesting adds stable element ids and pointer-style rows/cells/divs, and screenshots fall back to CDP when capturePage fails.

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

[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: 8834cb66-be84-4273-a921-43d3e4b089ce

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

---

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.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default behavior of existing preview automation calls, including which snapshot data is collected and where waits search, while also restructuring shared control-session handling. The changes span desktop runtime, IPC, web/server routing, and public contracts, so the product-default and cross-cutting behavior changes warrant human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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

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