fix: polish helper subpath typings

Author: thymikee

src/__tests__/finders-public.test.ts

@@ -1,5 +1,5 @@
-import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import { test } from 'vitest';
 import {
   findBestMatchesByLocator,
   normalizeRole,
@@ -21,10 +21,16 @@ test('public finders entrypoint re-exports pure helpers', () => {
   const nodes: SnapshotNode[] = [makeNode('e1', 'Continue')];
 
   const parsed = parseFindArgs(['label', 'Continue', 'click']);
-  const best = findBestMatchesByLocator(nodes, 'label', 'Continue', true);
+  const best = findBestMatchesByLocator(nodes, 'label', 'Continue');
+  const requireRectLegacy = findBestMatchesByLocator(nodes, 'label', 'Continue', true);
+  const requireRectOptions = findBestMatchesByLocator(nodes, 'label', 'Continue', {
+    requireRect: true,
+  });
 
   assert.equal(normalizeText('  Continue\nNow  '), 'continue now');
   assert.equal(normalizeRole('XCUIElementTypeApplication.XCUIElementTypeButton'), 'button');
   assert.equal(parsed.action, 'click');
-  assert.equal(best.matches.length, 0);
+  assert.equal(best.matches.length, 1);
+  assert.equal(requireRectLegacy.matches.length, 0);
+  assert.equal(requireRectOptions.matches.length, 0);
 });

src/__tests__/selectors-public.test.ts

@@ -1,5 +1,5 @@
-import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import { test } from 'vitest';
 import {
   findSelectorChainMatch,
   formatSelectorFailure,

src/finders.ts

@@ -1,4 +1,5 @@
 export type { FindLocator } from './utils/finders.ts';
+export type { SnapshotNode } from './utils/snapshot.ts';
 export { normalizeRole, normalizeText, parseFindArgs } from './utils/finders.ts';
 
 import {
@@ -7,11 +8,16 @@ import {
 } from './utils/finders.ts';
 import type { SnapshotNode } from './utils/snapshot.ts';
 
+export type FindMatchOptions = {
+  requireRect?: boolean;
+};
+
 export function findBestMatchesByLocator(
   nodes: SnapshotNode[],
   locator: FindLocator,
   query: string,
-  requireRect?: boolean,
+  options?: boolean | FindMatchOptions,
 ) {
-  return findBestMatchesByLocatorInternal(nodes, locator, query, { requireRect });
+  const matchOptions = typeof options === 'boolean' ? { requireRect: options } : options;
+  return findBestMatchesByLocatorInternal(nodes, locator, query, matchOptions);
 }

src/selectors.ts

@@ -4,6 +4,7 @@ export type {
   SelectorDiagnostics,
   SelectorResolution,
 } from './daemon/selectors.ts';
+export type { SnapshotNode } from './utils/snapshot.ts';
 
 export {
   findSelectorChainMatch,

website/docs/docs/client-api.md

@@ -32,13 +32,13 @@ Public subpath API exposed for Node consumers:
   - `isNodeVisible(node)`
   - `isSelectorToken(token)`
   - `isNodeEditable(node, platform)`
-  - types: `Selector`, `SelectorChain`, `SelectorDiagnostics`, `SelectorResolution`
+  - types: `Selector`, `SelectorChain`, `SelectorDiagnostics`, `SelectorResolution`, `SnapshotNode`
 - `agent-device/finders`
-  - `findBestMatchesByLocator(nodes, locator, query, requireRect)`
+  - `findBestMatchesByLocator(nodes, locator, query, requireRectOrOptions)`
   - `normalizeRole(value)`
   - `normalizeText(value)`
   - `parseFindArgs(args)`
-  - types: `FindLocator`
+  - types: `FindLocator`, `FindMatchOptions`, `SnapshotNode`
 - `agent-device/install-source`
   - `ARCHIVE_EXTENSIONS`
   - `isBlockedIpAddress(address)`