chore: simplify snapshotForAI to return string with mode option

docs/src/api/class-locator.md

@@ -2487,8 +2487,7 @@ This method expects [Locator] to point to an
 
 ## async method: Locator.snapshotForAI
 * since: v1.59
-- returns: <[Object]>
-  - `full` <[string]> Accessibility snapshot of the element matching this locator.
+- returns: <[string]>
 
 Returns an accessibility snapshot of the element's subtree optimized for AI consumption.
 

docs/src/api/class-page.md

@@ -4213,9 +4213,7 @@ Page height in pixels.
 
 ## async method: Page.snapshotForAI
 * since: v1.59
-- returns: <[Object]>
-  - `full` <[string]> Full accessibility snapshot of the page.
-  - `incremental` ?<[string]> Incremental snapshot containing only changes since the last tracked snapshot, when using the [`option: Page.snapshotForAI.track`] option.
+- returns: <[string]>
 
 Returns an accessibility snapshot of the page optimized for AI consumption.
 
@@ -4229,8 +4227,16 @@ Returns an accessibility snapshot of the page optimized for AI consumption.
 * since: v1.59
 - `track` <[string]>
 
-When specified, enables incremental snapshots. Subsequent calls with the same track name will return
-an incremental snapshot containing only changes since the last call.
+When specified, enables incremental snapshots. Subsequent calls with the same track name will
+track changes between calls.
+
+### option: Page.snapshotForAI.mode
+* since: v1.59
+- `mode` <[string]>
+
+When set to `"incremental"` and [`option: Page.snapshotForAI.track`] is specified, returns an
+incremental snapshot containing only changes since the last call with the same track name.
+Defaults to `"full"`.
 
 ### option: Page.snapshotForAI.depth
 * since: v1.59

packages/playwright-client/types/types.d.ts

@@ -4525,6 +4525,13 @@ export interface Page {
      */
     depth?: number;
 
+    /**
+     * When set to `"incremental"` and
+     * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an
+     * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.
+     */
+    mode?: string;
+
     /**
      * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
      * option in the config, or by using the
@@ -4534,22 +4541,11 @@ export interface Page {
     timeout?: number;
 
     /**
-     * When specified, enables incremental snapshots. Subsequent calls with the same track name will return an incremental
-     * snapshot containing only changes since the last call.
+     * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between
+     * calls.
      */
     track?: string;
-  }): Promise<{
-    /**
-     * Full accessibility snapshot of the page.
-     */
-    full: string;
-
-    /**
-     * Incremental snapshot containing only changes since the last tracked snapshot, when using the
-     * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) option.
-     */
-    incremental?: string;
-  }>;
+  }): Promise<string>;
 
   /**
    * **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
@@ -14706,12 +14702,7 @@ export interface Locator {
      * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
      */
     timeout?: number;
