From d70649fbd169d8d55f5a60b87596c8f6379199d5 Mon Sep 17 00:00:00 2001
From: Pavel Feldman <pavel.feldman@gmail.com>
Date: Mon, 3 Aug 2026 13:58:08 -0700
Subject: [PATCH] feat(mcp): emit structured snapshot in --json responses

Add Page.ariaSnapshotJSON and Locator.ariaSnapshotJSON that return the
aria snapshot as a free form JSON object. MCP response sections can now
carry structured content, so inline snapshots in --json replies are
emitted as the node tree instead of YAML text.

Fixes: https://github.com/microsoft/playwright/issues/42076
---
 docs/src/api/class-locator.md                 |  55 ++++++
 docs/src/api/class-page.md                    |  37 ++++
 packages/injected/src/ariaSnapshot.ts         |  68 +++++++
 packages/injected/src/injectedScript.ts       |  14 +-
 packages/isomorphic/ariaSnapshot.ts           |   9 +
 packages/isomorphic/protocolMetainfo.ts       |   1 +
 packages/playwright-client/types/types.d.ts   | 116 ++++++++++++
 .../playwright-core/src/client/channels.d.ts  |  16 ++
 .../playwright-core/src/client/locator.ts     |   5 +
 packages/playwright-core/src/client/page.ts   |   5 +
 .../playwright-core/src/server/channels.d.ts  |  16 ++
 .../src/server/dispatchers/frameDispatcher.ts |   4 +
 packages/playwright-core/src/server/frames.ts |  14 +-
 packages/playwright-core/src/server/page.ts   |  60 ++++++
 .../src/tools/backend/response.ts             |  30 ++-
 .../playwright-core/src/tools/backend/tab.ts  |  33 +++-
 packages/playwright-core/types/types.d.ts     | 116 ++++++++++++
 packages/protocol/spec/frame.yml              |  15 ++
 packages/protocol/src/validator.ts            |   9 +
 tests/mcp/cli-json.spec.ts                    |  34 +++-
 tests/page/page-aria-snapshot-json.spec.ts    | 173 ++++++++++++++++++
 21 files changed, 805 insertions(+), 25 deletions(-)
 create mode 100644 tests/page/page-aria-snapshot-json.spec.ts

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index c252b318fdd91..7a6d5957ce2de 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -239,6 +239,61 @@ When `true`, appends each element's bounding box as `[box=x,y,width,height]` to
 relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
 Defaults to `false`.
 
