@bun-win32/uia 1.0.0

package/element.ts

@@ -0,0 +1,512 @@
+// Element: a live IUIAutomationElement pointer with typed property reads, tree search, and the
+// proven control-pattern actions. Property readers live in reads.ts; pattern actions in patterns.ts.
+
+import { FFIType } from 'bun:ffi';
+
+import User32 from '@bun-win32/user32';
+
+import { automation } from './automation';
+import type { CacheRequest } from './cache';
+import { comRelease, hresult, vcall } from './com';
+import { compileCondition, type ElementProperties, formatNoMatch, matches, type Selector } from './condition';
+import { ControlType, S_OK, SLOT, TreeScope } from './constants';
+import { clickAt, type as inputType } from './input';
+import { screenshot as windowScreenshot, windowForProcess } from './window';
+import {
+  collapse,
+  expand,
+  expandCollapseState,
+  getValue,
+  invoke,
+  isSelected,
+  rangeValue,
+  readText,
+  scrollIntoView,
+  select,
+  setRangeValue,
+  setValue,
+  setWindowVisualState,
+  toggle,
+  toggleState,
+  windowClose,
+  type WindowVisualState,
+} from './patterns';
+import { getBstr, getHandle, getLong, getRect, type Rect } from './reads';
+
+// Reused scratch for out-parameters in the tree-search path. Each value is read out immediately.
+const scratch8 = Buffer.alloc(8);
+const scratch4 = Buffer.alloc(4);
+
+/** Read the four properties the client-side matcher needs, in one pass (live). */
+function readProperties(ptr: bigint): ElementProperties {
+  return {
+    automationId: getBstr(ptr, SLOT.get_CurrentAutomationId),
+    className: getBstr(ptr, SLOT.get_CurrentClassName),
+    controlType: getLong(ptr, SLOT.get_CurrentControlType),
+    name: getBstr(ptr, SLOT.get_CurrentName),
+  };
+}
+
+/** Read the matcher's four properties from the prefetched cache (zero further round-trips). */
+function readCachedProperties(ptr: bigint): ElementProperties {
+  return {
+    automationId: getBstr(ptr, SLOT.get_CachedAutomationId),
+    className: getBstr(ptr, SLOT.get_CachedClassName),
+    controlType: getLong(ptr, SLOT.get_CachedControlType),
+    name: getBstr(ptr, SLOT.get_CachedName),
+  };
+}
+
+function findFirstPointer(scopeElement: bigint, scope: number, condition: bigint): bigint {
+  if (vcall(scopeElement, SLOT.FindFirst, [FFIType.i32, FFIType.u64, FFIType.ptr], [scope, condition, scratch8.ptr!]) !== S_OK) return 0n;
+  return scratch8.readBigUInt64LE(0);
+}
+
+function findAllPointers(scopeElement: bigint, scope: number, condition: bigint): bigint[] {
+  if (vcall(scopeElement, SLOT.FindAll, [FFIType.i32, FFIType.u64, FFIType.ptr], [scope, condition, scratch8.ptr!]) !== S_OK) return [];
+  const pArray = scratch8.readBigUInt64LE(0);
+  if (pArray === 0n) return [];
+  try {
+    if (vcall(pArray, SLOT.get_Length, [FFIType.ptr], [scratch4.ptr!]) !== S_OK) return [];
+    const length = scratch4.readInt32LE(0);
+    const pointers: bigint[] = new Array(length);
+    let count = 0;
+    for (let index = 0; index < length; index += 1) {
+      if (vcall(pArray, SLOT.GetElement, [FFIType.i32, FFIType.ptr], [index, scratch8.ptr!]) !== S_OK) continue;
+      const pointer = scratch8.readBigUInt64LE(0);
+      if (pointer !== 0n) {
+        pointers[count] = pointer;
+        count += 1;
+      }
+    }
+    pointers.length = count;
+    return pointers;
+  } finally {
+    comRelease(pArray);
+  }
+}
+
+export class Element {
+  readonly ptr: bigint;
+
+  constructor(ptr: bigint) {
+    this.ptr = ptr;
+  }
+
+  get automationId(): string {
+    return getBstr(this.ptr, SLOT.get_CurrentAutomationId);
+  }
+
+  get boundingRectangle(): Rect {
+    return getRect(this.ptr, SLOT.get_CurrentBoundingRectangle);
+  }
+
+  get className(): string {
+    return getBstr(this.ptr, SLOT.get_CurrentClassName);
+  }
+
+  get controlType(): number {
+    return getLong(this.ptr, SLOT.get_CurrentControlType);
+  }
+
+  get controlTypeName(): string {
+    const id = this.controlType;
+    return ControlType[id] ?? `Type(${id})`;
+  }
+
+  get isEnabled(): boolean {
+    return getLong(this.ptr, SLOT.get_CurrentIsEnabled) !== 0;
+  }
+
+  get name(): string {
+    return getBstr(this.ptr, SLOT.get_CurrentName);
+  }
+
+  get nativeWindowHandle(): bigint {
+    return getHandle(this.ptr, SLOT.get_CurrentNativeWindowHandle);
+  }
+
+  /** Immediate children (control view) as Elements. The caller owns and should release them. */
+  get children(): Element[] {
+    return this.findAll({}, TreeScope.TreeScope_Children);
+  }
+
+  /** The control-view parent, or null at a root. The caller owns the returned Element. */
+  get parent(): Element | null {
+    if (vcall(automation(), SLOT.get_ControlViewWalker, [FFIType.ptr], [scratch8.ptr!]) !== S_OK) return null;
+    const walker = scratch8.readBigUInt64LE(0);
+    if (walker === 0n) return null;
+    try {
+      if (vcall(walker, SLOT.GetParentElement, [FFIType.u64, FFIType.ptr], [this.ptr, scratch8.ptr!]) !== S_OK) return null;
+      const pointer = scratch8.readBigUInt64LE(0);
+      return pointer === 0n ? null : new Element(pointer);
+    } finally {
+      comRelease(walker);
+    }
+  }
+
+  /** The first descendant (by default) matching the selector, or null. Releases the non-matches. */
+  find(selector: Selector, scope: number = TreeScope.TreeScope_Descendants): Element | null {
+    const pAutomation = automation();
+    const { condition, needsClientFilter } = compileCondition(pAutomation, selector);
+    try {
+      if (!needsClientFilter) {
+        const pointer = findFirstPointer(this.ptr, scope, condition);
+        return pointer === 0n ? null : new Element(pointer);
+      }
+      const pointers = findAllPointers(this.ptr, scope, condition);
+      for (let index = 0; index < pointers.length; index += 1) {
+        const pointer = pointers[index]!;
+        if (matches(readProperties(pointer), selector)) {
+          for (let rest = index + 1; rest < pointers.length; rest += 1) comRelease(pointers[rest]!);
+          return new Element(pointer);
+        }
+        comRelease(pointer);
+      }
+      return null;
+    } finally {
+      comRelease(condition);
+    }
+  }
+
+  /**
+   * Poll `find` until the selector matches or `timeout` (ms) elapses — the killer feature for flaky
+   * native UIs. Paced by an async sleep (never busy-spins). On timeout, throws an error quoting the
+   * selector, this element's name, and the nearest candidates.
+   */
+  async waitFor(selector: Selector, options: { timeout?: number; interval?: number } = {}): Promise<Element> {
+    const timeout = options.timeout ?? 5000;
+    const interval = options.interval ?? 100;
+    const start = Bun.nanoseconds();
+    for (;;) {
+      const found = this.find(selector);
+      if (found !== null) return found;
+      if ((Bun.nanoseconds() - start) / 1e6 >= timeout) throw new Error(this.describeNoMatch(selector));
+      await Bun.sleep(interval);
+    }
+  }
+
+  /** Build the actionable no-match message by scanning the candidate set under this element. */
+  describeNoMatch(selector: Selector): string {
+    const candidates = this.findAll(selector.controlType !== undefined ? { controlType: selector.controlType } : {});
+    const names = candidates.map((candidate) => candidate.name);
+    for (const candidate of candidates) candidate.release();
+    return formatNoMatch(selector, this.name, names);
+  }
+
+  /** Every descendant (by default) matching the selector. The caller owns and should release them. */
+  findAll(selector: Selector, scope: number = TreeScope.TreeScope_Descendants): Element[] {
+    const pAutomation = automation();
+    const { condition, needsClientFilter } = compileCondition(pAutomation, selector);
+    try {
+      const pointers = findAllPointers(this.ptr, scope, condition);
+      if (!needsClientFilter) return pointers.map((pointer) => new Element(pointer));
+      const result: Element[] = [];
+      for (const pointer of pointers) {
+        if (matches(readProperties(pointer), selector)) result.push(new Element(pointer));
+        else comRelease(pointer);
+      }
+      return result;
+    } finally {
+      comRelease(condition);
+    }
+  }
+
+  /**
+   * Every descendant matching the selector, prefetched through one cached round-trip. The returned
+   * Elements expose their cached* properties with zero further round-trips. The caller owns them.
+   */
+  findAllCached(selector: Selector, request: CacheRequest, scope: number = TreeScope.TreeScope_Descendants): Element[] {
+    const pAutomation = automation();
+    const { condition, needsClientFilter } = compileCondition(pAutomation, selector);
+    try {
+      if (vcall(this.ptr, SLOT.FindAllBuildCache, [FFIType.i32, FFIType.u64, FFIType.u64, FFIType.ptr], [scope, condition, request.ptr, scratch8.ptr!]) !== S_OK) return [];
+      const pArray = scratch8.readBigUInt64LE(0);
+      if (pArray === 0n) return [];
+      try {
+        if (vcall(pArray, SLOT.get_Length, [FFIType.ptr], [scratch4.ptr!]) !== S_OK) return [];
+        const length = scratch4.readInt32LE(0);
+        const result: Element[] = [];
+        for (let index = 0; index < length; index += 1) {
+          if (vcall(pArray, SLOT.GetElement, [FFIType.i32, FFIType.ptr], [index, scratch8.ptr!]) !== S_OK) continue;
+          const pointer = scratch8.readBigUInt64LE(0);
+          if (pointer === 0n) continue;
+          if (!needsClientFilter || matches(readCachedProperties(pointer), selector)) result.push(new Element(pointer));
+          else comRelease(pointer);
+        }
+        return result;
+      } finally {
+        comRelease(pArray);
+      }
+    } finally {
+      comRelease(condition);
+    }
+  }
+
+  /** Refresh this element's cache (properties + structure) per the request. Returns the cached element. */
+  buildUpdatedCache(request: CacheRequest): Element {
+    if (vcall(this.ptr, SLOT.BuildUpdatedCache, [FFIType.u64, FFIType.ptr], [request.ptr, scratch8.ptr!]) !== S_OK) return this;
+    const pointer = scratch8.readBigUInt64LE(0);
+    return pointer === 0n ? this : new Element(pointer);
+  }
+
+  // --- cached property reads (valid only on elements returned by findAllCached / buildUpdatedCache) ---
+
+  /** Cached immediate children (in-proc; valid after a Subtree-scoped buildUpdatedCache). */
+  get cachedChildren(): Element[] {
+    if (vcall(this.ptr, SLOT.GetCachedChildren, [FFIType.ptr], [scratch8.ptr!]) !== S_OK) return [];
+    const pArray = scratch8.readBigUInt64LE(0);
+    if (pArray === 0n) return [];
+    try {
+      if (vcall(pArray, SLOT.get_Length, [FFIType.ptr], [scratch4.ptr!]) !== S_OK) return [];
+      const length = scratch4.readInt32LE(0);
+      const children: Element[] = new Array(length);
+      let count = 0;
+      for (let index = 0; index < length; index += 1) {
+        if (vcall(pArray, SLOT.GetElement, [FFIType.i32, FFIType.ptr], [index, scratch8.ptr!]) !== S_OK) continue;
+        const pointer = scratch8.readBigUInt64LE(0);
+        if (pointer !== 0n) {
+          children[count] = new Element(pointer);
+          count += 1;
+        }
+      }
+      children.length = count;
+      return children;
+    } finally {
+      comRelease(pArray);
+    }
+  }
+
+  get cachedAutomationId(): string {
+    return getBstr(this.ptr, SLOT.get_CachedAutomationId);
+  }
+
+  get cachedBoundingRectangle(): Rect {
+    return getRect(this.ptr, SLOT.get_CachedBoundingRectangle);
+  }
+
+  get cachedClassName(): string {
+    return getBstr(this.ptr, SLOT.get_CachedClassName);
+  }
+
+  get cachedControlType(): number {
+    return getLong(this.ptr, SLOT.get_CachedControlType);
+  }
+
+  get cachedIsEnabled(): boolean {
+    return getLong(this.ptr, SLOT.get_CachedIsEnabled) !== 0;
+  }
+
+  get cachedName(): string {
+    return getBstr(this.ptr, SLOT.get_CachedName);
+  }
+
+  /** Release the underlying COM pointer. */
+  release(): void {
+    comRelease(this.ptr);
+  }
+
+  // --- control-pattern actions (each proven against a real control in Phase 5) ---
+
+  /** Press via InvokePattern. Throws if unsupported (try `.click()`). */
+  invoke(): void {
+    invoke(this.ptr);
+  }
+
+  /** Read a ValuePattern value (e.g. a text box), or '' if unsupported. */
+  get value(): string {
+    return getValue(this.ptr);
+  }
+
+  /** Set a ValuePattern value in one call — no keystrokes. Throws if unsupported (try `.type()`). */
+  setValue(text: string): void {
+    setValue(this.ptr, text);
+  }
+
+  /** Read the TextPattern document text, or '' if unsupported. */
+  text(): string {
+    return readText(this.ptr);
+  }
+
+  /** Toggle a checkbox via TogglePattern. Throws if unsupported. */
+  toggle(): void {
+    toggle(this.ptr);
+  }
+
+  /** TogglePattern state (0 Off, 1 On, 2 Indeterminate), or -1 if unsupported. */
+  get toggleState(): number {
+    return toggleState(this.ptr);
+  }
+
+  /** Expand via ExpandCollapsePattern. Throws if unsupported. */
+  expand(): void {
+    expand(this.ptr);
+  }
+
+  /** Collapse via ExpandCollapsePattern. Throws if unsupported. */
+  collapse(): void {
+    collapse(this.ptr);
+  }
+
+  /** ExpandCollapsePattern state (0 Collapsed, 1 Expanded, 2 Partial, 3 Leaf), or -1 if unsupported. */
+  get expandCollapseState(): number {
+    return expandCollapseState(this.ptr);
+  }
+
+  /** Select via SelectionItemPattern, replacing the selection. Throws if unsupported. */
+  select(): void {
+    select(this.ptr);
+  }
+
+  /** Whether selected (SelectionItemPattern); false if unsupported. */
+  get isSelected(): boolean {
+    return isSelected(this.ptr);
+  }
+
+  /** Scroll into view via ScrollItemPattern. Throws if unsupported. */
+  scrollIntoView(): void {
+    scrollIntoView(this.ptr);
+  }
+
+  /** RangeValuePattern value (slider), or NaN if unsupported. */
+  get rangeValue(): number {
+    return rangeValue(this.ptr);
+  }
+
+  /** Set a RangeValuePattern value (slider). Throws if unsupported. */
+  setRangeValue(value: number): void {
+    setRangeValue(this.ptr, value);
+  }
+
+  /** Close a window via WindowPattern. Throws if unsupported. */
+  close(): void {
+    windowClose(this.ptr);
+  }
+
+  /** Set a window's visual state (WindowVisualState) via WindowPattern. Throws if unsupported. */
+  setVisualState(state: WindowVisualState): void {
+    setWindowVisualState(this.ptr, state);
+  }
+
+  // --- synthetic input fallbacks (SendInput) for controls without a usable pattern ---
+
+  /** Give the element keyboard focus (UIA SetFocus). Returns this for chaining. */
+  focus(): this {
+    vcall(this.ptr, SLOT.SetFocus, [], []);
+    return this;
+  }
+
+  /** Focus the element, then type Unicode text into it via SendInput. Returns this for chaining. */
+  type(text: string): this {
+    this.focus();
+    inputType(text);
+    return this;
+  }
+
+  /** Click the element's bounding-rectangle center via SendInput (the no-InvokePattern fallback). */
+  click(): this {
+    const hWnd = this.nativeWindowHandle;
+    if (hWnd !== 0n) User32.SetForegroundWindow(hWnd);
+    const rect = this.boundingRectangle;
+    clickAt(rect.x + Math.floor(rect.width / 2), rect.y + Math.floor(rect.height / 2));
+    return this;
+  }
+}
+
+/** Attach an Element to a window handle (ElementFromHandle, slot 6 — NativeWindowHandle round-trips). */
+export function fromHandle(hWnd: bigint): Element {
+  const hr = vcall(automation(), SLOT.ElementFromHandle, [FFIType.u64, FFIType.ptr], [hWnd, scratch8.ptr!]);
+  const pointer = scratch8.readBigUInt64LE(0);
+  if (hr !== S_OK || pointer === 0n) throw new Error(`ElementFromHandle(0x${hWnd.toString(16)}) failed: ${hresult(hr)}`);
+  return new Element(pointer);
+}
+
+/** The element with keyboard focus. */
+export function focused(): Element {
+  const hr = vcall(automation(), SLOT.GetFocusedElement, [FFIType.ptr], [scratch8.ptr!]);
+  const pointer = scratch8.readBigUInt64LE(0);
+  if (hr !== S_OK || pointer === 0n) throw new Error(`GetFocusedElement failed: ${hresult(hr)}`);
+  return new Element(pointer);
+}
+
+/** The element at a screen point (POINT packed by value: x in the low dword, y in the high dword). */
+export function fromPoint(x: number, y: number): Element {
+  const point = (BigInt(y >>> 0) << 32n) | BigInt(x >>> 0);
+  const hr = vcall(automation(), SLOT.ElementFromPoint, [FFIType.u64, FFIType.ptr], [point, scratch8.ptr!]);
+  const pointer = scratch8.readBigUInt64LE(0);
+  if (hr !== S_OK || pointer === 0n) throw new Error(`ElementFromPoint(${x},${y}) failed: ${hresult(hr)}`);
+  return new Element(pointer);
+}
+
+/** The desktop root element. Never FindAll(Descendants) from here — scope to a window. */
+export function root(): Element {
+  const hr = vcall(automation(), SLOT.GetRootElement, [FFIType.ptr], [scratch8.ptr!]);
+  const pointer = scratch8.readBigUInt64LE(0);
+  if (hr !== S_OK || pointer === 0n) throw new Error(`GetRootElement failed: ${hresult(hr)}`);
+  return new Element(pointer);
+}
+
+/** A top-level window — an Element scoped to a window handle, with `using`-friendly disposal. */
+export class Window extends Element {
+  readonly hWnd: bigint;
+
+  constructor(ptr: bigint, hWnd: bigint) {
+    super(ptr);
+    this.hWnd = hWnd;
+  }
+
+  /** Bring the window to the foreground (best-effort; blocked on a locked session). */
+  activate(): this {
+    User32.SetForegroundWindow(this.hWnd);
+    return this;
+  }
+
+  /** Capture the window via PrintWindow as PNG bytes (blank on a locked session). */
+  screenshot(): Uint8Array {
+    return windowScreenshot(this.hWnd);
+  }
+
+  /** Release the window element. Enables `using app = uia.attach(...)`. */
+  dispose(): void {
+    this.release();
+  }
+
+  [Symbol.dispose](): void {
+    this.dispose();
+  }
+}
+
+function resolveWindow(target: string | bigint | { className?: string; process?: number; title?: string }): bigint {
+  if (typeof target === 'bigint') return target;
+  if (typeof target !== 'string' && target.process !== undefined) return windowForProcess(target.process);
+  const title = typeof target === 'string' ? target : target.title;
+  const className = typeof target === 'string' ? undefined : target.className;
+  const classBuffer = className === undefined ? null : Buffer.from(`${className}\0`, 'utf16le').ptr!;
+  const titleBuffer = title === undefined ? null : Buffer.from(`${title}\0`, 'utf16le').ptr!;
+  return User32.FindWindowW(classBuffer, titleBuffer);
+}
+
+/** Attach to a top-level window by title, handle, `{ title, className }`, or `{ process }`. Throws if absent. */
+export function attach(target: string | bigint | { className?: string; process?: number; title?: string }): Window {
+  const hWnd = resolveWindow(target);
+  if (hWnd === 0n) throw new Error(`attach: no window found for ${JSON.stringify(target, (_key, value) => (typeof value === 'bigint' ? `0x${value.toString(16)}` : value))}`);
+  const hr = vcall(automation(), SLOT.ElementFromHandle, [FFIType.u64, FFIType.ptr], [hWnd, scratch8.ptr!]);
+  const pointer = scratch8.readBigUInt64LE(0);
+  if (hr !== S_OK || pointer === 0n) throw new Error(`attach: ElementFromHandle failed: ${hresult(hr)}`);
+  return new Window(pointer, hWnd);
+}
+
+/** Spawn a process and wait for its window to appear, then attach — no hand-rolled FindWindow loop. */
+export async function launch(command: string | readonly string[], target: { className?: string; title?: string }, timeout = 8000): Promise<Window> {
+  Bun.spawn(typeof command === 'string' ? command.split(' ') : [...command], { stdout: 'ignore', stderr: 'ignore' });
+  const start = Bun.nanoseconds();
+  for (;;) {
+    const hWnd = resolveWindow(target);
+    if (hWnd !== 0n) {
+      Bun.sleepSync(400); // let the content realize
+      return attach(hWnd);
+    }
+    if ((Bun.nanoseconds() - start) / 1e6 >= timeout) throw new Error(`launch: window ${JSON.stringify(target)} did not appear within ${timeout}ms`);
+    await Bun.sleep(150);
+  }
+}

