@bun-win32/uia 1.0.0

package/AI.md

@@ -0,0 +1,130 @@
+# AI Guide for @bun-win32/uia
+
+Everything below is reachable from `@bun-win32/uia` (or its unscoped alias `bun-uia`) alone. **Bun + Windows only.** This file is the complete surface — an agent should not need to read the source. When it must, the "Where to look" section says exactly which one file to open.
+
+## What it is
+
+Playwright for Windows desktop apps. Query the live UI Automation (accessibility) tree by name / control-type / automationId, invoke controls, type, read values, wait for elements to appear, and serialize a window's tree to JSON for an LLM agent. Three engines behind one facade:
+
+1. **IUIAutomation COM client** (the spine) — driven through a cast-free vtable invoker. Query + invoke + patterns + cache.
+2. **Flat `uiautomationcore` C-API** — a VARIANT-free fast path (secondary; the COM path is the default).
+3. **`oleacc` MSAA fallback** — for legacy / owner-draw windows that expose no useful UIA tree.
+
+Escalation rule: stay on the `uia` facade. Drop to a lower engine (`msaaTree`, the raw `vcall`) only when you need something the facade lacks.
+
+## Mental model (read this first)
+
+- **UIA is cross-process.** Every property read and `find` marshals into the target app. `initialize()` once (it sets up a single-threaded COM apartment + makes the process DPI-aware); `uninitialize()` at the end, or `using app = uia.attach(...)`.
+- **Selectors are hybrid.** Exact scalars (`controlType`, `name` string, `automationId`, `className`) compile to a **server-side** UIA condition — the target app filters in-process and only matches come back. Rich predicates (`name` RegExp, `nameContains`) are matched **client-side** on the (already-narrowed) results. Always scope a search to a window (`attach`), **never** `findAll` from the desktop root.
+- **CacheRequest batches.** Naive walks pay N cross-process round-trips; `findAllCached` / `tree()` prefetch a whole subtree in one. The cache wins more the larger the tree.
+- **Only the listed patterns are proven.** `invoke`, `value`/`setValue`, `text`, `toggle`, `expand`/`collapse`, `select`, `rangeValue`/`setRangeValue`, window `close`/`setVisualState` are each proven against a real control. `scrollIntoView` is implemented but unproven (see roadmap).
+- **Synthetic input needs an unlocked, interactive desktop.** `type`, `sendKeys`, `click` go through `SendInput` — they are silently dropped on a locked session. UIA queries, `invoke`, `setValue`, and `screenshot` all work locked. Prefer `setValue` / `invoke` over `type` / `click` when a pattern exists.
+- **Element pointers have apartment affinity.** Keep them on the creating thread; tolerate `UIA_E_ELEMENTNOTAVAILABLE (0x80040201)` if a window closes mid-walk. UIA **events** are out of scope in v1 — poll with `waitFor`.
+
+## Capability → API
+
+| I want to … | call |
+| --- | --- |
+| attach to an app | `uia.attach('Calculator')` · `uia.attach({ className })` · `uia.attach({ process: pid })` · `uia.attach(hWnd)` |
+| spawn + wait for an app | `await uia.launch(['notepad.exe'], { className: 'Notepad' })` |
+| find by name/type/automationId | `app.find({ controlType: ControlType.Button, name: 'Five' })` |
+| find all matches | `app.findAll({ controlType: ControlType.Button })` |
+| wait for a control (auto-retry) | `await app.waitFor(selector, { timeout: 5000 })` |
+| click / press | `el.invoke()` (UIA) · `el.click()` (bbox + SendInput fallback) |
+| type | `el.type('text')` (Unicode keystrokes) · `uia.sendKeys('Control+S')` |
+| set / read a value | `el.setValue('text')` · `el.value` · `el.text()` (TextPattern) |
+| toggle / expand / select / slider | `el.toggle()` · `el.expand()`/`el.collapse()` · `el.select()` · `el.setRangeValue(n)` |
+| read state | `el.name` `el.controlType` `el.controlTypeName` `el.automationId` `el.className` `el.isEnabled` `el.boundingRectangle` |
+| serialize the tree for an LLM | `uia.tree(app, { agentProfile: true })` |
+| run a JSON action list (agent) | `uia.execute(app, [{ find: {...}, do: 'invoke' }, …])` |
+| screenshot | `app.screenshot()` → PNG bytes |
+| list / target windows | `uia.windows()` · `findWindow({ title })` · `windowForProcess(pid)` |
+| fall back to MSAA | `uia.msaaTree(hWnd)` |
+
+## Full API
+
+### `uia` — the facade object
+`attach(target)`, `launch(command, target, timeout?)`, `focused()`, `fromPoint(x, y)`, `root()`, `windows()`, `tree(element, options?)`, `execute(element, actions)`, `msaaTree(hWnd, maxDepth?)`, `click(x, y)`, `sendKeys(combo)`, `type(text)`, `initialize()`, `uninitialize()`.
+
+### `class Element`
+- Live properties (getters): `name`, `controlType`, `controlTypeName`, `automationId`, `className`, `isEnabled`, `boundingRectangle: Rect`, `nativeWindowHandle: bigint`, `value`, `toggleState`, `expandCollapseState`, `isSelected`, `rangeValue`.
+- Tree: `find(selector, scope?)`, `findAll(selector, scope?)`, `findAllCached(selector, request, scope?)`, `children`, `parent`, `await waitFor(selector, { timeout?, interval? })`, `describeNoMatch(selector)`, `buildUpdatedCache(request)`, `cachedChildren`, `cached{Name,ControlType,AutomationId,ClassName,BoundingRectangle,IsEnabled}`.
+- Patterns (throw if unsupported): `invoke()`, `setValue(text)`, `text()`, `toggle()`, `expand()`, `collapse()`, `select()`, `scrollIntoView()`, `setRangeValue(n)`, `close()`, `setVisualState(WindowVisualState)`.
+- Input (need an unlocked session): `focus()`, `type(text)`, `click()`.
+- Lifecycle: `release()`, `ptr: bigint`.
+
+### `class Window extends Element`
+Adds `hWnd: bigint`, `activate()`, `screenshot(): Uint8Array`, `dispose()` / `[Symbol.dispose]`.
+
+### Selector & matching
+`interface Selector { controlType?, name? (string | RegExp), nameContains?, automationId?, className? }`. `interface ElementProperties { name, controlType, automationId, className }` (what `matches` reads). `matches(props, selector)`, `selectorToString(selector)`, `formatNoMatch(selector, windowName, candidateNames)`.
+
+### Root accessors (return a live `Element`/`Window`)
+`fromHandle(hWnd)` (an `Element` for a window handle — `attach` wraps this in a `Window`), `focused()`, `fromPoint(x, y)`, `root()`.
+
+### Constants / enums
+`ControlType` (Button=50000 … AppBar=50040), `PatternId` (10000–10033), `PropertyId` (30000–30024), `TreeScope`, `PropertyConditionFlags`, `ToggleState`, `ExpandCollapseState`, `WindowVisualState`, `SLOT` (verified vtable slots).
+
+### Cache
+`createCacheRequest(properties?, scope?, mode?)`, `class CacheRequest { property, pattern, treeScope, elementMode, release }`, `DEFAULT_CACHE_PROPERTIES`, `AutomationElementMode`.
+
+### Tree / agent
+`serialize(element, options?: SerializeOptions): UiaNode`, `interface SerializeOptions { maxDepth?, agentProfile? }`, `interface UiaNode { role, name, automationId?, className?, bounds?, enabled?, children }`, `countNodes`, `estimateTokens`, `execute(element, actions): AgentActionResult[]`, `AGENT_TOOLS`, `groundingTree(element)`, `type AgentAction`.
+
+### Windows / input / msaa / low-level
+`findWindow`, `listWindows`, `windowForProcess`, `screenshot`, `type WindowInfo`; `sendKeys`, `clickAt`, `virtualKeyCode`, `INPUT_SIZE`, `packKeyboardInput`, `packMouseInput`; `msaaTree`, `accessibleFromWindow`, `type MsaaNode`; `vcall`, `comRelease`, `guid`, `hresult`, `getBstr`, `getLong`, `getRect`, `getHandle`, `decodeBstr`, `encodePNG`, `initialize`, `uninitialize`, `automation`, `type Rect`.
+
+## Recipes
+
+```ts
+// Notepad round-trip (the 10-line wow) — needs an unlocked session for type()
+import { ControlType, uia } from '@bun-win32/uia';
+const app = await uia.launch(['notepad.exe'], { className: 'Notepad' });
+const edit = await app.waitFor({ controlType: ControlType.Document });
+edit.focus().type('hello from bun-uia');
+console.log(edit.text());
+```
+```ts
+// Calculator 5 + 3 = 8 (works on a locked session — invoke is UIA, not SendInput)
+const calc = await uia.launch(['cmd', '/c', 'start', 'calc'], { title: 'Calculator' });
+for (const name of ['Five', 'Plus', 'Three', 'Equals']) calc.find({ controlType: ControlType.Button, name })?.invoke();
+console.log(calc.find({ automationId: 'CalculatorResults' })?.name); // → "Display is 8"
+```
+```ts
+// Wait for a dialog, dismiss it
+uia.sendKeys('Control+S');
+const cancel = await app.waitFor({ name: 'Cancel', controlType: ControlType.Button }, { timeout: 4000 });
+cancel.invoke();
+```
+```ts
+// Tree → JSON for an LLM agent (ground-truth identity + bounds, no pixel-counting)
+const grounding = uia.tree(app, { agentProfile: true }); // { role, name, bounds, children }
+const results = uia.execute(app, [{ find: { name: 'Five' }, do: 'invoke' }, { find: { automationId: 'CalculatorResults' }, do: 'read' }]);
+```
+```ts
+// Reliable text entry without keyboard focus battles (works locked): ValuePattern
+edit.setValue('typed without keystrokes');
+// Verify visually
+await Bun.write('shot.png', app.screenshot());
+```
+```ts
+// MSAA fallback for an app with no good UIA tree
+const accessible = uia.msaaTree(hWnd, 6);
+```
+
+## Gotchas (the traps ledger)
+
+- **Selectors are client-scoped, never from the desktop root.** `attach` a window first; `find` defaults to `TreeScope_Descendants` of that window.
+- **`ElementFromHandle` is vtable slot 6** (slot 7 is `ElementFromPoint`). The package has the verified slot table; if you hand-roll `vcall`, regenerate slots from `UIAutomationClient.h` and prove each — a wrong slot segfaults.
+- **Server-side property conditions work** (the 16-byte VARIANT goes by hidden pointer in the x64 ABI). `nameContains` / RegExp still filter client-side.
+- **`type` / `sendKeys` / `click` are dropped on a locked session.** Prefer `setValue` / `invoke`; they work locked. `screenshot` (PrintWindow) also works locked.
+- **Process is DPI-aware** after `initialize()` so click coordinates match UIA bounds; `click()` uses `SetCursorPos` + physical pixels.
+- **`SendInput` cbSize must be 40** (handled internally) — the x64 `INPUT` is 40 bytes.
+- **BSTR names are bulk-copied before free**; never read after `SysFreeString`.
+- **Only proven patterns ship.** Calling a pattern an element doesn't support throws a clear message (pointing at `.click()` / `.type()` where relevant). `scrollIntoView` is unproven (roadmap).
+- **Non-English / different builds** differ: Calculator's result element is `automationId: 'CalculatorResults'`, buttons are named `Five`/`Plus`/… (full words). Configure selectors per app.
+- **Threading:** v1 is STA, fire-and-forget out-of-process driving. Events / self-UI automation need MTA — out of scope.
+
+## Where to look (source)
+
+`automation.ts` activation + the singleton · `com.ts` `vcall`/`guid` · `constants.ts` ids + verified slots · `element.ts` `Element`/`Window`/`attach`/`launch`/`waitFor` · `condition.ts` the typed selector · `patterns.ts` control patterns · `input.ts` `SendInput` · `cache.ts` CacheRequest · `tree.ts` agent grounding · `window.ts` targeting + screenshots · `msaa.ts` oleacc fallback · `agent.ts` the LLM tool adapter · `reads.ts` property readers.

