@bun-win32/uia 1.0.0

package/msaa.ts

@@ -0,0 +1,99 @@
+// MSAA (oleacc IAccessible) fallback for legacy / owner-draw windows that expose no useful UIA tree.
+// IAccessible is IDispatch-derived (IUnknown 0-2, IDispatch 3-6, then its members): get_accChildCount
+// 8, get_accName 10, get_accRole 13. The VARIANT child-id is passed by pointer (the 16-byte aggregate
+// goes by hidden reference). AccessibleChildren returns VARIANTs: VT_DISPATCH → QI to IAccessible;
+// VT_I4 → a simple child-id leaf of the same parent (never a pointer).
+
+import { FFIType } from 'bun:ffi';
+
+import Oleacc, { IID_IAccessible, OBJID } from '@bun-win32/oleacc';
+
+import { comRelease, guid, vcall } from './com';
+import { S_OK, VT_DISPATCH, VT_I4 } from './constants';
+import { decodeBstr } from './reads';
+
+const IACC_QUERYINTERFACE = 0;
+const IACC_GET_ACCCHILDCOUNT = 8;
+const IACC_GET_ACCNAME = 10;
+const IACC_GET_ACCROLE = 13;
+const VARIANT_SIZE = 16;
+const CHILDID_SELF = 0;
+
+export interface MsaaNode {
+  name: string;
+  role: number;
+  children: MsaaNode[];
+}
+
+function childVariant(childId: number): Buffer {
+  const variant = Buffer.alloc(VARIANT_SIZE);
+  variant.writeUInt16LE(VT_I4, 0);
+  variant.writeInt32LE(childId, 8);
+  return variant;
+}
+
+function accName(accessible: bigint, childId: number): string {
+  const out = Buffer.alloc(8);
+  if (vcall(accessible, IACC_GET_ACCNAME, [FFIType.ptr, FFIType.ptr], [childVariant(childId).ptr!, out.ptr!]) !== S_OK) return '';
+  return decodeBstr(out.readBigUInt64LE(0));
+}
+
+function accRole(accessible: bigint, childId: number): number {
+  const roleVariant = Buffer.alloc(VARIANT_SIZE);
+  if (vcall(accessible, IACC_GET_ACCROLE, [FFIType.ptr, FFIType.ptr], [childVariant(childId).ptr!, roleVariant.ptr!]) !== S_OK) return -1;
+  return roleVariant.readUInt16LE(0) === VT_I4 ? roleVariant.readInt32LE(8) : -1;
+}
+
+function accChildCount(accessible: bigint): number {
+  const out = Buffer.alloc(4);
+  if (vcall(accessible, IACC_GET_ACCCHILDCOUNT, [FFIType.ptr], [out.ptr!]) !== S_OK) return 0;
+  return out.readInt32LE(0);
+}
+
+/** Acquire the root IAccessible for a window via MSAA (OBJID_WINDOW). Returns 0n on failure. */
+export function accessibleFromWindow(hWnd: bigint): bigint {
+  const out = Buffer.alloc(8);
+  if (Oleacc.AccessibleObjectFromWindow(hWnd, OBJID.OBJID_WINDOW >>> 0, guid(`{${IID_IAccessible}}`).ptr!, out.ptr!) !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+function walk(accessible: bigint, childId: number, maxDepth: number, depth: number): MsaaNode {
+  const node: MsaaNode = { name: accName(accessible, childId), role: accRole(accessible, childId), children: [] };
+  if (childId !== CHILDID_SELF || depth >= maxDepth) return node;
+  const count = accChildCount(accessible);
+  if (count <= 0) return node;
+  const children = Buffer.alloc(VARIANT_SIZE * count);
+  const obtained = Buffer.alloc(4);
+  if (Oleacc.AccessibleChildren(accessible, 0, count, children.ptr!, obtained.ptr!) !== S_OK) return node;
+  const got = obtained.readInt32LE(0);
+  for (let index = 0; index < got; index += 1) {
+    const base = index * VARIANT_SIZE;
+    const variantType = children.readUInt16LE(base);
+    if (variantType === VT_DISPATCH) {
+      const dispatch = children.readBigUInt64LE(base + 8);
+      if (dispatch === 0n) continue;
+      const childOut = Buffer.alloc(8);
+      const queried = vcall(dispatch, IACC_QUERYINTERFACE, [FFIType.ptr, FFIType.ptr], [guid(`{${IID_IAccessible}}`).ptr!, childOut.ptr!]);
+      const childAccessible = childOut.readBigUInt64LE(0);
+      if (queried === S_OK && childAccessible !== 0n) {
+        node.children.push(walk(childAccessible, CHILDID_SELF, maxDepth, depth + 1));
+        comRelease(childAccessible);
+      }
+      comRelease(dispatch);
+    } else if (variantType === VT_I4) {
+      node.children.push(walk(accessible, children.readInt32LE(base + 8), maxDepth, depth + 1));
+    }
+  }
+  return node;
+}
+
+/** Walk a window's MSAA (IAccessible) tree — the legacy/owner-draw fallback. Null when MSAA is absent. */
+export function msaaTree(hWnd: bigint, maxDepth = 8): MsaaNode | null {
+  const root = accessibleFromWindow(hWnd);
+  if (root === 0n) return null;
+  try {
+    return walk(root, CHILDID_SELF, maxDepth, 0);
+  } finally {
+    comRelease(root);
+  }
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "author": "Stev Peifer <stev.p@outlook.com>",
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "dependencies": {
+    "@bun-win32/combase": "1.1.0",
+    "@bun-win32/core": "1.1.4",
+    "@bun-win32/gdi32": "1.0.14",
+    "@bun-win32/oleacc": "1.0.1",
+    "@bun-win32/oleaut32": "1.0.1",
+    "@bun-win32/user32": "3.0.22"
+  },
+  "description": "Playwright for Windows desktop apps — query the UI Automation accessibility tree, invoke controls by name, type, and assert, from Bun. Zero native dependencies, no node-gyp, no server.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/uia",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ObscuritySRL/bun-win32.git",
+    "directory": "packages/uia"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "accessibility",
+    "automation",
+    "bun",
+    "desktop",
+    "e2e",
+    "ffi",
+    "playwright",
+    "testing",
+    "typescript",
+    "uiautomation",
+    "win32",
+    "windows"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "agent.ts",
+    "automation.ts",
+    "cache.ts",
+    "com.ts",
+    "condition.ts",
+    "constants.ts",
+    "element.ts",
+    "index.ts",
+    "input.ts",
+    "msaa.ts",
+    "patterns.ts",
+    "png.ts",
+    "reads.ts",
+    "tree.ts",
+    "window.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example:agent-grounding": "bun ./example/agent-grounding.ts",
+    "example:automate-calculator": "bun ./example/automate-calculator.ts",
+    "example:benchmark": "bun ./example/benchmark.ts",
+    "example:hello-uia": "bun ./example/hello-uia.ts",
+    "example:inspector": "bun ./example/inspector.ts",
+    "example:selftest": "bun ./example/uia.selftest.ts",
+    "example:uia-report": "bun ./example/uia-report.ts"
+  }
+}

package/patterns.ts

@@ -0,0 +1,234 @@
+// Control-pattern actions. Each acquires the pattern via GetCurrentPattern (slot 16), invokes the
+// method, and releases the pattern interface. State reads return the raw enum number; compare against
+// the exported enums. Patterns the element does not support throw (actions) or return null/-1 (reads),
+// pointing the caller at the SendInput fallbacks (.click()/.type()) where one exists.
+
+import { FFIType, type Pointer } from 'bun:ffi';
+
+import Oleaut32 from '@bun-win32/oleaut32';
+
+import { comRelease, hresult, vcall } from './com';
+import { PatternId, S_OK, SLOT } from './constants';
+import { decodeBstr, getBstr, getDouble, getLong } from './reads';
+
+export enum ToggleState {
+  Off = 0,
+  On = 1,
+  Indeterminate = 2,
+}
+
+export enum ExpandCollapseState {
+  Collapsed = 0,
+  Expanded = 1,
+  PartiallyExpanded = 2,
+  LeafNode = 3,
+}
+
+export enum WindowVisualState {
+  Normal = 0,
+  Maximized = 1,
+  Minimized = 2,
+}
+
+/** Acquire a control pattern interface. Returns 0n when the element does not support it. */
+function getPattern(ptr: bigint, patternId: number): bigint {
+  const out = Buffer.alloc(8);
+  if (vcall(ptr, SLOT.GetCurrentPattern, [FFIType.i32, FFIType.ptr], [patternId, out.ptr!]) !== S_OK) return 0n;
+  return out.readBigUInt64LE(0);
+}
+
+function invokeNoArg(pattern: bigint, slot: number, label: string): void {
+  const hr = vcall(pattern, slot, [], []);
+  if (hr !== S_OK) throw new Error(`${label} failed: ${hresult(hr)}`);
+}
+
+/** Press the element via InvokePattern. */
+export function invoke(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.Invoke);
+  if (pattern === 0n) throw new Error('element does not support InvokePattern — use .click() for the coordinate fallback');
+  try {
+    invokeNoArg(pattern, SLOT.Invoke, 'Invoke');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Set a ValuePattern control's value (e.g. a text box) in one call — no keystrokes, no VARIANT. */
+export function setValue(ptr: bigint, text: string): void {
+  const pattern = getPattern(ptr, PatternId.Value);
+  if (pattern === 0n) throw new Error('element does not support ValuePattern — use .type() to send keystrokes');
+  const bstr = Oleaut32.SysAllocString(Buffer.from(`${text}\0`, 'utf16le').ptr!);
+  try {
+    const hr = vcall(pattern, SLOT.SetValue, [FFIType.ptr], [bstr]);
+    if (hr !== S_OK) throw new Error(`ValuePattern.SetValue failed: ${hresult(hr)}`);
+  } finally {
+    Oleaut32.SysFreeString(bstr);
+    comRelease(pattern);
+  }
+}
+
+/** Read a ValuePattern control's value, or '' if unsupported. */
+export function getValue(ptr: bigint): string {
+  const pattern = getPattern(ptr, PatternId.Value);
+  if (pattern === 0n) return '';
+  try {
+    return getBstr(pattern, SLOT.get_CurrentValue);
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Toggle a TogglePattern control (checkbox). */
+export function toggle(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.Toggle);
+  if (pattern === 0n) throw new Error('element does not support TogglePattern');
+  try {
+    invokeNoArg(pattern, SLOT.Toggle, 'Toggle');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Read a TogglePattern's state (ToggleState), or -1 if unsupported. */
+export function toggleState(ptr: bigint): number {
+  const pattern = getPattern(ptr, PatternId.Toggle);
+  if (pattern === 0n) return -1;
+  try {
+    return getLong(pattern, SLOT.get_CurrentToggleState);
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Expand an ExpandCollapsePattern control (combo box, tree item). */
+export function expand(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.ExpandCollapse);
+  if (pattern === 0n) throw new Error('element does not support ExpandCollapsePattern');
+  try {
+    invokeNoArg(pattern, SLOT.Expand, 'Expand');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Collapse an ExpandCollapsePattern control. */
+export function collapse(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.ExpandCollapse);
+  if (pattern === 0n) throw new Error('element does not support ExpandCollapsePattern');
+  try {
+    invokeNoArg(pattern, SLOT.Collapse, 'Collapse');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Read an ExpandCollapsePattern's state (ExpandCollapseState), or -1 if unsupported. */
+export function expandCollapseState(ptr: bigint): number {
+  const pattern = getPattern(ptr, PatternId.ExpandCollapse);
+  if (pattern === 0n) return -1;
+  try {
+    return getLong(pattern, SLOT.get_CurrentExpandCollapseState);
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Select a SelectionItemPattern control (list item, radio button), replacing the selection. */
+export function select(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.SelectionItem);
+  if (pattern === 0n) throw new Error('element does not support SelectionItemPattern');
+  try {
+    invokeNoArg(pattern, SLOT.Select, 'Select');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Whether a SelectionItemPattern control is selected (false if unsupported). */
+export function isSelected(ptr: bigint): boolean {
+  const pattern = getPattern(ptr, PatternId.SelectionItem);
+  if (pattern === 0n) return false;
+  try {
+    return getLong(pattern, SLOT.get_CurrentIsSelected) !== 0;
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Scroll a ScrollItemPattern control into view within its scrollable container. */
+export function scrollIntoView(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.ScrollItem);
+  if (pattern === 0n) throw new Error('element does not support ScrollItemPattern');
+  try {
+    invokeNoArg(pattern, SLOT.ScrollIntoView, 'ScrollIntoView');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Set a RangeValuePattern control's value (slider). Throws if unsupported. */
+export function setRangeValue(ptr: bigint, value: number): void {
+  const pattern = getPattern(ptr, PatternId.RangeValue);
+  if (pattern === 0n) throw new Error('element does not support RangeValuePattern');
+  try {
+    const hr = vcall(pattern, SLOT.SetValue, [FFIType.f64], [value]);
+    if (hr !== S_OK) throw new Error(`RangeValuePattern.SetValue failed: ${hresult(hr)}`);
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Read a RangeValuePattern control's value (slider), or NaN if unsupported. */
+export function rangeValue(ptr: bigint): number {
+  const pattern = getPattern(ptr, PatternId.RangeValue);
+  if (pattern === 0n) return Number.NaN;
+  try {
+    return getDouble(pattern, SLOT.get_CurrentValue);
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Read the full text of a TextPattern document (the document range), or '' if unsupported. */
+export function readText(ptr: bigint): string {
+  const pattern = getPattern(ptr, PatternId.Text);
+  if (pattern === 0n) return '';
+  try {
+    const rangeOut = Buffer.alloc(8);
+    if (vcall(pattern, SLOT.get_DocumentRange, [FFIType.ptr], [rangeOut.ptr!]) !== S_OK) return '';
+    const range = rangeOut.readBigUInt64LE(0);
+    if (range === 0n) return '';
+    try {
+      const textOut = Buffer.alloc(8);
+      if (vcall(range, SLOT.GetText, [FFIType.i32, FFIType.ptr], [-1, textOut.ptr!]) !== S_OK) return '';
+      return decodeBstr(textOut.readBigUInt64LE(0));
+    } finally {
+      comRelease(range);
+    }
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Close a window via WindowPattern. */
+export function windowClose(ptr: bigint): void {
+  const pattern = getPattern(ptr, PatternId.Window);
+  if (pattern === 0n) throw new Error('element does not support WindowPattern');
+  try {
+    invokeNoArg(pattern, SLOT.Close, 'Close');
+  } finally {
+    comRelease(pattern);
+  }
+}
+
+/** Set a window's visual state (normal/maximized/minimized) via WindowPattern. */
+export function setWindowVisualState(ptr: bigint, state: WindowVisualState): void {
+  const pattern = getPattern(ptr, PatternId.Window);
+  if (pattern === 0n) throw new Error('element does not support WindowPattern');
+  try {
+    const hr = vcall(pattern, SLOT.SetWindowVisualState, [FFIType.i32], [state]);
+    if (hr !== S_OK) throw new Error(`SetWindowVisualState failed: ${hresult(hr)}`);
+  } finally {
+    comRelease(pattern);
+  }
+}

package/png.ts

@@ -0,0 +1,75 @@
+// Minimal pure-TS PNG encoder (adapted from @bun-win32/terminal's png.ts) for PrintWindow screenshots.
+// `Bun.deflateSync` returns a raw DEFLATE stream, so the IDAT payload is hand-wrapped in a zlib
+// container (0x78 0x01 + data + Adler-32 of the unfiltered scanlines).
+
+const crcTable = (() => {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index++) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    table[index] = value >>> 0;
+  }
+  return table;
+})();
+
+const crc32 = (bytes: Uint8Array): number => {
+  let value = 0xffffffff;
+  for (let index = 0; index < bytes.length; index++) value = crcTable[(value ^ bytes[index]!) & 0xff]! ^ (value >>> 8);
+  return (value ^ 0xffffffff) >>> 0;
+};
+
+const adler32 = (bytes: Uint8Array): number => {
+  let low = 1;
+  let high = 0;
+  for (let index = 0; index < bytes.length; index++) {
+    low = (low + bytes[index]!) % 65521;
+    high = (high + low) % 65521;
+  }
+  return ((high << 16) | low) >>> 0;
+};
+
+const uint32BigEndian = (value: number): Uint8Array => Uint8Array.of((value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+
+const pngChunk = (type: string, data: Uint8Array): Uint8Array => {
+  const typeBytes = Uint8Array.from(type, (character) => character.charCodeAt(0));
+  const body = new Uint8Array(typeBytes.length + data.length);
+  body.set(typeBytes, 0);
+  body.set(data, typeBytes.length);
+  const chunk = new Uint8Array(4 + body.length + 4);
+  chunk.set(uint32BigEndian(data.length), 0);
+  chunk.set(body, 4);
+  chunk.set(uint32BigEndian(crc32(body)), 4 + body.length);
+  return chunk;
+};
+
+/** Encode a tightly packed width×height RGB8 buffer to a PNG byte array. */
+export const encodePNG = (rgbPixels: Uint8Array, width: number, height: number): Uint8Array => {
+  const scanlineLength = 1 + width * 3;
+  const filtered = new Uint8Array(height * scanlineLength);
+  for (let row = 0; row < height; row++) {
+    filtered[row * scanlineLength] = 0;
+    filtered.set(rgbPixels.subarray(row * width * 3, (row + 1) * width * 3), row * scanlineLength + 1);
+  }
+  const deflated = Bun.deflateSync(filtered);
+  const zlib = new Uint8Array(2 + deflated.length + 4);
+  zlib[0] = 0x78;
+  zlib[1] = 0x01;
+  zlib.set(deflated, 2);
+  zlib.set(uint32BigEndian(adler32(filtered)), 2 + deflated.length);
+  const headerData = new Uint8Array(13);
+  headerData.set(uint32BigEndian(width), 0);
+  headerData.set(uint32BigEndian(height), 4);
+  headerData[8] = 8;
+  headerData[9] = 2;
+  const signature = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10);
+  const chunks = [signature, pngChunk('IHDR', headerData), pngChunk('IDAT', zlib), pngChunk('IEND', new Uint8Array(0))];
+  let totalLength = 0;
+  for (const chunk of chunks) totalLength += chunk.length;
+  const png = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    png.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return png;
+};

package/reads.ts

@@ -0,0 +1,66 @@
+// Typed property readers built on the COM vtable invoker. Out-parameters use hoisted, reused scratch
+// buffers (no per-read allocation); each value is read out immediately so the buffers never alias a
+// live value, and `.ptr` is read inline at each call (small Buffers relocate — never cache it). BSTR
+// names are bulk-copied in one operation BEFORE SysFreeString (never per-character, never after free).
+
+import { FFIType, type Pointer, toArrayBuffer } from 'bun:ffi';
+
+import Oleaut32 from '@bun-win32/oleaut32';
+
+import { vcall } from './com';
+import { S_OK } from './constants';
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+const scratch8 = Buffer.alloc(8);
+const scratch4 = Buffer.alloc(4);
+const scratch16 = Buffer.alloc(16);
+
+/** Bulk-copy a BSTR's UTF-16 region into a string in one operation, then free it. No-op on null. */
+export function decodeBstr(bstr: bigint): string {
+  if (bstr === 0n) return '';
+  const pointer = Number(bstr) as Pointer;
+  const length = Oleaut32.SysStringLen(pointer); // characters, not bytes
+  const text = length === 0 ? '' : Buffer.from(toArrayBuffer(pointer, 0, length * 2)).toString('utf16le');
+  Oleaut32.SysFreeString(pointer);
+  return text;
+}
+
+/** Read a `[propget] BSTR*` accessor, bulk-copying the UTF-16 region before freeing the BSTR. */
+export function getBstr(ptr: bigint, slot: number): string {
+  if (vcall(ptr, slot, [FFIType.ptr], [scratch8.ptr!]) !== S_OK) return '';
+  return decodeBstr(scratch8.readBigUInt64LE(0));
+}
+
+/** Read a `[propget] LONG*` (or BOOL*) accessor. */
+export function getLong(ptr: bigint, slot: number): number {
+  if (vcall(ptr, slot, [FFIType.ptr], [scratch4.ptr!]) !== S_OK) return 0;
+  return scratch4.readInt32LE(0);
+}
+
+/** Read a `[propget] double*` accessor (e.g. RangeValuePattern values). */
+export function getDouble(ptr: bigint, slot: number): number {
+  if (vcall(ptr, slot, [FFIType.ptr], [scratch8.ptr!]) !== S_OK) return Number.NaN;
+  return scratch8.readDoubleLE(0);
+}
+
+/** Read a `[propget] UIA_HWND*` / handle accessor. */
+export function getHandle(ptr: bigint, slot: number): bigint {
+  if (vcall(ptr, slot, [FFIType.ptr], [scratch8.ptr!]) !== S_OK) return 0n;
+  return scratch8.readBigUInt64LE(0);
+}
+
+/** Read a `[propget] RECT*` accessor (4× LONG) into an {x,y,width,height} rectangle. */
+export function getRect(ptr: bigint, slot: number): Rect {
+  if (vcall(ptr, slot, [FFIType.ptr], [scratch16.ptr!]) !== S_OK) return { x: 0, y: 0, width: 0, height: 0 };
+  const left = scratch16.readInt32LE(0);
+  const top = scratch16.readInt32LE(4);
+  const right = scratch16.readInt32LE(8);
+  const bottom = scratch16.readInt32LE(12);
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}

package/tree.ts

@@ -0,0 +1,95 @@
+// Agent grounding: serialize a window's accessibility subtree to compact JSON for an LLM — ground-truth
+// element identity + bounds, no pixel-counting. One BuildUpdatedCache round-trip prefetches the whole
+// subtree; the recursion then reads cached children/properties in-process. The agent profile prunes to
+// interactive + named controls (fewer tokens) the way Microsoft UFO2 grounds desktop agents.
+
+import { AutomationElementMode, createCacheRequest } from './cache';
+import { ControlType, TreeScope } from './constants';
+import type { Element } from './element';
+import type { Rect } from './reads';
+
+export interface UiaNode {
+  role: string;
+  name: string;
+  automationId?: string;
+  className?: string;
+  bounds?: Rect;
+  enabled?: boolean;
+  children: UiaNode[];
+}
+
+export interface SerializeOptions {
+  /** Maximum tree depth (default 40). */
+  maxDepth?: number;
+  /** Prune to interactive/named controls — the compact profile to hand an LLM agent. */
+  agentProfile?: boolean;
+}
+
+const INTERACTIVE = new Set<number>([
+  ControlType.Button,
+  ControlType.CheckBox,
+  ControlType.ComboBox,
+  ControlType.Document,
+  ControlType.Edit,
+  ControlType.Hyperlink,
+  ControlType.ListItem,
+  ControlType.MenuItem,
+  ControlType.RadioButton,
+  ControlType.Slider,
+  ControlType.Spinner,
+  ControlType.SplitButton,
+  ControlType.TabItem,
+  ControlType.TreeItem,
+]);
+
+function walk(element: Element, options: SerializeOptions, maxDepth: number, depth: number): UiaNode | null {
+  const controlType = element.cachedControlType;
+  const node: UiaNode = {
+    role: ControlType[controlType] ?? `Type(${controlType})`,
+    name: element.cachedName,
+    children: [],
+  };
+  const automationId = element.cachedAutomationId;
+  if (automationId.length > 0) node.automationId = automationId;
+  const className = element.cachedClassName;
+  if (className.length > 0) node.className = className;
+  const bounds = element.cachedBoundingRectangle;
+  if (bounds.width !== 0 || bounds.height !== 0) node.bounds = bounds;
+  node.enabled = element.cachedIsEnabled;
+
+  if (depth < maxDepth) {
+    for (const child of element.cachedChildren) {
+      const childNode = walk(child, options, maxDepth, depth + 1);
+      child.release();
+      if (childNode !== null) node.children.push(childNode);
+    }
+  }
+
+  if (options.agentProfile && node.children.length === 0 && node.name.trim().length === 0 && !INTERACTIVE.has(controlType)) return null;
+  return node;
+}
+
+/** Serialize an element's subtree to a JSON-able tree. Build once via a single cached round-trip. */
+export function serialize(element: Element, options: SerializeOptions = {}): UiaNode {
+  const maxDepth = options.maxDepth ?? 40;
+  const request = createCacheRequest(undefined, TreeScope.TreeScope_Subtree, AutomationElementMode.None);
+  const cached = element.buildUpdatedCache(request);
+  try {
+    return walk(cached, options, maxDepth, 0) ?? { role: 'Pane', name: '', children: [] };
+  } finally {
+    request.release();
+    if (cached.ptr !== element.ptr) cached.release();
+  }
+}
+
+/** Count the nodes in a serialized tree (for benchmarks / agent-grounding stats). */
+export function countNodes(node: UiaNode): number {
+  let total = 1;
+  for (const child of node.children) total += countNodes(child);
+  return total;
+}
+
+/** Rough token estimate of the JSON form (~4 chars/token) — what an agent pays per grounding step. */
+export function estimateTokens(node: UiaNode): number {
+  return Math.ceil(JSON.stringify(node).length / 4);
+}