-  }): Promise<{
-    /**
-     * Accessibility snapshot of the element matching this locator.
-     */
-    full: string;
-  }>;
+  }): Promise<string>;
 
   /**
    * Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually

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

@@ -378,8 +378,9 @@ export class Locator implements api.Locator {
     await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, omitReturnValue: true, ...options, timeout: this._frame._timeout(options) });
   }
 
-  async snapshotForAI(options: TimeoutOptions & { depth?: number } = {}): Promise<{ full: string }> {
-    return await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });
+  async snapshotForAI(options: TimeoutOptions & { depth?: number } = {}): Promise<string> {
+    const result = await this._frame._page!._channel.snapshotForAI({ timeout: this._frame._timeout(options), selector: this._selector, depth: options.depth });
+    return result.snapshot;
   }
 
   async _expect(expression: string, options: FrameExpectParams): Promise<{ matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string }> {

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

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

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

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

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

@@ -886,7 +886,7 @@ export class Page extends SdkObject<PageEventMap> {
     await Promise.all(this.frames().map(frame => frame.hideHighlight().catch(() => {})));
   }
 
-  async snapshotForAI(progress: Progress, options: { track?: string, doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ full: string, incremental?: string }> {
+  async snapshotForAI(progress: Progress, options: { track?: string, mode?: 'full' | 'incremental', doNotRenderActive?: boolean, selector?: string, depth?: number } = {}): Promise<{ snapshot: string }> {
     if (options.selector && options.track)
       throw new Error('Cannot specify both selector and track options');
 
@@ -902,8 +902,9 @@ export class Page extends SdkObject<PageEventMap> {
       frame = this.mainFrame();
     }
 
-    const snapshot = await snapshotFrameForAI(progress, frame, { ...options, info });
-    return { full: snapshot.full.join('\n'), incremental: snapshot.incremental?.join('\n') };
+    const result = await snapshotFrameForAI(progress, frame, { ...options, info });
+    const snapshot = options.mode === 'incremental' && result.incremental !== undefined ? result.incremental.join('\n') : result.full.join('\n');
+    return { snapshot };
   }
 
   async setDockTile(image: Buffer) {

packages/playwright-core/src/tools/backend/response.ts

@@ -197,7 +197,7 @@ export class Response {
       addSection('Ran Playwright code', this._code, 'js');
 
     // Render tab titles upon changes or when more than one tab.
-    const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotSelector, this._includeSnapshotDepth, this._clientWorkspace) : undefined;
+    const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotSelector, this._includeSnapshotDepth, this._clientWorkspace, this._includeSnapshot === 'incremental' ? 'incremental' : 'full') : undefined;
     const tabHeaders = await Promise.all(this._context.tabs().map(tab => tab.headerSnapshot()));
     if (this._includeSnapshot !== 'none' || tabHeaders.some(header => header.changed)) {
       if (tabHeaders.length !== 1)
@@ -213,7 +213,7 @@ export class Response {
 
     // Handle tab snapshot
     if (tabSnapshot && this._includeSnapshot !== 'none') {
-      const snapshot = this._includeSnapshot === 'full' ? tabSnapshot.ariaSnapshot : tabSnapshot.ariaSnapshotDiff ?? tabSnapshot.ariaSnapshot;
+      const snapshot = tabSnapshot.ariaSnapshot;
       if (this._context.config.outputMode === 'file' || this._includeSnapshotFileName) {
         const resolvedFile = await this.resolveClientFile({ prefix: 'page', ext: 'yml', suggestedFilename: this._includeSnapshotFileName }, 'Snapshot');
         await fs.promises.writeFile(resolvedFile.fileName, snapshot, 'utf-8');

packages/playwright-core/src/tools/backend/tab.ts

@@ -84,7 +84,6 @@ export type TabHeader = {
 
 type TabSnapshot = {
   ariaSnapshot: string;
-  ariaSnapshotDiff?: string;
   modalStates: ModalState[];
   events: EventEntry[];
   consoleLink?: string;
@@ -375,14 +374,15 @@ export class Tab extends EventEmitter<TabEventsInterface> {
     this._requests.length = 0;
   }
 
-  async captureSnapshot(selector: string | undefined, depth: number | undefined, relativeTo: string | undefined): Promise<TabSnapshot> {
+  async captureSnapshot(selector: string | undefined, depth: number | undefined, relativeTo: string | undefined, mode: 'full' | 'incremental'): Promise<TabSnapshot> {
     await this._initializedPromise;
     let tabSnapshot: TabSnapshot | undefined;
     const modalStates = await this._raceAgainstModalStates(async () => {
-      const snapshot: { full: string, incremental?: string } = selector ? await this.page.locator(selector).snapshotForAI({ depth }) : await this.page.snapshotForAI({ track: 'response', depth });
+      const ariaSnapshot = selector
+        ? await this.page.locator(selector).snapshotForAI({ depth })
+        : await this.page.snapshotForAI({ track: 'response', mode: this._needsFullSnapshot ? 'full' : mode, depth });
       tabSnapshot = {
-        ariaSnapshot: snapshot.full,
-        ariaSnapshotDiff: this._needsFullSnapshot ? undefined : snapshot.incremental,
+        ariaSnapshot,
         modalStates: [],
         events: [],
       };
@@ -398,7 +398,6 @@ export class Tab extends EventEmitter<TabEventsInterface> {
     this._needsFullSnapshot = !tabSnapshot;
     return tabSnapshot ?? {
       ariaSnapshot: '',
-      ariaSnapshotDiff: '',
       modalStates,
       events: [],
     };

packages/playwright-core/types/types.d.ts

@@ -4525,6 +4525,13 @@ export interface Page {
      */
     depth?: number;
 
+    /**
+     * When set to `"incremental"` and
+     * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) is specified, returns an
+     * incremental snapshot containing only changes since the last call with the same track name. Defaults to `"full"`.
+     */
+    mode?: string;
+
     /**
      * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
      * option in the config, or by using the
@@ -4534,22 +4541,11 @@ export interface Page {
     timeout?: number;
 
     /**
-     * When specified, enables incremental snapshots. Subsequent calls with the same track name will return an incremental
-     * snapshot containing only changes since the last call.
+     * When specified, enables incremental snapshots. Subsequent calls with the same track name will track changes between
+     * calls.
      */
     track?: string;
