From 0df51b482288edba19626c0c0fdcbd9de6c2d20a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 12 Oct 2026 21:04:37 +0200
Subject: [PATCH 1/3] fix(web): put on-screen text in the snapshot tree instead
 of losing it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The web capture asked agent-browser for `--compact`, and that flag removes a ref-less
element TOGETHER WITH the text under it: on one page the role census goes ListMarker
200 -> 0 and status 1 -> 0, so a `status` region that just announced something never
reaches the projection at all. Measured on the page this fix was developed against:
`wait text "Hello Zed"` times out on text the user can read off the screen, and
`find text`/`get text` cannot answer for it either. The flag's pruning is owned here
instead, by a projection that can tell an empty container from the text inside it.

What survives the projection is now decided per line. Text the backend issued no ref
for becomes a node carrying that text on `value`, in the ref-less shape the layer above
already models (see `SnapshotRefMinting`). A string rides on `value` rather than `label`
because the backend spells a control's visible string twice — as the control's name and
as its own text line — and a second `label` claiming it would refuse every `label="Name"`
read as ambiguous.

Suppression of a text line is a structural relation read off the tree, not a page-global
denylist: a line is a duplicate when it renders inside a `<label>` element whose control
reports the string as its name, or sits inside the control that reports it as its name or
value. Anything else keeps its own node, which is what preserves the content this capture
exists to publish — an announcement that happens to repeat a button's label, or a table
cell echoing a field's contents, is content. `extractQuotedText` parses and unescapes an
escaped quoted payload; the trailing `: value` form stays raw, because that is what the
backend prints and unescaping it would publish a value the page does not hold.

Closes #3509
---
 .../agent-browser-snapshot-refless.test.ts    | 308 ++++++++++++++++
 .../src/agent-browser-provider.test.ts        |   3 +-
 .../src/agent-browser-provider.ts             |  11 +-
 .../src/agent-browser-snapshot.ts             | 333 ++++++++++++++++--
 website/docs/docs/commands.md                 |   1 +
 5 files changed, 618 insertions(+), 38 deletions(-)
 create mode 100644 packages/platform-web/src/__tests__/agent-browser-snapshot-refless.test.ts