package/README.md

@@ -0,0 +1,79 @@
+# @bun-win32/uia
+
+**Playwright for Windows desktop apps.** Query the live UI Automation accessibility tree by name and role, invoke controls, type, wait for elements, and serialize a window to JSON for an LLM agent — from Bun, with **zero native dependencies**. No node-gyp, no prebuild matrix, no Appium server, no .NET.
+
+> The unscoped alias [`bun-uia`](https://www.npmjs.com/package/bun-uia) re-exports this package — `bun add bun-uia` is the discoverable front door.
+
+```ts
+import { ControlType, uia } from '@bun-win32/uia';
+
+const app = await uia.launch(['notepad.exe'], { className: 'Notepad' });
+const edit = await app.waitFor({ controlType: ControlType.Document });
+edit.focus().type('nothing native compiles, and it just works');
+console.log(edit.text()); // → nothing native compiles, and it just works
+```
+
+```ts
+// Drive Calculator to 5 + 3 = 8 by name — survives DPI/theme/layout shifts that break pixel scripts:
+const calc = await uia.launch(['cmd', '/c', 'start', 'calc'], { title: 'Calculator' });
+for (const name of ['Five', 'Plus', 'Three', 'Equals']) calc.find({ controlType: ControlType.Button, name })?.invoke();
+console.log(calc.find({ automationId: 'CalculatorResults' })?.name); // → "Display is 8"
+```
+
+`bun add @bun-win32/uia` is the entire install story.
+
+## Why this exists
+
+The Windows desktop-automation cluster on npm is a field of native-addon pain, paywalls, and abandoned daemons. Downloads verified against `api.npmjs.org` for the week of 2026-06-05→11.
+
+| Tool | Weekly dl | Install / runtime | The catch |
+| --- | --- | --- | --- |
+| `@nut-tree-fork/nut-js` | 32,360 | libnut N-API addon (cmake-js) | Fork of a **paywalled** original — *"all of my packages around nut.js will cease to exist publicly on npm … only available through the private … registry, which requires an active subscription."* Pixel/image-match, **no a11y tree**. |
+| `appium-windows-driver` | 30,749 | Appium server **+ a separate WinAppDriver.exe** | *"WinAppDriver server has not been maintained by Microsoft for years … Developer mode must be enabled."* Two daemons + a W3C HTTP hop per element read. |
+| `@jitsi/robotjs` / `robotjs` | 15,333 / 11,375 | node-gyp / prebuild matrix | *"No prebuilt binaries found … node-gyp rebuild"* C++ compile fallback — the #1 documented install failure. Blind pixel + keystroke, **no element model**. |
+| `uiohook-napi` (input hooks) | 21,965 | N-API addon | Healthy — but global `SetWindowsHookEx` hooks run on a foreign thread and can assert/segfault (node-addon-api #903). |
+| `@bright-fish/node-ui-automation` | 33 | NAPI/COM native addon | The only real npm UIA wrapper — **dead since 2022**. |
+| NodeRT `windows.ui.uiautomation` | 15 | NodeRT native addon | Dead 2022 **and wrong namespace** (projects WinRT, not the Win32 `IUIAutomation`). |
+| FlaUI / pywinauto / AutoIt | n/a | .NET / Python / bespoke EXE | A foreign runtime to install and ship. |
+
+**There is no zero-install, typed, in-process `IUIAutomation` client for Node or Bun.** @bun-win32/uia is a few kilobytes of TypeScript over `bun:ffi` — the runtime's own FFI, not a third-party N-API addon that rots against each Node minor (*"PLEASE ARCHIVE THIS REPO"* — node-ffi-napi #269). It **can't be paywalled** (no compiled binary to gate behind a subscription registry), has **no build step** (no node-gyp, no ABI matrix, no MSVC/Python), and talks to UIA **in-process** (no WinAppDriver.exe, no Appium daemon, no `127.0.0.1:4723` round-trip, no Developer Mode).
+
+## What you can do
+
+- **Find controls semantically** — by name, role, or automationId, not a fragile `(x, y)`. Exact scalars compile to a **server-side** UIA condition (the target app filters in-process); regex/substring filter client-side.
+- **Act** — `invoke()`, `click()`, `setValue()`, `type()`, `toggle()`, `expand()`, `select()`, `setRangeValue()`, window `close()`/`setVisualState()`. Each pattern is proven against a real control.
+- **`waitFor`** — Playwright-class auto-retry for flaky native UIs. No other Windows-desktop npm tool has it. Timeouts quote the selector, the window, and the nearest candidates.
+- **Read & assert** — `value`, `text()`, `isEnabled`, `boundingRectangle`, `toggleState`. Read state back through the tree to assert — pixel tools can't.
+- **Serialize the tree to JSON** for an LLM agent (`uia.tree`), with a token-svelte agent profile.
+- **Screenshot** any window via PrintWindow (works even on a locked session).
+- **MSAA fallback** (`uia.msaaTree`) for legacy / owner-draw windows.
+- **Crash-safe input observation** via `GetAsyncKeyState` polling — no foreign-thread hook, no message-pump assert.
+
+## For AI agents
+
+Frontier computer-use agents ground actions in **screenshots** and the literature calls it fragile and expensive. Microsoft **UFO2** (arXiv 2504.14603) fuses the **UI Automation tree first, vision second**, to fix *"fragile screenshot-based interaction"*; OmniParser exists because VLMs can't reliably locate clickable elements from a bitmap; and **OSWorld-Human** (arXiv 2506.16042) reports a11y-tree builds taking **3–26 seconds** and "thousands more tokens per step."
+
+@bun-win32/uia is exactly that UIA-first substrate — served **fast and in-process**. `uia.tree(app, { agentProfile: true })` walks a window's subtree in **one cached round-trip** and emits ground-truth `{ role, name, automationId, bounds, children }` an agent acts on without pixel-counting. The measured build time below beats the OSWorld 3–26 s reference by **two-to-three orders of magnitude**. `uia.execute(app, actions)` runs a JSON action list; `AGENT_TOOLS` is a ready LLM tool schema. Honest limit: UIA can't see owner-draw/canvas/games, so this **complements** a vision agent rather than replacing screenshots.
+
+## Benchmarks
+
+Measured on Windows 11, Bun 1.4, by `bun run example/benchmark.ts` (run it to reproduce):
+
+| operation | result |
+| --- | --- |
+| single property read (cross-process) | ~55 µs |
+| naive subtree walk (65 nodes) | ~44 ms |
+| **cached subtree walk** (one round-trip) | **~37 ms** (1.2× faster; the gap widens with tree size) |
+| agent-grounding tree build | ~9 ms, ~2.7k tokens |
+| **vs OSWorld a11y-tree build (3–26 s)** | **~345–2987× faster** |
+
+## Requirements & honest scoping
+
+- **Windows 10/11, Bun ≥ 1.1.** Windows-only and Bun-only — the owned trade-off (nut.js/robotjs/uiohook are genuinely cross-platform; this is not).
+- **UIA-tree based.** Apps with no accessibility tree (games, canvas/WebGL, custom-draw) get MSAA + screenshots + coordinate `click()`, not vision matching — a complement to screenshot tools, not a replacement.
+- **Synthetic input (`type`/`sendKeys`/`click`) needs an unlocked, interactive desktop.** UIA queries, `invoke`, `setValue`, and `screenshot` work on a locked session; prefer them.
+- **Selectors are client-side for regex/substring** (exact scalars are server-side). **UIA events are roadmap** — poll with `waitFor`. `scrollIntoView` is implemented but not yet proven against a real list.
+
+Read [`AI.md`](./AI.md) — it is the complete surface; an agent should not need the source.
+
+MIT.

package/agent.ts

@@ -0,0 +1,83 @@
+// Drop-in computer-use grounding for the Windows desktop: turn the UIA surface into an LLM tool schema
+// plus a JSON-action executor. Hand an agent the tree() JSON (ground-truth element identity + bounds,
+// not pixels) and these tools; it grounds actions on roles and names instead of counting pixels — the
+// structured alternative the computer-use literature (UFO2, OSWorld) is converging on.
+
+import type { Selector } from './condition';
+import type { Element } from './element';
+import { serialize, type UiaNode } from './tree';
+
+export interface AgentAction {
+  find: Selector;
+  do: 'click' | 'invoke' | 'read' | 'setValue' | 'toggle' | 'type';
+  text?: string;
+}
+
+export interface AgentActionResult {
+  action: AgentAction;
+  ok: boolean;
+  value?: string;
+  error?: string;
+}
+
+/** Execute a JSON action list against a window: each step finds an element by selector, then acts. */
+export function execute(window: Element, actions: readonly AgentAction[]): AgentActionResult[] {
+  const results: AgentActionResult[] = [];
+  for (const action of actions) {
+    const element = window.find(action.find);
+    if (element === null) {
+      results.push({ action, ok: false, error: window.describeNoMatch(action.find) });
+      continue;
+    }
+    try {
+      let value: string | undefined;
+      if (action.do === 'invoke') element.invoke();
+      else if (action.do === 'click') element.click();
+      else if (action.do === 'type') element.type(action.text ?? '');
+      else if (action.do === 'setValue') element.setValue(action.text ?? '');
+      else if (action.do === 'toggle') element.toggle();
+      else value = element.value || element.text() || element.name;
+      results.push({ action, ok: true, value });
+    } catch (error) {
+      results.push({ action, ok: false, error: (error as Error).message });
+    } finally {
+      element.release();
+    }
+  }
+  return results;
+}
+
+/** Serialize a window for an agent — the compact, interactive-only grounding profile. */
+export function groundingTree(window: Element): UiaNode {
+  return serialize(window, { agentProfile: true });
+}
+
+/** LLM tool definitions (Anthropic/OpenAI tool-use shape) for desktop grounding. */
+export const AGENT_TOOLS = [
+  {
+    name: 'find_and_act',
+    description: 'Find a desktop control by name/control-type/automationId and act on it (invoke, click, type, setValue, toggle, or read its value).',
+    input_schema: {
+      type: 'object',
+      properties: {
+        find: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            controlType: { type: 'number', description: 'a UIA control-type id, e.g. 50000 Button, 50004 Edit' },
+            automationId: { type: 'string' },
+            nameContains: { type: 'string' },
+          },
+        },
+        do: { type: 'string', enum: ['invoke', 'click', 'type', 'setValue', 'toggle', 'read'] },
+        text: { type: 'string', description: 'the text for type/setValue' },
+      },
+      required: ['find', 'do'],
+    },
+  },
+  {
+    name: 'read_tree',
+    description: 'Serialize the target window accessibility tree to JSON (role, name, automationId, bounds) for grounding actions.',
+    input_schema: { type: 'object', properties: { agentProfile: { type: 'boolean', description: 'prune to interactive/named controls' } } },
+  },
+] as const;

