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

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.

Author: gbarros-dev

apps/desktop/src/ipc/methods/preview.ts

@@ -2,6 +2,7 @@ import {
   DesktopPreviewAnnotationThemeInputSchema,
   DesktopPreviewArtifactInputSchema,
   DesktopPreviewAutomationClickInputSchema,
+  DesktopPreviewAutomationSnapshotInputSchema,
   DesktopPreviewAutomationEvaluateInputSchema,
   DesktopPreviewAutomationPressInputSchema,
   DesktopPreviewAutomationScrollInputSchema,
@@ -281,11 +282,11 @@ export const automationStatus = DesktopIpc.makeIpcMethod({
 
 export const automationSnapshot = DesktopIpc.makeIpcMethod({
   channel: IpcChannels.PREVIEW_AUTOMATION_SNAPSHOT_CHANNEL,
-  payload: DesktopPreviewTabInputSchema,
+  payload: DesktopPreviewAutomationSnapshotInputSchema,
   result: PreviewAutomationSnapshot,
-  handler: Effect.fn("desktop.ipc.preview.automationSnapshot")(function* ({ tabId }) {
+  handler: Effect.fn("desktop.ipc.preview.automationSnapshot")(function* ({ tabId, include }) {
     const manager = yield* PreviewManager.PreviewManager;
-    return yield* manager.automationSnapshot(tabId);
+    return yield* manager.automationSnapshot(tabId, include ?? []);
   }),
 });
 

apps/desktop/src/preload.ts

@@ -230,8 +230,11 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     automation: {
       status: (tabId) =>
         ipcRenderer.invoke(IpcChannels.PREVIEW_AUTOMATION_STATUS_CHANNEL, { tabId }),
-      snapshot: (tabId) =>
-        ipcRenderer.invoke(IpcChannels.PREVIEW_AUTOMATION_SNAPSHOT_CHANNEL, { tabId }),
+      snapshot: (tabId, include) =>
+        ipcRenderer.invoke(IpcChannels.PREVIEW_AUTOMATION_SNAPSHOT_CHANNEL, {
+          tabId,
+          ...(include === undefined ? {} : { include }),
+        }),
       click: (tabId, input) =>
         ipcRenderer.invoke(IpcChannels.PREVIEW_AUTOMATION_CLICK_CHANNEL, { tabId, input }),
       type: (tabId, input) =>

apps/desktop/src/preview/Manager.ts

@@ -25,6 +25,7 @@ import type {
   PreviewAutomationNetworkEntry,
   PreviewAutomationScrollInput,
   PreviewAutomationSnapshot,
+  PreviewAutomationSnapshotInclude,
   PreviewAutomationStatus,
   PreviewAutomationTypeInput,
   PreviewAutomationWaitForInput,
@@ -2863,11 +2864,17 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
   });
 
   const captureAutomationSnapshot = Effect.fn("PreviewManager.captureAutomationSnapshot")(
-    function* (tabId: string, wc: Electron.WebContents, send: SendCommand) {
-      yield* Effect.all([send("Runtime.enable"), send("Accessibility.enable")], {
-        concurrency: 2,
-        discard: true,
-      });
+    function* (
+      tabId: string,
+      wc: Electron.WebContents,
+      send: SendCommand,
+      include: ReadonlyArray<PreviewAutomationSnapshotInclude> = [],
+    ) {
+      const includeAx = include.includes("ax");
+      const includeConsole = include.includes("console");
+      const includeNetwork = include.includes("network");
+      yield* send("Runtime.enable");
+      if (includeAx) yield* send("Accessibility.enable");
       const page = yield* evaluateWithDebugger<{
         url: string;
         title: string;
@@ -2905,44 +2912,73 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
             const rect = element.getBoundingClientRect();
             return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
           };
+          const clickable = (element) => {
+            if (element.matches("a[href],button,input,textarea,select,[role],[tabindex]")) return true;
+            const role = element.getAttribute("role");
+            if (role === "row" || role === "gridcell" || role === "option") return true;
+            const style = getComputedStyle(element);
+            return style.cursor === "pointer" && (element.tagName === "TR" || element.tagName === "TD" || element.tagName === "DIV");
+          };
+          const seen = new Set();
           const elements = Array.from(document.querySelectorAll(
-            "a[href],button,input,textarea,select,[role],[tabindex]"
-          )).filter(visible).slice(0, ${MAX_INTERACTIVE_ELEMENTS}).map((element) => {
+            "a[href],button,input,textarea,select,[role],[tabindex],[role=row],tr,[role=gridcell]"
+          )).filter((element) => {
+            if (!visible(element) || !clickable(element) || seen.has(element)) return false;
+            seen.add(element);
+            return true;
+          }).slice(0, ${MAX_INTERACTIVE_ELEMENTS}).map((element, index) => {
             const rect = element.getBoundingClientRect();
             return {
+              id: "e" + (index + 1),
               tag: element.tagName.toLowerCase(),
               role: element.getAttribute("role"),
-              name: element.getAttribute("aria-label") || element.innerText || element.getAttribute("name") || "",
+              name: (element.getAttribute("aria-label") || element.innerText || element.getAttribute("name") || "").slice(0, 160),
               selector: selectorFor(element),
               x: rect.x,
               y: rect.y,
               width: rect.width,
               height: rect.height
             };
           });
+          const main = document.querySelector("main");
           return {
             url: location.href,
             title: document.title,
             loading: document.readyState !== "complete",
-            visibleText: (document.body?.innerText || "").slice(0, ${MAX_VISIBLE_TEXT_LENGTH}),
+            visibleText: ((main && main.innerText) || document.body?.innerText || "").slice(0, ${MAX_VISIBLE_TEXT_LENGTH}),
             interactiveElements: elements
           };
         })()`,
         true,
       );
-      const [accessibility, sourceImage, diagnostics, timelines] = yield* Effect.all([
-        send("Accessibility.getFullAXTree"),
-        attemptPromise(
-          {
-            operation: "automationSnapshot.capturePage",
-            tabId,
-            webContentsId: wc.id,
-          },
-          () => wc.capturePage(),
+      const accessibility = includeAx ? yield* send("Accessibility.getFullAXTree") : undefined;
+      const [diagnostics, timelines] = yield* Effect.all(
+        [Ref.get(diagnosticsRef), Ref.get(actionTimelineRef)],
+        { concurrency: 2 },
+      );
+      const sourceImage = yield* attemptPromise(
+        {
+          operation: "automationSnapshot.capturePage",
+          tabId,
+          webContentsId: wc.id,
+        },
+        () => wc.capturePage(),
+      ).pipe(
+        Effect.catch(() =>
+          send("Page.captureScreenshot", { format: "png" }).pipe(
+            Effect.map((result) => {
+              const data =
+                result !== null &&
+                typeof result === "object" &&
+                "data" in result &&
+                typeof result.data === "string"
+                  ? result.data
+                  : "";
+              return nativeImage.createFromBuffer(Buffer.from(data, "base64"));
+            }),
+          ),
         ),
-        Ref.get(diagnosticsRef),
-        Ref.get(actionTimelineRef),
-      ]);
+      );
       const sourceSize = sourceImage.getSize();
       const image =
         sourceSize.width > MAX_SCREENSHOT_WIDTH
@@ -2952,9 +2988,9 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       const browserDiagnostics = diagnostics.get(wc.id);
       return {
         ...page,
-        accessibilityTree: accessibility,
-        consoleEntries: [...(browserDiagnostics?.consoleEntries ?? [])],
-        networkEntries: [...(browserDiagnostics?.networkEntries ?? [])],
+        ...(includeAx ? { accessibilityTree: accessibility } : {}),
+        consoleEntries: includeConsole ? [...(browserDiagnostics?.consoleEntries ?? [])] : [],
+        networkEntries: includeNetwork ? [...(browserDiagnostics?.networkEntries ?? [])] : [],
         actionTimeline: [...(timelines.get(tabId) ?? [])],
         screenshot: {
           mimeType: "image/png" as const,
@@ -2968,10 +3004,11 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
 
   const automationSnapshot = Effect.fn("PreviewManager.automationSnapshot")(function* (
     tabId: string,
+    include: ReadonlyArray<PreviewAutomationSnapshotInclude> = [],
   ) {
     const wc = yield* requireWebContents(tabId);
     return yield* withControlSession(tabId, wc, "snapshot", (send) =>
-      captureAutomationSnapshot(tabId, wc, send),
+      captureAutomationSnapshot(tabId, wc, send, include),
     );
   });
 
@@ -3398,7 +3435,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     yield* send("Runtime.enable");
     const locator = automationLocator(input);
     if (locator) yield* ensurePlaywrightInjected(tabId, send);
-    const [locatorJson, textJson, urlIncludesJson] = yield* Effect.all([
+    const [locatorJson, textJson, urlIncludesJson, scopeJson] = yield* Effect.all([
       locator
         ? encodeJson({ operation: "automationWaitFor.encodeLocator", tabId }, locator)
         : Effect.succeed(null),
@@ -3408,6 +3445,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       input.urlIncludes
         ? encodeJson({ operation: "automationWaitFor.encodeUrl", tabId }, input.urlIncludes)
         : Effect.succeed(null),
+      encodeJson({ operation: "automationWaitFor.encodeScope", tabId }, input.scope ?? "main"),
     ]);
     const deadline = (yield* currentMillis) + timeoutMs;
     while ((yield* currentMillis) <= deadline) {
@@ -3418,9 +3456,29 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         send,
         `(() => {
               try {
-                const selectorMatched = ${locatorJson ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${locatorJson}), document, false) !== null; })()` : "true"};
+                const root = ${scopeJson} === "document"
+                  ? document.documentElement
+                  : (document.querySelector("main") || document.documentElement);
+                const selectorMatched = ${
+                  locatorJson
+                    ? `(() => {
+                  const injected = globalThis.__t3PlaywrightInjected;
+                  const parsed = injected.parseSelector(${locatorJson});
+                  const element = injected.querySelector(parsed, root, false);
+                  if (!element) return false;
+                  const visible = injected.elementState(element, "visible");
+                  if (!visible.matches) return false;
+                  if (element.getAttribute("role") === "dialog") {
+                    const slot = element.getAttribute("data-slot") || "";
+                    if (slot.includes("trigger")) return false;
+                  }
+                  return true;
+                })()`
+                    : "true"
+                };
+                const textRoot = root instanceof Element ? root : (root.body || document.body);
                 const textMatched = ${
-                  textJson ? `(document.body?.innerText || "").includes(${textJson})` : "true"
+                  textJson ? `(textRoot?.innerText || "").includes(${textJson})` : "true"
                 };
                 const urlMatched = ${
                   urlIncludesJson ? `location.href.includes(${urlIncludesJson})` : "true"
@@ -3876,6 +3934,7 @@ export class PreviewManager extends Context.Service<
     ) => Effect.Effect<PreviewAutomationStatus, PreviewManagerError>;
     readonly automationSnapshot: (
       tabId: string,
+      include?: ReadonlyArray<PreviewAutomationSnapshotInclude>,
     ) => Effect.Effect<PreviewAutomationSnapshot, PreviewManagerError>;
     readonly automationClick: (
       tabId: string,

apps/server/src/mcp/toolkits/preview/tools.ts

@@ -13,6 +13,7 @@ import {
   PreviewAutomationSetColorSchemeInput,
   PreviewAutomationSetColorSchemeResult,
   PreviewAutomationSnapshot,
+  PreviewAutomationSnapshotInput,
   PreviewAutomationStatus,
   PreviewAutomationTabTargetInput,
   PreviewAutomationTypeInput,
@@ -108,8 +109,8 @@ export const PreviewSetAppearanceTool = safeBrowserTool(
 export const PreviewSnapshotTool = readonlyBrowserTool(
   Tool.make("preview_snapshot", {
     description:
-      "Inspect a page before interacting. Pass tabId to inspect a specific tab; omit it to use this agent session's current tab. Returns page state, semantic elements, diagnostics, action history, and a PNG screenshot.",
-    parameters: PreviewAutomationTabTargetInput,
+      "Inspect a page before interacting. Default is a slim snapshot: URL, visible text, interactive elements, and a PNG. Pass include:['ax'], include:['console'], or include:['network'] only when you need those heavier slices. Hidden tabs still capture.",
+    parameters: PreviewAutomationSnapshotInput,
     success: PreviewAutomationSnapshot,
     failure: PreviewAutomationError,
     dependencies,
@@ -174,7 +175,7 @@ export const PreviewEvaluateTool = browserTool(
 export const PreviewWaitForTool = readonlyBrowserTool(
   Tool.make("preview_wait_for", {
     description:
-      "Wait in the tab selected by tabId, or this agent session's current tab when omitted, until all supplied locator, selector, text, and URL conditions match.",
+      "Wait in the tab selected by tabId, or this agent session's current tab when omitted, until all supplied locator, selector, text, and URL conditions match. Text defaults to the main landmark so sidebar labels do not satisfy the wait. Locators must match a visible element.",
     parameters: PreviewAutomationWaitForInput,
     success: PreviewActionResult,
     failure: PreviewAutomationError,

apps/web/src/components/preview/PreviewAutomationHosts.tsx

@@ -9,6 +9,7 @@ import {
   type PreviewAutomationNavigateInput,
   type PreviewAutomationOpenInput,
   type PreviewAutomationResizeInput,
+  type PreviewAutomationSnapshotInput,
   type PreviewAutomationResizeResult,
   type PreviewAutomationSetColorSchemeInput,
   type PreviewAutomationSetColorSchemeResult,
@@ -584,7 +585,8 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
           }
           case "snapshot": {
             const ready = await requireReadyTab();
-            return await ready.bridge.automation.snapshot(ready.runtimeTabId);
+            const input = request.input as PreviewAutomationSnapshotInput;
+            return await ready.bridge.automation.snapshot(ready.runtimeTabId, input.include);
           }
           case "click": {
             const ready = await requireReadyTab();

packages/contracts/src/ipc.ts

@@ -71,6 +71,7 @@ import {
   PreviewAutomationResponse,
   PreviewAutomationScrollInput,
   PreviewAutomationSnapshot,
+  PreviewAutomationSnapshotInclude,
   PreviewAutomationStatus,
   PreviewAutomationStreamEvent,
   PreviewAutomationTypeInput,
@@ -974,6 +975,11 @@ export interface DesktopPreviewTabDefaults {
   readonly colorScheme?: DesktopPreviewColorScheme | undefined;
 }
 
+export const DesktopPreviewAutomationSnapshotInputSchema = Schema.Struct({
+  tabId: DesktopPreviewTabIdSchema,
+  include: Schema.optional(Schema.Array(PreviewAutomationSnapshotInclude)),
+});
+
 export const DesktopPreviewRegisterWebviewInputSchema = Schema.Struct({
   tabId: DesktopPreviewTabIdSchema,
   webContentsId: Schema.Int.check(Schema.isGreaterThan(0)),
@@ -1186,7 +1192,10 @@ export interface DesktopPreviewBridge {
   };
   automation: {
     status: (tabId: string) => Promise<PreviewAutomationStatus>;
-    snapshot: (tabId: string) => Promise<PreviewAutomationSnapshot>;
+    snapshot: (
+      tabId: string,
+      include?: ReadonlyArray<PreviewAutomationSnapshotInclude>,
+    ) => Promise<PreviewAutomationSnapshot>;
     click: (tabId: string, input: PreviewAutomationClickInput) => Promise<void>;
     type: (tabId: string, input: PreviewAutomationTypeInput) => Promise<void>;
     press: (tabId: string, input: PreviewAutomationPressInput) => Promise<void>;

packages/contracts/src/preview.test.ts

@@ -17,7 +17,9 @@ import {
   PreviewAutomationOpenInput,
   PreviewAutomationResizeInput,
   PreviewAutomationResizeResult,
+  PreviewAutomationSnapshotInput,
   PreviewAutomationStatus,
+  PreviewAutomationWaitForInput,
 } from "./previewAutomation.ts";
 
 const decodePreviewEvent = Schema.decodeUnknownSync(PreviewEvent);
@@ -32,6 +34,8 @@ const decodeResizeResult = Schema.decodeUnknownSync(PreviewAutomationResizeResul
 const decodeAutomationHost = Schema.decodeUnknownSync(PreviewAutomationHost);
 const decodeAutomationError = Schema.decodeUnknownSync(PreviewAutomationError);
 const decodeAutomationStatus = Schema.decodeUnknownSync(PreviewAutomationStatus);
+const decodeSnapshotInput = Schema.decodeUnknownSync(PreviewAutomationSnapshotInput);
+const decodeWaitForInput = Schema.decodeUnknownSync(PreviewAutomationWaitForInput);
 
 describe("PreviewAutomationOpenInput", () => {
   it("accepts the inline preview visibility flag", () => {
@@ -223,6 +227,26 @@ describe("PreviewAutomationStatus", () => {
   });
 });
 
+describe("PreviewAutomationSnapshotInput", () => {
+  it("defaults to a slim snapshot and accepts extra diagnostic slices", () => {
+    expect(decodeSnapshotInput({})).toEqual({});
+    expect(decodeSnapshotInput({ include: ["ax", "console", "network"] }).include).toEqual([
+      "ax",
+      "console",
+      "network",
+    ]);
+    expect(() => decodeSnapshotInput({ include: ["screenshot"] })).toThrow();
+  });
+});
+
+describe("PreviewAutomationWaitForInput", () => {
+  it("defaults text and locators to the main landmark", () => {
+    expect(decodeWaitForInput({ text: "Dashboard" })).toEqual({ text: "Dashboard" });
+    expect(decodeWaitForInput({ text: "Dashboard", scope: "document" }).scope).toBe("document");
+    expect(() => decodeWaitForInput({ scope: "main" })).toThrow();
+  });
+});
+
 describe("PreviewEvent", () => {
   it("decodes opened", () => {
     const event = decodePreviewEvent({