chore(mcp): do not render page state when snapshot has not changed

Drive-by: return both full and incremental snapshot from `_snapshotForAI`.

Author: dgozman

packages/injected/src/injectedScript.ts

@@ -301,21 +301,23 @@ export class InjectedScript {
   }
 
   ariaSnapshot(node: Node, options: AriaTreeOptions): string {
-    return this.incrementalAriaSnapshot(node, options).snapshot;
+    return this.incrementalAriaSnapshot(node, options).full;
   }
 
-  incrementalAriaSnapshot(node: Node, options: AriaTreeOptions & { track?: string, incremental?: boolean }): { snapshot: string, iframeRefs: string[], isIncremental: boolean } {
+  incrementalAriaSnapshot(node: Node, options: AriaTreeOptions & { track?: string }): { full: string, incremental?: string, iframeRefs: string[] } {
     if (node.nodeType !== Node.ELEMENT_NODE)
       throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');
     const ariaSnapshot = generateAriaTree(node as Element, options);
-    let previous: AriaSnapshot | undefined;
-    if (options.incremental)
-      previous = options.track ? this._lastAriaSnapshotForTrack.get(options.track) : undefined;
-    const snapshot = renderAriaTree(ariaSnapshot, options, previous);
-    if (options.track)
+    const full = renderAriaTree(ariaSnapshot, options);
+    let incremental: string | undefined;
+    if (options.track) {
+      const previousSnapshot = this._lastAriaSnapshotForTrack.get(options.track);
+      if (previousSnapshot)
+        incremental = renderAriaTree(ariaSnapshot, options, previousSnapshot);
       this._lastAriaSnapshotForTrack.set(options.track, ariaSnapshot);
+    }
     this._lastAriaSnapshotForQuery = ariaSnapshot;
-    return { snapshot, iframeRefs: ariaSnapshot.iframeRefs, isIncremental: !!previous };
+    return { full, incremental, iframeRefs: ariaSnapshot.iframeRefs };
   }
 
   ariaSnapshotForRecorder(): { ariaSnapshot: string, refs: Map<Element, string> } {

packages/playwright-core/src/client/page.ts

@@ -847,9 +847,8 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     return result.pdf;
   }
 
-  async _snapshotForAI(options: TimeoutOptions & { track?: string, mode?: 'full' | 'incremental' } = {}): Promise<string> {
-    const result = await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track, mode: options.mode });
-    return result.snapshot;
+  async _snapshotForAI(options: TimeoutOptions & { track?: string } = {}): Promise<{ full: string, incremental?: string }> {
+    return await this._channel.snapshotForAI({ timeout: this._timeoutSettings.timeout(options), track: options.track });
   }
 }
 

packages/playwright-core/src/protocol/validator.ts

@@ -1466,11 +1466,11 @@ scheme.PageRequestsResult = tObject({
 });
 scheme.PageSnapshotForAIParams = tObject({
   track: tOptional(tString),
-  mode: tOptional(tEnum(['full', 'incremental'])),
   timeout: tFloat,
 });
 scheme.PageSnapshotForAIResult = tObject({
-  snapshot: tString,
+  full: tString,
+  incremental: tOptional(tString),
 });
 scheme.PageStartJSCoverageParams = tObject({
   resetOnNavigation: tOptional(tBoolean),

packages/playwright-core/src/server/dispatchers/pageDispatcher.ts

@@ -352,7 +352,7 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
   }
 
   async snapshotForAI(params: channels.PageSnapshotForAIParams, progress: Progress): Promise<channels.PageSnapshotForAIResult> {
-    return { snapshot: await this._page.snapshotForAI(progress, params) };
+    return await this._page.snapshotForAI(progress, params);
   }
 
   async bringToFront(params: channels.PageBringToFrontParams, progress: Progress): Promise<void> {

packages/playwright-core/src/server/page.ts

@@ -858,9 +858,9 @@ export class Page extends SdkObject {
     await Promise.all(this.frames().map(frame => frame.hideHighlight().catch(() => {})));
   }
 
-  async snapshotForAI(progress: Progress, options: { track?: string, mode?: 'full' | 'incremental' }): Promise<string> {
+  async snapshotForAI(progress: Progress, options: { track?: string }): Promise<{ full: string, incremental?: string }> {
     const snapshot = await snapshotFrameForAI(progress, this.mainFrame(), options);
-    return snapshot.lines.join('\n');
+    return { full: snapshot.full.join('\n'), incremental: snapshot.incremental?.join('\n') };
   }
 }
 
@@ -1035,9 +1035,9 @@ class FrameThrottler {
   }
 }
 
-async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string, mode?: 'full' | 'incremental' }): Promise<{ lines: string[], isIncremental: boolean }> {
+async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, options: { track?: string }): Promise<{ full: string[], incremental?: string[] }> {
   // Only await the topmost navigations, inner frames will be empty when racing.
-  const { snapshot, iframeRefs, isIncremental } = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async continuePolling => {
+  const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async continuePolling => {
     try {
       const context = await progress.race(frame._utilityContext());
       const injectedScript = await progress.race(context.injectedScript());
@@ -1046,7 +1046,7 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optio
         if (!node)
           return true;
         return injected.incrementalAriaSnapshot(node, { mode: 'ai', ...options });
-      }, { refPrefix: frame.seq ? 'f' + frame.seq : '', incremental: options.mode === 'incremental', track: options.track }));
+      }, { refPrefix: frame.seq ? 'f' + frame.seq : '', track: options.track }));
       if (snapshotOrRetry === true)
         return continuePolling;
       return snapshotOrRetry;