package/automation.ts

@@ -0,0 +1,51 @@
+// The UI Automation root: the COM apartment plus the in-process IUIAutomation client, created once.
+
+import Combase from '@bun-win32/combase';
+import User32 from '@bun-win32/user32';
+
+import { comRelease, guid, hresult } from './com';
+import { CLSCTX_INPROC_SERVER, CLSID_CUIAutomation, COINIT_APARTMENTTHREADED, IID_IUIAutomation, S_FALSE, S_OK } from './constants';
+
+let pAutomation = 0n;
+let comInitialized = false;
+
+/**
+ * Initialize COM (single-threaded apartment) and create the in-process IUIAutomation client.
+ * Idempotent — returns the cached client pointer on subsequent calls. Throws (does not exit) when
+ * UI Automation is unavailable so callers can catch and degrade.
+ */
+export function initialize(): bigint {
+  if (pAutomation !== 0n) return pAutomation;
+  if (!comInitialized) {
+    // Physical-pixel coordinates so SendInput clicks match UIA bounding rectangles (best-effort).
+    User32.SetProcessDPIAware();
+    const initHr = Combase.CoInitializeEx(null, COINIT_APARTMENTTHREADED);
+    if (initHr !== S_OK && initHr !== S_FALSE) throw new Error(`CoInitializeEx failed: ${hresult(initHr)}`);
+    comInitialized = true;
+  }
+  const clsid = guid(CLSID_CUIAutomation);
+  const iid = guid(IID_IUIAutomation);
+  const out = Buffer.alloc(8);
+  const createHr = Combase.CoCreateInstance(clsid.ptr!, 0n, CLSCTX_INPROC_SERVER, iid.ptr!, out.ptr!);
+  if (createHr !== S_OK) throw new Error(`CoCreateInstance(CUIAutomation) failed: ${hresult(createHr)} — UI Automation is unavailable on this system.`);
+  pAutomation = out.readBigUInt64LE(0);
+  if (pAutomation === 0n) throw new Error('CoCreateInstance(CUIAutomation) returned a null client.');
+  return pAutomation;
+}
+
+/** The IUIAutomation client pointer, initializing on first use. */
+export function automation(): bigint {
+  return pAutomation !== 0n ? pAutomation : initialize();
+}
+
+/** Release the IUIAutomation client and uninitialize COM. Safe to call when never initialized. */
+export function uninitialize(): void {
+  if (pAutomation !== 0n) {
+    comRelease(pAutomation);
+    pAutomation = 0n;
+  }
+  if (comInitialized) {
+    Combase.CoUninitialize();
+    comInitialized = false;
+  }
+}