package/index.ts

@@ -0,0 +1,40 @@
+import { execute } from './agent';
+import { initialize, uninitialize } from './automation';
+import { attach, focused, fromPoint, launch, root } from './element';
+import { clickAt, sendKeys, type } from './input';
+import { msaaTree } from './msaa';
+import { serialize } from './tree';
+import { listWindows } from './window';
+
+/** The Playwright-for-desktop facade: attach to a window, then find/waitFor/act/serialize. */
+export const uia = {
+  attach,
+  click: clickAt,
+  execute,
+  focused,
+  fromPoint,
+  initialize,
+  launch,
+  msaaTree,
+  root,
+  sendKeys,
+  tree: serialize,
+  type,
+  uninitialize,
+  windows: listWindows,
+};
+
+export { type AgentAction, type AgentActionResult, AGENT_TOOLS, execute, groundingTree } from './agent';
+export { automation, initialize, uninitialize } from './automation';
+export { AutomationElementMode, CacheRequest, createCacheRequest, DEFAULT_CACHE_PROPERTIES } from './cache';
+export { comRelease, guid, hresult, vcall } from './com';
+export { type ElementProperties, formatNoMatch, matches, selectorToString, type Selector } from './condition';
+export { ControlType, PatternId, PropertyConditionFlags, PropertyId, SLOT, TreeScope } from './constants';
+export { attach, Element, focused, fromHandle, fromPoint, launch, root, Window } from './element';
+export { clickAt, INPUT_SIZE, packKeyboardInput, packMouseInput, sendKeys, type, virtualKeyCode } from './input';
+export { accessibleFromWindow, type MsaaNode, msaaTree } from './msaa';
+export { ExpandCollapseState, ToggleState, WindowVisualState } from './patterns';
+export { encodePNG } from './png';
+export { decodeBstr, getBstr, getHandle, getLong, getRect, type Rect } from './reads';
+export { countNodes, estimateTokens, serialize, type SerializeOptions, type UiaNode } from './tree';
+export { findWindow, listWindows, screenshot, type WindowInfo, windowForProcess } from './window';