@@ -1057,50 +1057,50 @@ async function snapshotFrameForAI(progress: Progress, frame: frames.Frame, optio
     }
   });
 
-  const lines = snapshot.split('\n');
-  const result = [];
-
-  if (isIncremental) {
-    result.push(...lines);
-    for (const ref of iframeRefs) {
-      const childSnapshot = await snapshotFrameRefForAI(progress, frame, ref, options);
-      if (!childSnapshot.lines.length)
-        continue;
-      if (childSnapshot.isIncremental)
-        result.push(...childSnapshot.lines);
-      else
-        result.push('- <changed> iframe [ref=' + ref + ']:', ...childSnapshot.lines.map(l => '  ' + l));
+  const childSnapshotPromises = snapshot.iframeRefs.map(ref => snapshotFrameRefForAI(progress, frame, ref, options));
+  const childSnapshots = await Promise.all(childSnapshotPromises);
+
+  const full = [];
+  let incremental: string[] | undefined;
+
+  if (snapshot.incremental !== undefined) {
+    incremental = snapshot.incremental.split('\n');
+    for (let i = 0; i < snapshot.iframeRefs.length; i++) {
+      const childSnapshot = childSnapshots[i];
+      if (childSnapshot.incremental)
+        incremental.push(...childSnapshot.incremental);
+      else if (childSnapshot.full.length)
+        incremental.push('- <changed> iframe [ref=' + snapshot.iframeRefs[i] + ']:', ...childSnapshot.full.map(l => '  ' + l));
     }
-    return { lines: result, isIncremental };
   }
 
-  for (const line of lines) {
+  for (const line of snapshot.full.split('\n')) {
     const match = line.match(/^(\s*)- iframe (?:\[active\] )?\[ref=([^\]]*)\]/);
     if (!match) {
-      result.push(line);
+      full.push(line);
       continue;
     }
 
     const leadingSpace = match[1];
     const ref = match[2];
-    const childSnapshot = await snapshotFrameRefForAI(progress, frame, ref, options);
-    result.push(childSnapshot.lines.length ? line + ':' : line);
-    result.push(...childSnapshot.lines.map(l => leadingSpace + '  ' + l));
+    const childSnapshot = childSnapshots[snapshot.iframeRefs.indexOf(ref)] ?? { full: [] };
+    full.push(childSnapshot.full.length ? line + ':' : line);
+    full.push(...childSnapshot.full.map(l => leadingSpace + '  ' + l));
   }
 
-  return { lines: result, isIncremental };
+  return { full, incremental };
 }
 
-async function snapshotFrameRefForAI(progress: Progress, parentFrame: frames.Frame, frameRef: string, options: { track?: string, mode?: 'full' | 'incremental' }): Promise<{ lines: string[], isIncremental: boolean }> {
+async function snapshotFrameRefForAI(progress: Progress, parentFrame: frames.Frame, frameRef: string, options: { track?: string, mode?: 'full' | 'incremental' }): Promise<{ full: string[], incremental?: string[] }> {
   const frameSelector = `aria-ref=${frameRef} >> internal:control=enter-frame`;
   const frameBodySelector = `${frameSelector} >> body`;
   const child = await progress.race(parentFrame.selectors.resolveFrameForSelector(frameBodySelector, { strict: true }));
   if (!child)
-    return { lines: [], isIncremental: false };
+    return { full: [] };
   try {
     return await snapshotFrameForAI(progress, child.frame, options);
   } catch {
-    return { lines: [], isIncremental: false };
+    return { full: [] };
   }
 }
 

packages/playwright/src/index.ts

@@ -681,7 +681,7 @@ class ArtifactsRecorder {
     try {
       // TODO: maybe capture snapshot when the error is created, so it's from the right page and right time
       await page._wrapApiCall(async () => {
-        this._pageSnapshot = await page._snapshotForAI({ timeout: 5000 });
+        this._pageSnapshot = (await page._snapshotForAI({ timeout: 5000 })).full;
       }, { internal: true });
     } catch {}
   }

packages/playwright/src/mcp/browser/response.ts

@@ -87,7 +87,7 @@ export class Response {
     // All the async snapshotting post-action is happening here.
     // Everything below should race against modal states.
     if (this._includeSnapshot !== 'none' && this._context.currentTab())
-      this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshot);
+      this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
     for (const tab of this._context.tabs())
       await tab.updateTitle();
   }
@@ -134,7 +134,8 @@ ${this._code.join('\n')}
       response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
       response.push('');
     } else if (this._tabSnapshot) {
-      response.push(renderTabSnapshot(this._tabSnapshot, options));
+      const includeSnapshot = options.omitSnapshot ? 'none' : this._includeSnapshot;
+      response.push(renderTabSnapshot(this._tabSnapshot, includeSnapshot));
       response.push('');
     }
 