package/cache.ts

@@ -0,0 +1,67 @@
+// CacheRequest batching — the performance spine. Naive UIA reads N properties with N cross-process
+// round-trips; IUIAutomationCacheRequest + FindAllBuildCache prefetches many properties for a whole
+// subtree in ONE round-trip, then get_Cached* reads pay zero further round-trips.
+
+import { FFIType } from 'bun:ffi';
+
+import { automation } from './automation';
+import { comRelease, vcall } from './com';
+import { PropertyId, S_OK, SLOT, TreeScope } from './constants';
+
+/** Properties the default cache prefetches — what tree() and the cached find/walk need. */
+export const DEFAULT_CACHE_PROPERTIES: readonly number[] = [PropertyId.Name, PropertyId.ControlType, PropertyId.AutomationId, PropertyId.ClassName, PropertyId.BoundingRectangle, PropertyId.IsEnabled];
+
+export enum AutomationElementMode {
+  /** Cached data only — the returned elements cannot be acted on, but BuildCache is cheaper. */
+  None = 0x0000_0000,
+  /** Full live reference (default) — the returned elements can be acted on. */
+  Full = 0x0000_0001,
+}
+
+export class CacheRequest {
+  readonly ptr: bigint;
+
+  constructor(ptr: bigint) {
+    this.ptr = ptr;
+  }
+
+  /** Prefetch a property (UIA_*PropertyId) for every element the cache covers. */
+  property(propertyId: number): this {
+    vcall(this.ptr, SLOT.AddProperty, [FFIType.i32], [propertyId]);
+    return this;
+  }
+
+  /** Prefetch a pattern (UIA_*PatternId) for every element the cache covers. */
+  pattern(patternId: number): this {
+    vcall(this.ptr, SLOT.AddPattern, [FFIType.i32], [patternId]);
+    return this;
+  }
+
+  /** Set the cache's tree scope (which relatives are cached around each match). */
+  treeScope(scope: number): this {
+    vcall(this.ptr, SLOT.put_TreeScope, [FFIType.i32], [scope]);
+    return this;
+  }
+
+  /** Set whether returned elements keep a live reference (Full) or carry cached data only (None). */
+  elementMode(mode: AutomationElementMode): this {
+    vcall(this.ptr, SLOT.put_AutomationElementMode, [FFIType.i32], [mode]);
+    return this;
+  }
+
+  /** Release the underlying COM pointer. */
+  release(): void {
+    comRelease(this.ptr);
+  }
+}
+
+/** Build a CacheRequest (default: standard property set, subtree scope, Full mode). Caller releases it. */
+export function createCacheRequest(properties: readonly number[] = DEFAULT_CACHE_PROPERTIES, scope: number = TreeScope.TreeScope_Subtree, mode: AutomationElementMode = AutomationElementMode.Full): CacheRequest {
+  const out = Buffer.alloc(8);
+  if (vcall(automation(), SLOT.CreateCacheRequest, [FFIType.ptr], [out.ptr!]) !== S_OK) throw new Error('CreateCacheRequest failed');
+  const request = new CacheRequest(out.readBigUInt64LE(0));
+  for (const propertyId of properties) request.property(propertyId);
+  request.treeScope(scope);
+  request.elementMode(mode);
+  return request;
+}

