Skip to content

Commit 37a4c73

Browse files
committed
docs(selectors): disclose the alias window's kind-adjacent matches precisely
PR review: is guaranteed BY a kind, not exactly equivalent to one — a windowed legacy node can match its old spelling beside a kind the vocabulary never renamed (AXWebArea), so the docs now state the guarantee and the alias separately, and the client-api anchor now carries the real github-slugger slug. Adds a kernel pin that the published kind leads the spellings even when it diverges from what formatRole(type) would derive — the mutation the prior test could not catch. Clarifies that the locator's substring leaf deliberately keeps the retired LOCATOR's '.'-only split (each surface's historical substring meaning survives); the retired TERM's '/'-reduced spelling rides as the exact alias, which is where term/locator agreement comes from.
1 parent 0bf1a38 commit 37a4c73

4 files changed

Lines changed: 26 additions & 8 deletions

File tree

‎packages/kernel/src/snapshot-role-kind.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,18 @@ test('roleSpellingsOfNode leads with the kind the capture published', () => {
1414
assert.deepEqual(roleSpellingsOfNode(node), ['text', 'statictext']);
1515
});
1616

17+
test('roleSpellingsOfNode reads a published kind even when it diverges from the type', () => {
18+
// Distinguishes kind-reading from type-only matching: a node whose `kind`
19+
// is NOT what formatRole(type) would derive must lead with the published
20+
// kind, with the type-derived spellings riding only as the window. A
21+
// regression to deriving the canonical spelling from `type` fails here even
22+
// though the alias rides along in both directions.
23+
assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeButton', kind: 'text' }), [
24+
'text',
25+
'button',
26+
]);
27+
});
28+
1729
test('roleSpellingsOfNode reuses formatRole for a node that predates kind publication', () => {
1830
// Fixtures that never route through `attachRefs` carry no `kind`; the reader
1931
// computes it with the SAME function that publishes it, not a second

‎packages/selectors/src/internal/find.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -141,11 +141,16 @@ function matchRole(node: SnapshotNode, query: string): number {
141141

142142
/**
143143
* The substring-scoring view of one role spelling: its last `.`-separated
144-
* segment, matching the retired locator's leaf. An AX-stripped query (`link`
145-
* against an `AXLink` node) reaches the exact score through the windowed
146-
* alias, not through substring — the retired selector TERM already matched
147-
* that spelling exactly (`contracts` `normalizeType` stripped the prefix), so
148-
* promoting it here is the locator/term parity #3021 requires.
144+
* segment. This is deliberately the RETIRED LOCATOR's leaf (`split('.').pop()`
145+
* only), not the kernel's retired-term spelling — the term also reduced a
146+
* trailing `/` segment, and mirroring that here would drop substring hits the
147+
* released locator kept (query `y/z` still scores 1 against kind `x.y/z`
148+
* today). The term's `/`-reduced spelling rides as the windowed exact alias
149+
* instead, so term/locator agreement comes from the exact side, and each
150+
* surface's historical substring meaning is preserved. An AX-stripped query
151+
* (`link` against an `AXLink` node) likewise reaches the exact score through
152+
* the windowed alias, not through substring — the retired term already matched
153+
* that spelling exactly, so promoting it here is the parity #3021 requires.
149154
*/
150155
function roleLeafSegment(spelling: string): string {
151156
const lastDot = spelling.lastIndexOf('.');

‎website/docs/docs/client-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -510,7 +510,7 @@ Use `agent-device/remote-config` for profile loading and path resolution, `agent
510510

511511
## Selector helpers
512512

513-
Use `agent-device/selectors` when a remote daemon or bridge needs to parse and match selector expressions without deep-importing daemon internals. The `role=` term matches the platform-neutral `kind` vocabulary that `snapshot --json` publishes (see [Snapshots](./snapshots.md#structured-node-fields--json)): pass the nodes as captured and a node matches `role=text` exactly when its `kind` is `text`. Pre-reconciliation leaf spellings (`statictext`, `edittext`, `textview`, …) still match during a deprecation window, each on the nodes that actually carried that class. Matching stays platform-aware because editability checks differ by backend.
513+
Use `agent-device/selectors` when a remote daemon or bridge needs to parse and match selector expressions without deep-importing daemon internals. The `role=` term matches the platform-neutral `kind` vocabulary that `snapshot --json` publishes (see [Snapshots](./snapshots.md#structured-node-fields---json)): pass the nodes as captured, and a node whose `kind` is `text` always matches `role=text`. Separately, pre-reconciliation leaf spellings (`statictext`, `edittext`, `textview`, …) still match during a deprecation window, each on the nodes that actually carried that class. A legacy spelling matches beside such a node's `kind`, not in place of it — `role=webarea` resolves a macOS-helper `AXWebArea` node whose `kind` is `axwebarea`, for example. Matching stays platform-aware because editability checks differ by backend.
514514

515515
`listSelectorChainMatches(nodes, chain, options)` returns every node the winning selector alternative matches, in snapshot order, plus that alternative and its index — the same first-match domain `findSelectorChainMatch` uses, without uniqueness refusal, so a runner applies its own strictness to the same nodes the CLI matched. `resolveSelectorChain` can name a LATER alternative: by default it refuses an ambiguous one and keeps walking, so the indices agree when it passes `requireUnique: false`, when the first matching alternative is unique, or when `disambiguateAmbiguous: true` resolves that alternative in place. It returns `null` when no alternative matches. `options` is `{ platform, requireRect? }`; the matched `SnapshotNode` objects are the ones passed in.
516516

‎website/docs/docs/snapshots.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,9 @@ Every node in `snapshot --json` output carries `kind`, next to `type` when the p
106106
On iOS, `role` (when present) is the native AX class (`UIButton`) — a different fact carried only
107107
on iOS nodes; `kind` is the cross-platform one, present on every node on every platform.
108108

109-
`role=` selectors (and `find role=...`) match `kind`'s vocabulary: `role=text` and `role=text-field`
110-
match exactly what the snapshot shows in brackets for that node
109+
`role=` selectors (and `find role=...`) match `kind`'s vocabulary: a node whose `kind` is `text`
110+
or `text-field` always matches `role=text` / `role=text-field` — the bracketed word a snapshot
111+
shows for that node
111112
([#3021](https://github.com/callstack/agent-device/issues/3021)). Spellings from before that
112113
reconciliation — the raw leaf classes `role=statictext`, `role=edittext`, `role=textview`,
113114
`role=searchfield`, and the rest of the leaf vocabulary — stay accepted during a deprecation window,

0 commit comments

Comments
 (0)