-  }): Promise<{
-    /**
-     * Full accessibility snapshot of the page.
-     */
-    full: string;
-
-    /**
-     * Incremental snapshot containing only changes since the last tracked snapshot, when using the
-     * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) option.
-     */
-    incremental?: string;
-  }>;
+  }): Promise<string>;
 
   /**
    * **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
@@ -14706,12 +14702,7 @@ export interface Locator {
      * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
      */
     timeout?: number;
-  }): Promise<{
-    /**
-     * Accessibility snapshot of the element matching this locator.
-     */
-    full: string;
-  }>;
+  }): Promise<string>;
 
   /**
    * Perform a tap gesture on the element matching the locator. For examples of emulating other gestures by manually

packages/playwright/src/index.ts

@@ -709,7 +709,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 })).full;
+        this._pageSnapshot = await page.snapshotForAI({ timeout: 5000 });
       }, { internal: true });
     } catch {}
   }

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

@@ -98,7 +98,7 @@ async function generatePausedMessage(testInfo: TestInfoImpl, context: playwright
     lines.push(
         `- Page Snapshot:`,
         '```yaml',
-        (await page.snapshotForAI()).full,
+        await page.snapshotForAI(),
         '```',
     );
   }

packages/protocol/src/channels.d.ts

@@ -2612,18 +2612,19 @@ export type PageRequestsResult = {
 };
 export type PageSnapshotForAIParams = {
   track?: string,
+  mode?: 'full' | 'incremental',
   selector?: string,
   depth?: number,
   timeout: number,
 };
 export type PageSnapshotForAIOptions = {
   track?: string,
+  mode?: 'full' | 'incremental',
   selector?: string,
   depth?: number,
 };
 export type PageSnapshotForAIResult = {
-  full: string,
-  incremental?: string,
+  snapshot: string,
 };
 export type PageStartJSCoverageParams = {
   resetOnNavigation?: boolean,

packages/protocol/src/protocol.yml

@@ -2013,12 +2013,16 @@ Page:
       parameters:
         # When track is present, an incremental snapshot is returned when possible.
         track: string?
+        mode:
+          type: enum?
+          literals:
+            - full
+            - incremental
         selector: string?
         depth: int?
         timeout: float
       returns:
-        full: string
-        incremental: string?
+        snapshot: string
 
     startJSCoverage:
       title: Start JS coverage

tests/page/page-aria-snapshot-ai.spec.ts

@@ -19,9 +19,8 @@ import { test as it, expect } from './pageTest';
 import { unshift } from '../config/utils';
 import type { Page } from 'playwright-core';
 
-async function snapshotForAI(page: Page, options?: Parameters<Page['snapshotForAI']>[0] & { mode?: 'full' | 'incremental' }): Promise<string> {
-  const snapshot = await page.snapshotForAI(options);
-  return options?.mode === 'incremental' ? snapshot.incremental : snapshot.full;
+async function snapshotForAI(page: Page, options?: Parameters<Page['snapshotForAI']>[0]): Promise<string> {
+  return await page.snapshotForAI(options);
 }
 
 it('should generate refs', async ({ page }) => {
@@ -717,7 +716,13 @@ it('should not create incremental snapshots without tracks', async ({ page }) =>
         - button "a button" [ref=e4]
       - listitem [ref=e5]: a span
   `);
-  expect(await snapshotForAI(page, { mode: 'incremental' })).toBe(undefined);
+  // Without a track, mode: 'incremental' falls back to full snapshot.
+  expect(await snapshotForAI(page, { mode: 'incremental' })).toContainYaml(`
+    - list [ref=e2]:
+      - listitem [ref=e3]:
+        - button "a button" [ref=e4]
+      - listitem [ref=e5]: a span
+  `);
 });
 
 it('should create incremental snapshot for children swap', async ({ page }) => {
@@ -794,7 +799,7 @@ it('should limit depth', async ({ page }) => {
               - listitem [ref=e10]: item3
   `);
 
-  const { full: snapshot4 } = await page.locator('#target').snapshotForAI({ depth: 1 });
+  const snapshot4 = await page.locator('#target').snapshotForAI({ depth: 1 });
   expect(snapshot4).toContainYaml(`
     - list [ref=e6]:
       - listitem [ref=e7]: item2