package/com.ts

@@ -0,0 +1,62 @@
+// The cast-free COM vtable invoker, GUID packing, and IUnknown teardown primitive.
+
+import { CFunction, FFIType, type Pointer, read } from 'bun:ffi';
+
+import Combase from '@bun-win32/combase';
+
+import { IUNKNOWN_RELEASE, S_OK } from './constants';
+
+// Keyed by the resolved method pointer (a plain number — user-mode addresses fit 2^53 and number
+// Map keys hash faster than bigint in JSC). A COM method has exactly one signature, so the method
+// pointer uniquely identifies it; the per-call vtable walk stays (an address can be reallocated to
+// a different object — the method pointer cannot lie). Every UIA method returns HRESULT, so i32-only.
+const invokers = new Map<number, ReturnType<typeof CFunction>>();
+
+/**
+ * Invoke the COM method at vtable `slot` on interface pointer `thisPtr`, returning its HRESULT.
+ * `argTypes`/`args` EXCLUDE the implicit `this` — the invoker prepends `FFIType.u64` (a spurious
+ * leading u64 segfaults multi-pointer calls). `argTypes` must match the method's real signature.
+ */
+export function vcall(thisPtr: bigint, slot: number, argTypes: readonly FFIType[], args: readonly unknown[]): number {
+  const vtable = read.ptr(Number(thisPtr) as Pointer, 0);
+  const method = read.ptr(Number(vtable) as Pointer, slot * 8);
+  let invoke = invokers.get(method);
+  if (invoke === undefined) {
+    invoke = CFunction({ ptr: Number(method) as Pointer, args: [FFIType.u64, ...argTypes], returns: FFIType.i32 });
+    invokers.set(method, invoke);
+  }
+  // Arity-specialized dispatch — spreading into a native CFunction costs ~16 ns/call (measured).
+  switch (args.length) {
+    case 0:
+      return Number(invoke(thisPtr));
+    case 1:
+      return Number(invoke(thisPtr, args[0]));
+    case 2:
+      return Number(invoke(thisPtr, args[0], args[1]));
+    case 3:
+      return Number(invoke(thisPtr, args[0], args[1], args[2]));
+    case 4:
+      return Number(invoke(thisPtr, args[0], args[1], args[2], args[3]));
+    default:
+      return Number(invoke(thisPtr, ...args));
+  }
+}
+
+/** Release a COM interface (IUnknown::Release, slot 2). No-op on a null handle. */
+export function comRelease(thisPtr: bigint): void {
+  if (thisPtr !== 0n) vcall(thisPtr, IUNKNOWN_RELEASE, [], []);
+}
+
+/** Parse a `{...}` GUID string into a 16-byte little-endian CLSID/IID buffer via CLSIDFromString. */
+export function guid(text: string): Buffer {
+  const wide = Buffer.from(`${text}\0`, 'utf16le');
+  const out = Buffer.alloc(16);
+  const hr = Combase.CLSIDFromString(wide.ptr!, out.ptr!);
+  if (hr !== S_OK) throw new Error(`CLSIDFromString(${text}) failed: ${hresult(hr)}`);
+  return out;
+}
+
+/** Format an HRESULT as `0xXXXXXXXX`. */
+export function hresult(hr: number): string {
+  return `0x${(hr >>> 0).toString(16).padStart(8, '0')}`;
+}

