From 6539b3ece957996bb389e6dadda60b0943af2e42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 16:30:42 +0200
Subject: [PATCH 1/7] feat(selectors): match role= against the snapshot kind
 vocabulary with a node-scoped alias window
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#3021: the role= selector term and the find role= locator each normalized
node.type into a raw leaf class name (statictext, edittext), diverging from
the coarse kind vocabulary formatRole publishes on every snapshot node. Both
surfaces now read one kernel-owned reader, roleSpellingsOfNode: the canonical
kind (the published kind, formatRole-derived only for nodes that bypass
attachRefs) plus a deprecation window carrying exactly the node's retired
spelling, so role=text and role=text-field start matching while released
role=statictext/role=edittext/role=textview scripts keep resolving — on the
nodes that actually carried the leaf, never a kind sibling's (role=linearlayout
still refuses a FrameLayout, pinned by the #1280 daemon fixtures).

No new runtime warning or response shape: the window is disclosed in the
versioned find help, user docs, and pinned by the alias tests. contracts
normalizeType (fillable/occlusion) and provider-webdriver roleFromWebDriverType
(the iOS role field) serve different fields and stay untouched.
---
 .../kernel/src/snapshot-role-kind.test.ts     | 108 ++++++++++++++++
 packages/kernel/src/snapshot.ts               | 121 +++++++++++++++---
 packages/selectors/src/internal/find.test.ts  | 104 +++++++++++++++
 packages/selectors/src/internal/find.ts       |  25 ++--
 packages/selectors/src/internal/match.test.ts | 115 +++++++++++++++++
 packages/selectors/src/internal/match.ts      |  19 ++-
 .../internal/replay-role-vocabulary.test.ts   |  57 +++++++++
 src/commands/interaction/metadata.ts          |   2 +-
 website/docs/docs/client-api.md               |   2 +-
 website/docs/docs/selectors.md                |   1 +
 website/docs/docs/snapshots.md                |  13 +-
 11 files changed, 525 insertions(+), 42 deletions(-)
 create mode 100644 packages/kernel/src/snapshot-role-kind.test.ts
 create mode 100644 packages/selectors/src/internal/replay-role-vocabulary.test.ts

diff --git a/packages/kernel/src/snapshot-role-kind.test.ts b/packages/kernel/src/snapshot-role-kind.test.ts
new file mode 100644
index 0000000000..8b48407a02
--- /dev/null
+++ b/packages/kernel/src/snapshot-role-kind.test.ts
@@ -0,0 +1,108 @@
+// #3021: the kernel-owned `role=` vocabulary shared by `kind`, the `role=`
+// selector term, and the `find role=` locator. Everything is pinned through
+// `roleSpellingsOfNode` — the ONE public reader both selector surfaces consume.
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { attachRefs, formatRole, roleSpellingsOfNode } from './snapshot.ts';
+
+test('roleSpellingsOfNode leads with the kind the capture published', () => {
+  const [node] = attachRefs([{ index: 0, type: 'XCUIElementTypeStaticText' }]);
+  assert.ok(node);
+  assert.equal(node.kind, 'text');
+  // A production node built by `attachRefs` matches on its published `kind`
+  // first; the documented meaning of `role=` is that vocabulary.
+  assert.deepEqual(roleSpellingsOfNode(node), ['text', 'statictext']);
+});
+
+test('roleSpellingsOfNode reuses formatRole for a node that predates kind publication', () => {
+  // Fixtures that never route through `attachRefs` carry no `kind`; the reader
+  // computes it with the SAME function that publishes it, not a second
+  // normalization.
+  assert.equal(roleSpellingsOfNode({ type: 'android.widget.EditText' })[0], 'text-field');
+  assert.equal(roleSpellingsOfNode({})[0], formatRole('Element'));
+});
+
+test('a renamed leaf stays windowed on the node that carries it', () => {
+  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeStaticText' }), [
+    'text',
+    'statictext',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.EditText' }), [
+    'text-field',
+    'edittext',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.FrameLayout' }), [
+    'group',
+    'framelayout',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeSearchField' }), [
+    'search',
+    'searchfield',
+  ]);
+});
+
+test('the window is node-scoped: sibling leaves of one coarse kind never alias each other', () => {
+  // The nearest-negative that makes the alias window a window and not a
+  // widening: `group` renames many leaves (`framelayout`, `linearlayout`,
+  // `viewgroup`, …), and #3021 must not make `role=linearlayout` match a
+  // FrameLayout node. Each node carries only ITS OWN old spelling.
+  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.LinearLayout' }), [
+    'group',
+    'linearlayout',
+  ]);
+  assert.ok(!roleSpellingsOfNode({ type: 'android.widget.FrameLayout' }).includes('linearlayout'));
+});
+
+test('the context-coarse `textview` leaf stays windowed on both spellings that emitted it', () => {
+  // `formatRole` answers `text-view` for the desktop/iOS spelling and `text`
+  // for the Android class; both nodes carried the matchable leaf `textview`.
+  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeTextView' }), [
+    'text-view',
+    'textview',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.TextView' }), ['text', 'textview']);
+});
+
+test('AX-prefixed class types carry the AX-stripped spelling the old normalizer matched', () => {
+  // The macOS helper's `subrole ?? role` fallback emits raw `AX…` classes whose
+  // canonical kind keeps the prefix while the retired matcher accepted the
+  // AX-stripped spelling; renumbered leaves like `AXStaticText` window to the
+  // leaf instead.
+  assert.deepEqual(roleSpellingsOfNode({ type: 'AXFloatingWindow' }), [
+    'axfloatingwindow',
+    'floatingwindow',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'AXUnknown' }), ['axunknown', 'unknown']);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'AXStaticText' }), ['axstatictext', 'statictext']);
+});
+
+test('the window replays the retired normalizer for arbitrary custom class names', () => {
+  // The retired spelling took the last `.`-separated segment of any class, so
+  // a released script could name a custom view class; the window must not
+  // silently drop spellings formatRole's own leaf step would not produce.
+  // (formatRole keeps the full dotted spelling as the kind for a non-Android
+  // class it does not recognize; the old last-segment leaf windows beside it.)
+  assert.deepEqual(roleSpellingsOfNode({ type: 'io.foo.app.MyButton' }), [
+    'io.foo.app.mybutton',
+    'mybutton',
+  ]);
+});
+
+test('a kind that equals its leaf carries no alias of its own', () => {
+  // The nearest-negative for the window itself: `button` and unmapped leaves
+  // like `gridview` are both the leaf and the kind, so the window adds nothing
+  // and no vocabulary entry leaks in.
+  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeButton' }), ['button']);
+  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.GridView' }), ['gridview']);
+});
+
+test('formatRole keeps its published vocabulary across the leaf-factorization', () => {
+  // The #3021 refactor moved formatRole's leaf step into a shared helper; the
+  // coarse answers every backend depends on must not move.
+  assert.equal(formatRole('XCUIElementTypeStaticText'), 'text');
+  assert.equal(formatRole('android.widget.TextView'), 'text');
+  assert.equal(formatRole('XCUIElementTypeTextView'), 'text-view');
+  assert.equal(formatRole('androidx.recyclerview.widget.RecyclerView'), 'list');
+  assert.equal(formatRole('Button'), 'button');
+  assert.equal(formatRole(''), 'element');
+});
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index 6691445f25..1ec3e2a66c 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -450,26 +450,113 @@ function lookupRoleLabel(normalized: string): string | undefined {
     : undefined;
 }
 