+## async method: Locator.ariaSnapshotJSON
+* since: v1.63
+* langs: js
+- returns: <[Serializable]>
+
+Captures the aria snapshot of the given element as a free form JSON object.
+
+**Usage**
+
+```js
+await page.getByRole('list').ariaSnapshotJSON();
+```
+
+**Details**
+
+This method returns the same tree as [`method: Locator.ariaSnapshot`], serialized as a JSON value instead of YAML markup.
+The result is a list of nodes, each node being either a plain string with static text, or an object with the following properties:
+* `role` <[string]> Aria role of the element.
+* `name` <[string]> Accessible name of the element, if any.
+* `text` <[string]> Text content of the element, when it is the only child.
+* `children` <[Array]> Child nodes and text fragments.
+* Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`, `level`, `pressed` and `selected`.
+* Additional element properties, for example `url` for links and `placeholder` for text boxes.
+* `ref` <[string]> Element reference for AI-optimized snapshots.
+* `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.
+* `box` <[Object]> Bounding box of the element when [`option: Locator.ariaSnapshotJSON.boxes`] is set.
+
+### option: Locator.ariaSnapshotJSON.mode
+* since: v1.63
+- `mode` <[AriaSnapshotMode]<"ai"|"default">>
+
+When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in [`method: Locator.ariaSnapshot`].
+
+### option: Locator.ariaSnapshotJSON.timeout = %%-input-timeout-%%
+* since: v1.63
+
+### option: Locator.ariaSnapshotJSON.timeout = %%-input-timeout-js-%%
+* since: v1.63
+
+### option: Locator.ariaSnapshotJSON.signal = %%-input-signal-%%
+
+### option: Locator.ariaSnapshotJSON.depth
+* since: v1.63
+- `depth` <[int]>
+
+When specified, limits the depth of the snapshot.
+
+### option: Locator.ariaSnapshotJSON.boxes
+* since: v1.63
+- `boxes` <[boolean]>
+
+When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`. Coordinates are
+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+Defaults to `false`.
+
 ## async method: Locator.blur
 * since: v1.28
 
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 423fc97eefcef..9cb83bef41cdf 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -4427,6 +4427,43 @@ When `true`, appends each element's bounding box as `[box=x,y,width,height]` to
 relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
 Defaults to `false`.
 
+## async method: Page.ariaSnapshotJSON
+* since: v1.63
+* langs: js
+- returns: <[Serializable]>
+
+Captures the aria snapshot of the page as a free form JSON object.
+Returns the same tree as [`method: Page.ariaSnapshot`], serialized as a JSON value instead of YAML markup.
+See [`method: Locator.ariaSnapshotJSON`] for the details of the format.
+
+### option: Page.ariaSnapshotJSON.mode
+* since: v1.63
+- `mode` <[AriaSnapshotMode]<"ai"|"default">>
+
+When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]` and snapshots of `<iframe>`s. Defaults to `"default"`.
+
+### option: Page.ariaSnapshotJSON.timeout = %%-input-timeout-%%
+* since: v1.63
+
+### option: Page.ariaSnapshotJSON.timeout = %%-input-timeout-js-%%
+* since: v1.63
+
+### option: Page.ariaSnapshotJSON.signal = %%-input-signal-%%
+
+### option: Page.ariaSnapshotJSON.depth
+* since: v1.63
+- `depth` <[int]>
+
+When specified, limits the depth of the snapshot.
+
+### option: Page.ariaSnapshotJSON.boxes
+* since: v1.63
+- `boxes` <[boolean]>
+
+When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`. Coordinates are
+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+Defaults to `false`.
+
 ## async method: Page.tap
 * since: v1.8
 * discouraged: Use locator-based [`method: Locator.tap`] instead. Read more about [locators](../locators.md).
diff --git a/packages/injected/src/ariaSnapshot.ts b/packages/injected/src/ariaSnapshot.ts
index 35384ad2f2154..267320635032d 100644
--- a/packages/injected/src/ariaSnapshot.ts
+++ b/packages/injected/src/ariaSnapshot.ts
@@ -583,6 +583,74 @@ export function renderAriaTree(ariaSnapshot: AriaSnapshot, publicOptions: AriaTr
   return { text: lines.join('\n'), iframeDepths };
 }
 
+export function renderAriaTreeAsJSON(ariaSnapshot: AriaSnapshot, publicOptions: AriaTreeOptions): { json: aria.AriaSnapshotJSON, iframeDepths: Record<string, number> } {
+  const options = toInternalOptions(publicOptions);
+  const iframeDepths: Record<string, number> = {};
+
+  const visit = (ariaNode: aria.AriaNode, depth: number, renderCursorPointer: boolean): aria.AriaNodeJSON => {
+    if (ariaNode.role === 'iframe' && ariaNode.ref)
+      iframeDepths[ariaNode.ref] = depth;
+
+    const node: aria.AriaNodeJSON = { role: ariaNode.role };
+    if (ariaNode.name)
+      node.name = ariaNode.name;
+    if (ariaNode.checked === 'mixed' || ariaNode.checked === true)
+      node.checked = ariaNode.checked;
+    if (ariaNode.disabled)
+      node.disabled = true;
+    if (ariaNode.expanded)
+      node.expanded = true;
+    if (ariaNode.active && options.renderActive)
+      node.active = true;
+    if (ariaNode.invalid)
+      node.invalid = ariaNode.invalid;
+    if (ariaNode.level)
+      node.level = ariaNode.level;
+    if (ariaNode.pressed === 'mixed' || ariaNode.pressed === true)
+      node.pressed = ariaNode.pressed;
+    if (ariaNode.selected === true)
+      node.selected = true;
+    if (ariaNode.ref) {
+      node.ref = ariaNode.ref;
+      if (renderCursorPointer && aria.hasPointerCursor(ariaNode))
+        node.cursor = 'pointer';
+    }
+    if (options.renderBoxes) {
+      const element = ariaNodeElement(ariaNode);
+      if (element) {
+        const r = element.getBoundingClientRect();
+        node.box = { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) };
+      }
+    }
+    for (const [name, value] of Object.entries(ariaNode.props))
+      node[name] = value;
+
+    const singleTextChild = ariaNode.children.length === 1 && typeof ariaNode.children[0] === 'string' ? ariaNode.children[0] : undefined;
+    const isAtDepthLimit = !!publicOptions.depth && depth === publicOptions.depth;
+    if (singleTextChild !== undefined) {
+      node.text = singleTextChild;
+    } else if (!isAtDepthLimit && ariaNode.children.length) {
+      const inCursorPointer = !!ariaNode.ref && renderCursorPointer && aria.hasPointerCursor(ariaNode);
+      node.children = ariaNode.children.map(child => {
+        if (typeof child === 'string')
+          return child;
+        return visit(child, depth + 1, renderCursorPointer && !inCursorPointer);
+      });
+    }
+    return node;
+  };
+
+  const json: aria.AriaSnapshotJSON = [];
+  const nodesToRender = ariaSnapshot.root.role === 'fragment' ? ariaSnapshot.root.children : [ariaSnapshot.root];
+  for (const nodeToRender of nodesToRender) {
+    if (typeof nodeToRender === 'string')
+      json.push(nodeToRender);
+    else
+      json.push(visit(nodeToRender, 0, !!options.renderCursorPointer));
+  }
+  return { json, iframeDepths };
+}
+
 function convertToBestGuessRegex(text: string): string {
   const dynamicContent = [
     // 550e8400-e29b-41d4-a716-446655440000
diff --git a/packages/injected/src/injectedScript.ts b/packages/injected/src/injectedScript.ts
index 42094de5185fb..6a36f1b153008 100644
--- a/packages/injected/src/injectedScript.ts
+++ b/packages/injected/src/injectedScript.ts
@@ -20,7 +20,7 @@ import { splitTestIdAttributeNames } from '@isomorphic/locatorUtils';
 import { parseAttributeSelector, parseSelector, stringifySelector, visitAllSelectorParts } from '@isomorphic/selectorParser';
 import { cacheNormalizedWhitespaces, normalizeWhiteSpace, trimStringWithEllipsis } from '@isomorphic/stringUtils';
 
-import { generateAriaTree, getAllElementsMatchingExpectAriaTemplate, matchesExpectAriaTemplate, renderAriaTree, findNewElement } from './ariaSnapshot';
+import { generateAriaTree, getAllElementsMatchingExpectAriaTemplate, matchesExpectAriaTemplate, renderAriaTree, renderAriaTreeAsJSON, findNewElement } from './ariaSnapshot';
 import { beginDOMCaches, enclosingShadowRootOrDocument, endDOMCaches, isElementVisible, isInsideScope, parentElementOrShadowHost, setGlobalOptions } from './domUtils';
 import { Highlight } from './highlight';
 import { kLayoutSelectorNames, layoutSelectorScore } from './layoutSelectorUtils';
@@ -33,7 +33,7 @@ import { XPathEngine } from './xpathSelectorEngine';
 import { ConsoleAPI } from './consoleApi';
 import { UtilityScript } from './utilityScript';
 
-import type { AriaTemplateNode } from '@isomorphic/ariaSnapshot';
+import type { AriaSnapshotJSON, AriaTemplateNode } from '@isomorphic/ariaSnapshot';
 import type { CSSComplexSelectorList } from '@isomorphic/cssParser';
 import type { Language } from '@isomorphic/locatorGenerators';
 import type { AttributeSelectorPart, NestedSelectorBody, ParsedSelector, ParsedSelectorPart } from '@isomorphic/selectorParser';
@@ -328,6 +328,16 @@ export class InjectedScript {
     return { text: rendered.text, iframeRefs: ariaSnapshot.iframeRefs, iframeDepths: rendered.iframeDepths };
   }
 
+  ariaSnapshotJSON(node: Node, options: AriaTreeOptions & { depth?: number }): { json: AriaSnapshotJSON, iframeRefs: string[], iframeDepths: Record<string, number> } {
+    if (node.nodeType !== Node.ELEMENT_NODE)
+      throw this.createStacklessError('Can only capture aria snapshot of Element nodes.');
+    options = { ...options, refPrefix: this._frameSeq && options.mode === 'ai' ? 'f' + this._frameSeq : '' };
+    const ariaSnapshot = generateAriaTree(node as Element, options);
+    const rendered = renderAriaTreeAsJSON(ariaSnapshot, options);
+    this._lastAriaSnapshotForQuery = ariaSnapshot;
+    return { json: rendered.json, iframeRefs: ariaSnapshot.iframeRefs, iframeDepths: rendered.iframeDepths };
+  }
+
   ariaSnapshotForRecorder(): { ariaSnapshot: string, refs: Map<Element, string> } {
     const tree = generateAriaTree(this.document.body, { mode: 'ai' });
     const { text: ariaSnapshot } = renderAriaTree(tree, { mode: 'ai' });
diff --git a/packages/isomorphic/ariaSnapshot.ts b/packages/isomorphic/ariaSnapshot.ts
index e710975467b45..9275732c30381 100644
--- a/packages/isomorphic/ariaSnapshot.ts
+++ b/packages/isomorphic/ariaSnapshot.ts
@@ -55,6 +55,15 @@ export function hasPointerCursor(ariaNode: AriaNode): boolean {
   return ariaNode.box.cursor === 'pointer';
 }
 
+// Free form JSON serialization of the aria tree. Nodes are either static text
+// fragments or plain objects with the role, name, state flags and children.
+export type AriaNodeJSON = {
+  [key: string]: string | number | boolean | object | undefined;
+  children?: (AriaNodeJSON | string)[];
+};
+
+export type AriaSnapshotJSON = (AriaNodeJSON | string)[];
+
 // We pass parsed template between worlds using JSON, make it easy.
 export type AriaRegex = { pattern: string };
 
diff --git a/packages/isomorphic/protocolMetainfo.ts b/packages/isomorphic/protocolMetainfo.ts
index 423b0a131c6df..d8afde4be244d 100644
--- a/packages/isomorphic/protocolMetainfo.ts
+++ b/packages/isomorphic/protocolMetainfo.ts
@@ -126,6 +126,7 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([
   ['Frame.addScriptTag', { title: 'Add script tag', snapshot: true, pause: true, }],
   ['Frame.addStyleTag', { title: 'Add style tag', snapshot: true, pause: true, }],
   ['Frame.ariaSnapshot', { title: 'Aria snapshot', group: 'getter', }],
+  ['Frame.ariaSnapshotJSON', { title: 'Aria snapshot JSON', group: 'getter', }],
   ['Frame.blur', { title: 'Blur', slowMo: true, snapshot: true, pause: true, }],
   ['Frame.check', { title: 'Check', slowMo: true, snapshot: true, pause: true, input: true, isAutoWaiting: true, }],
   ['Frame.click', { title: 'Click', slowMo: true, snapshot: true, pause: true, input: true, isAutoWaiting: true, }],
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 177bf2afe32aa..bf6569d6cd5aa 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -2138,6 +2138,54 @@ export interface Page {
     timeout?: number;
   }): Promise<string>;
 
+  /**
+   * Captures the aria snapshot of the page as a free form JSON object. Returns the same tree as
+   * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot), serialized as a JSON
+   * value instead of YAML markup. See
+   * [locator.ariaSnapshotJSON([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json) for
+   * the details of the format.
+   * @param options
+   */
+  ariaSnapshotJSON(options?: {
+    /**
+     * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
+     * Coordinates are relative to the viewport, in CSS pixels, as returned by
+     * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+     * Defaults to `false`.
+     */
+    boxes?: boolean;
+
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
+    /**
+     * When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`
+     * and snapshots of `<iframe>`s. Defaults to `"default"`.
+     */
+    mode?: "ai"|"default";
+
+    /**
+     * Allows to cancel the operation using an
+     * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
+     * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
+     * which can be changed using
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout); pass
+     * `timeout: 0` to disable the timeout entirely.
+     */
+    signal?: AbortSignal;
+
+    /**
+     * 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
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+  }): Promise<Serializable>;
+
   /**
    * Brings page to front (activates tab).
    */
