[fix]: include native selector state into snapshot (#2116)

thanks to @imorhun for this contribution! original PR can be found here
#2105

# why
Stagehand accessibility snapshot output was missing native selection
state markers (`selected` / `checked`) that are visible in Playwright
`ariaSnapshot({ mode: "ai" })`.
That mismatch made it impossible to extract the selected/checked item
for dropdowns and radio groups.

Example:
```html
<select aria-label="Select field">
  <option>Option A</option>
  <option selected>Option B</option>
  <option>Option C</option>
</select>
```

Before this fix, Stagehand-style snapshot output did not indicate the
selected option:

```
[1-4] select: Select field
  [1-5] option: Option A
  [1-6] option: Option B
  [1-7] option: Option C
```
Expected (and now aligned more closely with Playwright-style output):
selected state is explicit:

```
[1-4] select: Select field
  [1-5] option: Option A
  [1-6] option: Option B [selected]
  [1-7] option: Option C
```

# what changed
- added explicit boolean fields on `A11yNode`:
    - `selected?: boolean`
    - `checked?: boolean`
- updated AX mapping in `a11yTree` to:
    - read native AX `selected` / `checked` from AX properties
- normalize boolean-like AX values (`true/false`, `1/0`,
`"true"/"false"`)
    - store the result directly on `selected` / `checked`
- updated tree formatting in `treeFormatUtils` to render:
    - `[selected]` when `selected === true`
    - `[checked]` when `checked === true`

# test plan
- AX selected/checked extraction into boolean fields
- select/radio parent-child rendering with exactly one selected/checked
child
    - rendering both flags when a node carries both states

---------

Co-authored-by: Ihor <vreysu@gmail.com>

Author: seanmcguire12

.changeset/swift-geckos-arrive.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+include "[selected]" or "[checked]" state in snapshot

packages/core/lib/v3/types/private/snapshot.ts

@@ -101,6 +101,8 @@ export type A11yNode = {
   name?: string;
   description?: string;
   value?: string | number | boolean;
+  selected?: boolean;
+  checked?: boolean;
   nodeId: string;
   backendDOMNodeId?: number;
   parentId?: string;

packages/core/lib/v3/understudy/a11y/snapshot/a11yTree.ts

@@ -146,6 +146,8 @@ export function decorateRoles(
       name: n.name?.value,
       description: n.description?.value,
       value: n.value?.value,
+      selected: extractBooleanProperty(n, "selected"),
+      checked: extractBooleanProperty(n, "checked"),
       nodeId: n.nodeId,
       backendDOMNodeId: n.backendDOMNodeId,
       parentId: n.parentId,
@@ -234,6 +236,28 @@ export function extractUrlFromAXNode(
   const value = urlProp?.value?.value;
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function toBooleanValue(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+  }
+  if (typeof value === "string") {
+    const normalized = value.toLowerCase();
+    if (normalized === "true") return true;
+    if (normalized === "false") return false;
+  }
+  return undefined;
+}
+
+function extractBooleanProperty(
+  node: Protocol.Accessibility.AXNode,
+  propertyName: string,
+): boolean | undefined {
+  const value = node.properties?.find((p) => p.name === propertyName)?.value
+    ?.value;
+  return toBooleanValue(value);
+}
 
 export function removeRedundantStaticTextChildren(
   parent: A11yNode,

packages/core/lib/v3/understudy/a11y/snapshot/treeFormatUtils.ts

@@ -8,12 +8,20 @@ import type { A11yNode } from "../../../types/private/snapshot.js";
 export function formatTreeLine(node: A11yNode, level = 0): string {
   const indent = "  ".repeat(level);
   const labelId = node.encodedId ?? node.nodeId;
-  const label = `[${labelId}] ${node.role}${node.name ? `: ${cleanText(node.name)}` : ""}`;
+  const stateFlags = formatStateFlags(node);
+  const label = `[${labelId}] ${node.role}${node.name ? `: ${cleanText(node.name)}` : ""}${stateFlags}`;
   const kids =
     node.children?.map((c) => formatTreeLine(c, level + 1)).join("\n") ?? "";
   return kids ? `${indent}${label}\n${kids}` : `${indent}${label}`;
 }
 
+function formatStateFlags(node: A11yNode): string {
+  let flags = "";
+  if (node.selected) flags += " [selected]";
+  if (node.checked) flags += " [checked]";
+  return flags;
+}
+
 /**
  * Inject each child frame outline under the parent's iframe node line.
  * Keys in `idToTree` are the parent's iframe encoded ids.

packages/core/tests/unit/snapshot-a11y-tree-utils.test.ts

@@ -17,6 +17,11 @@ const axString = (value: string): Protocol.Accessibility.AXValue => ({
   value,
 });
 
+const axBool = (value: boolean): Protocol.Accessibility.AXValue => ({
+  type: "boolean",
+  value,
+});
+
 const defaultOpts: A11yOptions = {
   focusSelector: undefined,
   experimental: false,
@@ -114,6 +119,37 @@ describe("decorateRoles", () => {
     const decorated = decorateRoles(nodes, opts);
     expect(decorated[0]?.encodedId).toBeUndefined();
   });
+
+  it("maps selected/checked AX properties into boolean fields", () => {
+    const nodes = [
+      makeAxNode({
+        backendDOMNodeId: 12,
+        role: axString("option"),
+        name: axString("Option B"),
+        properties: [{ name: "selected", value: axBool(true) }],
+      }),
+      makeAxNode({
+        backendDOMNodeId: 13,
+        role: axString("radio"),
+        name: axString("Option C"),
+        properties: [{ name: "checked", value: axBool(true) }],
+      }),
+      makeAxNode({
+        backendDOMNodeId: 14,
+        role: axString("radio"),
+        name: axString("Option D"),
+        properties: [
+          { name: "selected", value: axBool(true) },
+          { name: "checked", value: axBool(true) },
+        ],
+      }),
+    ];
+
+    const decorated = decorateRoles(nodes, defaultOpts);
+    expect(decorated[0]).toMatchObject({ selected: true, checked: undefined });
+    expect(decorated[1]).toMatchObject({ selected: undefined, checked: true });
+    expect(decorated[2]).toMatchObject({ selected: true, checked: true });
+  });
 });
 
 describe("buildHierarchicalTree", () => {

packages/core/tests/unit/snapshot-tree-format-utils.test.ts

@@ -28,6 +28,61 @@ describe("formatTreeLine", () => {
       "[frame-1] section: Container\n  [ax-2] button: Submit",
     );
   });
+
+  it("renders a select with child options and only one selected option", () => {
+    const outline = formatTreeLine({
+      role: "select",
+      name: "Select field",
+      nodeId: "ax-4",
+      children: [
+        { role: "option", name: "Option A", nodeId: "ax-5" },
+        {
+          role: "option",
+          name: "Option B",
+          selected: true,
+          nodeId: "ax-6",
+        },
+        { role: "option", name: "Option C", nodeId: "ax-7" },
+      ],
+    });
+
+    expect(outline).toBe(
+      "[ax-4] select: Select field\n  [ax-5] option: Option A\n  [ax-6] option: Option B [selected]\n  [ax-7] option: Option C",
+    );
+    expect(outline.match(/\[selected]/g)?.length ?? 0).toBe(1);
+  });
+
+  it("renders a radio group with children and only one checked radio", () => {
+    const outline = formatTreeLine({
+      role: "group",
+      name: "Select field",
+      nodeId: "ax-8",
+      children: [
+        { role: "radio", name: "Option A", nodeId: "ax-9" },
+        { role: "radio", name: "Option B", checked: true, nodeId: "ax-10" },
+        { role: "radio", name: "Option C", nodeId: "ax-11" },
+      ],
+    });
+
+    expect(outline).toBe(
+      "[ax-8] group: Select field\n  [ax-9] radio: Option A\n  [ax-10] radio: Option B [checked]\n  [ax-11] radio: Option C",
+    );
+    expect(outline.match(/\[checked]/g)?.length ?? 0).toBe(1);
+  });
+
+  it("renders both flags when a node carries both states", () => {
+    const outline = formatTreeLine({
+      role: "menuitemcheckbox",
+      name: "Hybrid state",
+      selected: true,
+      checked: true,
+      nodeId: "ax-12",
+    });
+
+    expect(outline).toBe(
+      "[ax-12] menuitemcheckbox: Hybrid state [selected] [checked]",
+    );
+  });
 });
 
 describe("injectSubtrees", () => {