-export function formatRole(type: string): string {
-  const raw = type;
+function isAndroidRoleClass(type: string): boolean {
+  return (
+    type.includes('.') &&
+    (type.startsWith('android.') || type.startsWith('androidx.') || type.startsWith('com.'))
+  );
+}
+
+/**
+ * The leaf normalization {@link formatRole} runs before it consults
+ * {@link ROLE_LABELS}: strip `XCUIElementType`, lowercase, and reduce Android
+ * class packages to their leaf. Factored out for readability; the `role=`
+ * deprecation window below deliberately does NOT share this step — it replays
+ * the retired normalizer's spelling, not formatRole's leaf.
+ */
+function normalizeRoleLeaf(type: string): string {
   let normalized = type.replaceAll(/XCUIElementType/gi, '').toLowerCase();
-  const isAndroidClass =
-    raw.includes('.') &&
-    (raw.startsWith('android.') || raw.startsWith('androidx.') || raw.startsWith('com.'));
-  if (normalized.includes('.')) {
-    normalized = normalized
-      .replace(/^android\.widget\./, '')
-      .replace(/^android\.view\./, '')
-      .replace(/^android\.webkit\./, '')
-      .replace(/^androidx\./, '')
-      .replace(/^com\.google\.android\./, '')
-      .replace(/^com\.android\./, '');
-    if (isAndroidClass && normalized.includes('.')) {
-      normalized = normalized.slice(normalized.lastIndexOf('.') + 1);
-    }
+  if (!normalized.includes('.')) {
+    return normalized;
+  }
+  const isAndroidClass = isAndroidRoleClass(type);
+  normalized = normalized
+    .replace(/^android\.widget\./, '')
+    .replace(/^android\.view\./, '')
+    .replace(/^android\.webkit\./, '')
+    .replace(/^androidx\./, '')
+    .replace(/^com\.google\.android\./, '')
+    .replace(/^com\.android\./, '');
+  if (isAndroidClass && normalized.includes('.')) {
+    normalized = normalized.slice(normalized.lastIndexOf('.') + 1);
+  }
+  return normalized;
+}
+
+/**
+ * The `role=` deprecation window (#3021): the legacy spellings this node still
+ * accepts beside its canonical {@link roleKindOfNode} kind. One entry: the
+ * node's retired role spelling — what `role=` compared before #3021 — computed
+ * by {@link legacyRoleSpellingOfType} below and dropped when it already equals
+ * the canonical kind (the vocabulary-identity case, which needs no window).
+ *
+ * The window is deliberately NODE-scoped, not a kind→leaves alias table. One
+ * coarse kind renames many distinct leaves (`group` covers `framelayout`,
+ * `linearlayout`, `viewgroup`, …); a kind-keyed table would make
+ * `role=linearlayout` match a `FrameLayout` — silently WIDENING every released
+ * script that names a leaf, which is a new breaking change measured against
+ * the old matcher rather than a compatibility window. So the leaf stays
+ * matchable only on the nodes that actually carried it: the window is exactly
+ * the old spelling of THIS node, never a sibling's.
+ */
+function legacyRoleAliasesForNode(
+  node: Pick<RawSnapshotNode, 'type'> & { kind?: string },
+): readonly string[] {
+  const alias = legacyRoleSpellingOfType(node.type ?? '');
+  return alias && alias !== roleKindOfNode(node) ? [alias] : [];
+}
+
+/**
+ * The ONE owner of the pre-#3021 `role=` spelling: the retired normalizer's
+ * exact step — strip `XCUIElementType` and a leading `AX`, lowercase, take the
+ * last `.`/`/`-separated segment — kept here so the deprecation window can
+ * replay the old meaning of `role=` for the nodes that carry it while the
+ * canonical vocabulary stays `formatRole` alone. The retired matcher consumers
+ * (the selector term and `find`'s deleted `normalizeRole`) are gone; this
+ * window is their spelling's only remaining reader, and when the window closes
+ * this function leaves with it.
+ */
+function legacyRoleSpellingOfType(type: string): string {
+  let normalized = type
+    .trim()
+    .replaceAll(/XCUIElementType/gi, '')
+    .replace(/^AX/, '')
+    .toLowerCase();
+  const lastSeparator = Math.max(normalized.lastIndexOf('.'), normalized.lastIndexOf('/'));
+  if (lastSeparator !== -1) {
+    normalized = normalized.slice(lastSeparator + 1);
   }
+  return normalized;
+}
+
+/**
+ * Every `role=` spelling this node accepts, in ONE place (#3021): the
+ * canonical kind first, then its windowed legacy aliases. The `role=` selector
+ * term and the `find role=` locator both read this and nothing else, which is
+ * what keeps the two — and `kind` itself — unable to disagree.
+ */
+export function roleSpellingsOfNode(
+  node: Pick<RawSnapshotNode, 'type'> & { kind?: string },
+): readonly string[] {
+  return [roleKindOfNode(node), ...legacyRoleAliasesForNode(node)];
+}
+
+/**
+ * The canonical role kind of a snapshot node — the ONE node-role reader for
+ * `role=` selector matching (#3021). It prefers the `kind` the capture
+ * published through {@link attachRefs} and reuses this module's own
+ * {@link formatRole} when a node predates or bypasses that construction path;
+ * `kind` is by definition `formatRole(type)`, so there is no second
+ * normalization to drift from.
+ */
+function roleKindOfNode(node: Pick<RawSnapshotNode, 'type'> & { kind?: string }): string {
+  return node.kind ?? formatRole(node.type ?? 'Element');
+}
+
+export function formatRole(type: string): string {
+  const normalized = normalizeRoleLeaf(type);
   if (normalized === 'textview') {
-    return isAndroidClass ? 'text' : 'text-view';
+    return isAndroidRoleClass(type) ? 'text' : 'text-view';
   }
   return lookupRoleLabel(normalized) || normalized || 'element';
 }
diff --git a/packages/selectors/src/internal/find.test.ts b/packages/selectors/src/internal/find.test.ts
index 3e172126c8..1bd376cb9f 100644
--- a/packages/selectors/src/internal/find.test.ts
+++ b/packages/selectors/src/internal/find.test.ts
@@ -2,6 +2,8 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 import { findBestMatchesByLocator } from './find.ts';
+import { parseSelectorChain } from './parse.ts';
+import { resolveSelectorChain } from './resolve.ts';
 import { formatRole } from '@agent-device/kernel/snapshot';
 
 function makeNode(ref: string, label?: string, identifier?: string): SnapshotNode {
@@ -28,3 +30,105 @@ test('findBestMatchesByLocator returns all best-scored matches', () => {
   assert.equal(result.matches[0]?.ref, 'e1');
   assert.equal(result.matches[1]?.ref, 'e2');
 });
+
+// ── #3021: the `find role=` locator shares the matcher's kind vocabulary ──
+
+function makeTypedNode(ref: string, type: string): SnapshotNode {
+  return {
+    index: Number(ref.replace('e', '')) || 0,
+    ref,
+    type,
+    kind: formatRole(type),
+    rect: { x: 0, y: 0, width: 100, height: 20 },
+  };
+}
+
+function roleMatches(query: string, types: string[]) {
+  const nodes = types.map((type, idx) => makeTypedNode(`e${idx + 1}`, type));
+  return findBestMatchesByLocator(nodes, 'role', query);
+}
+
+test('find role= scores the coarse kind vocabulary exactly', () => {
+  // Forward direction: the kind a snapshot publishes for the node.
+  const text = roleMatches('text', ['android.widget.TextView', 'XCUIElementTypeStaticText']);
+  assert.equal(text.score, 2);
+  assert.deepEqual(
+    text.matches.map((node) => node.ref),
+    ['e1', 'e2'],
+  );
+});
+
+test('find role= still scores legacy leaf spellings exactly during the window', () => {
+  // Compatibility direction: `textview` was the old exact leaf for both class
+  // spellings; the kind is context-coarse (`text` vs `text-view`), and the
+  // window covers both.
+  const textView = roleMatches('textview', ['android.widget.TextView', 'XCUIElementTypeTextView']);
+  assert.equal(textView.score, 2);
+  assert.deepEqual(
+    textView.matches.map((node) => node.ref),
+    ['e1', 'e2'],
+  );
+  const editText = roleMatches('edittext', ['android.widget.EditText']);
+  assert.equal(editText.score, 2);
+});
+
+test('find role= keeps the historical substring score for legacy prefixes', () => {
+  // Before #3021 the locator substring-matched the leaf (`statictext`.includes
+  // ('static')); the alias window must keep that ranking, at score 1, not
+  // promote it to an exact hit.
+  const partial = roleMatches('static', ['XCUIElementTypeStaticText']);
+  assert.equal(partial.score, 1);
+  assert.equal(partial.matches[0]?.ref, 'e1');
+});
+
+test('find role= refuses sibling vocabulary words with no kind or alias match', () => {
+  // Nearest-negative: a kind one dash away and an unrelated kind score 0.
+  assert.equal(roleMatches('text-field', ['XCUIElementTypeStaticText']).score, 0);
+  assert.equal(roleMatches('switch', ['XCUIElementTypeStaticText']).score, 0);
+});
+
+test('find role= does not widen a legacy leaf onto kind siblings that never carried it', () => {
+  // The node-scoped window at the locator: `linearlayout` and `framelayout`
+  // share the coarse kind `group`, but the legacy leaf was the EXACT class
+  // leaf, and widening it onto the kind's other members would silently change
+  // what a released `find role linearlayout` click targets.
+  const both = roleMatches('linearlayout', [
+    'android.widget.LinearLayout',
+    'android.widget.FrameLayout',
+  ]);
+  assert.equal(both.score, 2);
+  assert.deepEqual(
+    both.matches.map((node) => node.ref),
+    ['e1'],
+  );
+});
+
+test('find role= and the role= selector term agree on every kind, alias, and negative', () => {
+  // Locator/matcher parity is the issue's both-paths-reachable proof: the same
+  // (query, type) pairs resolve through `resolveSelectorChain` exactly where
+  // the locator scored them exactly 2.
+  const cases: readonly [string, string][] = [
+    ['text', 'XCUIElementTypeStaticText'],
+    ['statictext', 'XCUIElementTypeStaticText'],
+    ['textview', 'android.widget.TextView'],
+    ['text-field', 'android.widget.EditText'],
+    ['edittext', 'android.widget.EditText'],
+    ['button', 'XCUIElementTypeButton'],
+    ['imagebutton', 'XCUIElementTypeOther'], // kind of Other is `other`; must NOT match
+    ['text-field', 'XCUIElementTypeStaticText'], // sibling kind: must NOT match
+  ];
+  for (const [query, type] of cases) {
+    const nodes = [makeTypedNode('e1', type)];
+    const locatorScore = findBestMatchesByLocator(nodes, 'role', query).score;
+    const chain = parseSelectorChain(`role=${query}`);
+    const resolved = resolveSelectorChain(nodes, chain, {
+      platform: 'android',
+      requireUnique: true,
+    });
+    assert.equal(
+      Boolean(resolved),
+      locatorScore === 2,
+      `query "${query}" against type "${type}" diverged: locator score ${locatorScore}, selector ${resolved ? 'matched' : 'missed'}`,
+    );
+  }
+});
diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index 31352ffa76..4b96c2fd37 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -1,4 +1,4 @@
-import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import { roleSpellingsOfNode, type SnapshotNode } from '@agent-device/kernel/snapshot';
 import { AppError } from '@agent-device/kernel/errors';
 import { tryParseSelectorChain } from './parse.ts';
 
@@ -95,7 +95,7 @@ export function findBestMatchesByLocator(
 function matchNode(node: SnapshotNode, locator: FindLocator, query: string): number {
   switch (locator) {
     case 'role':
-      return matchRole(node.type, query);
+      return matchRole(node, query);
     case 'label':
       return matchText(node.label, query);
     case 'value':
@@ -121,11 +121,14 @@ function matchText(value: string | undefined, query: string): number {
   return 0;
 }
 
-function matchRole(value: string | undefined, query: string): number {
-  const normalized = normalizeRole(value ?? '');
-  if (!normalized) return 0;
-  if (normalized === query) return 2;
-  if (normalized.includes(query)) return 1;
+function matchRole(node: SnapshotNode, query: string): number {
+  // The kernel's one role-spelling reader (#3021): the node's canonical `kind`
+  // first, then its windowed legacy leaf. Exact-vs-substring scoring is the
+  // historical one, so `find role=static` keeps ranking exactly as it did
+  // before the kind vocabulary arrived.
+  const spellings = roleSpellingsOfNode(node);
+  if (spellings.includes(query)) return 2;
+  if (spellings.some((spelling) => spelling.includes(query))) return 1;
   return 0;
 }
 
@@ -133,14 +136,6 @@ export function normalizeText(value: string): string {
   return value.trim().toLowerCase().replaceAll(/\s+/g, ' ');
 }
 
-function normalizeRole(value: string): string {
-  let normalized = value.trim();
-  if (!normalized) return '';
-  const lastSegment = normalized.split('.').pop() ?? normalized;
-  normalized = lastSegment.replaceAll(/XCUIElementType/gi, '').toLowerCase();
-  return normalized;
-}
-
 export type ParsedFindArgs = {
   locator: FindLocator;
   query: string;
diff --git a/packages/selectors/src/internal/match.test.ts b/packages/selectors/src/internal/match.test.ts
index 2eb1537a9d..c9cf5ef8c1 100644
--- a/packages/selectors/src/internal/match.test.ts
+++ b/packages/selectors/src/internal/match.test.ts
@@ -71,6 +71,121 @@ test('role selector normalization matches Android class names by leaf type', ()
   assert.equal(resolved.node.ref, 'a1');
 });
 
+// ── #3021: `role=` shares `kind`'s vocabulary, with a legacy-alias window ──
+
+// One tree covering the three vocabulary decisions at once: the coarse kind
+// `kind` publishes, the legacy leaf still windowed for it, and a sibling
+// vocabulary word that must match NOTHING here.
+const ROLE_VOCABULARY_NODES: SnapshotState['nodes'] = [
+  {
+    ref: 'text1',
+    index: 0,
+    type: 'XCUIElementTypeStaticText',
+    kind: formatRole('XCUIElementTypeStaticText'),
+    label: 'Total',
+    rect: { x: 0, y: 0, width: 120, height: 20 },
+    hittable: true,
+  },
+  {
+    ref: 'field1',
+    index: 1,
+    type: 'android.widget.EditText',
+    kind: formatRole('android.widget.EditText'),
+    label: 'Email',
+    rect: { x: 0, y: 30, width: 120, height: 44 },
+    hittable: true,
+  },
+  {
+    ref: 'button1',
+    index: 2,
+    type: 'XCUIElementTypeButton',
+    kind: formatRole('XCUIElementTypeButton'),
+    label: 'Continue',
+    rect: { x: 0, y: 90, width: 120, height: 44 },
+    hittable: true,
+  },
+];
+
+function resolveRole(role: string, platform: 'ios' | 'android' = 'ios') {
+  const chain = parseSelectorChain(`role=${role}`);
+  return resolveSelectorChain(ROLE_VOCABULARY_NODES, chain, {
+    platform,
+    requireRect: true,
+    requireUnique: true,
+  });
+}
+
+test('role= matches the coarse kind vocabulary: kind=text and kind=text-field resolve', () => {
+  // The migration's forward direction: these DID NOT match before #3021,
+  // because the matcher saw the raw leaf (`statictext`, `edittext`).
+  assert.equal(resolveRole('text')?.node.ref, 'text1');
+  assert.equal(resolveRole('text-field', 'android')?.node.ref, 'field1');
+});
+
+test('role= keeps matching legacy leaf spellings during the alias window', () => {
+  // The compatibility direction: released scripts write these; they must keep
+  // resolving to the same nodes they resolved to before #3021.
+  assert.equal(resolveRole('statictext')?.node.ref, 'text1');
+  assert.equal(resolveRole('edittext', 'android')?.node.ref, 'field1');
+  assert.equal(resolveRole('button')?.node.ref, 'button1');
+  // The window is the node's OWN old spelling: `textfield` was the old leaf of
+  // the iOS `TextField` class, never of `EditText`, and must not widen onto it.
+  assert.equal(resolveRole('textfield', 'android'), null);
+});
+
+test('role= refuses a sibling vocabulary word that matches no kind or windowed alias', () => {
+  // Nearest-negatives inside the same vocabulary: `text-view` is one dash from
+  // `text`, and `switch`/`searchfield` are vocabulary entries (a kind and a
+  // leaf windowed under kind `search`) that no node here carries.
+  assert.equal(resolveRole('text-view'), null);
+  assert.equal(resolveRole('switch'), null);
+  assert.equal(resolveRole('searchfield'), null);
+});
+
+test('role= does not widen a legacy leaf onto kind siblings that never carried it', () => {
+  // The window is the node's OWN old spelling. `linearlayout` and
+  // `framelayout` share the coarse kind `group`; matching the leaf may not
+  // pull in the kind's other members, or every released `role=linearlayout`
+  // script would silently start hitting FrameLayout rows.
+  const layoutNodes: SnapshotState['nodes'] = [
+    'android.widget.LinearLayout',
+    'android.widget.FrameLayout',
+  ].map((type, idx) => ({
+    ref: `row${idx + 1}`,
+    index: idx,
+    type,
+    kind: formatRole(type),
+    rect: { x: 0, y: idx * 50, width: 300, height: 48 },
+    hittable: true,
+  }));
+  const chain = parseSelectorChain('role=linearlayout');
+  const resolved = resolveSelectorChain(layoutNodes, chain, {
+    platform: 'android',
+    requireRect: true,
+    requireUnique: true,
+  });
+  assert.ok(resolved);
+  assert.equal(resolved.node.ref, 'row1');
+});
+
+test('role= agrees with the published kind for every node it matches (#3021 parity)', () => {
+  // The architecture pin: for every node in the tree, matching by that node's
+  // own published `kind` must resolve to exactly that node. This is what makes
+  // the selector/kind divergence that #3021 closes impossible to reintroduce
+  // silently for any vocabulary entry.
+  for (const node of ROLE_VOCABULARY_NODES) {
+    assert.ok(node.kind, 'fixture nodes carry a published kind');
+    const chain = parseSelectorChain(`role=${JSON.stringify(node.kind)}`);
+    const resolved = resolveSelectorChain(ROLE_VOCABULARY_NODES, chain, {
+      platform: 'ios',
+      requireRect: true,
+      requireUnique: false,
+    });
+    assert.ok(resolved, `role=${node.kind} resolved nothing`);
+    assert.equal(resolved.node.ref, node.ref, `role=${node.kind} resolved the wrong node`);
+  }
+});
+
 test('focused selector matches snapshot focus state', () => {
   const tvNodes: SnapshotState['nodes'] = [
     {
diff --git a/packages/selectors/src/internal/match.ts b/packages/selectors/src/internal/match.ts
index e3d8e1cc21..1b0fcc41d8 100644
--- a/packages/selectors/src/internal/match.ts
+++ b/packages/selectors/src/internal/match.ts
@@ -1,7 +1,7 @@
 import type { Platform, PublicPlatform } from '@agent-device/kernel/device';
-import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import { roleSpellingsOfNode, type SnapshotNode } from '@agent-device/kernel/snapshot';
 import { isNodeEditable, isNodeVisible } from './node.ts';
-import { extractNodeText, normalizeType } from '@agent-device/contracts/snapshot';
+import { extractNodeText } from '@agent-device/contracts/snapshot';
 import { normalizeText } from './find.ts';
 import type { Selector, SelectorTerm } from './parse.ts';
 
@@ -22,7 +22,7 @@ function matchesTerm(
     case 'id':
       return textEquals(node.identifier, String(term.value));
     case 'role':
-      return textEquals(normalizeType(node.type ?? ''), String(term.value));
+      return matchesRoleKind(node, String(term.value));
     case 'label':
       return textEquals(node.label, String(term.value));
     case 'value':
@@ -55,3 +55,16 @@ function matchesTerm(
 function textEquals(value: string | undefined, query: string): boolean {
   return normalizeText(value ?? '') === normalizeText(query);
 }
+
+/**
+ * `role=` matches the canonical `kind` vocabulary (#3021): a term value equals
+ * the node's role kind, or one of the legacy leaf spellings still windowed for
+ * that node. The kind and the window both come from the kernel's role
+ * vocabulary — the same authority `attachRefs` uses to publish `kind` — so the
+ * selector, the `find role=` locator, and snapshot output cannot disagree
+ * about a node's role again.
+ */
+function matchesRoleKind(node: SnapshotNode, query: string): boolean {
+  const normalizedQuery = normalizeText(query);
+  return roleSpellingsOfNode(node).some((spelling) => normalizeText(spelling) === normalizedQuery);
+}
diff --git a/packages/selectors/src/internal/replay-role-vocabulary.test.ts b/packages/selectors/src/internal/replay-role-vocabulary.test.ts
new file mode 100644
index 0000000000..69b2194693
--- /dev/null
+++ b/packages/selectors/src/internal/replay-role-vocabulary.test.ts
@@ -0,0 +1,57 @@
+// #3021 at the replay seam: `role=` vocabulary is resolved by the same
+// `resolveRecordedTarget` path `replay` dispatches recorded targets through, so
+// the alias window and the kind vocabulary are proven where released scripts
+// actually run — not only at the matcher unit. ADR 0012 is untouched: nothing
+// here rewrites a recorded expression; a miss still reports `no-match`.
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { attachRefs, type RawSnapshotNode, type SnapshotNode } from '@agent-device/kernel/snapshot';
+import { resolveRecordedTarget, type ReplayRecordedTargetPolicy } from './replay.ts';
+
+const POLICY: ReplayRecordedTargetPolicy = {
+  platform: 'ios',
+  requireRect: true,
+  allowDisambiguation: false,
+};
+
+// The production construction path, so the tree carries published `kind` the
+// way every captured session tree does.
+const rawNodes: RawSnapshotNode[] = [
+  {
+    index: 0,
+    type: 'XCUIElementTypeStaticText',
+    label: 'Total',
+    rect: { x: 0, y: 0, width: 120, height: 20 },
+  },
+  {
+    index: 1,
+    type: 'XCUIElementTypeButton',
+    label: 'Continue',
+    rect: { x: 0, y: 30, width: 120, height: 44 },
+  },
+];
+const nodes: SnapshotNode[] = attachRefs(rawNodes);
+
+test('recorded legacy role= scripts keep resolving through the replay seam', () => {
+  // `role=statictext` is the spelling released .ad scripts carry; the window
+  // keeps them replaying against the same node they recorded against.
+  const legacy = resolveRecordedTarget('role="statictext" label="Total"', nodes, POLICY);
+  assert.equal(legacy.kind, 'resolved');
+  if (legacy.kind === 'resolved') assert.equal(legacy.winner.ref, 'e1');
+});
+
+test('coarse kind selectors resolve through the replay seam too', () => {
+  // The forward direction on the SAME seam a repaired/healed script would use.
+  const coarse = resolveRecordedTarget('role="text" label="Total"', nodes, POLICY);
+  assert.equal(coarse.kind, 'resolved');
+  if (coarse.kind === 'resolved') assert.equal(coarse.winner.ref, 'e1');
+});
+
+test('a sibling kind stays a real miss at the replay seam — no silent widening', () => {
+  // Nearest-negative: the divergence machinery downstream keys on
+  // `reason: 'no-match'`; widening the vocabulary to a dash-sibling kind would
+  // resolve this to the wrong node instead of diverging honestly.
+  const miss = resolveRecordedTarget('role="text-field"', nodes, POLICY);
+  assert.equal(miss.kind, 'unresolved');
+  if (miss.kind === 'unresolved') assert.equal(miss.reason, 'no-match');
+});
diff --git a/src/commands/interaction/metadata.ts b/src/commands/interaction/metadata.ts
index 62a5b4ff26..54c607af99 100644
--- a/src/commands/interaction/metadata.ts
+++ b/src/commands/interaction/metadata.ts
@@ -73,7 +73,7 @@ const interactionCommandDescriptions = {
     'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
   get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
   is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
-  find: 'Find by text/label/value/role/id and run action',
+  find: 'Find by text/label/value/role/id and run action. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window.',
   gesture:
     'Perform a structured pan, fling, swipe, pinch, rotate, transform, or drag gesture. Select the gesture kind, then provide only the inputs that apply to that kind.',
 } as const;
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 076f57e8a4..0d068b15d4 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -510,7 +510,7 @@ Use `agent-device/remote-config` for profile loading and path resolution, `agent
 
 ## Selector helpers
 
-Use `agent-device/selectors` when a remote daemon or bridge needs to parse and match selector expressions without deep-importing daemon internals. Matching is platform-aware because role normalization and editability checks differ by backend.
+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.
 
 `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.
 
diff --git a/website/docs/docs/selectors.md b/website/docs/docs/selectors.md
index 1c148d66c6..4d0574b139 100644
--- a/website/docs/docs/selectors.md
+++ b/website/docs/docs/selectors.md
@@ -18,6 +18,7 @@ agent-device find id "com.example:id/login" click
 
 Tips:
 
+- `find role <value>` and the `role=` selector term match the platform-neutral `kind` vocabulary that `snapshot --json` publishes (`button`, `text`, `text-field`, `switch`, …). Older leaf spellings (`statictext`, `edittext`, `textview`) still match during a deprecation window, each on the nodes that actually carried that class.
 - Use `find ... wait <timeoutMs>` to wait for UI to appear.
 - Combine with scoped snapshots using `snapshot -s "<label>"` for speed.
 - [Android] If a matched node is not hittable, agent-device will click/focus the nearest hittable ancestor.
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index baa3c7b3fb..6cb5ab0362 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -106,11 +106,14 @@ Every node in `snapshot --json` output carries `kind`, next to `type` when the p
 On iOS, `role` (when present) is the native AX class (`UIButton`) — a different fact carried only
 on iOS nodes; `kind` is the cross-platform one, present on every node on every platform.
 
-`role=` selectors (and `find role=...`) do not share `kind`'s vocabulary yet: they match a raw,
-leaf-only normalization of `type` (`statictext`, `edittext`), not `kind` values like `text` or
-`text-field`. Reconciling the two is tracked separately
-([#3021](https://github.com/callstack/agent-device/issues/3021)) because it would change matching
-for selectors already in use.
+`role=` selectors (and `find role=...`) match `kind`'s vocabulary: `role=text` and `role=text-field`
+match exactly what the snapshot shows in brackets for that node
+([#3021](https://github.com/callstack/agent-device/issues/3021)). Spellings from before that
+reconciliation — the raw leaf classes `role=statictext`, `role=edittext`, `role=textview`,
+`role=searchfield`, and the rest of the leaf vocabulary — stay accepted during a deprecation window,
+each on the very nodes that carried that class (so `role=linearlayout` still never matches a
+`FrameLayout` row the way a shared `group` alias would). Prefer the `kind` spelling in new
+selectors; the leaf aliases are deprecated and will be removed in a future breaking release.
 
 ## iOS capture behavior
 

From 7d9c90f20f76a0892a641ddcad06a5c7c67de13d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 17:41:40 +0200
Subject: [PATCH 2/7] fix(selectors): keep find role= substring scoring on the
 leaf segment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adversarial review of the #3021 window: substring scoring against the whole
spellings let an unrecognized dotted class (whose kind keeps its package
path) match queries the retired locator refused — find role=fenix scored
org.mozilla.fenix.ReaderView. Substring scoring now reads only the last
'.'-separated segment, the retired locator's leaf; exact-kind scoring is
unchanged. Pins the AX-stripped locator promotion as the intended term/
locator parity it is (role=link was always exact on an AXLink node).
---
 packages/selectors/src/internal/find.test.ts | 25 ++++++++++++++++++++
 packages/selectors/src/internal/find.ts      | 24 +++++++++++++++----
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/packages/selectors/src/internal/find.test.ts b/packages/selectors/src/internal/find.test.ts
index 1bd376cb9f..a368bc5743 100644
--- a/packages/selectors/src/internal/find.test.ts
+++ b/packages/selectors/src/internal/find.test.ts
@@ -81,6 +81,31 @@ test('find role= keeps the historical substring score for legacy prefixes', () =
   assert.equal(partial.matches[0]?.ref, 'e1');
 });
 
+test('find role= substring-scores the leaf segment, never a dotted kind package path', () => {
+  // An unrecognized custom class keeps its full dotted lowercase as its kind.
+  // The retired locator substring-matched the LAST segment only, so a released
+  // `find role=fenix` refused `org.mozilla.fenix.ReaderView`; substringing the
+  // whole kind would silently pull such nodes into the best set. Exact-kind
+  // scoring still answers the full spelling when the query names it.
+  const type = 'org.mozilla.fenix.ReaderView';
+  assert.equal(roleMatches('fenix', [type]).score, 0);
+  assert.equal(roleMatches('readerview', [type]).score, 2); // windowed legacy leaf
+  assert.equal(roleMatches(type.toLowerCase(), [type]).score, 2); // the exact kind
+});
+
+test('find role= reaches AX-stripped queries through the exact window alias', () => {
+  // Pinned parity decision (#3021 finding): the retired selector TERM stripped
+  // a leading `AX` (`contracts` normalizeType) while the retired LOCATOR did
+  // not, so `find role link click` on a macOS-helper `AXLink` node scored 1
+  // there while `role=link` matched exactly. Adopting one shared authority
+  // promotes the locator's AX-stripped query to the exact score — the locator
+  // and the term cannot disagree about a node's role anymore.
+  const axNode = roleMatches('link', ['AXLink']);
+  assert.equal(axNode.score, 2);
+  // The prefix-kept spelling keeps its historical exact score.
+  assert.equal(roleMatches('axlink', ['AXLink']).score, 2);
+});
+
 test('find role= refuses sibling vocabulary words with no kind or alias match', () => {
   // Nearest-negative: a kind one dash away and an unrelated kind score 0.
   assert.equal(roleMatches('text-field', ['XCUIElementTypeStaticText']).score, 0);
diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index 4b96c2fd37..191057e8a8 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -123,15 +123,31 @@ function matchText(value: string | undefined, query: string): number {
 
 function matchRole(node: SnapshotNode, query: string): number {
   // The kernel's one role-spelling reader (#3021): the node's canonical `kind`
-  // first, then its windowed legacy leaf. Exact-vs-substring scoring is the
-  // historical one, so `find role=static` keeps ranking exactly as it did
-  // before the kind vocabulary arrived.
+  // first, then its windowed legacy leaf. Exact scoring is against the whole
+  // spellings; substring scoring stays on the leaf segment because the retired
+  // locator substring-matched a last-`.`-segment leaf, and an unrecognized
+  // dotted class keeps its package path in its `kind` — substringing the full
+  // kind would let `find role=fenix` score `org.mozilla.fenix.ReaderView`
+  // where the released query refused it.
   const spellings = roleSpellingsOfNode(node);
   if (spellings.includes(query)) return 2;
-  if (spellings.some((spelling) => spelling.includes(query))) return 1;
+  if (spellings.some((spelling) => roleLeafSegment(spelling).includes(query))) return 1;
   return 0;
 }
 
+/**
+ * The substring-scoring view of one role spelling: its last `.`-separated
+ * segment, matching the retired locator's leaf. An AX-stripped query (`link`
+ * against an `AXLink` node) reaches the exact score through the windowed
+ * alias, not through substring — the retired selector TERM already matched
+ * that spelling exactly (`contracts` `normalizeType` stripped the prefix), so
+ * promoting it here is the locator/term parity #3021 requires.
+ */
+function roleLeafSegment(spelling: string): string {
+  const lastDot = spelling.lastIndexOf('.');
+  return lastDot === -1 ? spelling : spelling.slice(lastDot + 1);
+}
+
 export function normalizeText(value: string): string {
   return value.trim().toLowerCase().replaceAll(/\s+/g, ' ');
 }

From 0bf1a384146ae6f0b4006800f39d5ff930456b24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 18:17:54 +0200
Subject: [PATCH 3/7] fix(selectors): exact-score role locators on
 term-normalized spellings

The selector term compared normalizeText on both sides, so role="some
widget" always matched the class 'Some  Widget' while the find locator
scored that query 0. #3021 promises one shared authority for both role=
surfaces, so the locator's exact compare now normalizes spellings the same
way; substring scoring stays on the raw retired leaf. Round-2 adversarial
review nit folded into behavior instead of a comment softening.
---
 packages/selectors/src/internal/find.test.ts | 9 +++++++++
 packages/selectors/src/internal/find.ts      | 6 +++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/selectors/src/internal/find.test.ts b/packages/selectors/src/internal/find.test.ts
index a368bc5743..9b86bab44f 100644
--- a/packages/selectors/src/internal/find.test.ts
+++ b/packages/selectors/src/internal/find.test.ts
@@ -106,6 +106,15 @@ test('find role= reaches AX-stripped queries through the exact window alias', ()
   assert.equal(roleMatches('axlink', ['AXLink']).score, 2);
 });
 
+test('find role= exact-scores whitespace-normalized spellings like the term does', () => {
+  // Same parity rule for the term's other normalization step: the selector
+  // term compared `normalizeText` on both sides, so `role="some widget"`
+  // always matched the class `Some  Widget`; the retired locator scored that
+  // query 0. One shared authority means the locator agrees — exact score, not
+  // a substring rescue.
+  assert.equal(roleMatches('some widget', ['Some  Widget']).score, 2);
+});
+
 test('find role= refuses sibling vocabulary words with no kind or alias match', () => {
   // Nearest-negative: a kind one dash away and an unrelated kind score 0.
   assert.equal(roleMatches('text-field', ['XCUIElementTypeStaticText']).score, 0);
diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index 191057e8a8..4201072ea9 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -130,7 +130,11 @@ function matchRole(node: SnapshotNode, query: string): number {
   // kind would let `find role=fenix` score `org.mozilla.fenix.ReaderView`
   // where the released query refused it.
   const spellings = roleSpellingsOfNode(node);
-  if (spellings.includes(query)) return 2;
+  // The query arrives `normalizeText`-ed, so the exact compare normalizes the
+  // spellings the same way the selector term's `textEquals` does — that is the
+  // locator/term agreement #3021 demands for whitespace-bearing class names.
+  // Substring scoring stays on the raw spelling (the retired locator's leaf).
+  if (spellings.some((spelling) => normalizeText(spelling) === query)) return 2;
   if (spellings.some((spelling) => roleLeafSegment(spelling).includes(query))) return 1;
   return 0;
 }

From 37a4c73b47f22e56da6cb06efc7c2928e50653d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 18:53:54 +0200
Subject: [PATCH 4/7] docs(selectors): disclose the alias window's
 kind-adjacent matches precisely
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 packages/kernel/src/snapshot-role-kind.test.ts | 12 ++++++++++++
 packages/selectors/src/internal/find.ts        | 15 ++++++++++-----
 website/docs/docs/client-api.md                |  2 +-
 website/docs/docs/snapshots.md                 |  5 +++--
 4 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/packages/kernel/src/snapshot-role-kind.test.ts b/packages/kernel/src/snapshot-role-kind.test.ts
index 8b48407a02..31d782e424 100644
--- a/packages/kernel/src/snapshot-role-kind.test.ts
+++ b/packages/kernel/src/snapshot-role-kind.test.ts
@@ -14,6 +14,18 @@ test('roleSpellingsOfNode leads with the kind the capture published', () => {
   assert.deepEqual(roleSpellingsOfNode(node), ['text', 'statictext']);
 });
 
+test('roleSpellingsOfNode reads a published kind even when it diverges from the type', () => {
+  // Distinguishes kind-reading from type-only matching: a node whose `kind`
+  // is NOT what formatRole(type) would derive must lead with the published
+  // kind, with the type-derived spellings riding only as the window. A
+  // regression to deriving the canonical spelling from `type` fails here even
+  // though the alias rides along in both directions.
+  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeButton', kind: 'text' }), [
+    'text',
+    'button',
+  ]);
+});
+
 test('roleSpellingsOfNode reuses formatRole for a node that predates kind publication', () => {
   // Fixtures that never route through `attachRefs` carry no `kind`; the reader
   // computes it with the SAME function that publishes it, not a second
diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index 4201072ea9..da3ef5b860 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -141,11 +141,16 @@ function matchRole(node: SnapshotNode, query: string): number {
 
 /**
  * The substring-scoring view of one role spelling: its last `.`-separated
- * segment, matching the retired locator's leaf. An AX-stripped query (`link`
- * against an `AXLink` node) reaches the exact score through the windowed
- * alias, not through substring — the retired selector TERM already matched
- * that spelling exactly (`contracts` `normalizeType` stripped the prefix), so
- * promoting it here is the locator/term parity #3021 requires.
+ * segment. This is deliberately the RETIRED LOCATOR's leaf (`split('.').pop()`
+ * only), not the kernel's retired-term spelling — the term also reduced a
+ * trailing `/` segment, and mirroring that here would drop substring hits the
+ * released locator kept (query `y/z` still scores 1 against kind `x.y/z`
+ * today). The term's `/`-reduced spelling rides as the windowed exact alias
+ * instead, so term/locator agreement comes from the exact side, and each
+ * surface's historical substring meaning is preserved. An AX-stripped query
+ * (`link` against an `AXLink` node) likewise reaches the exact score through
+ * the windowed alias, not through substring — the retired term already matched
+ * that spelling exactly, so promoting it here is the parity #3021 requires.
  */
 function roleLeafSegment(spelling: string): string {
   const lastDot = spelling.lastIndexOf('.');
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 0d068b15d4..6261a4949b 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -510,7 +510,7 @@ Use `agent-device/remote-config` for profile loading and path resolution, `agent
 
 ## Selector helpers
 
-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.
+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.
 
 `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.
 
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index 6cb5ab0362..33585f0e90 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -106,8 +106,9 @@ Every node in `snapshot --json` output carries `kind`, next to `type` when the p
 On iOS, `role` (when present) is the native AX class (`UIButton`) — a different fact carried only
 on iOS nodes; `kind` is the cross-platform one, present on every node on every platform.
 
-`role=` selectors (and `find role=...`) match `kind`'s vocabulary: `role=text` and `role=text-field`
-match exactly what the snapshot shows in brackets for that node
+`role=` selectors (and `find role=...`) match `kind`'s vocabulary: a node whose `kind` is `text`
+or `text-field` always matches `role=text` / `role=text-field` — the bracketed word a snapshot
+shows for that node
 ([#3021](https://github.com/callstack/agent-device/issues/3021)). Spellings from before that
 reconciliation — the raw leaf classes `role=statictext`, `role=edittext`, `role=textview`,
 `role=searchfield`, and the rest of the leaf vocabulary — stay accepted during a deprecation window,

From 304ba43d497cdcaeefa705a089c153110bb3e28f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 19:41:31 +0200
Subject: [PATCH 5/7] docs(kernel): name the chain-builder precondition for
 closing the role window
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Final adversarial nit: the sunset clause on the retired role spelling named
an exit criterion that is not self-sufficient — buildSelectorChainForNode
still emits the leaf spelling into recorded chains, so the window must
outlive the chain builder's emission, not the matcher's need.
---
 packages/kernel/src/snapshot.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index 1ec3e2a66c..26f9b96b15 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -514,7 +514,11 @@ function legacyRoleAliasesForNode(
  * canonical vocabulary stays `formatRole` alone. The retired matcher consumers
  * (the selector term and `find`'s deleted `normalizeRole`) are gone; this
  * window is their spelling's only remaining reader, and when the window closes
- * this function leaves with it.
+ * this function leaves with it — and only once the chain builder in
+ * `@agent-device/selectors` stops emitting leaf spellings into recorded
+ * chains: `buildSelectorChainForNode` still writes the retired spelling into
+ * every recorded `role=` chain, so closing the window first would break
+ * replay of freshly recorded scripts on the next release.
  */
 function legacyRoleSpellingOfType(type: string): string {
   let normalized = type

From dd8b85088cae1228c6897e21d47291493b104ef7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 20:18:30 +0200
Subject: [PATCH 6/7] refactor(selectors): window role= through contracts'
 normalizeType owner, leave kernel untouched
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR review: the kernel's legacyRoleSpellingOfType was a verbatim copy of
contracts' normalizeType, whose live callers include the chain recorder —
a drift there would silently split the window from what recorded scripts
carry. One owner for the legacy spelling: the window now lives in
@agent-device/selectors internals (node.ts roleSpellingsOfNode) as
[kind, normalizeType(type)] when they differ, read by both the selector
term and the find locator. contracts/snapshot is already a selectors
dependency and is the function buildSelectorChainForNode records chains
through, so window and recorded spelling move together by construction.
The kernel keeps only what it already published (kind, formatRole): the
formatRole leaf refactor, the new exports, and the kernel test all leave
with the copy; the vocabulary suite moves to node.test.ts beside the
helper, including a pin that the window entry equals normalizeType for
every probed backend spelling.
---
 .../kernel/src/snapshot-role-kind.test.ts     | 120 --------------
 packages/kernel/src/snapshot.ts               | 125 ++------------
 packages/selectors/src/internal/find.ts       |  17 +-
 packages/selectors/src/internal/match.ts      |  14 +-
 packages/selectors/src/internal/node.test.ts  | 155 ++++++++++++++++++
 packages/selectors/src/internal/node.ts       |  32 +++-
 6 files changed, 218 insertions(+), 245 deletions(-)
 delete mode 100644 packages/kernel/src/snapshot-role-kind.test.ts
 create mode 100644 packages/selectors/src/internal/node.test.ts

diff --git a/packages/kernel/src/snapshot-role-kind.test.ts b/packages/kernel/src/snapshot-role-kind.test.ts
deleted file mode 100644
index 31d782e424..0000000000
--- a/packages/kernel/src/snapshot-role-kind.test.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-// #3021: the kernel-owned `role=` vocabulary shared by `kind`, the `role=`
-// selector term, and the `find role=` locator. Everything is pinned through
-// `roleSpellingsOfNode` — the ONE public reader both selector surfaces consume.
-import assert from 'node:assert/strict';
-import { test } from 'vitest';
-import { attachRefs, formatRole, roleSpellingsOfNode } from './snapshot.ts';
-
-test('roleSpellingsOfNode leads with the kind the capture published', () => {
-  const [node] = attachRefs([{ index: 0, type: 'XCUIElementTypeStaticText' }]);
-  assert.ok(node);
-  assert.equal(node.kind, 'text');
-  // A production node built by `attachRefs` matches on its published `kind`
-  // first; the documented meaning of `role=` is that vocabulary.
-  assert.deepEqual(roleSpellingsOfNode(node), ['text', 'statictext']);
-});
-
-test('roleSpellingsOfNode reads a published kind even when it diverges from the type', () => {
-  // Distinguishes kind-reading from type-only matching: a node whose `kind`
-  // is NOT what formatRole(type) would derive must lead with the published
-  // kind, with the type-derived spellings riding only as the window. A
-  // regression to deriving the canonical spelling from `type` fails here even
-  // though the alias rides along in both directions.
-  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeButton', kind: 'text' }), [
-    'text',
-    'button',
-  ]);
-});
-
-test('roleSpellingsOfNode reuses formatRole for a node that predates kind publication', () => {
-  // Fixtures that never route through `attachRefs` carry no `kind`; the reader
-  // computes it with the SAME function that publishes it, not a second
-  // normalization.
-  assert.equal(roleSpellingsOfNode({ type: 'android.widget.EditText' })[0], 'text-field');
-  assert.equal(roleSpellingsOfNode({})[0], formatRole('Element'));
-});
-
-test('a renamed leaf stays windowed on the node that carries it', () => {
-  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeStaticText' }), [
-    'text',
-    'statictext',
-  ]);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.EditText' }), [
-    'text-field',
-    'edittext',
-  ]);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.FrameLayout' }), [
-    'group',
-    'framelayout',
-  ]);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeSearchField' }), [
-    'search',
-    'searchfield',
-  ]);
-});
-
-test('the window is node-scoped: sibling leaves of one coarse kind never alias each other', () => {
-  // The nearest-negative that makes the alias window a window and not a
-  // widening: `group` renames many leaves (`framelayout`, `linearlayout`,
-  // `viewgroup`, …), and #3021 must not make `role=linearlayout` match a
-  // FrameLayout node. Each node carries only ITS OWN old spelling.
-  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.LinearLayout' }), [
-    'group',
-    'linearlayout',
-  ]);
-  assert.ok(!roleSpellingsOfNode({ type: 'android.widget.FrameLayout' }).includes('linearlayout'));
-});
-
-test('the context-coarse `textview` leaf stays windowed on both spellings that emitted it', () => {
-  // `formatRole` answers `text-view` for the desktop/iOS spelling and `text`
-  // for the Android class; both nodes carried the matchable leaf `textview`.
-  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeTextView' }), [
-    'text-view',
-    'textview',
-  ]);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.TextView' }), ['text', 'textview']);
-});
-
-test('AX-prefixed class types carry the AX-stripped spelling the old normalizer matched', () => {
-  // The macOS helper's `subrole ?? role` fallback emits raw `AX…` classes whose
-  // canonical kind keeps the prefix while the retired matcher accepted the
-  // AX-stripped spelling; renumbered leaves like `AXStaticText` window to the
-  // leaf instead.
-  assert.deepEqual(roleSpellingsOfNode({ type: 'AXFloatingWindow' }), [
-    'axfloatingwindow',
-    'floatingwindow',
-  ]);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'AXUnknown' }), ['axunknown', 'unknown']);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'AXStaticText' }), ['axstatictext', 'statictext']);
-});
-
-test('the window replays the retired normalizer for arbitrary custom class names', () => {
-  // The retired spelling took the last `.`-separated segment of any class, so
-  // a released script could name a custom view class; the window must not
-  // silently drop spellings formatRole's own leaf step would not produce.
-  // (formatRole keeps the full dotted spelling as the kind for a non-Android
-  // class it does not recognize; the old last-segment leaf windows beside it.)
-  assert.deepEqual(roleSpellingsOfNode({ type: 'io.foo.app.MyButton' }), [
-    'io.foo.app.mybutton',
-    'mybutton',
-  ]);
-});
-
-test('a kind that equals its leaf carries no alias of its own', () => {
-  // The nearest-negative for the window itself: `button` and unmapped leaves
-  // like `gridview` are both the leaf and the kind, so the window adds nothing
-  // and no vocabulary entry leaks in.
-  assert.deepEqual(roleSpellingsOfNode({ type: 'XCUIElementTypeButton' }), ['button']);
-  assert.deepEqual(roleSpellingsOfNode({ type: 'android.widget.GridView' }), ['gridview']);
-});
-
-test('formatRole keeps its published vocabulary across the leaf-factorization', () => {
-  // The #3021 refactor moved formatRole's leaf step into a shared helper; the
-  // coarse answers every backend depends on must not move.
-  assert.equal(formatRole('XCUIElementTypeStaticText'), 'text');
-  assert.equal(formatRole('android.widget.TextView'), 'text');
-  assert.equal(formatRole('XCUIElementTypeTextView'), 'text-view');
-  assert.equal(formatRole('androidx.recyclerview.widget.RecyclerView'), 'list');
-  assert.equal(formatRole('Button'), 'button');
-  assert.equal(formatRole(''), 'element');
-});
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index 26f9b96b15..6691445f25 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -450,117 +450,26 @@ function lookupRoleLabel(normalized: string): string | undefined {
     : undefined;
 }
 
-function isAndroidRoleClass(type: string): boolean {
-  return (
-    type.includes('.') &&
-    (type.startsWith('android.') || type.startsWith('androidx.') || type.startsWith('com.'))
-  );
-}
-
-/**
- * The leaf normalization {@link formatRole} runs before it consults
- * {@link ROLE_LABELS}: strip `XCUIElementType`, lowercase, and reduce Android
- * class packages to their leaf. Factored out for readability; the `role=`
- * deprecation window below deliberately does NOT share this step — it replays
- * the retired normalizer's spelling, not formatRole's leaf.
- */
-function normalizeRoleLeaf(type: string): string {
+export function formatRole(type: string): string {
+  const raw = type;
   let normalized = type.replaceAll(/XCUIElementType/gi, '').toLowerCase();
-  if (!normalized.includes('.')) {
-    return normalized;
-  }
-  const isAndroidClass = isAndroidRoleClass(type);
-  normalized = normalized
-    .replace(/^android\.widget\./, '')
-    .replace(/^android\.view\./, '')
-    .replace(/^android\.webkit\./, '')
-    .replace(/^androidx\./, '')
-    .replace(/^com\.google\.android\./, '')
-    .replace(/^com\.android\./, '');
-  if (isAndroidClass && normalized.includes('.')) {
-    normalized = normalized.slice(normalized.lastIndexOf('.') + 1);
-  }
-  return normalized;
-}
-
-/**
- * The `role=` deprecation window (#3021): the legacy spellings this node still
- * accepts beside its canonical {@link roleKindOfNode} kind. One entry: the
- * node's retired role spelling — what `role=` compared before #3021 — computed
- * by {@link legacyRoleSpellingOfType} below and dropped when it already equals
- * the canonical kind (the vocabulary-identity case, which needs no window).
- *
- * The window is deliberately NODE-scoped, not a kind→leaves alias table. One
- * coarse kind renames many distinct leaves (`group` covers `framelayout`,
- * `linearlayout`, `viewgroup`, …); a kind-keyed table would make
- * `role=linearlayout` match a `FrameLayout` — silently WIDENING every released
- * script that names a leaf, which is a new breaking change measured against
- * the old matcher rather than a compatibility window. So the leaf stays
- * matchable only on the nodes that actually carried it: the window is exactly
- * the old spelling of THIS node, never a sibling's.
- */
-function legacyRoleAliasesForNode(
-  node: Pick<RawSnapshotNode, 'type'> & { kind?: string },
-): readonly string[] {
-  const alias = legacyRoleSpellingOfType(node.type ?? '');
-  return alias && alias !== roleKindOfNode(node) ? [alias] : [];
-}
-
-/**
- * The ONE owner of the pre-#3021 `role=` spelling: the retired normalizer's
- * exact step — strip `XCUIElementType` and a leading `AX`, lowercase, take the
- * last `.`/`/`-separated segment — kept here so the deprecation window can
- * replay the old meaning of `role=` for the nodes that carry it while the
- * canonical vocabulary stays `formatRole` alone. The retired matcher consumers
- * (the selector term and `find`'s deleted `normalizeRole`) are gone; this
- * window is their spelling's only remaining reader, and when the window closes
- * this function leaves with it — and only once the chain builder in
- * `@agent-device/selectors` stops emitting leaf spellings into recorded
- * chains: `buildSelectorChainForNode` still writes the retired spelling into
- * every recorded `role=` chain, so closing the window first would break
- * replay of freshly recorded scripts on the next release.
- */
-function legacyRoleSpellingOfType(type: string): string {
-  let normalized = type
-    .trim()
-    .replaceAll(/XCUIElementType/gi, '')
-    .replace(/^AX/, '')
-    .toLowerCase();
-  const lastSeparator = Math.max(normalized.lastIndexOf('.'), normalized.lastIndexOf('/'));
-  if (lastSeparator !== -1) {
-    normalized = normalized.slice(lastSeparator + 1);
+  const isAndroidClass =
+    raw.includes('.') &&
+    (raw.startsWith('android.') || raw.startsWith('androidx.') || raw.startsWith('com.'));
+  if (normalized.includes('.')) {
+    normalized = normalized
+      .replace(/^android\.widget\./, '')
+      .replace(/^android\.view\./, '')
+      .replace(/^android\.webkit\./, '')
+      .replace(/^androidx\./, '')
+      .replace(/^com\.google\.android\./, '')
+      .replace(/^com\.android\./, '');
+    if (isAndroidClass && normalized.includes('.')) {
+      normalized = normalized.slice(normalized.lastIndexOf('.') + 1);
+    }
   }
-  return normalized;
-}
-
-/**
- * Every `role=` spelling this node accepts, in ONE place (#3021): the
- * canonical kind first, then its windowed legacy aliases. The `role=` selector
- * term and the `find role=` locator both read this and nothing else, which is
- * what keeps the two — and `kind` itself — unable to disagree.
- */
-export function roleSpellingsOfNode(
-  node: Pick<RawSnapshotNode, 'type'> & { kind?: string },
-): readonly string[] {
-  return [roleKindOfNode(node), ...legacyRoleAliasesForNode(node)];
-}
-
-/**
- * The canonical role kind of a snapshot node — the ONE node-role reader for
- * `role=` selector matching (#3021). It prefers the `kind` the capture
- * published through {@link attachRefs} and reuses this module's own
- * {@link formatRole} when a node predates or bypasses that construction path;
- * `kind` is by definition `formatRole(type)`, so there is no second
- * normalization to drift from.
- */
-function roleKindOfNode(node: Pick<RawSnapshotNode, 'type'> & { kind?: string }): string {
-  return node.kind ?? formatRole(node.type ?? 'Element');
-}
-
-export function formatRole(type: string): string {
-  const normalized = normalizeRoleLeaf(type);
   if (normalized === 'textview') {
-    return isAndroidRoleClass(type) ? 'text' : 'text-view';
+    return isAndroidClass ? 'text' : 'text-view';
   }
   return lookupRoleLabel(normalized) || normalized || 'element';
 }
diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index da3ef5b860..615d3b7085 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -1,5 +1,6 @@
-import { roleSpellingsOfNode, type SnapshotNode } from '@agent-device/kernel/snapshot';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 import { AppError } from '@agent-device/kernel/errors';
+import { roleSpellingsOfNode } from './node.ts';
 import { tryParseSelectorChain } from './parse.ts';
 
 export const FIND_LOCATORS = ['any', 'text', 'label', 'value', 'role', 'id'] as const;
@@ -122,13 +123,13 @@ function matchText(value: string | undefined, query: string): number {
 }
 
 function matchRole(node: SnapshotNode, query: string): number {
-  // The kernel's one role-spelling reader (#3021): the node's canonical `kind`
-  // first, then its windowed legacy leaf. Exact scoring is against the whole
-  // spellings; substring scoring stays on the leaf segment because the retired
-  // locator substring-matched a last-`.`-segment leaf, and an unrecognized
-  // dotted class keeps its package path in its `kind` — substringing the full
-  // kind would let `find role=fenix` score `org.mozilla.fenix.ReaderView`
-  // where the released query refused it.
+  // The package's one role-spelling reader (#3021, `node.ts`): the node's
+  // canonical `kind` first, then its windowed legacy spelling. Exact scoring
+  // is against the whole spellings; substring scoring stays on the leaf
+  // segment because the retired locator substring-matched a last-`.`-segment
+  // leaf, and an unrecognized dotted class keeps its package path in its
+  // `kind` — substringing the full kind would let `find role=fenix` score
+  // `org.mozilla.fenix.ReaderView` where the released query refused it.
   const spellings = roleSpellingsOfNode(node);
   // The query arrives `normalizeText`-ed, so the exact compare normalizes the
   // spellings the same way the selector term's `textEquals` does — that is the
diff --git a/packages/selectors/src/internal/match.ts b/packages/selectors/src/internal/match.ts
index 1b0fcc41d8..fe8a3446d8 100644
--- a/packages/selectors/src/internal/match.ts
+++ b/packages/selectors/src/internal/match.ts
@@ -1,6 +1,6 @@
 import type { Platform, PublicPlatform } from '@agent-device/kernel/device';
-import { roleSpellingsOfNode, type SnapshotNode } from '@agent-device/kernel/snapshot';
-import { isNodeEditable, isNodeVisible } from './node.ts';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import { isNodeEditable, isNodeVisible, roleSpellingsOfNode } from './node.ts';
 import { extractNodeText } from '@agent-device/contracts/snapshot';
 import { normalizeText } from './find.ts';
 import type { Selector, SelectorTerm } from './parse.ts';
@@ -58,11 +58,11 @@ function textEquals(value: string | undefined, query: string): boolean {
 
 /**
  * `role=` matches the canonical `kind` vocabulary (#3021): a term value equals
- * the node's role kind, or one of the legacy leaf spellings still windowed for
- * that node. The kind and the window both come from the kernel's role
- * vocabulary — the same authority `attachRefs` uses to publish `kind` — so the
- * selector, the `find role=` locator, and snapshot output cannot disagree
- * about a node's role again.
+ * the node's role kind, or one of the legacy spellings still windowed for that
+ * node. Both come from {@link roleSpellingsOfNode} — the same `kind`
+ * `attachRefs` publishes and the same `normalizeType` that RECORDS selector
+ * chains — so the selector, the `find role=` locator, snapshot output, and
+ * recorded scripts cannot disagree about a node's role.
  */
 function matchesRoleKind(node: SnapshotNode, query: string): boolean {
   const normalizedQuery = normalizeText(query);
diff --git a/packages/selectors/src/internal/node.test.ts b/packages/selectors/src/internal/node.test.ts
new file mode 100644
index 0000000000..a2b7510140
--- /dev/null
+++ b/packages/selectors/src/internal/node.test.ts
@@ -0,0 +1,155 @@
+// #3021: the package-owned `role=` vocabulary shared by the `role=` selector
+// term and the `find role=` locator, pinned in `node.ts` where it lives. The
+// canonical spelling is the published `kind` vocabulary; the deprecation
+// window replays `@agent-device/contracts` `normalizeType` — the SAME function
+// `buildSelectorChainForNode` records chains through — so a drift in that
+// owner moves the window and the recorded spelling together instead of
+// silently splitting replay.
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { attachRefs, formatRole, type SnapshotNode } from '@agent-device/kernel/snapshot';
+import { normalizeType } from '@agent-device/contracts/snapshot';
+import { roleSpellingsOfNode } from './node.ts';
+
+function bareNode(type: string): SnapshotNode {
+  return { index: 0, ref: 'e1', type, kind: formatRole(type) };
+}
+
+test('roleSpellingsOfNode leads with the kind the capture published', () => {
+  const [node] = attachRefs([{ index: 0, type: 'XCUIElementTypeStaticText' }]);
+  assert.ok(node);
+  assert.equal(node.kind, 'text');
+  // A production node built by `attachRefs` matches on its published `kind`
+  // first; the documented meaning of `role=` is that vocabulary.
+  assert.deepEqual(roleSpellingsOfNode(node), ['text', 'statictext']);
+});
+
+test('roleSpellingsOfNode reads a published kind even when it diverges from the type', () => {
+  // Distinguishes kind-reading from type-only matching: a node whose `kind`
+  // is NOT what formatRole(type) would derive must lead with the published
+  // kind, with the retired spelling riding only as the window. A regression
+  // to deriving the canonical spelling from `type` fails here even though the
+  // window spelling rides along in both directions.
+  assert.deepEqual(roleSpellingsOfNode({ ...bareNode('XCUIElementTypeButton'), kind: 'text' }), [
+    'text',
+    'button',
+  ]);
+});
+
+test('roleSpellingsOfNode reuses formatRole for a node that predates kind publication', () => {
+  // Fixtures that never route through `attachRefs` carry no `kind`; the reader
+  // computes it with the SAME function that publishes it, not a second
+  // normalization.
+  assert.equal(
+    roleSpellingsOfNode({ index: 0, ref: 'e1', type: 'android.widget.EditText' })[0],
+    'text-field',
+  );
+  assert.equal(roleSpellingsOfNode({ index: 0, ref: 'e1' })[0], formatRole('Element'));
+});
+
+test('a renamed leaf stays windowed on the node that carries it', () => {
+  assert.deepEqual(roleSpellingsOfNode(bareNode('XCUIElementTypeStaticText')), [
+    'text',
+    'statictext',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('android.widget.EditText')), [
+    'text-field',
+    'edittext',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('android.widget.FrameLayout')), [
+    'group',
+    'framelayout',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('XCUIElementTypeSearchField')), [
+    'search',
+    'searchfield',
+  ]);
+});
+
+test('the window is node-scoped: sibling leaves of one coarse kind never alias each other', () => {
+  // The nearest-negative that makes the window a window and not a widening:
+  // `group` renames many leaves (`framelayout`, `linearlayout`, `viewgroup`,
+  // …), and #3021 must not make `role=linearlayout` match a FrameLayout node.
+  // Each node carries only ITS OWN retired spelling.
+  assert.deepEqual(roleSpellingsOfNode(bareNode('android.widget.LinearLayout')), [
+    'group',
+    'linearlayout',
+  ]);
+  assert.ok(!roleSpellingsOfNode(bareNode('android.widget.FrameLayout')).includes('linearlayout'));
+});
+
+test('the context-coarse `textview` leaf stays windowed on both spellings that emitted it', () => {
+  // `formatRole` answers `text-view` for the desktop/iOS spelling and `text`
+  // for the Android class; both nodes carried the matchable leaf `textview`.
+  assert.deepEqual(roleSpellingsOfNode(bareNode('XCUIElementTypeTextView')), [
+    'text-view',
+    'textview',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('android.widget.TextView')), ['text', 'textview']);
+});
+
+test('AX-prefixed class types carry the AX-stripped spelling the old matcher accepted', () => {
+  // The macOS helper's `subrole ?? role` fallback emits raw `AX…` classes
+  // whose canonical kind keeps the prefix while the retired matcher accepted
+  // the AX-stripped spelling; renumbered leaves like `AXStaticText` window to
+  // the leaf instead.
+  assert.deepEqual(roleSpellingsOfNode(bareNode('AXFloatingWindow')), [
+    'axfloatingwindow',
+    'floatingwindow',
+  ]);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('AXUnknown')), ['axunknown', 'unknown']);
+  // `axstatictext` is NOT a ROLE_LABELS key, so the kind keeps the prefix and
+  // the window carries the AX-stripped leaf.
+  assert.deepEqual(roleSpellingsOfNode(bareNode('AXStaticText')), ['axstatictext', 'statictext']);
+});
+
+test('the window replays the owner normalizer for arbitrary custom class names', () => {
+  // `normalizeType` took the last `.`/`/`-separated segment of any class, so a
+  // released script could name a custom view class; the window rides that
+  // owner's answer directly.
+  // (formatRole keeps the full dotted spelling as the kind for a non-Android
+  // class it does not recognize; the last-segment spelling windows beside it.)
+  assert.deepEqual(roleSpellingsOfNode(bareNode('io.foo.app.MyButton')), [
+    'io.foo.app.mybutton',
+    'mybutton',
+  ]);
+});
+
+test('a kind that equals its retired spelling carries no window entry', () => {
+  // The nearest-negative for the window itself: `button` and unmapped leaves
+  // like `gridview` are both the retired spelling and the kind, so the window
+  // adds nothing and no vocabulary entry leaks in.
+  assert.deepEqual(roleSpellingsOfNode(bareNode('XCUIElementTypeButton')), ['button']);
+  assert.deepEqual(roleSpellingsOfNode(bareNode('android.widget.GridView')), ['gridview']);
+});
+
+test('the window IS normalizeType: drift in the owner moves the window and the recorded chain together', () => {
+  // The #3021 review rule — one owner for the legacy role spelling: the window
+  // reads `@agent-device/contracts` `normalizeType` directly, the SAME
+  // function `buildSelectorChainForNode` records `role=` chains through. This
+  // pin fails the moment the window grows a private copy: for any backend type
+  // the window's second entry must equal `normalizeType(type)` whenever that
+  // differs from the kind, and equal nothing when it does not.
+  const TYPES = [
+    'XCUIElementTypeStaticText',
+    'XCUIElementTypeButton',
+    'android.widget.TextView',
+    'androidx.recyclerview.widget.RecyclerView',
+    'com.google.android.material.textfield.TextInputEditText',
+    'AXWebArea',
+    'AXUnknown',
+    'StaticText',
+    'a.b/c',
+    'SearchField',
+  ];
+  for (const type of TYPES) {
+    const spellings = roleSpellingsOfNode(bareNode(type));
+    const retired = normalizeType(type);
+    const kind = formatRole(type);
+    if (retired && retired !== kind) {
+      assert.deepEqual(spellings, [kind, retired], `window drifted for ${type}`);
+    } else {
+      assert.deepEqual(spellings, [kind], `spurious window entry for ${type}`);
+    }
+  }
+});
diff --git a/packages/selectors/src/internal/node.ts b/packages/selectors/src/internal/node.ts
index 64d9897b23..54b8569a04 100644
--- a/packages/selectors/src/internal/node.ts
+++ b/packages/selectors/src/internal/node.ts
@@ -1,6 +1,6 @@
 import type { Platform, PublicPlatform } from '@agent-device/kernel/device';
-import type { SnapshotNode } from '@agent-device/kernel/snapshot';
-import { isFillableType } from '@agent-device/contracts/snapshot';
+import { formatRole, type SnapshotNode } from '@agent-device/kernel/snapshot';
+import { isFillableType, normalizeType } from '@agent-device/contracts/snapshot';
 
 export function isNodeVisible(node: SnapshotNode): boolean {
   if (node.hittable === true) return true;
@@ -11,3 +11,31 @@ export function isNodeVisible(node: SnapshotNode): boolean {
 export function isNodeEditable(node: SnapshotNode, platform: Platform | PublicPlatform): boolean {
   return isFillableType(node.type ?? '', platform) && node.enabled !== false;
 }
+
+/**
+ * Every `role=` spelling this node accepts, in ONE place (#3021): the
+ * canonical `kind` vocabulary first, then — during the deprecation window —
+ * the node's retired role spelling. The `role=` selector term and the
+ * `find role=` locator both read this and nothing else, which is what keeps
+ * the two, and `kind` itself, unable to disagree.
+ *
+ * The canonical spelling prefers the `kind` the capture published through
+ * `attachRefs` and falls back to the same `formatRole` that publishes it, so
+ * there is no second normalization of `kind` in this package. The window
+ * spells the retired meaning through `@agent-device/contracts` `normalizeType`
+ * — the live owner of that spelling, and the SAME function
+ * `buildSelectorChainForNode` uses to RECORD `role=` chains — so the window
+ * cannot drift from what recorded scripts carry; if `normalizeType` moves,
+ * both sides move together. It is node-scoped, never a kind→leaves table:
+ * `role=linearlayout` must not start matching a `FrameLayout` row just
+ * because the coarse `group` kind renamed both leaves.
+ *
+ * Closing the window means deleting the second entry, and only once
+ * `buildSelectorChainForNode` stops recording leaf spellings into chains —
+ * freshly recorded scripts replay against the window.
+ */
+export function roleSpellingsOfNode(node: SnapshotNode): readonly string[] {
+  const kind = node.kind ?? formatRole(node.type ?? 'Element');
+  const retired = normalizeType(node.type ?? '');
+  return retired && retired !== kind ? [kind, retired] : [kind];
+}

From 4f8031a7adde94bd71a6fb7b876e0f26716f8e79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 20:19:00 +0200
Subject: [PATCH 7/7] docs(selectors): point the locator leaf comment at
 normalizeType, not kernel

The retired-term spelling moved out of kernel with the window; the comment
named the stale owner.
---
 packages/selectors/src/internal/find.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/selectors/src/internal/find.ts b/packages/selectors/src/internal/find.ts
index 615d3b7085..8b6fe0db63 100644
--- a/packages/selectors/src/internal/find.ts
+++ b/packages/selectors/src/internal/find.ts
@@ -143,11 +143,11 @@ function matchRole(node: SnapshotNode, query: string): number {
 /**
  * The substring-scoring view of one role spelling: its last `.`-separated
  * segment. This is deliberately the RETIRED LOCATOR's leaf (`split('.').pop()`
- * only), not the kernel's retired-term spelling — the term also reduced a
- * trailing `/` segment, and mirroring that here would drop substring hits the
- * released locator kept (query `y/z` still scores 1 against kind `x.y/z`
- * today). The term's `/`-reduced spelling rides as the windowed exact alias
- * instead, so term/locator agreement comes from the exact side, and each
+ * only), not the retired term spelling (`normalizeType`) — the term also
+ * reduced a trailing `/` segment, and mirroring that here would drop substring
+ * hits the released locator kept (query `y/z` still scores 1 against kind
+ * `x.y/z` today). The term's `/`-reduced spelling rides as the windowed exact
+ * alias instead, so term/locator agreement comes from the exact side, and each
  * surface's historical substring meaning is preserved. An AX-stripped query
  * (`link` against an `AXLink` node) likewise reaches the exact score through
  * the windowed alias, not through substring — the retired term already matched