@@ -166,7 +167,7 @@ ${this._code.join('\n')}
   }
 }
 
-function renderTabSnapshot(tabSnapshot: TabSnapshot, options: { omitSnapshot?: boolean } = {}): string {
+function renderTabSnapshot(tabSnapshot: TabSnapshot, includeSnapshot: 'none' | 'full' | 'incremental'): string {
   const lines: string[] = [];
 
   if (tabSnapshot.consoleMessages.length) {
@@ -187,14 +188,24 @@ function renderTabSnapshot(tabSnapshot: TabSnapshot, options: { omitSnapshot?: b
     lines.push('');
   }
 
+  if (includeSnapshot === 'incremental' && tabSnapshot.ariaSnapshotDiff === '') {
+    // When incremental snapshot is present, but empty, do not render page state altogether.
+    return lines.join('\n');
+  }
+
   lines.push(`### Page state`);
   lines.push(`- Page URL: ${tabSnapshot.url}`);
   lines.push(`- Page Title: ${tabSnapshot.title}`);
-  lines.push(`- Page Snapshot:`);
-  lines.push('```yaml');
-  // TODO: perhaps not render page state when there are no changes?
-  lines.push(options.omitSnapshot ? '<snapshot>' : (tabSnapshot.ariaSnapshot || '<no changes>'));
-  lines.push('```');
+
+  if (includeSnapshot !== 'none') {
+    lines.push(`- Page Snapshot:`);
+    lines.push('```yaml');
+    if (includeSnapshot === 'incremental' && tabSnapshot.ariaSnapshotDiff !== undefined)
+      lines.push(tabSnapshot.ariaSnapshotDiff);
+    else
+      lines.push(tabSnapshot.ariaSnapshot);
+    lines.push('```');
+  }
 
   return lines.join('\n');
 }

packages/playwright/src/mcp/browser/tab.ts

@@ -40,6 +40,7 @@ export type TabSnapshot = {
   url: string;
   title: string;
   ariaSnapshot: string;
+  ariaSnapshotDiff?: string;
   modalStates: ModalState[];
   consoleMessages: ConsoleMessage[];
   downloads: { download: playwright.Download, finished: boolean, outputFile: string }[];
@@ -217,14 +218,15 @@ export class Tab extends EventEmitter<TabEventsInterface> {
     return this._requests;
   }
 
-  async captureSnapshot(mode: 'full' | 'incremental'): Promise<TabSnapshot> {
+  async captureSnapshot(): Promise<TabSnapshot> {
     let tabSnapshot: TabSnapshot | undefined;
     const modalStates = await this._raceAgainstModalStates(async () => {
-      const snapshot = await this.page._snapshotForAI({ mode, track: 'response' });
+      const snapshot = await this.page._snapshotForAI({ track: 'response' });
       tabSnapshot = {
         url: this.page.url(),
         title: await this.page.title(),
-        ariaSnapshot: snapshot,
+        ariaSnapshot: snapshot.full,
+        ariaSnapshotDiff: snapshot.incremental,
         modalStates: [],
         consoleMessages: [],
         downloads: this._downloads,

packages/playwright/src/mcp/test/browserBackend.ts

@@ -61,7 +61,7 @@ export async function runBrowserBackendAtEnd(context: playwright.BrowserContext,
     lines.push(
         `- Page Snapshot:`,
         '```yaml',
-        await (page as Page)._snapshotForAI(),
+        (await (page as Page)._snapshotForAI()).full,
         '```',
     );
   }

packages/protocol/src/channels.d.ts

@@ -2549,15 +2549,14 @@ export type PageRequestsResult = {
 };
 export type PageSnapshotForAIParams = {
   track?: string,
-  mode?: 'full' | 'incremental',
   timeout: number,
 };
 export type PageSnapshotForAIOptions = {
   track?: string,
-  mode?: 'full' | 'incremental',
 };
 export type PageSnapshotForAIResult = {
-  snapshot: string,
+  full: string,
+  incremental?: string,
 };
 export type PageStartJSCoverageParams = {
   resetOnNavigation?: boolean,