package/input.ts

@@ -0,0 +1,149 @@
+// Synthetic input via SendInput, for the cases UIA patterns can't cover: typing into a control with
+// no ValuePattern, and clicking a control with no InvokePattern. Greenfield — the x64 INPUT struct is
+// 40 bytes (DWORD type @0, 4 pad, union @8: MOUSEINPUT 32B / KEYBDINPUT 24B with ULONG_PTR fields
+// 8-byte aligned). cbSize MUST be 40 or SendInput silently injects nothing.
+
+import User32 from '@bun-win32/user32';
+
+export const INPUT_MOUSE = 0x0000_0000;
+export const INPUT_KEYBOARD = 0x0000_0001;
+
+export const KEYEVENTF_EXTENDEDKEY = 0x0000_0001;
+export const KEYEVENTF_KEYUP = 0x0000_0002;
+export const KEYEVENTF_UNICODE = 0x0000_0004;
+export const KEYEVENTF_SCANCODE = 0x0000_0008;
+
+export const MOUSEEVENTF_MOVE = 0x0000_0001;
+export const MOUSEEVENTF_LEFTDOWN = 0x0000_0002;
+export const MOUSEEVENTF_LEFTUP = 0x0000_0004;
+export const MOUSEEVENTF_RIGHTDOWN = 0x0000_0008;
+export const MOUSEEVENTF_RIGHTUP = 0x0000_0010;
+export const MOUSEEVENTF_ABSOLUTE = 0x0000_8000;
+export const MOUSEEVENTF_VIRTUALDESK = 0x0000_4000;
+
+/** sizeof(INPUT) on x64 — pass this as cbSize, or SendInput injects nothing. */
+export const INPUT_SIZE = 40;
+
+const NAMED_KEYS: Record<string, number> = {
+  alt: 0x12,
+  backspace: 0x08,
+  control: 0x11,
+  ctrl: 0x11,
+  del: 0x2e,
+  delete: 0x2e,
+  down: 0x28,
+  end: 0x23,
+  enter: 0x0d,
+  esc: 0x1b,
+  escape: 0x1b,
+  f1: 0x70,
+  f10: 0x79,
+  f11: 0x7a,
+  f12: 0x7b,
+  f2: 0x71,
+  f3: 0x72,
+  f4: 0x73,
+  f5: 0x74,
+  f6: 0x75,
+  f7: 0x76,
+  f8: 0x77,
+  f9: 0x78,
+  home: 0x24,
+  insert: 0x2d,
+  left: 0x25,
+  menu: 0x12,
+  meta: 0x5b,
+  pagedown: 0x22,
+  pageup: 0x21,
+  return: 0x0d,
+  right: 0x27,
+  shift: 0x10,
+  space: 0x20,
+  tab: 0x09,
+  up: 0x26,
+  win: 0x5b,
+};
+
+// Keys that require KEYEVENTF_EXTENDEDKEY to behave correctly across apps.
+const EXTENDED_KEYS = new Set([0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x2d, 0x2e]);
+
+/** Map a key name ('Enter', 'Control', 'A', '5', 'F4') to its virtual-key code. Throws if unknown. */
+export function virtualKeyCode(name: string): number {
+  const lower = name.toLowerCase();
+  if (lower in NAMED_KEYS) return NAMED_KEYS[lower]!;
+  if (name.length === 1) {
+    const code = name.toUpperCase().charCodeAt(0);
+    if ((code >= 0x41 && code <= 0x5a) || (code >= 0x30 && code <= 0x39)) return code;
+  }
+  throw new Error(`unknown key: ${JSON.stringify(name)}`);
+}
+
+/** Pack a KEYBDINPUT-bearing INPUT at `offset` (the buffer must be zero-filled first). */
+export function packKeyboardInput(buffer: Buffer, offset: number, virtualKey: number, scanCode: number, flags: number): void {
+  buffer.writeUInt32LE(INPUT_KEYBOARD, offset); // type @0
+  buffer.writeUInt16LE(virtualKey, offset + 8); // KEYBDINPUT.wVk @8
+  buffer.writeUInt16LE(scanCode, offset + 10); // wScan @10
+  buffer.writeUInt32LE(flags, offset + 12); // dwFlags @12
+  buffer.writeUInt32LE(0, offset + 16); // time @16
+  buffer.writeBigUInt64LE(0n, offset + 24); // dwExtraInfo @24 (ULONG_PTR, 8-byte aligned)
+}
+
+/** Pack a MOUSEINPUT-bearing INPUT at `offset` (the buffer must be zero-filled first). */
+export function packMouseInput(buffer: Buffer, offset: number, dx: number, dy: number, mouseData: number, flags: number): void {
+  buffer.writeUInt32LE(INPUT_MOUSE, offset); // type @0
+  buffer.writeInt32LE(dx, offset + 8); // MOUSEINPUT.dx @8
+  buffer.writeInt32LE(dy, offset + 12); // dy @12
+  buffer.writeUInt32LE(mouseData, offset + 16); // mouseData @16
+  buffer.writeUInt32LE(flags, offset + 20); // dwFlags @20
+  buffer.writeUInt32LE(0, offset + 24); // time @24
+  buffer.writeBigUInt64LE(0n, offset + 32); // dwExtraInfo @32
+}
+
+/** Type Unicode text into the focused control, code unit by code unit (locale/layout-independent). */
+export function type(text: string): void {
+  if (text.length === 0) return;
+  const count = text.length * 2; // down + up per UTF-16 code unit
+  const buffer = Buffer.alloc(count * INPUT_SIZE);
+  let offset = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    packKeyboardInput(buffer, offset, 0, code, KEYEVENTF_UNICODE);
+    offset += INPUT_SIZE;
+    packKeyboardInput(buffer, offset, 0, code, KEYEVENTF_UNICODE | KEYEVENTF_KEYUP);
+    offset += INPUT_SIZE;
+  }
+  User32.SendInput(count, buffer.ptr!, INPUT_SIZE);
+}
+
+/** Send a key chord like 'Enter', 'Control+S', 'Control+Shift+Tab' to the focused control. */
+export function sendKeys(combo: string): void {
+  const parts = combo.split('+').map((part) => part.trim());
+  const key = parts[parts.length - 1]!;
+  const modifiers = parts.slice(0, -1).map(virtualKeyCode);
+  const keyCode = virtualKeyCode(key);
+  const sequence: Array<{ virtualKey: number; flags: number }> = [];
+  for (const modifier of modifiers) sequence.push({ virtualKey: modifier, flags: 0 });
+  sequence.push({ virtualKey: keyCode, flags: EXTENDED_KEYS.has(keyCode) ? KEYEVENTF_EXTENDEDKEY : 0 });
+  sequence.push({ virtualKey: keyCode, flags: KEYEVENTF_KEYUP | (EXTENDED_KEYS.has(keyCode) ? KEYEVENTF_EXTENDEDKEY : 0) });
+  for (let index = modifiers.length - 1; index >= 0; index -= 1) sequence.push({ virtualKey: modifiers[index]!, flags: KEYEVENTF_KEYUP });
+  const buffer = Buffer.alloc(sequence.length * INPUT_SIZE);
+  let offset = 0;
+  for (const event of sequence) {
+    packKeyboardInput(buffer, offset, event.virtualKey, 0, event.flags);
+    offset += INPUT_SIZE;
+  }
+  User32.SendInput(sequence.length, buffer.ptr!, INPUT_SIZE);
+}
+
+/**
+ * Move the cursor to a screen point (physical pixels — the process is DPI-aware) and left-click.
+ * Uses SetCursorPos for exact placement, then SendInput button events. Requires an unlocked,
+ * interactive desktop (synthetic input is blocked on a locked session).
+ */
+export function clickAt(x: number, y: number): void {
+  User32.SetCursorPos(x, y);
+  const buffer = Buffer.alloc(2 * INPUT_SIZE);
+  packMouseInput(buffer, 0, 0, 0, 0, MOUSEEVENTF_LEFTDOWN);
+  packMouseInput(buffer, INPUT_SIZE, 0, 0, 0, MOUSEEVENTF_LEFTUP);
+  User32.SendInput(2, buffer.ptr!, INPUT_SIZE);
+}