diff --git a/packages/platform-web/src/__tests__/agent-browser-snapshot-refless.test.ts b/packages/platform-web/src/__tests__/agent-browser-snapshot-refless.test.ts
new file mode 100644
index 0000000000..3f427124cd
--- /dev/null
+++ b/packages/platform-web/src/__tests__/agent-browser-snapshot-refless.test.ts
@@ -0,0 +1,308 @@
+import { describe, expect, test } from 'vitest';
+
+import { normalizeAgentBrowserSnapshot } from '../agent-browser-snapshot.ts';
+
+/**
+ * Payloads captured from agent-browser 0.27.1 against a real page (`snapshot` with no `--compact`,
+ * which is what the capture now asks for), so the projection is tested against the wording the
+ * backend actually produces rather than a hand-written approximation of it.
+ */
+const FORM_AFTER_SUBMIT = {
+  snapshot: [
+    '- heading "Bench form" [level=1, ref=e1]',
+    '- form',
+    '  - LabelText',
+    '    - StaticText "Name"',
+    '  - textbox "Name" [ref=e2]: Zed',
+    '    - StaticText "Zed"',
+    '  - LabelText',
+    '    - StaticText "Email"',
+    '  - textbox "Email" [ref=e3]',
+    '  - checkbox "I agree" [checked=false, ref=e4]',
+    '  - combobox "Color" [expanded=false, ref=e5]: Red',
+    '    - MenuListPopup',
+    '      - option "Red" [selected, ref=e7]',
+    '      - option "Blue" [ref=e8]',
+    '  - button "Submit" [ref=e6]',
+    '- status',
+    '  - StaticText "Hello Zed"',
+    '- list',
+  ].join('\n'),
+  refs: {
+    e1: { name: 'Bench form', role: 'heading' },
+    e2: { name: 'Name', role: 'textbox' },
+    e3: { name: 'Email', role: 'textbox' },
+    e4: { name: 'I agree', role: 'checkbox' },
+    e5: { name: 'Color', role: 'combobox' },
+    e6: { name: 'Submit', role: 'button' },
+    e7: { name: 'Red', role: 'option' },
+    e8: { name: 'Blue', role: 'option' },
+  },
+};
+
+/** The same page before the submit announced anything: the `status` region is there and silent. */
+const FORM_BEFORE_SUBMIT = {
+  snapshot: [
+    '- heading "Bench form" [level=1, ref=e1]',
+    '- form',
+    '  - LabelText',
+    '    - StaticText "Name"',
+    '  - textbox "Name" [ref=e2]',
+    '  - button "Submit" [ref=e6]',
+    '- status',
+    '- list',
+  ].join('\n'),
+  refs: {
+    e1: { name: 'Bench form', role: 'heading' },
+    e2: { name: 'Name', role: 'textbox' },
+    e6: { name: 'Submit', role: 'button' },
+  },
+};
+
+const ROLE_VOCABULARY = {
+  snapshot: [
+    '- heading "Roles probe" [level=1, ref=e1]',
+    '- paragraph',
+    '  - StaticText "Paragraph text"',
+    '- StaticText "Span text"',
+    '- status',
+    '  - StaticText "Status text"',
+    '- alert',
+    '  - StaticText "Alert text"',
+    '- note',
+    '  - StaticText "Note text"',
+    '- LabelText',
+    '  - StaticText "Label text"',
+    '- textbox "Label text" [ref=e2]',
+    '- button "Go" [ref=e3]',
+  ].join('\n'),
+  refs: {
+    e1: { name: 'Roles probe', role: 'heading' },
+    e2: { name: 'Label text', role: 'textbox' },
+    e3: { name: 'Go', role: 'button' },
+  },
+};
+
+/** One list item per row, each carrying the bullet the renderer draws. */
+const LIST_WITH_MARKERS = {
+  snapshot: [
+    '- heading "Items" [level=1, ref=e1]',
+    '- list',
+    '  - listitem',
+    '    - ListMarker "• "',
+    '    - StaticText "First"',
+    '  - listitem',
+    '    - ListMarker "• "',
+    '    - StaticText "Second"',
+  ].join('\n'),
+  refs: { e1: { name: 'Items', role: 'heading' } },
+};
+
+function refLessNodes(result: Awaited<ReturnType<typeof normalizeAgentBrowserSnapshot>>) {
+  return result.nodes.filter((node) => node.ref === undefined);
+}
+
+describe('normalizeAgentBrowserSnapshot ref-less content', () => {
+  test('publishes the text of a region the backend issued no ref for', async () => {
+    const result = await normalizeAgentBrowserSnapshot(FORM_AFTER_SUBMIT);
+    const announcement = refLessNodes(result).filter((node) => node.value === 'Hello Zed');
+
+    // The announcement is the reason the capture is taken, and the backend has no ref for it: before,
+    // it reached no reader at all, because the backend's `--compact` removed the region with it.
+    expect(announcement.length).toBe(1);
+    expect(announcement[0]?.type).toBe('StaticText');
+    expect(announcement[0]?.ref).toBeUndefined();
+    expect(announcement[0]?.label).toBeUndefined();
+  });
+
+  test('leaves the ref each control carries untouched', async () => {
+    const result = await normalizeAgentBrowserSnapshot(FORM_AFTER_SUBMIT);
+
+    expect(
+      result.nodes
+        .filter((node) => node.ref !== undefined)
+        .map((node) => `${node.type} ${node.ref} ${node.label}`),
+    ).toEqual([
+      'heading e1 Bench form',
+      'textbox e2 Name',
+      'textbox e3 Email',
+      'checkbox e4 I agree',
+      'combobox e5 Color',
+      'option e7 Red',
+      'option e8 Blue',
+      'button e6 Submit',
+    ]);
+  });
+
+  test('subsumes a label element text under the control that carries it as its name', async () => {
+    // The backend prints the same visible string twice: as the `<label>` element's text and as the
+    // accessible name of the control it labels. Two nodes reporting `Name` would make the ordinary
+    // `text="Name"` on a form refuse as ambiguous, so the string stays on the node an action can
+    // address — which is also the answer to "where is this text".
+    const result = await normalizeAgentBrowserSnapshot(FORM_AFTER_SUBMIT);
+    const refLess = refLessNodes(result).map((node) => node.value);
+
+    expect(refLess).toEqual(['Hello Zed']);
+    expect(result.nodes.find((node) => node.ref === 'e2')).toMatchObject({
+      label: 'Name',
+      value: 'Zed',
+    });
+  });
+
+  test('carries the text on value, never label', async () => {
+    const result = await normalizeAgentBrowserSnapshot(ROLE_VOCABULARY);
+
+    // `label` is the accessible name a selector resolves to an addressable control; a second node
+    // claiming it would refuse every `label="Go"` read as ambiguous.
+    expect(refLessNodes(result).every((node) => node.label === undefined)).toBe(true);
+    expect(
+      result.nodes.filter((node) => node.label === 'Label text').map((node) => node.ref),
+    ).toEqual(['e2']);
+  });
+
+  test('keeps the text of every non-empty region the tree reports', async () => {
+    const result = await normalizeAgentBrowserSnapshot(ROLE_VOCABULARY);
+
+    expect(refLessNodes(result).map((node) => `${node.type}=${node.value}`)).toEqual([
+      'StaticText=Paragraph text',
+      'StaticText=Span text',
+      'StaticText=Status text',
+      'StaticText=Alert text',
+      'StaticText=Note text',
+    ]);
+  });
+
+  test('drops the empty structural containers compact used to hide', async () => {
+    const result = await normalizeAgentBrowserSnapshot(FORM_BEFORE_SUBMIT);
+    const types = result.nodes.map((node) => node.type);
+
+    // `form`, `list` and the silent `status` region say nothing the rest of the tree does not say.
+    expect(types).not.toContain('form');
+    expect(types).not.toContain('list');
+    expect(types).not.toContain('status');
+    expect(refLessNodes(result)).toEqual([]);
+    expect(result.nodes.map((node) => node.ref)).toEqual(['e1', 'e2', 'e6']);
+  });
+
+  test('drops the list marker and keeps the text of the item it marks', async () => {
+    const result = await normalizeAgentBrowserSnapshot(LIST_WITH_MARKERS);
+
+    expect(result.nodes.map((node) => `${node.type}=${node.value ?? node.label}`)).toEqual([
+      'heading=Items',
+      'StaticText=First',
+      'StaticText=Second',
+    ]);
+  });
+
+  test('re-parents the children of a dropped container to its parent', async () => {
+    // `list` is dropped and `listitem` with it, so each item's text attaches under the root rather
+    // than under whichever node happened to be kept last before it.
+    const result = await normalizeAgentBrowserSnapshot(LIST_WITH_MARKERS);
+    const byValue = new Map(result.nodes.map((node) => [node.value ?? node.label, node]));
+
+    expect(byValue.get('First')?.parentIndex).toBeUndefined();
+    expect(byValue.get('Second')?.parentIndex).toBeUndefined();
+    expect(byValue.get('Items')?.parentIndex).toBeUndefined();
+  });
+
+  test('keeps page text that only coincidentally repeats a control name elsewhere', async () => {
+    // Suppression is a structural relation (see `isTextAlreadyReported`), not a page-global
+    // denylist: this announcement repeats the SUBMIT button's label and is still the reason a reader
+    // opened the page. A table cell echoing a field's contents survives for the same reason. A
+    // page-global "drop what any control reports" rule is the mutation this test fails on.
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: [
+        '- form',
+        '  - button "Submitting" [ref=e1]',
+        '- status',
+        '  - StaticText "Submitting"',
+        '- table',
+        '  - row',
+        '    - cell',
+        '      - StaticText "Zed"',
+      ].join('\n'),
+      refs: { e1: { name: 'Submitting', role: 'button' }, e2: { name: 'Zed', role: 'textbox' } },
+    });
+
+    expect(refLessNodes(result).map((node) => node.value)).toEqual(['Submitting', 'Zed']);
+  });
+
+  test('subsumes a control name printed as its own text line inside the control', async () => {
+    // The backend spells a control's own string twice — as its name and as a text line under it —
+    // and only the descendant shape is a duplicate of that control.
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: ['- button "Go" [ref=e1]', '  - StaticText "Go"', '- StaticText "Go"'].join('\n'),
+      refs: { e1: { name: 'Go', role: 'button' } },
+    });
+
+    expect(refLessNodes(result).map((node) => node.value)).toEqual(['Go']);
+  });
+
+  test('unescapes the quoted name a line carries', async () => {
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: [
+        String.raw`- button "He said \"hello\"" [ref=e1]`,
+        String.raw`  - StaticText "He said \"hello\""`,
+      ].join('\n'),
+      refs: { e1: { name: 'He said "hello"', role: 'button' } },
+    });
+
+    // Stopping at the escaped quote would report `He said \` as the button's name and leave its own
+    // text line looking like different content.
+    expect(result.nodes.find((node) => node.ref === 'e1')?.label).toBe('He said "hello"');
+    expect(refLessNodes(result)).toEqual([]);
+  });
+
+  test('matches a value across the two spellings the backend prints for one string', async () => {
+    // agent-browser prints a control's value two ways (both captured live): the trailing `: value`
+    // form carries it RAW and a quoted payload carries it ESCAPED. Those are the same string, and
+    // the projection must read them that way — unescaping the trailing form as well would turn a
+    // value that legitimately contains a backslash into a different string.
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: [
+        '- textbox "Name" [ref=e2]: He said "hi"',
+        String.raw`  - StaticText "He said \"hi\""`,
+      ].join('\n'),
+      refs: { e2: { name: 'Name', role: 'textbox' } },
+    });
+
+    expect(result.nodes.find((node) => node.ref === 'e2')?.value).toBe('He said "hi"');
+    expect(refLessNodes(result)).toEqual([]);
+  });
+
+  test('preserves a backslash in a value the backend printed raw', async () => {
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: [String.raw`- textbox "Name" [ref=e2]: a\"b`].join('\n'),
+      refs: { e2: { name: 'Name', role: 'textbox' } },
+    });
+
+    // The page really holds `a\"b` (verified through the backend against a live input), and the
+    // trailing form is not an escaped payload, so the two characters stay.
+    expect(result.nodes.find((node) => node.ref === 'e2')?.value).toBe(String.raw`a\"b`);
+  });
+
+  test('attaches geometry only to the nodes the backend can measure', async () => {
+    const result = await normalizeAgentBrowserSnapshot(FORM_AFTER_SUBMIT, async (ref) =>
+      ref === 'e2' ? { x: 1, y: 2, width: 10, height: 20 } : undefined,
+    );
+
+    expect(result.nodes.find((node) => node.ref === 'e2')?.rect).toEqual({
+      x: 1,
+      y: 2,
+      width: 10,
+      height: 20,
+    });
+    expect(refLessNodes(result).every((node) => !node.rect)).toBe(true);
+  });
+
+  test('reads no ref from text that merely mentions a ref-shaped word', async () => {
+    const result = await normalizeAgentBrowserSnapshot({
+      snapshot: ['- status', '  - StaticText "retry in e3 seconds"'].join('\n'),
+      refs: {},
+    });
+
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0]).toMatchObject({ type: 'StaticText', value: 'retry in e3 seconds' });
+    expect(result.nodes[0]?.ref).toBeUndefined();
+  });
+});
diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts
index 51af0a1074..3a49b3277e 100644
--- a/packages/platform-web/src/agent-browser-provider.test.ts
+++ b/packages/platform-web/src/agent-browser-provider.test.ts
@@ -162,7 +162,6 @@ test('agent-browser provider normalizes snapshot refs, labels, values, and paren
     assert.deepEqual(calls[0]?.args, [
       'snapshot',
       '--interactive',
-      '--compact',
       '--depth',
       '4',
       '--selector',
@@ -208,7 +207,7 @@ test('agent-browser provider fetches snapshot rects only when requested', async
     assert.deepEqual(
       calls.map((call) => call.args.slice(0, 3)),
       [
-        ['snapshot', '--compact', '--json'],
+        ['snapshot', '--json', '--session'],
         ['get', 'box', '@e1'],
         ['get', 'box', '@e2'],
         ['get', 'box', '@e3'],
diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts
index 17be828d63..a54aae808c 100644
--- a/packages/platform-web/src/agent-browser-provider.ts
+++ b/packages/platform-web/src/agent-browser-provider.ts
@@ -258,7 +258,7 @@ async function movePointer(send: AgentBrowserSend, x: number, y: number): Promis
 }
 
 async function captureAgentBrowserSnapshot(
-  runJson: (args: string[]) => Promise<unknown>,
+  runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
   options: WebSnapshotOptions | undefined,
 ): Promise<WebSnapshotResult> {
   const data = await runJson(buildSnapshotArgs(options));
@@ -268,18 +268,23 @@ async function captureAgentBrowserSnapshot(
   );
 }
 
+/**
+ * The backend's own `--compact` is deliberately not requested: it removes an element with no ref
+ * TOGETHER WITH the text under it, so a status region that just announced something never reaches
+ * the projection at all. The empty structural lines it existed to hide are dropped by
+ * `parseSnapshotDraftNodes` instead, which can tell an empty container from the text inside it.
+ */
 function buildSnapshotArgs(options: WebSnapshotOptions | undefined): string[] {
   return [
     'snapshot',
     ...(options?.interactiveOnly ? ['--interactive'] : []),
-    ...(options?.raw ? [] : ['--compact']),
     ...(typeof options?.depth === 'number' ? ['--depth', String(options.depth)] : []),
     ...(options?.scope ? ['--selector', options.scope] : []),
   ];
 }
 
 async function fetchRefRect(
-  runJson: (args: string[]) => Promise<unknown>,
+  runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
   ref: string,
 ): Promise<Rect | undefined> {
   try {
diff --git a/packages/platform-web/src/agent-browser-snapshot.ts b/packages/platform-web/src/agent-browser-snapshot.ts
index 9994570ba6..9b49271975 100644
--- a/packages/platform-web/src/agent-browser-snapshot.ts
+++ b/packages/platform-web/src/agent-browser-snapshot.ts
@@ -14,10 +14,29 @@ type SnapshotRefRecord = {
 };
 
 type SnapshotDraftNode = {
-  ref: string;
+  /** The backend ref an action resolves against; absent for content nothing addresses. */
+  ref?: string;
   node: RawSnapshotNode;
 };
 
+/**
+ * Ref-less roles the backend emits as text that no reader asked for. `ListMarker` is the bullet a
+ * list item renders: on a page of list items it is one node per item and says nothing about them.
+ *
+ * Ref-less lines that carry no text (`form`, `list`, `paragraph`) are not nodes either — their
+ * content arrives on their own child lines. That is why the backend's own `--compact` flag cannot
+ * serve a capture that has to see text: it drops an empty container TOGETHER with the text under it,
+ * so a status region that just announced something disappears from the tree entirely.
+ */
+const PRESENTATIONAL_REFLESS_ROLES = new Set(['listmarker']);
+
+/**
+ * The ref-less role a `<label>` element reports. Its text line and the accessible name of the
+ * control it labels are the same string, which is the one duplication the projection resolves by
+ * dropping the text — see `isTextAlreadyReported`.
+ */
+const LABEL_ELEMENT_ROLES = new Set(['labeltext']);
+
 const MAX_CONCURRENT_BOX_FETCHES = 8;
 
 export async function normalizeAgentBrowserSnapshot(
@@ -37,7 +56,14 @@ export async function normalizeAgentBrowserSnapshot(
     // backend ref, not a re-minted dense positional ref. `attachRefs` (downstream) keeps
     // it. Without this the snapshot could show `@e3` = username while the action on
     // `@e3` lands on the backend's `@e3` (a different element, e.g. the passcode field).
-    nodes: drafts.map((draft, index) => ({ ...draft.node, index, ref: draft.ref })),
+    // A line the backend issued no ref for stays ref-less: on-screen content a reader sees
+    // and a text search finds, which nothing can act on — exactly what the backend itself
+    // would refuse the next moment.
+    nodes: drafts.map((draft, index) => ({
+      ...draft.node,
+      index,
+      ...(draft.ref === undefined ? {} : { ref: draft.ref }),
+    })),
     truncated: readBooleanProperty(data, 'truncated'),
   };
 }
@@ -46,48 +72,247 @@ async function attachDraftRects(
   drafts: SnapshotDraftNode[],
   fetchBox: (ref: string) => Promise<Rect | undefined>,
 ): Promise<void> {
-  for (let index = 0; index < drafts.length; index += MAX_CONCURRENT_BOX_FETCHES) {
-    const chunk = drafts.slice(index, index + MAX_CONCURRENT_BOX_FETCHES);
-    const rects = await Promise.all(chunk.map((draft) => fetchBox(draft.ref)));
+  // Only a node the backend issued a ref for has a box to ask for: a ref-less line is text the
+  // backend never measured, and `get box` has no handle for it.
+  const addressable = drafts.flatMap((draft) =>
+    draft.ref === undefined ? [] : [{ draft, ref: draft.ref }],
+  );
+  for (let index = 0; index < addressable.length; index += MAX_CONCURRENT_BOX_FETCHES) {
+    const chunk = addressable.slice(index, index + MAX_CONCURRENT_BOX_FETCHES);
+    const rects = await Promise.all(chunk.map((entry) => fetchBox(entry.ref)));
     for (const [chunkIndex, rect] of rects.entries()) {
-      if (rect) chunk[chunkIndex]!.node.rect = rect;
+      const entry = chunk[chunkIndex];
+      if (rect && entry) entry.draft.node.rect = rect;
     }
   }
 }
 
+/** One snapshot line, with the node it reports when the backend issued a ref for it. */
+type SnapshotLine = {
+  line: string;
+  depth: number;
+  ref: string | null;
+  /** Parsed here so the reported-string survey and the tree walk read a line the same way. */
+  addressableNode?: RawSnapshotNode;
+};
+
 function parseSnapshotDraftNodes(
   snapshotText: string,
   refs: SnapshotRefRecord[],
 ): SnapshotDraftNode[] {
+  const lines = parseSnapshotLines(snapshotText, refs);
+  return indexDraftNodes(buildDraftTree(lines, collectAddressableNames(lines, refs), refs));
+}
+
+function parseSnapshotLines(
+  snapshotText: string,
+  refs: readonly SnapshotRefRecord[],
+): SnapshotLine[] {
   const byRef = new Map(refs.map((ref) => [ref.ref, ref]));
+  return snapshotText.split(/\r?\n/).map((line) => {
+    const depth = inferSnapshotDepth(line);
+    const ref = extractBrowserRef(line);
+    return ref === null
+      ? { line, depth, ref }
+      : {
+          line,
+          depth,
+          ref,
+          addressableNode: snapshotNodeFromLine(line, byRef.get(ref)?.data, depth),
+        };
+  });
+}
+
+/**
+ * The kept lines, in tree order.
+ *
+ * `parentIndexByDepth` records, for the most recent line at each depth, the index of the kept node
+ * its children belong under. A line that is kept records itself; a line that is dropped records its
+ * OWN parent, which is how the children of a dropped container re-parent to the container's parent
+ * instead of to whichever sibling happened to be kept last.
+ *
+ * `labelElementByDepth` carries one boolean the same way, for the same reason: it says whether the
+ * subtree under the most recent line at that depth renders inside a `<label>` element.
+ */
+function buildDraftTree(
+  lines: readonly SnapshotLine[],
+  reportedByLabels: ReadonlySet<string>,
+  refs: readonly SnapshotRefRecord[],
+): SnapshotDraftNode[] {
   const drafts: SnapshotDraftNode[] = [];
   const seenRefs = new Set<string>();
-  const lastIndexByDepth = new Map<number, number>();
+  const parentIndexByDepth = new Map<number, number | undefined>();
+  const labelElementByDepth = new Map<number, boolean>();
 
-  for (const line of snapshotText.split(/\r?\n/)) {
-    const ref = extractBrowserRef(line);
-    if (!ref) continue;
-    seenRefs.add(ref);
-    const metadata = byRef.get(ref)?.data;
-    const depth = inferSnapshotDepth(line);
-    const node = snapshotNodeFromLine(line, metadata, depth);
-    const parentIndex = findParentIndex(lastIndexByDepth, depth);
-    if (parentIndex !== undefined) node.parentIndex = parentIndex;
-    drafts.push({ ref, node: { ...node, index: drafts.length } });
-    lastIndexByDepth.set(depth, drafts.length - 1);
+  for (const entry of lines) {
+    const parentIndex = findParentIndex(parentIndexByDepth, entry.depth);
+    const context = resolveLineContext(drafts, parentIndex, labelElementByDepth, entry.depth);
+    const draft = draftFromLine(entry, reportedByLabels, context);
+    labelElementByDepth.set(
+      entry.depth,
+      isLabelElementLine(entry) ? true : context.insideLabelElement,
+    );
+    if (draft) {
+      if (entry.ref !== null) seenRefs.add(entry.ref);
+      if (parentIndex !== undefined) draft.node.parentIndex = parentIndex;
+      parentIndexByDepth.set(entry.depth, drafts.length);
+      drafts.push(draft);
+      continue;
+    }
+    parentIndexByDepth.set(entry.depth, parentIndex);
   }
 
   for (const ref of refs) {
     if (seenRefs.has(ref.ref)) continue;
-    drafts.push({
-      ref: ref.ref,
-      node: { ...snapshotNodeFromMetadata(ref.data), index: drafts.length },
-    });
+    drafts.push({ ref: ref.ref, node: snapshotNodeFromMetadata(ref.data) });
   }
-
   return drafts;
 }
 
+/** Where a ref-less line sits, for the two structural duplicates it could be. */
+type ReflessLineContext = {
+  /** The line renders inside a `<label>` element, which the control it labels answers for. */
+  insideLabelElement: boolean;
+  /** The nearest kept ancestor that has a ref, i.e. the control this line could sit inside. */
+  addressedAncestor?: SnapshotDraftNode;
+};
+
+/**
+ * Reads both of the walk's inherited facts for one line: whether the recorded subtree above it
+ * renders inside a `<label>` element, and which kept ancestor above it can be addressed.
+ */
+function resolveLineContext(
+  drafts: readonly SnapshotDraftNode[],
+  parentIndex: number | undefined,
+  labelElementByDepth: Map<number, boolean>,
+  depth: number,
+): ReflessLineContext {
+  const insideLabelElement = findInheritedLabelElement(labelElementByDepth, depth);
+  const addressedAncestor = findAddressedAncestor(drafts, parentIndex);
+  return {
+    insideLabelElement,
+    ...(addressedAncestor ? { addressedAncestor } : {}),
+  };
+}
+
+/** The nearest kept ancestor the backend issued a ref for: the control a nested text line repeats. */
+function findAddressedAncestor(
+  drafts: readonly SnapshotDraftNode[],
+  parentIndex: number | undefined,
+): SnapshotDraftNode | undefined {
+  let index = parentIndex;
+  while (index !== undefined) {
+    const draft = drafts[index];
+    if (!draft) return undefined;
+    if (draft.ref !== undefined) return draft;
+    index = draft.node.parentIndex;
+  }
+  return undefined;
+}
+
+/** The node a line reports: the addressable one parsed up front, or the ref-less text it carries. */
+function draftFromLine(
+  entry: SnapshotLine,
+  reportedByLabels: ReadonlySet<string>,
+  context: ReflessLineContext,
+): SnapshotDraftNode | undefined {
+  if (entry.ref !== null) {
+    return { ref: entry.ref, node: { ...entry.addressableNode! } };
+  }
+  return reflessDraftFromLine(entry, reportedByLabels, context);
+}
+
+function indexDraftNodes(drafts: SnapshotDraftNode[]): SnapshotDraftNode[] {
+  return drafts.map((draft, index) => ({ ...draft, node: { ...draft.node, index } }));
+}
+
+/**
+ * Every string an agent can address a node BY: the accessible name of each node the backend issued
+ * a ref for.
+ *
+ * A `<label>` element's text and the accessible name of the control it labels are the same string,
+ * and the accessibility tree's own rule is that the control answers for the label. Keeping both
+ * would publish two matches for `text="Name"` on an ordinary form and make the answer ambiguous, so
+ * the label's text line loses to the node that can be acted on — but only for a line that renders
+ * inside a `<label>` element (see `isTextAlreadyReported`). A string nothing addresses, or one that
+ * only coincidentally repeats a name from elsewhere on the page — the announcement a `status`
+ * region just made — stays a node of its own.
+ */
+function collectAddressableNames(
+  lines: readonly SnapshotLine[],
+  refs: readonly SnapshotRefRecord[],
+): Set<string> {
+  const names = new Set<string>();
+  for (const entry of lines) {
+    if (entry.addressableNode?.label) names.add(entry.addressableNode.label);
+  }
+  // Refs the snapshot text never showed are nodes too, and report the same strings.
+  for (const ref of refs) {
+    const label = snapshotNodeFromMetadata(ref.data).label;
+    if (label) names.add(label);
+  }
+  return names;
+}
+
+function isLabelElementLine(entry: SnapshotLine): boolean {
+  const role = extractRole(entry.line);
+  return role !== undefined && LABEL_ELEMENT_ROLES.has(role.toLowerCase());
+}
+
+/**
+ * The node for a line the backend issued no ref for: text a reader needs and no action can target.
+ *
+ * The string rides on `value`, not `label`. `label` is the accessible name a selector resolves to
+ * the control an action addresses, and a second node claiming it would make every `label="Name"`
+ * read refuse as ambiguous. Every text door reads `value` as well as `label` — `wait text`,
+ * `find text`, `get text`, `text=`, the scope filter, and the printed line — so the text becomes
+ * visible without competing for the name.
+ */
+function reflessDraftFromLine(
+  entry: SnapshotLine,
+  reportedByLabels: ReadonlySet<string>,
+  context: ReflessLineContext,
+): SnapshotDraftNode | undefined {
+  const role = extractRole(entry.line);
+  if (role && PRESENTATIONAL_REFLESS_ROLES.has(role.toLowerCase())) return undefined;
+  const text = extractReflessLineText(entry.line);
+  if (!text || isTextAlreadyReported(text, reportedByLabels, context)) return undefined;
+  const type = role ?? 'StaticText';
+  return {
+    node: {
+      index: 0,
+      type,
+      role: type,
+      value: text,
+      depth: entry.depth,
+    },
+  };
+}
+
+/**
+ * Whether this ref-less text line duplicates a control rather than adding content of its own.
+ *
+ * Only two shapes count, and both are read off the tree rather than off the string:
+ *
+ * 1. the line renders inside a `<label>` element whose control reports the string as its name;
+ * 2. the line sits inside the control itself, which reports the string as its name or as its value
+ *    — the way the backend prints the selected option of a combo box twice.
+ *
+ * Anything else keeps its own node. A page-global "drop what any control anywhere reports" rule
+ * would take from the tree precisely the content this capture exists to publish: a `status`
+ * announcement that happens to repeat a button's label, or a table cell echoing an input's contents,
+ * is content, not a duplicate of a control.
+ */
+function isTextAlreadyReported(
+  text: string,
+  reportedByLabels: ReadonlySet<string>,
+  context: ReflessLineContext,
+): boolean {
+  if (context.insideLabelElement && reportedByLabels.has(text)) return true;
+  const ancestor = context.addressedAncestor?.node;
+  return ancestor?.label === text || ancestor?.value === text;
+}
+
 function snapshotNodeFromLine(
   line: string,
   metadata: JsonObject | undefined,
@@ -121,6 +346,19 @@ function snapshotNodeFromMetadata(metadata: JsonObject | undefined): RawSnapshot
   };
 }
 
+/** The text a ref-less line carries: its quoted name, or the value it prints after the role. */
+function extractReflessLineText(line: string): string | undefined {
+  const quoted = extractQuotedText(line);
+  if (quoted) return quoted;
+  const role = extractRole(line);
+  if (!role) return undefined;
+  const trailing = line
+    .slice(line.indexOf(role) + role.length)
+    .match(/^\s*[:=]\s*(.+)$/)?.[1]
+    ?.trim();
+  return trailing || undefined;
+}
+
 function collectSnapshotRefs(value: unknown): SnapshotRefRecord[] {
   if (Array.isArray(value)) {
     return value.flatMap((entry) => {
@@ -142,9 +380,25 @@ function inferSnapshotDepth(line: string): number {
   return Math.floor(leadingWhitespace / 2);
 }
 
-function findParentIndex(lastIndexByDepth: Map<number, number>, depth: number): number | undefined {
+/** Whether the most recent line recorded above this depth sits inside a `<label>` element. */
+function findInheritedLabelElement(
+  labelElementByDepth: Map<number, boolean>,
+  depth: number,
+): boolean {
   for (let candidateDepth = depth - 1; candidateDepth >= 0; candidateDepth -= 1) {
-    const parent = lastIndexByDepth.get(candidateDepth);
+    const recorded = labelElementByDepth.get(candidateDepth);
+    if (recorded !== undefined) return recorded;
+  }
+  return false;
+}
+
+/** The nearest line recorded above this depth, or nothing above it at all. */
+function findParentIndex(
+  parentIndexByDepth: Map<number, number | undefined>,
+  depth: number,
+): number | undefined {
+  for (let candidateDepth = depth - 1; candidateDepth >= 0; candidateDepth -= 1) {
+    const parent = parentIndexByDepth.get(candidateDepth);
     if (parent !== undefined) return parent;
   }
   return undefined;
@@ -152,16 +406,24 @@ function findParentIndex(lastIndexByDepth: Map<number, number>, depth: number):
 
 function extractBrowserRef(line: string): string | null {
   const annotation = extractNodeAnnotation(line);
-  return normalizeBrowserRef(
-    annotation?.match(/\bref\s*=\s*['"]?(@?e\d+)['"]?/i)?.[1] ?? line.match(/@?(e\d+)\b/i)?.[1],
-  );
+  if (annotation) {
+    return normalizeBrowserRef(annotation.match(/\bref\s*=\s*['"]?(@?e\d+)['"]?/i)?.[1]);
+  }
+  return normalizeBrowserRef(stripQuotedText(line).match(/@(e\d+)\b/i)?.[1]);
+}
+
+/**
+ * Refs are structure, never content: a `ref=eN` annotation or an `@eN` token outside a quoted
+ * name. Text that merely mentions something shaped like a ref (`StaticText "retry in e3 seconds"`)
+ * names no element, and reading one from it would give a text line a ref that resolves to some
+ * other element.
+ */
+function stripQuotedText(line: string): string {
+  return line.replaceAll(/"(?:[^"\\]|\\.)*"/g, '""').replaceAll(/'(?:[^'\\]|\\.)*'/g, "''");
 }
 
 function extractNodeAnnotation(line: string): string | undefined {
-  const structure = line
-    .replaceAll(/"(?:[^"\\]|\\.)*"/g, '""')
-    .replaceAll(/'(?:[^'\\]|\\.)*'/g, "''");
-  return structure.match(/\[([^\]]*\bref\s*=\s*['"]?@?e\d+[^\]]*)\]\s*(?=:|$)/i)?.[1];
+  return stripQuotedText(line).match(/\[([^\]]*\bref\s*=\s*['"]?@?e\d+[^\]]*)\]\s*(?=:|$)/i)?.[1];
 }
 
 function normalizeBrowserRef(value: string | undefined): string | null {
@@ -178,8 +440,13 @@ function extractRole(line: string): string | undefined {
   return cleaned.match(/^([A-Za-z][\w-]*)\b/)?.[1];
 }
 
+/**
+ * The quoted name a line carries, with the escapes the backend printed inside it undone: a control
+ * named `He said "hello"` is that string, not the `He said \` up to the first inner quote.
+ */
 function extractQuotedText(line: string): string | undefined {
-  return line.match(/"([^"]+)"/)?.[1] ?? line.match(/'([^']+)'/)?.[1];
+  const quoted = line.match(/"((?:[^"\\]|\\.)+)"/)?.[1] ?? line.match(/'((?:[^'\\]|\\.)+)'/)?.[1];
+  return quoted?.replaceAll(/\\(["'\\])/g, '$1');
 }
 
 function isLineMarkedDisabled(line: string): boolean {
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index fbaccaa708..2f83ff0d80 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -513,6 +513,7 @@ agent-device is text 'id="greeting"' "Welcome back"
 - `is absent` passes only when the selector has zero matches in one readable, complete, settled, unscoped, full-depth capture. It does not mean hidden: `--scope` and `--depth` are rejected, and sparse, unreadable, truncated, or unsettled captures fail.
 - Predicates that name one element (all except `exists` and `absent`) and `get attrs` fail with `AMBIGUOUS_MATCH` when the selector matches more than one node; that is not a missing element. `error.details.matches` has the count, and up to five candidate `@ref`s are listed, pinned to `error.details.refsGeneration`, so you can act on one directly. Without a stored tree (a sparse capture), only the count is reported. See [Selectors](/docs/selectors#find-an-element).
 - On iOS, React Native text appears as two nodes with the same label. Selectors that must resolve one element (`is`, `get attrs`, `screenshot --crop-on`, replay) treat the pair as one; `find ... list` and `snapshot --json` show both.
+- On the web, on-screen text the browser cannot hand an action to (static text, a `status` announcement) is in the tree and readable by `wait text`, `find text`, `get text`, and `text=`, but carries no `@ref` and has no rect: `find ... list` prints it as `(no ref)`, and it is never a tap target.
 - The first read after `scroll`, `swipe`, or `gesture swipe` waits for two captures to agree. When that proves something about the gesture, `is`, `get`, `find`, `wait`, interactions that captured it, and `snapshot` add a warning, and all but `snapshot` report `postGestureOutcome` (`{ "kind", "gesture": { "action", "positionals" } }`) in `data` or `error.details`:
   - `kind: "unsettled"`: the screen was still changing. A miss is not proof of absence; read again. `is absent` refuses with `observation: "unsettled"`, and `wait absent` keeps polling.
   - `kind: "no-effect"`: nothing changed. The list may be at its edge or ignore synthesized scrolls; a raw `swipe x1 y1 x2 y2` inside it moves such lists.

From 0ae56db1ed4a687f919ed20b9ba78d41b7da9b38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 13 Oct 2026 11:33:26 +0200
Subject: [PATCH 2/3] test(web): pin that a web capture publishes only
 backend-issued refs

The one thing standing between a web capture and dense numbering was the minting-mode argument at snapshot-state.ts:83, and no test drove it through the router: every agent-browser fixture gave every node a ref, so deleting the argument minted e7 onto ref-less page text with the whole suite green (#2283 is the collision that pays for it). The scenario page now has a ref-less line as the backend prints one - text on value, no ref, no box - and four router assertions follow it: snapshot --json publishes it with no ref key, find text <it> list prints it as (no ref), wait text answers it, and click text=<it> refuses with selector_not_found.
---
 .../provider-scenarios/web-desktop.test.ts    | 60 +++++++++++++++++++
 .../provider-scenarios/web-world.ts           | 25 +++++++-
 2 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/test/integration/provider-scenarios/web-desktop.test.ts b/test/integration/provider-scenarios/web-desktop.test.ts
index 895f47ed2d..4c7febe27e 100644
--- a/test/integration/provider-scenarios/web-desktop.test.ts
+++ b/test/integration/provider-scenarios/web-desktop.test.ts
@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import { test } from 'vitest';
+import { interactionCliOutputFormatters } from '../../../src/commands/interaction/output.ts';
 import { assertFlatToolCall, assertPngFile } from './assertions.ts';
 import { PROVIDER_SCENARIO_WEB } from './fixtures.ts';
 import { createProviderScenarioTempPath, withProviderScenarioResource } from './harness.ts';
@@ -70,6 +71,52 @@ test('Provider-backed integration web desktop flow uses semantic web provider ca
           positionals: ['text', 'Submit order', 'exists'],
           expectData: { found: true },
         },
+        // #2283, the whole reason a web capture mints no refs of its own: this node reached the
+        // stored state through `buildSnapshotState` with agent-browser provenance and carries no
+        // ref, so it must be published, listed and waited on without ever being offered an
+        // address. Delete `snapshotRefMinting(data)` from snapshot-state and this block turns red
+        // on the first step (the node would be minted `e7`, colliding with nothing here and with a
+        // real control on a real page).
+        {
+          name: 'publish the ref-less text with no ref key',
+          command: 'snapshot',
+          flags: { snapshotInteractiveOnly: false },
+          assert: (response) => {
+            const nodes = response.json?.result?.data?.nodes as
+              | Array<Record<string, unknown>>
+              | undefined;
+            const refLess = nodes?.find((node) => node.value === 'Order saved');
+            assert.ok(
+              refLess,
+              `Ref-less text missing from the published tree: ${JSON.stringify(nodes)}`,
+            );
+            assert.equal('ref' in refLess, false, JSON.stringify(refLess));
+          },
+        },
+        {
+          name: 'list the ref-less text without an address',
+          command: 'find',
+          positionals: ['text', 'Order saved', 'list'],
+          assert: async (response) => {
+            const matches = response.json?.result?.data?.matches as
+              | Array<Record<string, unknown>>
+              | undefined;
+            assert.equal(matches?.length, 1, JSON.stringify(response.json?.result?.data));
+            assert.equal('ref' in (matches?.[0] ?? {}), false, JSON.stringify(matches?.[0]));
+            const cli = await interactionCliOutputFormatters.find({
+              input: {},
+              result: response.json?.result?.data,
+            });
+            assert.equal(cli.text, ['1 match:', '= (no ref) [text] "Order saved"'].join('\n'));
+          },
+        },
+        {
+          name: 'wait for the ref-less text',
+          command: 'wait',
+          positionals: ['text', 'Order saved', '100'],
+          expectData: { text: 'Order saved' },
+        },
+
         {
           name: 'assert visible text',
           command: 'is',
@@ -169,6 +216,19 @@ test('Provider-backed integration web desktop flow uses semantic web provider ca
         },
       ]);
 
+      // This step pins the acting row's `requireRect`, not the minting rule: a ref-less line is one
+      // the backend never measured and never issued a handle for, and a line the backend DID mint a
+      // ref for still carries no rect here, so this refusal would hold either way. The minting rule
+      // itself is pinned by the `snapshot --json` and `find text … list` assertions above. The
+      // refusal has to name no match — an action here would be a blind tap, which is the collision
+      // #2283 is about.
+      const refLessClick = await daemon.callCommand('click', ['text="Order saved"']);
+      assert.equal(
+        refLessClick.json?.error?.data?.details?.reason,
+        'selector_not_found',
+        JSON.stringify(refLessClick.json),
+      );
+
       const actions = daemon.session()?.actions ?? [];
       assert.ok(
         actions.some(
diff --git a/test/integration/provider-scenarios/web-world.ts b/test/integration/provider-scenarios/web-world.ts
index 35a0dbdaba..4982919ba1 100644
--- a/test/integration/provider-scenarios/web-world.ts
+++ b/test/integration/provider-scenarios/web-world.ts
@@ -55,7 +55,10 @@ export async function createWebDesktopWorld(): Promise<WebDesktopWorld> {
         String(options?.interactiveOnly ?? ''),
         String(options?.surface ?? ''),
       ]);
-      return { nodes: webSnapshotNodes(state), truncated: false };
+      return {
+        nodes: webSnapshotNodes(state, options?.interactiveOnly === true),
+        truncated: false,
+      };
     },
     screenshot: async (outPath, options) => {
       semanticCalls.push([
@@ -142,7 +145,7 @@ export async function createWebDesktopWorld(): Promise<WebDesktopWorld> {
   };
 }
 
-function webSnapshotNodes(state: WebPageState): RawSnapshotNode[] {
+function webSnapshotNodes(state: WebPageState, interactiveOnly: boolean): RawSnapshotNode[] {
   // Every element of the emulated page carries a ref, in the tree order the backend mints them in:
   // a web capture publishes its producer's refs and mints no replacement, so a page that wants to be
   // addressable has to issue them itself.
@@ -219,6 +222,24 @@ function webSnapshotNodes(state: WebPageState): RawSnapshotNode[] {
       depth: 1,
       parentIndex: 0,
     },
+    // On-screen text the backend reports but issues no ref for, exactly as a real agent-browser
+    // capture prints a ref-less line: text on `value`, no ref, and no box to ask for. Nothing may
+    // mint it an address (#2283) — every web tree reaching `buildSnapshotState` publishes only the
+    // refs its producer issued. `--interactive` prints only the lines carrying a handle, so the
+    // interactive capture leaves it out.
+    ...(interactiveOnly
+      ? []
+      : [
+          {
+            index: 6,
+            type: 'StaticText',
+            role: 'StaticText',
+            value: 'Order saved',
+            visibleToUser: true,
+            depth: 1,
+            parentIndex: 0,
+          },
+        ]),
   ];
 }
 

From 20b6693ae73f810fd7e44ac26232521c4a9a3c50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 13 Oct 2026 11:33:26 +0200
Subject: [PATCH 3/3] docs(web): tell a value= query it can now match page text

Ref-less on-screen text is published on value, so value="X" resolves against page text that repeats a control's value and a predicate needing one element answers AMBIGUOUS_MATCH. commands.md names text= and editable=true as the way out. Also the take-it-or-leave-it round: the paragraph the body claimed for docs/agents/web-backend.md was already in commands.md, so the body points there; keyboard-occlusion's import goes back to type-only (nothing here reads a value from kernel/snapshot); WebSnapshotOptions.raw goes, since buildSnapshotArgs no longer reads it and no caller sets it; and the two runJson signature hunks that added a signal nothing passes are reverted.
---
 packages/platform-web/src/agent-browser-provider.ts  |  4 ++--
 packages/platform-web/src/provider.ts                |  1 -
 .../interaction/runtime/keyboard-occlusion.ts        | 12 ++++++------
 website/docs/docs/commands.md                        |  2 +-
 4 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts
index a54aae808c..490e9f92d4 100644
--- a/packages/platform-web/src/agent-browser-provider.ts
+++ b/packages/platform-web/src/agent-browser-provider.ts
@@ -258,7 +258,7 @@ async function movePointer(send: AgentBrowserSend, x: number, y: number): Promis
 }
 
 async function captureAgentBrowserSnapshot(
-  runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
+  runJson: (args: string[]) => Promise<unknown>,
   options: WebSnapshotOptions | undefined,
 ): Promise<WebSnapshotResult> {
   const data = await runJson(buildSnapshotArgs(options));
@@ -284,7 +284,7 @@ function buildSnapshotArgs(options: WebSnapshotOptions | undefined): string[] {
 }
 
 async function fetchRefRect(
-  runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
+  runJson: (args: string[]) => Promise<unknown>,
   ref: string,
 ): Promise<Rect | undefined> {
   try {
diff --git a/packages/platform-web/src/provider.ts b/packages/platform-web/src/provider.ts
index 1618a5015d..38d50209fd 100644
--- a/packages/platform-web/src/provider.ts
+++ b/packages/platform-web/src/provider.ts
@@ -23,7 +23,6 @@ export type WebSnapshotOptions = {
   interactiveOnly?: boolean;
   depth?: number;
   scope?: string;
-  raw?: boolean;
   includeRects?: boolean;
   surface?: SessionSurface;
   signal?: AbortSignal;
diff --git a/src/commands/interaction/runtime/keyboard-occlusion.ts b/src/commands/interaction/runtime/keyboard-occlusion.ts
index 7535dfce65..d9d1599297 100644
--- a/src/commands/interaction/runtime/keyboard-occlusion.ts
+++ b/src/commands/interaction/runtime/keyboard-occlusion.ts
@@ -1,9 +1,9 @@
-import {
-  type Point,
-  type Rect,
-  type SnapshotKeyboardBandFact,
-  type SnapshotNode,
-  type SnapshotState,
+import type {
+  Point,
+  Rect,
+  SnapshotKeyboardBandFact,
+  SnapshotNode,
+  SnapshotState,
 } from '@agent-device/kernel/snapshot';
 import { AppError, discloseDispatch } from '@agent-device/kernel/errors';
 import { createSnapshotVisibility } from '@agent-device/contracts/snapshot';
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 2f83ff0d80..7291f3c47d 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -513,7 +513,7 @@ agent-device is text 'id="greeting"' "Welcome back"
 - `is absent` passes only when the selector has zero matches in one readable, complete, settled, unscoped, full-depth capture. It does not mean hidden: `--scope` and `--depth` are rejected, and sparse, unreadable, truncated, or unsettled captures fail.
 - Predicates that name one element (all except `exists` and `absent`) and `get attrs` fail with `AMBIGUOUS_MATCH` when the selector matches more than one node; that is not a missing element. `error.details.matches` has the count, and up to five candidate `@ref`s are listed, pinned to `error.details.refsGeneration`, so you can act on one directly. Without a stored tree (a sparse capture), only the count is reported. See [Selectors](/docs/selectors#find-an-element).
 - On iOS, React Native text appears as two nodes with the same label. Selectors that must resolve one element (`is`, `get attrs`, `screenshot --crop-on`, replay) treat the pair as one; `find ... list` and `snapshot --json` show both.
-- On the web, on-screen text the browser cannot hand an action to (static text, a `status` announcement) is in the tree and readable by `wait text`, `find text`, `get text`, and `text=`, but carries no `@ref` and has no rect: `find ... list` prints it as `(no ref)`, and it is never a tap target.
+- On the web, on-screen text the browser cannot hand an action to (static text, a `status` announcement) is in the tree and readable by `wait text`, `find text`, `get text`, and `text=`, but carries no `@ref` and has no rect: `find ... list` prints it as `(no ref)`, and it is never a tap target. Such text is published on `value`, so `value="X"` can match page text as well as a field holding that text, and a predicate that needs one element then reports `AMBIGUOUS_MATCH`; use `text=` for page text, or add `editable=true` to name the field.
 - The first read after `scroll`, `swipe`, or `gesture swipe` waits for two captures to agree. When that proves something about the gesture, `is`, `get`, `find`, `wait`, interactions that captured it, and `snapshot` add a warning, and all but `snapshot` report `postGestureOutcome` (`{ "kind", "gesture": { "action", "positionals" } }`) in `data` or `error.details`:
   - `kind: "unsettled"`: the screen was still changing. A miss is not proof of absence; read again. `is absent` refuses with `observation: "unsettled"`, and `wait absent` keeps polling.
   - `kind: "no-effect"`: nothing changed. The list may be at its edge or ignore synthesized scrolls; a raw `swipe x1 y1 x2 y2` inside it moves such lists.