@superbased/win-uia

Windows UI Automation (UIA) tree inspector via IUIAutomation. Published as an optional dependency of superbased for AI-agent UI automation; not intended as a standalone consumer surface.

Requirements

• Windows 10 1903+ or Windows 11 (x64 or arm64)
• Node.js 20+
• No runtime permission API. Cross-process UIA reads work at the same integrity level. Reading an app running at higher integrity (admin) requires the caller to run with matching integrity.

Install

npm install @superbased/win-uia

API

import {
  isSupported,
  getTreeForHwnd,
  getTreeForPid,
  getFocusedElement,
} from '@superbased/win-uia';

isSupported();                    // boolean

// Walk the UIA tree rooted at an HWND.
const tree = getTreeForHwnd(0x000F03AE, { maxDepth: 16, includeAttributes: false });

// Or walk rooted at a pid's primary visible window.
getTreeForPid(1234, { maxDepth: 16 });

// Currently-focused element system-wide.
getFocusedElement();              // UiaNode | null

Error shape

try {
  getTreeForHwnd(0xbad);
} catch (err) {
  // err.code is one of:
  //   'uia_init_failed'             — CoCreateInstance(CUIAutomation) failed
  //   'element_from_hwnd_failed'    — ElementFromHandle() rejected the HWND
  //   'no_window_for_pid'           — the pid has no visible top-level window
  //   'uia_walker_failed'           — RawViewWalker construction failed
  // err.hresult may contain the raw HRESULT when applicable.
}

Building from source

npm install
npm run build

Requires Visual Studio 2022 Build Tools (or Visual Studio with "Desktop development with C++" + "Windows 10/11 SDK"). binding.gyp passes /std:c++17, /EHsc, /permissive-, and links oleaut32.lib + ole32.lib.

License

MIT. Authored by Gaja AI Private Limited.