@@ -14350,6 +14398,74 @@ export interface Locator {
     timeout?: number;
   }): Promise<string>;
 
+  /**
+   * Captures the aria snapshot of the given element as a free form JSON object.
+   *
+   * **Usage**
+   *
+   * ```js
+   * await page.getByRole('list').ariaSnapshotJSON();
+   * ```
+   *
+   * **Details**
+   *
+   * This method returns the same tree as
+   * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot), serialized
+   * as a JSON value instead of YAML markup. The result is a list of nodes, each node being either a plain string with
+   * static text, or an object with the following properties:
+   * - `role` <[string]> Aria role of the element.
+   * - `name` <[string]> Accessible name of the element, if any.
+   * - `text` <[string]> Text content of the element, when it is the only child.
+   * - `children` <[Array]> Child nodes and text fragments.
+   * - Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`,
+   *   `level`, `pressed` and `selected`.
+   * - Additional element properties, for example `url` for links and `placeholder` for text boxes.
+   * - `ref` <[string]> Element reference for AI-optimized snapshots.
+   * - `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.
+   * - `box` <[Object]> Bounding box of the element when
+   *   [`boxes`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json-option-boxes) is set.
+   * @param options
+   */
+  ariaSnapshotJSON(options?: {
+    /**
+     * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
+     * Coordinates are relative to the viewport, in CSS pixels, as returned by
+     * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+     * Defaults to `false`.
+     */
+    boxes?: boolean;
+
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
+    /**
+     * When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in
+     * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
+     */
+    mode?: "ai"|"default";
+
+    /**
+     * Allows to cancel the operation using an
+     * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
+     * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
+     * which can be changed using
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout); pass
+     * `timeout: 0` to disable the timeout entirely.
+     */
+    signal?: AbortSignal;
+
+    /**
+     * 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
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+  }): Promise<Serializable>;
+
   /**
    * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
    * @param options
diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.ts
index 07944f33b1768..b6bb08cd17b44 100644
--- a/packages/playwright-core/src/client/channels.d.ts
+++ b/packages/playwright-core/src/client/channels.d.ts
@@ -2179,6 +2179,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {
   addScriptTag(params: FrameAddScriptTagParams, options: TimeoutOptions): Promise<FrameAddScriptTagResult>;
   addStyleTag(params: FrameAddStyleTagParams, options: TimeoutOptions): Promise<FrameAddStyleTagResult>;
   ariaSnapshot(params: FrameAriaSnapshotParams, options: TimeoutOptions): Promise<FrameAriaSnapshotResult>;
+  ariaSnapshotJSON(params: FrameAriaSnapshotJSONParams, options: TimeoutOptions): Promise<FrameAriaSnapshotJSONResult>;
   blur(params: FrameBlurParams, options: TimeoutOptions): Promise<FrameBlurResult>;
   check(params: FrameCheckParams, options: TimeoutOptions): Promise<FrameCheckResult>;
   click(params: FrameClickParams, options: TimeoutOptions): Promise<FrameClickResult>;
@@ -2301,6 +2302,21 @@ export type FrameAriaSnapshotOptions = {
 export type FrameAriaSnapshotResult = {
   snapshot: string,
 };
+export type FrameAriaSnapshotJSONParams = {
+  mode?: 'ai' | 'default',
+  selector?: string,
+  depth?: number,
+  boxes?: boolean,
+};
+export type FrameAriaSnapshotJSONOptions = {
+  mode?: 'ai' | 'default',
+  selector?: string,
+  depth?: number,
+  boxes?: boolean,
+};
+export type FrameAriaSnapshotJSONResult = {
+  snapshot: any,
+};
 export type FrameBlurParams = {
   selector: string,
   strict?: boolean,
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index e1cdf3c615449..8be9d2b102604 100644
--- a/packages/playwright-core/src/client/locator.ts
+++ b/packages/playwright-core/src/client/locator.ts
@@ -333,6 +333,11 @@ export class Locator implements api.Locator {
     return result.snapshot;
   }
 
+  async ariaSnapshotJSON(options: TimeoutOptions & { mode?: 'ai' | 'default', depth?: number, boxes?: boolean } = {}): Promise<any> {
+    const result = await this._frame._channel.ariaSnapshotJSON({ mode: options.mode, selector: this._selector, depth: options.depth, boxes: options.boxes }, this._frame._timeout(options));
+    return result.snapshot;
+  }
+
   async scrollIntoViewIfNeeded(options: channels.ElementHandleScrollIntoViewIfNeededOptions & TimeoutOptions = {}) {
     return await this._withElement((h, timeout) => h.scrollIntoViewIfNeeded({ ...options, timeout }), { title: 'Scroll into view', timeout: options.timeout, signal: options.signal });
   }
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index e9b088be1de01..d7ea623f7db8a 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -924,6 +924,11 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     return result.snapshot;
   }
 
+  async ariaSnapshotJSON(options: TimeoutOptions & { mode?: 'ai' | 'default', depth?: number, boxes?: boolean } = {}): Promise<any> {
+    const result = await this.mainFrame()._channel.ariaSnapshotJSON({ mode: options.mode, depth: options.depth, boxes: options.boxes }, this._timeoutSettings.timeout(options));
+    return result.snapshot;
+  }
+
   async _setDockTile(image: Buffer) {
     await this._channel.setDockTile({ image }, kNoTimeout);
   }
diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.ts
index e8e7962f2bcf1..48da3163a0244 100644
--- a/packages/playwright-core/src/server/channels.d.ts
+++ b/packages/playwright-core/src/server/channels.d.ts
@@ -2180,6 +2180,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {
   addScriptTag(params: FrameAddScriptTagParams, progress: Progress): Promise<FrameAddScriptTagResult>;
   addStyleTag(params: FrameAddStyleTagParams, progress: Progress): Promise<FrameAddStyleTagResult>;
   ariaSnapshot(params: FrameAriaSnapshotParams, progress: Progress): Promise<FrameAriaSnapshotResult>;
+  ariaSnapshotJSON(params: FrameAriaSnapshotJSONParams, progress: Progress): Promise<FrameAriaSnapshotJSONResult>;
   blur(params: FrameBlurParams, progress: Progress): Promise<FrameBlurResult>;
   check(params: FrameCheckParams, progress: Progress): Promise<FrameCheckResult>;
   click(params: FrameClickParams, progress: Progress): Promise<FrameClickResult>;
@@ -2302,6 +2303,21 @@ export type FrameAriaSnapshotOptions = {
 export type FrameAriaSnapshotResult = {
   snapshot: string,
 };
+export type FrameAriaSnapshotJSONParams = {
+  mode?: 'ai' | 'default',
+  selector?: string,
+  depth?: number,
+  boxes?: boolean,
+};
+export type FrameAriaSnapshotJSONOptions = {
+  mode?: 'ai' | 'default',
+  selector?: string,
+  depth?: number,
+  boxes?: boolean,
+};
+export type FrameAriaSnapshotJSONResult = {
+  snapshot: any,
+};
 export type FrameBlurParams = {
   selector: string,
   strict?: boolean,
diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
index 67593bde88012..e72af9d0cdff5 100644
--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
@@ -138,6 +138,10 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Br
     return await this._frame.ariaSnapshot(progress, params);
   }
 
+  async ariaSnapshotJSON(params: channels.FrameAriaSnapshotJSONParams, progress: Progress): Promise<channels.FrameAriaSnapshotJSONResult> {
+    return await this._frame.ariaSnapshotJSON(progress, params);
+  }
+
   async click(params: channels.FrameClickParams, progress: Progress): Promise<void> {
     return await this._frame.click(progress, params.selector, params);
   }
diff --git a/packages/playwright-core/src/server/frames.ts b/packages/playwright-core/src/server/frames.ts
index 637d429e4df3f..e614cdc293d86 100644
--- a/packages/playwright-core/src/server/frames.ts
+++ b/packages/playwright-core/src/server/frames.ts
@@ -35,7 +35,7 @@ import { helper } from './helper';
 import { SdkObject } from './instrumentation';
 import * as js from './javascript';
 import * as network from './network';
-import { Page, ariaSnapshotForFrame } from './page';
+import { Page, ariaSnapshotForFrame, ariaSnapshotJSONForFrame } from './page';
 import { isAbortError, nullProgress, ProgressController, raceUncancellableOperationWithCleanup } from './progress';
 import * as types from './types';
 import { isSessionClosedError } from './protocolError';
@@ -46,6 +46,7 @@ import type { Progress } from './progress';
 import type { ScreenshotOptions } from './screenshotter';
 import type { RegisteredListener } from '@utils/eventsHelper';
 import type * as channels from './channels';
+import type { AriaSnapshotJSON } from '@isomorphic/ariaSnapshot';
 
 type ContextData = {
   contextPromise: ManualPromise<dom.FrameExecutionContext | { destroyedReason: string }>;
@@ -1874,6 +1875,17 @@ export class Frame extends SdkObject<FrameEventMap> {
     return { snapshot: lines.join('\n') };
   }
 
+  async ariaSnapshotJSON(progress: Progress, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, selector?: string, depth?: number, boxes?: boolean } = {}): Promise<{ snapshot: AriaSnapshotJSON }> {
+    if (options.selector && options.mode !== 'ai') {
+      // Non-ai locator snapshot is auto-waiting and does not include iframes.
+      const snapshot = await this._retryWithProgressIfNotConnected(progress, options.selector, { strict: true, performActionPreChecks: true }, async (progress, handle) => {
+        return await progress.race(handle.evaluateInUtility(([injected, element, opts]) => injected.ariaSnapshotJSON(element, opts).json, { mode: 'default' as const, depth: options.depth, boxes: options.boxes }));
+      });
+      return { snapshot };
+    }
+    return { snapshot: await ariaSnapshotJSONForFrame(progress, this, options.selector, options) };
+  }
+
   private _asLocator(selector: string) {
     return asLocator(this._page.browserContext._browser.sdkLanguage(), selector);
   }
diff --git a/packages/playwright-core/src/server/page.ts b/packages/playwright-core/src/server/page.ts
index a68b5b21b4142..7d87d378021b7 100644
--- a/packages/playwright-core/src/server/page.ts
+++ b/packages/playwright-core/src/server/page.ts
@@ -53,6 +53,7 @@ import type * as types from './types';
 import type { ImageComparatorOptions } from '@utils/comparators';
 import type * as channels from './channels';
 import type { BindingPayload } from '@injected/bindingsController';
+import type { AriaNodeJSON, AriaSnapshotJSON } from '@isomorphic/ariaSnapshot';
 
 export interface PageDelegate {
   readonly rawMouse: input.RawMouse;
@@ -1171,6 +1172,65 @@ export async function ariaSnapshotForFrame(progress: Progress, frame: frames.Fra
   return lines;
 }
 
+export async function ariaSnapshotJSONForFrame(progress: Progress, frame: frames.Frame, selector: string | undefined, options: { mode?: 'ai' | 'default', doNotRenderActive?: boolean, depth?: number, boxes?: boolean, strict?: boolean, noDefaultPierce?: boolean } = {}): Promise<AriaSnapshotJSON> {
+  const snapshot = await frame.retryWithProgressAndTimeouts(progress, [1000, 2000, 4000, 8000], async (progress, continuePolling) => {
+    try {
+      // Note: the resolved frame might differ from the original |frame|.
+      // See https://developer.mozilla.org/en-US/docs/Web/API/Document/body for body/frameset explanation.
+      // Non-strict, because pages with nested framesets have multiple "frameset" elements.
+      const resolved = await progress.race(frame.selectors.callOnSelector(selector || 'body,frameset', { strict: options.strict ?? !!selector, noDefaultPierce: !selector || options.noDefaultPierce }, ({ injected, elements }, ariaOptions) => {
+        return injected.ariaSnapshotJSON(elements[0], ariaOptions);
+      }, {
+        mode: options.mode ?? 'default',
+        doNotRenderActive: options.doNotRenderActive,
+        depth: options.depth,
+        boxes: options.boxes,
+      }));
+      if (!resolved) {
+        if (selector)
+          throw new NonRecoverableDOMError(`Selector "${selector}" does not match any element`);
+        // Retry only for the main frame "body" being absent, so that `page.ariaSnapshotJSON()` does not fail.
+        return continuePolling;
+      }
+      return { ...resolved.result, resolvedFrame: resolved.frame };
+    } catch (e) {
+      if (frame.isNonRetriableError(e))
+        throw e;
+      return continuePolling;
+    }
+  });
+
+  // Only fetch child snapshots for iframes that were actually rendered (not filtered by depth).
+  const renderedIframeRefs = snapshot.iframeRefs.filter(ref => ref in snapshot.iframeDepths);
+  progress.setAllowConcurrentOrNestedRaces(true);
+  const childSnapshotPromises = renderedIframeRefs.map(async ref => {
+    const childDepth = options.depth ? options.depth - snapshot.iframeDepths[ref] - 1 : undefined;
+    // Non-strict, because child frameset documents have multiple "frameset" elements.
+    const frameRootSelector = `aria-ref=${ref} >> internal:control=enter-frame >> body,frameset`;
+    try {
+      return await ariaSnapshotJSONForFrame(progress, snapshot.resolvedFrame, frameRootSelector, { ...options, depth: childDepth, strict: false, noDefaultPierce: true });
+    } catch {
+      return [];
+    }
+  });
+  const childSnapshots = await Promise.all(childSnapshotPromises);
+  progress.setAllowConcurrentOrNestedRaces(false);
+
+  const mergeIframeChildren = (node: AriaNodeJSON | string) => {
+    if (typeof node === 'string')
+      return;
+    if (node.role === 'iframe' && typeof node.ref === 'string') {
+      const childSnapshot = childSnapshots[renderedIframeRefs.indexOf(node.ref)];
+      if (childSnapshot?.length)
+        node.children = childSnapshot;
+      return;
+    }
+    (node.children || []).forEach(mergeIframeChildren);
+  };
+  snapshot.json.forEach(mergeIframeChildren);
+  return snapshot.json;
+}
+
 function ensureArrayLimit<T>(array: T[], limit: number): T[] {
   if (array.length > limit)
     return array.splice(0, limit / 10);
diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.ts
index 725edcdaaff78..e419366179cc7 100644
--- a/packages/playwright-core/src/tools/backend/response.ts
+++ b/packages/playwright-core/src/tools/backend/response.ts
@@ -36,11 +36,13 @@ type ResolvedFile = {
   printableLink: string;
 };
 
+type SectionContent = string[] | { json: unknown };
+
 type Section = {
   title: string;
-  content: string[];
+  content: SectionContent;
   isError?: boolean;
-  codeframe?: 'yaml' | 'js';
+  codeframe?: 'yaml' | 'js' | 'json';
 };
 
 export class Response {
@@ -168,9 +170,14 @@ export class Response {
       if (isError)
         payload.isError = true;
       for (const section of sections) {
+        const key = section.title.toLowerCase();
+        if (!Array.isArray(section.content)) {
+          if (section.content.json !== undefined)
+            payload[key] = section.content.json;
+          continue;
+        }
         if (!section.content.length)
           continue;
-        const key = section.title.toLowerCase();
         if (key === 'snapshot') {
           const match = section.content[0]?.match(/^- \[Snapshot\]\(([^)]+)\)$/);
           payload.snapshot = match ? { file: match[1] } : section.content.join('\n');
@@ -182,17 +189,18 @@ export class Response {
     } else {
       const text: string[] = [];
       for (const section of sections) {
-        if (!section.content.length)
+        const lines = Array.isArray(section.content) ? section.content : (section.content.json === undefined ? [] : [JSON.stringify(section.content.json, null, 2)]);
+        if (!lines.length)
           continue;
         if (!this._raw) {
           text.push(`### ${section.title}`);
           if (section.codeframe)
             text.push(`\`\`\`${section.codeframe}`);
-          text.push(...section.content);
+          text.push(...lines);
           if (section.codeframe)
             text.push('```');
         } else {
-          text.push(...section.content);
+          text.push(...lines);
         }
       }
       serializedText = text.join('\n');
@@ -253,7 +261,7 @@ export class Response {
 
   private async _build(): Promise<Section[]> {
     const sections: Section[] = [];
-    const addSection = (title: string, content: string[], codeframe?: 'yaml' | 'js') => {
+    const addSection = (title: string, content: SectionContent, codeframe?: 'yaml' | 'js' | 'json') => {
       const section = { title, content, isError: title === 'Error', codeframe };
       sections.push(section);
       return content;
@@ -270,7 +278,9 @@ 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._includeSnapshotRoot, this._includeSnapshotDepth, this._includeSnapshotBoxes, this._clientWorkspace, this._includeSnapshot !== 'none') : undefined;
+    const snapshotToFile = this._includeSnapshot !== 'explicit' || !!this._includeSnapshotFileName;
+    const ariaFormat = this._includeSnapshot === 'none' ? 'none' : (this._json && !snapshotToFile ? 'json' : 'text');
+    const tabSnapshot = this._context.currentTab() ? await this._context.currentTabOrDie().captureSnapshot(this._includeSnapshotRoot, this._includeSnapshotDepth, this._includeSnapshotBoxes, this._clientWorkspace, ariaFormat) : 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)
@@ -284,11 +294,13 @@ export class Response {
 
     // Handle tab snapshot
     if (tabSnapshot && this._includeSnapshot !== 'none') {
-      if (this._includeSnapshot !== 'explicit' || this._includeSnapshotFileName) {
+      if (snapshotToFile) {
         const suggestedFilename = this._includeSnapshotFileName === '<auto>' ? undefined : this._includeSnapshotFileName;
         const resolvedFile = await this.resolveClientFile({ prefix: 'page', ext: 'yml', suggestedFilename }, 'Snapshot');
         await this._writeFile(resolvedFile, tabSnapshot.ariaSnapshot);
         addSection('Snapshot', [resolvedFile.printableLink]);
+      } else if (tabSnapshot.ariaSnapshotJSON !== undefined) {
+        addSection('Snapshot', { json: tabSnapshot.ariaSnapshotJSON }, 'json');
       } else {
         addSection('Snapshot', [tabSnapshot.ariaSnapshot], 'yaml');
       }
diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.ts
index a23a6a1a91f23..7d17a14e949b1 100644
--- a/packages/playwright-core/src/tools/backend/tab.ts
+++ b/packages/playwright-core/src/tools/backend/tab.ts
@@ -83,6 +83,7 @@ export type TabHeader = {
 
 type TabSnapshot = {
   ariaSnapshot: string;
+  ariaSnapshotJSON?: unknown;
   modalStates: ModalState[];
   events: EventEntry[];
   consoleLink?: string;
@@ -411,20 +412,32 @@ export class Tab extends EventEmitter<TabEventsInterface> {
     this._requests.length = 0;
   }
 
-  async captureSnapshot(root: playwright.Locator | undefined, depth: number | undefined, boxes: boolean | undefined, relativeTo: string | undefined, includeAria: boolean = true): Promise<TabSnapshot> {
+  async captureSnapshot(root: playwright.Locator | undefined, depth: number | undefined, boxes: boolean | undefined, relativeTo: string | undefined, ariaFormat: 'none' | 'text' | 'json' = 'text'): Promise<TabSnapshot> {
     await this._initializedPromise;
     let tabSnapshot: TabSnapshot | undefined;
     let modalStates: ModalState[] = [];
-    if (includeAria) {
+    if (ariaFormat !== 'none') {
       modalStates = await this._raceAgainstModalStates(async () => {
-        const ariaSnapshot = root
-          ? await root.ariaSnapshot({ mode: 'ai', depth, boxes })
-          : await this.page.ariaSnapshot({ mode: 'ai', depth, boxes });
-        tabSnapshot = {
-          ariaSnapshot,
-          modalStates: [],
-          events: [],
-        };
+        if (ariaFormat === 'json') {
+          const ariaSnapshotJSON = root
+            ? await root.ariaSnapshotJSON({ mode: 'ai', depth, boxes })
+            : await this.page.ariaSnapshotJSON({ mode: 'ai', depth, boxes });
+          tabSnapshot = {
+            ariaSnapshot: '',
+            ariaSnapshotJSON,
+            modalStates: [],
+            events: [],
+          };
+        } else {
+          const ariaSnapshot = root
+            ? await root.ariaSnapshot({ mode: 'ai', depth, boxes })
+            : await this.page.ariaSnapshot({ mode: 'ai', depth, boxes });
+          tabSnapshot = {
+            ariaSnapshot,
+            modalStates: [],
+            events: [],
+          };
+        }
       });
     } else if (this.modalStates().length) {
       // Matches the aria path's modal fallback below, without the race: there
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 177bf2afe32aa..bf6569d6cd5aa 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -2138,6 +2138,54 @@ export interface Page {
     timeout?: number;
   }): Promise<string>;
 
+  /**
+   * Captures the aria snapshot of the page as a free form JSON object. Returns the same tree as
+   * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot), serialized as a JSON
+   * value instead of YAML markup. See
+   * [locator.ariaSnapshotJSON([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json) for
+   * the details of the format.
+   * @param options
+   */
+  ariaSnapshotJSON(options?: {
+    /**
+     * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
+     * Coordinates are relative to the viewport, in CSS pixels, as returned by
+     * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+     * Defaults to `false`.
+     */
+    boxes?: boolean;
+
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
+    /**
+     * When set to `"ai"`, returns a snapshot optimized for AI consumption: including element references like `[ref=e2]`
+     * and snapshots of `<iframe>`s. Defaults to `"default"`.
+     */
+    mode?: "ai"|"default";
+
+    /**
+     * Allows to cancel the operation using an
+     * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
+     * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
+     * which can be changed using
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout); pass
+     * `timeout: 0` to disable the timeout entirely.
+     */
+    signal?: AbortSignal;
+
+    /**
+     * 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
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+  }): Promise<Serializable>;
+
   /**
    * Brings page to front (activates tab).
    */
@@ -14350,6 +14398,74 @@ export interface Locator {
     timeout?: number;
   }): Promise<string>;
 
+  /**
+   * Captures the aria snapshot of the given element as a free form JSON object.
+   *
+   * **Usage**
+   *
+   * ```js
+   * await page.getByRole('list').ariaSnapshotJSON();
+   * ```
+   *
+   * **Details**
+   *
+   * This method returns the same tree as
+   * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot), serialized
+   * as a JSON value instead of YAML markup. The result is a list of nodes, each node being either a plain string with
+   * static text, or an object with the following properties:
+   * - `role` <[string]> Aria role of the element.
+   * - `name` <[string]> Accessible name of the element, if any.
+   * - `text` <[string]> Text content of the element, when it is the only child.
+   * - `children` <[Array]> Child nodes and text fragments.
+   * - Boolean and value properties for element state flags: `checked`, `disabled`, `expanded`, `active`, `invalid`,
+   *   `level`, `pressed` and `selected`.
+   * - Additional element properties, for example `url` for links and `placeholder` for text boxes.
+   * - `ref` <[string]> Element reference for AI-optimized snapshots.
+   * - `cursor` <[string]> Set to `"pointer"` for clickable elements in AI-optimized snapshots.
+   * - `box` <[Object]> Bounding box of the element when
+   *   [`boxes`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json-option-boxes) is set.
+   * @param options
+   */
+  ariaSnapshotJSON(options?: {
+    /**
+     * When `true`, includes each element's bounding box as a `box` property with `x`, `y`, `width` and `height`.
+     * Coordinates are relative to the viewport, in CSS pixels, as returned by
+     * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+     * Defaults to `false`.
+     */
+    boxes?: boolean;
+
+    /**
+     * When specified, limits the depth of the snapshot.
+     */
+    depth?: number;
+
+    /**
+     * When set to `"ai"`, returns a snapshot optimized for AI consumption. Defaults to `"default"`. See details in
+     * [locator.ariaSnapshot([options])](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
+     */
+    mode?: "ai"|"default";
+
+    /**
+     * Allows to cancel the operation using an
+     * [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). If the signal is aborted, the
+     * operation will be aborted and throw an error. Note that providing a signal does not disable the default timeout,
+     * which can be changed using
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout); pass
+     * `timeout: 0` to disable the timeout entirely.
+     */
+    signal?: AbortSignal;
+
+    /**
+     * 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
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+  }): Promise<Serializable>;
+
   /**
    * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
    * @param options
diff --git a/packages/protocol/spec/frame.yml b/packages/protocol/spec/frame.yml
index 421530f52abfb..a8dd00d337918 100644
--- a/packages/protocol/spec/frame.yml
+++ b/packages/protocol/spec/frame.yml
@@ -90,6 +90,21 @@ Frame:
       returns:
         snapshot: string
 
+    ariaSnapshotJSON:
+      title: Aria snapshot JSON
+      group: getter
+      parameters:
+        mode:
+          type: enum?
+          literals:
+            - ai
+            - default
+        selector: string?
+        depth: int?
+        boxes: boolean?
+      returns:
+        snapshot: json
+
     blur:
       title: Blur
       parameters:
diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.ts
index 719f94a430931..9e5cd7dcde914 100644
--- a/packages/protocol/src/validator.ts
+++ b/packages/protocol/src/validator.ts
@@ -1248,6 +1248,15 @@ scheme.FrameAriaSnapshotParams = tObject({
 scheme.FrameAriaSnapshotResult = tObject({
   snapshot: tString,
 });
+scheme.FrameAriaSnapshotJSONParams = tObject({
+  mode: tOptional(tEnum(['ai', 'default'])),
+  selector: tOptional(tString),
+  depth: tOptional(tInt),
+  boxes: tOptional(tBoolean),
+});
+scheme.FrameAriaSnapshotJSONResult = tObject({
+  snapshot: tAny,
+});
 scheme.FrameBlurParams = tObject({
   selector: tString,
   strict: tOptional(tBoolean),
diff --git a/tests/mcp/cli-json.spec.ts b/tests/mcp/cli-json.spec.ts
index d702d5ecbfffc..31060c2cb3f09 100644
--- a/tests/mcp/cli-json.spec.ts
+++ b/tests/mcp/cli-json.spec.ts
@@ -151,13 +151,41 @@ test('tab-close closes a tab and returns remaining tabs', async ({ cli, server }
   ]);
 });
 
-test('snapshot returns inline snapshot yaml', async ({ cli, server }) => {
+test('snapshot returns structured inline snapshot', async ({ cli, server }) => {
   server.setContent('/', '<h1>Hi</h1>', 'text/html');
   await cli('open', server.PREFIX);
   const { output } = await cli('--json', 'snapshot');
   const parsed = JSON.parse(output);
-  expect(typeof parsed.snapshot).toBe('string');
-  expect(parsed.snapshot).toContain('heading "Hi"');
+  expect(parsed.snapshot).toEqual([
+    { role: 'heading', name: 'Hi', level: 1, ref: expect.stringMatching(/^e\d+$/) },
+  ]);
+});
+
+test('snapshot returns structured children and flags', async ({ cli, server }) => {
+  server.setContent('/', `
+    <a style="cursor: pointer" href="https://example.com/">Link</a>
+    <button disabled>Click</button>
+  `, 'text/html');
+  await cli('open', server.PREFIX);
+  const { output } = await cli('--json', 'snapshot');
+  const parsed = JSON.parse(output);
+  expect(parsed.snapshot).toEqual([
+    {
+      role: 'generic',
+      active: true,
+      ref: expect.stringMatching(/^e\d+$/),
+      children: [
+        {
+          role: 'link',
+          name: 'Link',
+          url: 'https://example.com/',
+          ref: expect.stringMatching(/^e\d+$/),
+          cursor: 'pointer',
+        },
+        { role: 'button', name: 'Click', disabled: true, ref: expect.stringMatching(/^e\d+$/) },
+      ],
+    },
+  ]);
 });
 
 test('tool error on bad navigation returns JSON error', async ({ cli, server }) => {
diff --git a/tests/page/page-aria-snapshot-json.spec.ts b/tests/page/page-aria-snapshot-json.spec.ts
new file mode 100644
index 0000000000000..413046ba41432
--- /dev/null
+++ b/tests/page/page-aria-snapshot-json.spec.ts
@@ -0,0 +1,173 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test as it, expect } from './pageTest';
+
+type NodeJSON = { role: string, name?: string, ref?: string, children?: (NodeJSON | string)[] } & Record<string, any>;
+
+function findNode(nodes: (NodeJSON | string)[], predicate: (node: NodeJSON) => boolean): NodeJSON | undefined {
+  for (const node of nodes) {
+    if (typeof node === 'string')
+      continue;
+    if (predicate(node))
+      return node;
+    const result = findNode(node.children || [], predicate);
+    if (result)
+      return result;
+  }
+  return undefined;
+}
+
+it('should snapshot roles, names and text', async ({ page }) => {
+  await page.setContent(`
+    <h1>title</h1>
+    <ul aria-label="my list">
+      <li>one</li>
+      <li>two</li>
+    </ul>
+  `);
+  expect(await page.ariaSnapshotJSON()).toEqual([
+    { role: 'heading', name: 'title', level: 1 },
+    {
+      role: 'list',
+      name: 'my list',
+      children: [
+        { role: 'listitem', text: 'one' },
+        { role: 'listitem', text: 'two' },
+      ],
+    },
+  ]);
+});
+
+it('should snapshot flags as properties', async ({ page }) => {
+  await page.setContent(`
+    <input type="checkbox" title="Check" checked>
+    <button disabled>Click</button>
+  `);
+  expect(await page.ariaSnapshotJSON()).toEqual([
+    { role: 'checkbox', name: 'Check', checked: true },
+    { role: 'button', name: 'Click', disabled: true },
+  ]);
+});
+
+it('should snapshot link url and textbox value', async ({ page }) => {
+  await page.setContent(`
+    <a href="https://example.com/">Link</a>
+    <input title="Input" value="hello">
+  `);
+  expect(await page.ariaSnapshotJSON()).toEqual([
+    { role: 'link', name: 'Link', url: 'https://example.com/' },
+    { role: 'textbox', name: 'Input', text: 'hello' },
+  ]);
+});
+
+it('should snapshot text fragments in children', async ({ page }) => {
+  await page.setContent(`<p>Hello <a href="/link">world</a> again</p>`);
+  expect(await page.ariaSnapshotJSON()).toEqual([
+    {
+      role: 'paragraph',
+      children: [
+        'Hello',
+        { role: 'link', name: 'world', url: '/link' },
+        'again',
+      ],
+    },
+  ]);
+});
+
+it('should generate refs in ai mode', async ({ page }) => {
+  await page.setContent(`
+    <button>One</button>
+    <button>Two</button>
+  `);
+  expect(await page.ariaSnapshotJSON({ mode: 'ai' })).toEqual([
+    {
+      role: 'generic',
+      active: true,
+      ref: 'e1',
+      children: [
+        { role: 'button', name: 'One', ref: 'e2' },
+        { role: 'button', name: 'Two', ref: 'e3' },
+      ],
+    },
+  ]);
+  await expect(page.locator('aria-ref=e2')).toHaveText('One');
+});
+
+it('should mark clickable elements with cursor in ai mode', async ({ page }) => {
+  await page.setContent(`<button style="cursor: pointer">One</button>`);
+  const json = await page.ariaSnapshotJSON({ mode: 'ai' }) as NodeJSON[];
+  const button = findNode(json, node => node.role === 'button');
+  expect(button?.cursor).toBe('pointer');
+});
+
+it('should snapshot iframes in ai mode', async ({ page }) => {
+  await page.setContent(`
+    <h1>Hello</h1>
+    <iframe srcdoc="<button>In frame</button>"></iframe>
+  `);
+  const json = await page.ariaSnapshotJSON({ mode: 'ai' }) as NodeJSON[];
+  const iframe = findNode(json, node => node.role === 'iframe');
+  expect(iframe?.ref).toBeTruthy();
+  const button = findNode(iframe!.children!, node => node.role === 'button');
+  expect(button?.name).toBe('In frame');
+  expect(button?.ref).toMatch(/^f\d+e\d+$/);
+});
+
+it('should limit depth', async ({ page }) => {
+  await page.setContent(`<ul><li><button>One</button></li></ul>`);
+  expect(await page.ariaSnapshotJSON({ depth: 1 })).toEqual([
+    {
+      role: 'list',
+      children: [
+        { role: 'listitem' },
+      ],
+    },
+  ]);
+});
+
+it('should include boxes when requested', async ({ page }) => {
+  await page.setContent(`<button>One</button>`);
+  const json = await page.ariaSnapshotJSON({ boxes: true }) as NodeJSON[];
+  const button = findNode(json, node => node.role === 'button');
+  expect(button?.box).toEqual({
+    x: expect.any(Number),
+    y: expect.any(Number),
+    width: expect.any(Number),
+    height: expect.any(Number),
+  });
+  expect(button!.box.width).toBeGreaterThan(0);
+  expect(button!.box.height).toBeGreaterThan(0);
+});
+
+it('should snapshot a locator', async ({ page }) => {
+  await page.setContent(`
+    <h1>title</h1>
+    <ul>
+      <li>one</li>
+      <li>two</li>
+    </ul>
+  `);
+  expect(await page.locator('ul').ariaSnapshotJSON()).toEqual([
+    {
+      role: 'list',
+      children: [
+        { role: 'listitem', text: 'one' },
+        { role: 'listitem', text: 'two' },
+      ],
+    },
+  ]);
+});