package/condition.ts

@@ -0,0 +1,132 @@
+// The typed Selector: a hybrid of server-side UIA property conditions (one cross-process round-trip
+// filters in the target app's provider, marshaling only matches) and a client-side matcher for the
+// predicates UIA conditions cannot express (regex, substring). Server-side conditions work because
+// the MS x64 ABI passes a 16-byte VARIANT by hidden reference — modeled as a pointer to a VARIANT.
+
+import { FFIType } from 'bun:ffi';
+
+import Oleaut32 from '@bun-win32/oleaut32';
+
+import { comRelease, vcall } from './com';
+import { ControlType, PropertyId, S_OK, SLOT, VT_BSTR, VT_I4 } from './constants';
+
+export interface Selector {
+  automationId?: string;
+  className?: string;
+  controlType?: ControlType | number;
+  /** Exact string (server-side) or a regular expression (client-side). */
+  name?: RegExp | string;
+  /** Substring of the name (client-side). */
+  nameContains?: string;
+}
+
+/** The minimal property surface the client-side matcher reads — `Element` satisfies it. */
+export interface ElementProperties {
+  automationId: string;
+  className: string;
+  controlType: number;
+  name: string;
+}
+
+/** Render a selector as a readable string for error messages. */
+export function selectorToString(selector: Selector): string {
+  const parts: string[] = [];
+  if (selector.controlType !== undefined) parts.push(`controlType: ${ControlType[selector.controlType] ?? selector.controlType}`);
+  if (selector.name !== undefined) parts.push(`name: ${selector.name instanceof RegExp ? selector.name.toString() : JSON.stringify(selector.name)}`);
+  if (selector.nameContains !== undefined) parts.push(`nameContains: ${JSON.stringify(selector.nameContains)}`);
+  if (selector.automationId !== undefined) parts.push(`automationId: ${JSON.stringify(selector.automationId)}`);
+  if (selector.className !== undefined) parts.push(`className: ${JSON.stringify(selector.className)}`);
+  return `{ ${parts.join(', ')} }`;
+}
+
+/** Build the actionable "no element matched … nearest were …" message (the gripe→error design). */
+export function formatNoMatch(selector: Selector, windowName: string, candidateNames: readonly string[]): string {
+  const nearest = candidateNames.filter((candidate) => candidate.trim().length > 0).slice(0, 8);
+  const tail = nearest.length > 0 ? ` — nearest: ${nearest.map((candidate) => JSON.stringify(candidate)).join(', ')}` : '';
+  return `no element matched ${selectorToString(selector)} in "${windowName}"${tail}`;
+}
+
+/** Match a (already-read) element against a selector — all fields AND together. Pure logic. */
+export function matches(element: ElementProperties, selector: Selector): boolean {
+  if (selector.controlType !== undefined && element.controlType !== selector.controlType) return false;
+  if (selector.automationId !== undefined && element.automationId !== selector.automationId) return false;
+  if (selector.className !== undefined && element.className !== selector.className) return false;
+  if (selector.name !== undefined) {
+    if (selector.name instanceof RegExp) {
+      if (!selector.name.test(element.name)) return false;
+    } else if (element.name !== selector.name) return false;
+  }
+  if (selector.nameContains !== undefined && !element.name.includes(selector.nameContains)) return false;
+  return true;
+}
+
+function propertyConditionInt(pAutomation: bigint, propertyId: number, value: number): bigint {
+  const variant = Buffer.alloc(16);
+  variant.writeUInt16LE(VT_I4, 0);
+  variant.writeInt32LE(value, 8);
+  const out = Buffer.alloc(8);
+  if (vcall(pAutomation, SLOT.CreatePropertyCondition, [FFIType.i32, FFIType.ptr, FFIType.ptr], [propertyId, variant.ptr!, out.ptr!]) !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+function propertyConditionString(pAutomation: bigint, propertyId: number, value: string): bigint {
+  const bstr = Oleaut32.SysAllocString(Buffer.from(`${value}\0`, 'utf16le').ptr!);
+  const variant = Buffer.alloc(16);
+  variant.writeUInt16LE(VT_BSTR, 0);
+  variant.writeBigUInt64LE(BigInt(bstr), 8);
+  const out = Buffer.alloc(8);
+  const hr = vcall(pAutomation, SLOT.CreatePropertyCondition, [FFIType.i32, FFIType.ptr, FFIType.ptr], [propertyId, variant.ptr!, out.ptr!]);
+  Oleaut32.SysFreeString(bstr); // CreatePropertyCondition copies the VARIANT (SysAllocStrings its own BSTR)
+  if (hr !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+function trueCondition(pAutomation: bigint): bigint {
+  const out = Buffer.alloc(8);
+  if (vcall(pAutomation, SLOT.CreateTrueCondition, [FFIType.ptr], [out.ptr!]) !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+function andCondition(pAutomation: bigint, first: bigint, second: bigint): bigint {
+  const out = Buffer.alloc(8);
+  if (vcall(pAutomation, SLOT.CreateAndCondition, [FFIType.u64, FFIType.u64, FFIType.ptr], [first, second, out.ptr!]) !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+/**
+ * Compile a selector into a server-side condition (the caller must `comRelease` it) plus whether a
+ * client-side `matches` pass is still required. Exact scalars (controlType, name, automationId,
+ * className) become a server-side AND of property conditions; regex/substring fall to the client.
+ */
+export function compileCondition(pAutomation: bigint, selector: Selector): { condition: bigint; needsClientFilter: boolean } {
+  const parts: bigint[] = [];
+  let needsClientFilter = false;
+  if (selector.controlType !== undefined) {
+    const part = propertyConditionInt(pAutomation, PropertyId.ControlType, selector.controlType);
+    if (part !== 0n) parts.push(part);
+  }
+  if (typeof selector.name === 'string') {
+    const part = propertyConditionString(pAutomation, PropertyId.Name, selector.name);
+    if (part !== 0n) parts.push(part);
+  } else if (selector.name instanceof RegExp) {
+    needsClientFilter = true;
+  }
+  if (selector.automationId !== undefined) {
+    const part = propertyConditionString(pAutomation, PropertyId.AutomationId, selector.automationId);
+    if (part !== 0n) parts.push(part);
+  }
+  if (selector.className !== undefined) {
+    const part = propertyConditionString(pAutomation, PropertyId.ClassName, selector.className);
+    if (part !== 0n) parts.push(part);
+  }
+  if (selector.nameContains !== undefined) needsClientFilter = true;
+  if (parts.length === 0) return { condition: trueCondition(pAutomation), needsClientFilter: true };
+  let condition = parts[0]!;
+  for (let index = 1; index < parts.length; index += 1) {
+    const combined = andCondition(pAutomation, condition, parts[index]!);
+    comRelease(condition);
+    comRelease(parts[index]!);
+    condition = combined;
+  }
+  return { condition, needsClientFilter };
+}