feat: expose selector helper subpath (#384)

Author: thymikee

package.json

@@ -23,6 +23,10 @@
     "./contracts": {
       "import": "./dist/src/contracts.js",
       "types": "./dist/src/contracts.d.ts"
+    },
+    "./selectors": {
+      "import": "./dist/src/selectors.js",
+      "types": "./dist/src/selectors.d.ts"
     }
   },
   "engines": {

rslib.config.ts

@@ -20,6 +20,7 @@ export default defineConfig({
           metro: 'src/metro.ts',
           'remote-config': 'src/remote-config.ts',
           contracts: 'src/contracts.ts',
+          selectors: 'src/selectors.ts',
         },
         tsconfigPath: 'tsconfig.lib.json',
       },

src/__tests__/selectors-public.test.ts

@@ -0,0 +1,70 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import {
+  findSelectorChainMatch,
+  formatSelectorFailure,
+  isNodeEditable,
+  isNodeVisible,
+  isSelectorToken,
+  parseSelectorChain,
+  resolveSelectorChain,
+  tryParseSelectorChain,
+  type Selector,
+  type SelectorChain,
+  type SelectorDiagnostics,
+  type SelectorResolution,
+} from '../selectors.ts';
+import type { SnapshotNode } from '../utils/snapshot.ts';
+
+const nodes: SnapshotNode[] = [
+  {
+    ref: 'e1',
+    index: 0,
+    type: 'android.widget.Button',
+    label: 'Continue',
+    rect: { x: 0, y: 0, width: 120, height: 48 },
+    enabled: true,
+  },
+  {
+    ref: 'e2',
+    index: 1,
+    type: 'android.widget.EditText',
+    label: 'Email',
+    rect: { x: 0, y: 64, width: 200, height: 48 },
+    enabled: true,
+  },
+];
+
+test('public selector subpath exposes platform-aware matching helpers', () => {
+  const chain: SelectorChain = parseSelectorChain('role=button label="Continue" visible=true');
+  const firstSelector: Selector = chain.selectors[0];
+  assert.equal(firstSelector.raw, 'role=button label="Continue" visible=true');
+  assert.equal(tryParseSelectorChain(chain.raw)?.raw, chain.raw);
+  assert.equal(isSelectorToken('visible=true'), true);
+
+  const match = findSelectorChainMatch(nodes, chain, {
+    platform: 'android',
+    requireRect: true,
+  });
+  assert.ok(match);
+  assert.equal(match.matches, 1);
+
+  const resolved: SelectorResolution | null = resolveSelectorChain(nodes, chain, {
+    platform: 'android',
+    requireRect: true,
+  });
+  assert.equal(resolved?.node.ref, 'e1');
+
+  assert.equal(isNodeVisible(nodes[0]), true);
+  assert.equal(isNodeEditable(nodes[1], 'android'), true);
+});
+
+test('public selector diagnostics format failures', () => {
+  const chain = parseSelectorChain('label=Missing');
+  const diagnostics: SelectorDiagnostics[] = [{ selector: 'label=Missing', matches: 0 }];
+
+  assert.equal(
+    formatSelectorFailure(chain, diagnostics, { unique: false }),
+    'Selector did not match (label=Missing -> 0)',
+  );
+});

src/daemon/selectors-resolve.ts

@@ -8,7 +8,7 @@ export type SelectorDiagnostics = {
   matches: number;
 };
 
-type SelectorResolution = {
+export type SelectorResolution = {
   node: SnapshotNode;
   selector: Selector;
   selectorIndex: number;

src/daemon/selectors.ts

@@ -1,4 +1,5 @@
-export type { SelectorChain } from './selectors-parse.ts';
+export type { Selector, SelectorChain } from './selectors-parse.ts';
+export type { SelectorDiagnostics, SelectorResolution } from './selectors-resolve.ts';
 
 export {
   parseSelectorChain,

src/selectors.ts

@@ -0,0 +1,17 @@
+export type {
+  Selector,
+  SelectorChain,
+  SelectorDiagnostics,
+  SelectorResolution,
+} from './daemon/selectors.ts';
+
+export {
+  findSelectorChainMatch,
+  formatSelectorFailure,
+  isNodeEditable,
+  isNodeVisible,
+  isSelectorToken,
+  parseSelectorChain,
+  resolveSelectorChain,
+  tryParseSelectorChain,
+} from './daemon/selectors.ts';

website/docs/docs/client-api.md

@@ -23,6 +23,16 @@ Public subpath API exposed for Node consumers:
   - types: `RemoteConfigProfile`, `RemoteConfigProfileOptions`, `ResolvedRemoteConfigProfile`
 - `agent-device/contracts`
   - types: `SessionRuntimeHints`, `DaemonInstallSource`, `DaemonLockPolicy`, `DaemonRequestMeta`, `DaemonRequest`, `DaemonArtifact`, `DaemonResponseData`, `DaemonError`, `DaemonResponse`
+- `agent-device/selectors`
+  - `parseSelectorChain(expression)`
+  - `tryParseSelectorChain(expression)`
+  - `resolveSelectorChain(nodes, chain, options)`
+  - `findSelectorChainMatch(nodes, chain, options)`
+  - `formatSelectorFailure(chain, diagnostics, options)`
+  - `isNodeVisible(node)`
+  - `isSelectorToken(token)`
+  - `isNodeEditable(node, platform)`
+  - types: `Selector`, `SelectorChain`, `SelectorDiagnostics`, `SelectorResolution`
 
 ## Basic usage
 
@@ -189,3 +199,22 @@ await stopMetroTunnel({
 ```
 
 Use `agent-device/remote-config` for profile loading and path resolution, `agent-device/metro` for Metro preparation and tunnel lifecycle, and `agent-device/contracts` when a server consumer needs daemon request or runtime contract types.
+
+## 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.
+
+```ts
+import { findSelectorChainMatch, parseSelectorChain } from 'agent-device/selectors';
+
+const chain = parseSelectorChain('role=button label="Continue" visible=true');
+
+const match = findSelectorChainMatch(snapshot.nodes, chain, {
+  platform: 'android',
+  requireRect: true,
+});
+
+if (!match) {
+  // Build a daemon-shaped error with formatSelectorFailure(...) if needed.
+}
+```