Skip to content

Commit 724d305

Browse files
committed
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.
1 parent 2adf955 commit 724d305

4 files changed

Lines changed: 9 additions & 10 deletions

File tree

‎packages/platform-web/src/agent-browser-provider.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ async function movePointer(send: AgentBrowserSend, x: number, y: number): Promis
258258
}
259259

260260
async function captureAgentBrowserSnapshot(
261-
runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
261+
runJson: (args: string[]) => Promise<unknown>,
262262
options: WebSnapshotOptions | undefined,
263263
): Promise<WebSnapshotResult> {
264264
const data = await runJson(buildSnapshotArgs(options));
@@ -284,7 +284,7 @@ function buildSnapshotArgs(options: WebSnapshotOptions | undefined): string[] {
284284
}
285285

286286
async function fetchRefRect(
287-
runJson: (args: string[], signal?: AbortSignal) => Promise<unknown>,
287+
runJson: (args: string[]) => Promise<unknown>,
288288
ref: string,
289289
): Promise<Rect | undefined> {
290290
try {

‎packages/platform-web/src/provider.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ export type WebSnapshotOptions = {
2323
interactiveOnly?: boolean;
2424
depth?: number;
2525
scope?: string;
26-
raw?: boolean;
2726
includeRects?: boolean;
2827
surface?: SessionSurface;
2928
signal?: AbortSignal;

‎src/commands/interaction/runtime/keyboard-occlusion.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
import {
2-
type Point,
3-
type Rect,
4-
type SnapshotKeyboardBandFact,
5-
type SnapshotNode,
6-
type SnapshotState,
1+
import type {
2+
Point,
3+
Rect,
4+
SnapshotKeyboardBandFact,
5+
SnapshotNode,
6+
SnapshotState,
77
} from '@agent-device/kernel/snapshot';
88
import { AppError, discloseDispatch } from '@agent-device/kernel/errors';
99
import { createSnapshotVisibility } from '@agent-device/contracts/snapshot';

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -513,7 +513,7 @@ agent-device is text 'id="greeting"' "Welcome back"
513513
- `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.
514514
- 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).
515515
- 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.
516-
- 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.
516+
- 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.
517517
- 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`:
518518
- `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.
519519
- `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.

0 commit comments

Comments
 (0)