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

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed #7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default snapshot payloads and wait/match semantics for agent browser automation; behavior shifts could affect existing agent flows but scope is preview tooling with new contract tests.

Overview
Preview automation snapshots are slim by default: URL, title, <main> text, interactive elements, PNG, and action timeline. AX tree, console, and network load only when callers pass optional include: ['ax' | 'console' | 'network'] through contracts, IPC, preload, web bridge, and the preview_snapshot MCP tool; accessibilityTree is omitted unless ax is requested.

preview_wait_for now searches <main> by default (optional scope: 'document' for full page), requires visible locator matches, and ignores dialog trigger slots so sidebar/nav text does not satisfy readiness.

Snapshot harvesting adds stable element ids, pointer-cursor clickable filtering with deduping, 160-char name caps, and capturePage → CDP Page.captureScreenshot fallback when capture fails.

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

Note

Make automation snapshots slim by default, including ax/console/network only when requested

• Snapshots now return only interactive elements and a screenshot by default; accessibilityTree, consoleEntries, and networkEntries are omitted unless explicitly requested via a new include array parameter.
• The preview_snapshot MCP tool, IPC channel, desktop bridge, and web automation host all accept and forward the optional include array through the full stack.
• automationWaitFor now scopes text and locator searches to the <main> landmark by default, with an optional scope field to override to document.
• Interactive element filtering adds a clickable predicate, deduplicates results, assigns stable id fields, and truncates names to 160 chars.
• captureAutomationSnapshot falls back to CDP Page.captureScreenshot if WebContents.capturePage throws.
• Behavioral Change: PreviewAutomationSnapshot.accessibilityTree is now optional; callers that always expect it will need to pass include: ['ax'].

^{Macroscope summarized 149b56c.}

[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: Needs human review

This PR changes default automation snapshot behavior - data that was previously included by default (accessibility tree, console/network entries) now requires explicit opt-in. Additional changes to text/locator scoping and element detection logic represent significant runtime behavior changes to agent workflows that warrant review.

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

[cursor]

Cursor Bugbot has reviewed your changes using high 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 b1fbd6c. Configure here.}