@mseep/clawdcursor 1.5.5

package/dist/platform/windows.js

@@ -0,0 +1,1210 @@
+"use strict";
+/**
+ * Windows PlatformAdapter — all Windows-specific code lives here.
+ *
+ * Strategy:
+ *   - Mouse + keyboard: nut-js directly (no TCC blocking as on macOS)
+ *   - Screenshot: nut-js screen.grab() — no special helper binary
+ *   - Screen size + DPI: System.Windows.Forms.Screen via PowerShell for logical px,
+ *                        compared with nut-js physical px to derive dpiRatio
+ *   - Windows + A11y: persistent PSRunner (../../ps-runner.ts) driving UI Automation
+ *   - Clipboard: Get-Clipboard / Set-Clipboard via PowerShell
+ *   - App launch: Start-Process via PowerShell
+ *
+ * Permissions: Windows has no TCC-style gate — returns all-true.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WindowsAdapter = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const sharp_1 = __importDefault(require("sharp"));
+const nut_js_1 = require("@nut-tree-fork/nut-js");
+const ps_runner_1 = require("./ps-runner");
+const launch_poll_1 = require("./launch-poll");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+// Tunables
+const PS_TIMEOUT_MS = 8_000;
+const CLIPBOARD_TIMEOUT_MS = 3_000;
+class WindowsAdapter {
+    platform = 'win32';
+    screenSize = null;
+    async init() {
+        // Configure nut-js for snappy input; same tuning as native-desktop.ts.
+        nut_js_1.mouse.config.mouseSpeed = 2000;
+        nut_js_1.mouse.config.autoDelayMs = 0;
+        nut_js_1.keyboard.config.autoDelayMs = 0;
+        // Kick off the PowerShell bridge so the ~800ms UIA assembly load happens
+        // in the background. Errors surface on first real a11y call.
+        ps_runner_1.psRunner.start().catch(() => { });
+        // Pre-warm screen size so the first capture / first click isn't paying for it.
+        await this.getScreenSize().catch(() => null);
+    }
+    async shutdown() {
+        try {
+            ps_runner_1.psRunner.stop();
+        }
+        catch { /* */ }
+    }
+    // ─── PERMISSIONS ──────────────────────────────────────────────────
+    async checkPermissions() {
+        // Windows doesn't gate any of these behind TCC-style prompts. If the
+        // user can run the binary at all, they can do input / capture / a11y.
+        return { input: true, accessibility: true, screenRecording: true };
+    }
+    async requestPermissions() {
+        return this.checkPermissions();
+    }
+    // ─── DISPLAY ──────────────────────────────────────────────────────
+    async getScreenSize() {
+        if (this.screenSize)
+            return this.screenSize;
+        // nut-js screen.grab() returns PHYSICAL pixels on Windows.
+        let physicalWidth = 0, physicalHeight = 0;
+        try {
+            const img = await nut_js_1.screen.grab();
+            physicalWidth = img.width;
+            physicalHeight = img.height;
+            img.data = null;
+        }
+        catch { /* fall through with zeros */ }
+        // System.Windows.Forms.Screen returns LOGICAL (DPI-scaled) pixels on Win —
+        // that's the coordinate space nut-js mouse API expects.
+        let logicalWidth = physicalWidth;
+        let logicalHeight = physicalHeight;
+        try {
+            const { stdout } = await execFileAsync('powershell.exe', [
+                '-NoProfile',
+                '-Command',
+                'Add-Type -AssemblyName System.Windows.Forms; ' +
+                    '$s=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; ' +
+                    '"$($s.Width),$($s.Height)"',
+            ], { timeout: PS_TIMEOUT_MS });
+            const [w, h] = stdout.trim().split(',').map(s => parseInt(s, 10));
+            if (w > 0 && h > 0) {
+                logicalWidth = w;
+                logicalHeight = h;
+            }
+        }
+        catch { /* non-fatal — fall back to physical */ }
+        if (!physicalWidth)
+            physicalWidth = logicalWidth;
+        if (!physicalHeight)
+            physicalHeight = logicalHeight;
+        const dpiRatio = physicalWidth > logicalWidth ? physicalWidth / logicalWidth : 1;
+        this.screenSize = {
+            physicalWidth,
+            physicalHeight,
+            logicalWidth,
+            logicalHeight,
+            dpiRatio,
+        };
+        return this.screenSize;
+    }
+    async listDisplays() {
+        // System.Windows.Forms.Screen.AllScreens enumerates every connected
+        // display with bounds + primary flag. We call it via the PS UIA path
+        // we already have warmed up.
+        try {
+            const { stdout } = await execFileAsync('powershell.exe', [
+                '-NoProfile',
+                '-Command',
+                'Add-Type -AssemblyName System.Windows.Forms; ' +
+                    '[System.Windows.Forms.Screen]::AllScreens | ForEach-Object { ' +
+                    '  $b = $_.Bounds; ' +
+                    '  [pscustomobject]@{ ' +
+                    '    name = $_.DeviceName; ' +
+                    '    primary = $_.Primary; ' +
+                    '    x = $b.X; y = $b.Y; w = $b.Width; h = $b.Height ' +
+                    '  } ' +
+                    '} | ConvertTo-Json -Compress',
+            ], { timeout: PS_TIMEOUT_MS });
+            const raw = JSON.parse(stdout.trim() || '[]');
+            const arr = Array.isArray(raw) ? raw : [raw];
+            // Physical pixel dimensions: we can only confidently compute these for
+            // the primary display (via our cached ScreenSize). For secondaries we
+            // assume the same dpiRatio — accurate on homogeneous setups, a safe
+            // approximation on mixed-DPI (caller can override per-monitor later).
+            const size = await this.getScreenSize();
+            return arr.map((s, i) => {
+                const w = Number(s.w) || 0;
+                const h = Number(s.h) || 0;
+                return {
+                    index: i,
+                    label: String(s.name || `Display ${i + 1}`),
+                    primary: !!s.primary,
+                    bounds: { x: Number(s.x) || 0, y: Number(s.y) || 0, width: w, height: h },
+                    physicalSize: {
+                        width: Math.round(w * size.dpiRatio),
+                        height: Math.round(h * size.dpiRatio),
+                    },
+                    dpiRatio: size.dpiRatio,
+                };
+            });
+        }
+        catch {
+            // Fallback to single display so callers don't have to special-case.
+            const size = await this.getScreenSize();
+            return [{
+                    index: 0,
+                    label: 'Display 1',
+                    primary: true,
+                    bounds: { x: 0, y: 0, width: size.logicalWidth, height: size.logicalHeight },
+                    physicalSize: { width: size.physicalWidth, height: size.physicalHeight },
+                    dpiRatio: size.dpiRatio,
+                }];
+        }
+    }
+    async screenshot(opts) {
+        // displayIndex is plumbed through but nut-js's screen.grab() always
+        // captures ALL displays combined. For index selection on Windows,
+        // we crop to the target display's bounds after the grab.
+        const img = await nut_js_1.screen.grab();
+        let srcWidth = img.width;
+        let srcHeight = img.height;
+        let rgba = img.data;
+        let pipeline;
+        if (opts?.displayIndex !== undefined && opts.displayIndex > 0) {
+            const displays = await this.listDisplays();
+            const target = displays[opts.displayIndex];
+            if (target) {
+                // Translate logical bounds into the physical image (nut-js returns
+                // hardware pixels; multiply by dpiRatio).
+                const r = target.dpiRatio || 1;
+                const left = Math.max(0, Math.round(target.bounds.x * r));
+                const top = Math.max(0, Math.round(target.bounds.y * r));
+                const width = Math.max(1, Math.min(Math.round(target.bounds.width * r), img.width - left));
+                const height = Math.max(1, Math.min(Math.round(target.bounds.height * r), img.height - top));
+                pipeline = (0, sharp_1.default)(rgba, { raw: { width: img.width, height: img.height, channels: 4 } })
+                    .extract({ left, top, width, height });
+                srcWidth = width;
+                srcHeight = height;
+            }
+            else {
+                pipeline = (0, sharp_1.default)(rgba, { raw: { width: srcWidth, height: srcHeight, channels: 4 } });
+            }
+        }
+        else {
+            pipeline = (0, sharp_1.default)(rgba, { raw: { width: srcWidth, height: srcHeight, channels: 4 } });
+        }
+        let width = srcWidth;
+        let height = srcHeight;
+        let scaleFactor = 1;
+        if (opts?.maxWidth && srcWidth > opts.maxWidth) {
+            scaleFactor = srcWidth / opts.maxWidth;
+            const newH = Math.round(srcHeight / scaleFactor);
+            pipeline = pipeline.resize(opts.maxWidth, newH, { fit: 'fill', kernel: 'lanczos3' });
+            width = opts.maxWidth;
+            height = newH;
+        }
+        const buffer = await pipeline.png().toBuffer();
+        img.data = null;
+        return { buffer, width, height, scaleFactor };
+    }
+    async screenshotRegion(x, y, w, h) {
+        const img = await nut_js_1.screen.grab();
+        const rx = Math.max(0, Math.min(x, img.width - 1));
+        const ry = Math.max(0, Math.min(y, img.height - 1));
+        const rw = Math.min(w, img.width - rx);
+        const rh = Math.min(h, img.height - ry);
+        const buffer = await (0, sharp_1.default)(img.data, {
+            raw: { width: img.width, height: img.height, channels: 4 },
+        })
+            .extract({ left: rx, top: ry, width: rw, height: rh })
+            .png()
+            .toBuffer();
+        img.data = null;
+        return { buffer, width: rw, height: rh, scaleFactor: 1 };
+    }
+    // ─── WINDOWS ──────────────────────────────────────────────────────
+    async listWindows() {
+        try {
+            const result = await ps_runner_1.psRunner.run({ cmd: 'get-screen-context', maxDepth: 0 });
+            const raw = Array.isArray(result?.windows) ? result.windows : [];
+            return raw.map(this.normalizeWindow);
+        }
+        catch {
+            return [];
+        }
+    }
+    async getActiveWindow() {
+        try {
+            const fg = await ps_runner_1.psRunner.run({ cmd: 'get-foreground-window' });
+            if (!fg || fg.success === false)
+                return null;
+            // Try to find the same window in the full list so we get bounds/minimized.
+            const all = await this.listWindows();
+            const match = all.find(w => w.processId === fg.processId);
+            if (match)
+                return match;
+            return this.normalizeWindow({
+                title: fg.title ?? '',
+                processName: fg.processName ?? '',
+                processId: fg.processId ?? 0,
+                handle: fg.handle,
+                bounds: { x: 0, y: 0, width: 0, height: 0 },
+                isMinimized: false,
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async focusWindow(query) {
+        // The PSRunner focus-window command takes title and/or processId. Look up by
+        // processName first so callers can pass just that.
+        let processId = query.processId;
+        let title = query.title;
+        if (processId === undefined && query.processName) {
+            const target = query.processName.toLowerCase();
+            const windows = await this.listWindows();
+            const hit = windows.find(w => w.processName.toLowerCase() === target)
+                ?? windows.find(w => w.processName.toLowerCase().includes(target));
+            if (hit)
+                processId = hit.processId;
+        }
+        try {
+            const result = await ps_runner_1.psRunner.run({
+                cmd: 'focus-window',
+                restore: true,
+                ...(title !== undefined ? { title } : {}),
+                ...(processId !== undefined ? { processId } : {}),
+            });
+            // The PS script reports `success` (target window was found and SetFocus
+            // was attempted) and `foreground` (Win32 SetForegroundWindow actually
+            // promoted the window). We need foreground=true for subsequent keystroke
+            // tools to land on the right app, so treat foreground=false as a focus
+            // failure even if SetFocus succeeded. This is the difference between
+            // "a11y-focused" and "will receive global SendInput keystrokes".
+            if (result?.success !== true)
+                return false;
+            if (result?.foreground === false)
+                return false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async maximizeWindow() {
+        // Win+Up is the portable Windows maximize shortcut.
+        await this.keyPress('super+up').catch(() => { });
+    }
+    async setWindowState(state, query) {
+        // Resolve the target: either the caller-supplied window or the
+        // foreground one. We drive the transition through a single PowerShell
+        // call that wraps Win32 ShowWindow / PostMessage so we don't depend
+        // on focus timing of a key-press chord.
+        let pid;
+        let hwnd;
+        if (query) {
+            // Prefer pid resolution when we can — cheaper than listWindows.
+            pid = query.processId;
+            if (pid === undefined) {
+                const match = await this.resolveWindow(query);
+                if (match) {
+                    pid = match.processId;
+                    const handle = match.handle;
+                    if (typeof handle === 'number')
+                        hwnd = handle;
+                }
+            }
+        }
+        const showCmd = state === 'maximize' ? 3 // SW_MAXIMIZE
+            : state === 'minimize' ? 6 // SW_MINIMIZE
+                : state === 'normal' ? 9 // SW_RESTORE
+                    : null;
+        const target = hwnd !== undefined
+            ? `[IntPtr]${hwnd}`
+            : pid !== undefined
+                ? `(Get-Process -Id ${pid}).MainWindowHandle`
+                : '[NativeMethods]::GetForegroundWindow()';
+        try {
+            if (state === 'close') {
+                // WM_CLOSE — polite close request. App may prompt, we return true
+                // when the message was posted, not when the window actually closed.
+                const ps = 
+                // Single-quoted -MemberDefinition (not a here-string) — a here-string header
+                // is illegal in a single-line `-Command` and fails to parse (see #153).
+                "Add-Type -Name NativeMethods -Namespace Win32 -MemberDefinition '" +
+                    '[DllImport("user32.dll")] public static extern System.IntPtr GetForegroundWindow();' +
+                    '[DllImport("user32.dll")] public static extern bool PostMessage(System.IntPtr hWnd, uint Msg, System.IntPtr wParam, System.IntPtr lParam);' +
+                    "' -PassThru | Out-Null;" +
+                    `$h = ${target};` +
+                    'if ($h -ne [System.IntPtr]::Zero) { [Win32.NativeMethods]::PostMessage($h, 0x0010, [System.IntPtr]::Zero, [System.IntPtr]::Zero) | Out-Null; "ok" } else { "no-window" }';
+                const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', ps], { timeout: PS_TIMEOUT_MS });
+                return stdout.trim() === 'ok';
+            }
+            if (showCmd !== null) {
+                // UWP windows hosted by ApplicationFrameHost ignore a cross-process
+                // Win32 ShowWindow(SW_MINIMIZE) — it silently no-ops (#153: minimize
+                // failed for Calculator/Settings while maximize/restore worked). Drive
+                // the transition through the UIA WindowPattern (the supported
+                // cross-process way, and what we already use for restore), which works
+                // for UWP *and* Win32. Fall back to ShowWindowAsync (plus SW_FORCEMINIMIZE
+                // for the minimize case) only if the pattern isn't available.
+                const visualState = state === 'maximize' ? 'Maximized'
+                    : state === 'minimize' ? 'Minimized'
+                        : 'Normal';
+                const titleQ = this.psQuote(query?.title ?? '');
+                const forceMin = state === 'minimize'
+                    ? ' [Win32.NativeMethods]::ShowWindowAsync($nwh, 11) | Out-Null;'
+                    : '';
+                const ps = 
+                // NB: a here-string header (@"...) is illegal in a single-line `-Command`
+                // ("No characters are allowed after a here-string header before the end of
+                // the line") — it fails to PARSE, so the whole script silently produced no
+                // output and minimize returned false (#153). Use a PS single-quoted
+                // -MemberDefinition instead: the C# double-quotes are literal inside it, and
+                // Node handles the wire-escaping of those quotes for us.
+                'Add-Type -AssemblyName UIAutomationClient,UIAutomationTypes | Out-Null;' +
+                    "Add-Type -Name NativeMethods -Namespace Win32 -MemberDefinition '" +
+                    '[DllImport("user32.dll")] public static extern System.IntPtr GetForegroundWindow();' +
+                    '[DllImport("user32.dll")] public static extern bool ShowWindowAsync(System.IntPtr hWnd, int nCmdShow);' +
+                    "' -PassThru | Out-Null;" +
+                    `$title = ${titleQ};` +
+                    `$h = ${target};` +
+                    '$el = $null;' +
+                    // Strategy A — find the top-level window by title via UIA. This is the
+                    // ONLY reliable handle for UWP / ApplicationFrameHost apps, whose
+                    // visible window is owned by ApplicationFrameHost (so pid→MainWindowHandle
+                    // is 0/wrong) and whose cross-process ShowWindow(SW_MINIMIZE) no-ops (#153).
+                    'if ($title -ne "") {' +
+                    '  $root = [System.Windows.Automation.AutomationElement]::RootElement;' +
+                    '  $cond = New-Object System.Windows.Automation.PropertyCondition([System.Windows.Automation.AutomationElement]::ControlTypeProperty, [System.Windows.Automation.ControlType]::Window);' +
+                    '  foreach ($w in $root.FindAll([System.Windows.Automation.TreeScope]::Children, $cond)) {' +
+                    '    $n = $w.Current.Name; if ($n -and $n.ToLower().Contains($title.ToLower())) { $el = $w; break }' +
+                    '  }' +
+                    '}' +
+                    // Strategy B — the caller-resolved handle. Strategy C — foreground.
+                    'if ($el -eq $null -and $h -ne [System.IntPtr]::Zero) { try { $el = [System.Windows.Automation.AutomationElement]::FromHandle($h) } catch {} }' +
+                    'if ($el -eq $null) { $fg = [Win32.NativeMethods]::GetForegroundWindow(); if ($fg -ne [System.IntPtr]::Zero) { try { $el = [System.Windows.Automation.AutomationElement]::FromHandle($fg) } catch {} } }' +
+                    'if ($el -eq $null) { "no-window" } else {' +
+                    '  $ok = $false;' +
+                    `  try { $wp = $el.GetCurrentPattern([System.Windows.Automation.WindowPattern]::Pattern); $wp.SetWindowVisualState([System.Windows.Automation.WindowVisualState]::${visualState}); $ok = $true } catch { $ok = $false }` +
+                    '  if (-not $ok) { $nwh = [System.IntPtr]$el.Current.NativeWindowHandle; if ($nwh -ne [System.IntPtr]::Zero) {' +
+                    `    [Win32.NativeMethods]::ShowWindowAsync($nwh, ${showCmd}) | Out-Null;${forceMin}` +
+                    '    $ok = $true } }' +
+                    '  if ($ok) { "ok" } else { "no-window" } }';
+                const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', ps], { timeout: PS_TIMEOUT_MS });
+                return stdout.trim() === 'ok';
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async setWindowBounds(bounds, query) {
+        // SetWindowPos takes hwnd + x/y/w/h. Use SWP_NOZORDER to keep z-order.
+        let hwnd;
+        if (query) {
+            const match = await this.resolveWindow(query);
+            if (match && typeof match.handle === 'number')
+                hwnd = match.handle;
+        }
+        const handleExpr = hwnd !== undefined
+            ? `[IntPtr]${hwnd}`
+            : '[Win32.NativeMethods]::GetForegroundWindow()';
+        try {
+            const x = bounds.x ?? -1;
+            const y = bounds.y ?? -1;
+            const w = bounds.width ?? -1;
+            const h = bounds.height ?? -1;
+            // When a dim is -1, we read the current rect and preserve it.
+            const ps = 
+            // Single-quoted -MemberDefinition (not a here-string) — a here-string header
+            // is illegal in a single-line `-Command` and fails to parse (see #153).
+            "Add-Type -Name NativeMethods -Namespace Win32 -MemberDefinition '" +
+                '[DllImport("user32.dll")] public static extern System.IntPtr GetForegroundWindow();' +
+                '[DllImport("user32.dll")] public static extern bool GetWindowRect(System.IntPtr hWnd, out System.Drawing.Rectangle rect);' +
+                '[DllImport("user32.dll")] public static extern bool SetWindowPos(System.IntPtr hWnd, System.IntPtr hWndAfter, int X, int Y, int cx, int cy, uint uFlags);' +
+                "' -ReferencedAssemblies System.Drawing -PassThru | Out-Null;" +
+                `$h = ${handleExpr};` +
+                'if ($h -eq [System.IntPtr]::Zero) { "no-window"; exit }' +
+                '$r = New-Object System.Drawing.Rectangle;' +
+                '[Win32.NativeMethods]::GetWindowRect($h, [ref] $r) | Out-Null;' +
+                `$nx = ${x}; $ny = ${y}; $nw = ${w}; $nh = ${h};` +
+                'if ($nx -lt 0) { $nx = $r.X }' +
+                'if ($ny -lt 0) { $ny = $r.Y }' +
+                'if ($nw -lt 0) { $nw = $r.Width - $r.X }' +
+                'if ($nh -lt 0) { $nh = $r.Height - $r.Y }' +
+                '[Win32.NativeMethods]::SetWindowPos($h, [System.IntPtr]::Zero, $nx, $ny, $nw, $nh, 0x0004) | Out-Null;' +
+                '"ok"';
+            const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', ps], { timeout: PS_TIMEOUT_MS });
+            return stdout.trim() === 'ok';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Internal helper — resolve a focusWindow-style query to a single
+     * WindowInfo. Same precedence the public `focusWindow` uses.
+     */
+    async resolveWindow(query) {
+        const windows = await this.listWindows();
+        return windows.find(w => {
+            if (query.processId !== undefined && w.processId === query.processId)
+                return true;
+            if (query.processName && w.processName.toLowerCase() === query.processName.toLowerCase())
+                return true;
+            if (query.title && w.title.toLowerCase().includes(query.title.toLowerCase()))
+                return true;
+            return false;
+        }) ?? null;
+    }
+    // ─── ACCESSIBILITY ────────────────────────────────────────────────
+    async getUiTree(processId) {
+        // Default to the foreground window's pid when the caller omits it — exactly
+        // as findElements does below. Without this, get-screen-context is called
+        // with focusedPid=0 and the bridge returns NO tree (Cmd-GetScreenContext
+        // only walks a window when focusedPid>0), so read_screen over MCP came back
+        // "(empty a11y tree)" for EVERY app — a regression once the pid-resolving
+        // System-A read_screen was projected away in favor of this path.
+        let pid = processId;
+        if (pid === undefined) {
+            const fg = await this.getActiveWindow().catch(() => null);
+            if (fg?.processId)
+                pid = fg.processId;
+        }
+        try {
+            const result = await ps_runner_1.psRunner.run({
+                cmd: 'get-screen-context',
+                maxDepth: 8,
+                ...(pid !== undefined ? { focusedProcessId: pid } : {}),
+            });
+            const tree = result?.uiTree;
+            if (!tree)
+                return [];
+            const nodes = Array.isArray(tree) ? tree : [tree];
+            const flat = [];
+            for (const n of nodes)
+                this.flattenTree(n, flat);
+            return flat;
+        }
+        catch {
+            return [];
+        }
+    }
+    async findElements(query) {
+        // Default to the foreground window's pid when caller omits processId.
+        // Without this, the PSBridge searches from the desktop root across ALL
+        // windows and hits its 20-element cap before finding deep targets. The
+        // foreground window is almost always the right scope for an unscoped
+        // "find me X" query coming from the agent.
+        let processId = query.processId;
+        if (processId === undefined) {
+            const fg = await this.getActiveWindow();
+            if (fg?.processId)
+                processId = fg.processId;
+        }
+        try {
+            const result = await ps_runner_1.psRunner.run({
+                cmd: 'find-element',
+                ...(query.name !== undefined ? { name: query.name } : {}),
+                ...(query.controlType !== undefined ? { controlType: query.controlType } : {}),
+                ...(processId !== undefined ? { processId } : {}),
+            });
+            const raw = Array.isArray(result) ? result : [];
+            return raw.map(this.normalizeElement);
+        }
+        catch {
+            return [];
+        }
+    }
+    async getFocusedElement() {
+        try {
+            const result = await ps_runner_1.psRunner.run({ cmd: 'get-focused-element' });
+            if (!result || result.success === false)
+                return null;
+            return this.normalizeElement(result);
+        }
+        catch {
+            return null;
+        }
+    }
+    async invokeElement(query) {
+        // The underlying PS bridge requires a processId for invoke-element.
+        // Resolution order when caller omits processId:
+        //   1. Foreground window (the agent's usual implicit scope).
+        //   2. Fall back to find-element scan if the foreground window has no match.
+        // Without this, find-element ran from the desktop root and could miss
+        // deeply-nested targets due to the PSBridge 20-result cap.
+        let processId = query.processId;
+        if (processId === undefined && query.name) {
+            const fg = await this.getActiveWindow();
+            if (fg?.processId) {
+                processId = fg.processId;
+            }
+            else {
+                const candidates = await this.findElements({
+                    name: query.name,
+                    controlType: query.controlType,
+                });
+                if (candidates.length === 0)
+                    return { success: false };
+                processId = candidates[0].processId
+                    ?? candidates[0].pid;
+                // If still no pid but we have bounds, caller can fall back to a coord click.
+                if (processId === undefined) {
+                    return {
+                        success: false,
+                        bounds: candidates[0].bounds,
+                    };
+                }
+            }
+        }
+        if (processId === undefined)
+            return { success: false };
+        try {
+            const result = await ps_runner_1.psRunner.run({
+                cmd: 'invoke-element',
+                processId,
+                action: query.action ?? 'click',
+                ...(query.name !== undefined ? { name: query.name } : {}),
+                ...(query.controlType !== undefined ? { controlType: query.controlType } : {}),
+                ...(query.value !== undefined ? { value: query.value } : {}),
+            });
+            return {
+                success: result?.success === true,
+                bounds: result?.bounds,
+                // The bridge returns get-value's payload at the TOP level
+                // ({success, action, value, method}), not nested under .data — but
+                // every consumer reads res.data?.value. Surface it so a11y_get_value /
+                // element_value_contains actually see the value (review 2026-06-11).
+                data: result?.data ?? (result?.value !== undefined ? { value: result.value } : undefined),
+            };
+        }
+        catch {
+            return { success: false };
+        }
+    }
+    async waitForElement(query, timeoutMs) {
+        const interval = query.intervalMs ?? 250;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const hits = await this.findElements({
+                name: query.name,
+                controlType: query.controlType,
+                processId: query.processId,
+            });
+            if (hits.length > 0)
+                return hits[0];
+            await this.delay(interval);
+        }
+        return null;
+    }
+    // ─── INPUT (mouse) ────────────────────────────────────────────────
+    // All coords are LOGICAL pixels — nut-js mouse API lives in that space on Win.
+    /** Cursor cache for mouseMoveRelative — last known target. */
+    lastCursor = null;
+    /**
+     * Ensure the window at (x, y) is the foreground window before clicking.
+     *
+     * Problem: On Windows, nut-js sends mouse input via SendInput which
+     * delivers to whatever window is topmost at those coordinates — not
+     * necessarily the foreground window. When a Save As dialog sits over a
+     * File Explorer window (or any background window), a click intended for
+     * the dialog's filename field can land on the Explorer window if the
+     * dialog's owning process lost foreground between the screenshot and the
+     * click (race) or if the click coords are slightly outside the dialog rect
+     * due to DPI-related rounding.
+     *
+     * Fix: use Win32 WindowFromPoint (via the warm psRunner bridge) to
+     * identify the window at the target coords. If it is not the current
+     * foreground window, call SetForegroundWindow to bring it forward before
+     * the click lands. Non-fatal — if the PS call fails we proceed anyway.
+     */
+    async ensureForegroundAtPoint(x, y) {
+        try {
+            const r = await ps_runner_1.psRunner.run({ cmd: 'activate-at-point', x, y });
+            // 'noop' reasons mean nothing to promote (no window, or already foreground)
+            // — both are fine, treat as activated.
+            const activated = r?.activated !== false;
+            return { activated, title: r?.title, processName: r?.processName, reason: r?.reason };
+        }
+        catch {
+            // Non-fatal — click proceeds regardless. We do not want to block
+            // mouse input if the foreground check fails. Undefined = unknown.
+            return undefined;
+        }
+    }
+    toNutButton(button) {
+        if (button === 'right')
+            return nut_js_1.Button.RIGHT;
+        if (button === 'middle')
+            return nut_js_1.Button.MIDDLE;
+        return nut_js_1.Button.LEFT;
+    }
+    async mouseClick(x, y, opts) {
+        // Bring the window at (x, y) to the foreground before sending any
+        // button events. Without this, a click intended for a Save As dialog
+        // can land on a background Explorer window when the dialog lost focus
+        // between the screenshot and the click (z-order / activation race).
+        // The activation verdict flows back to the caller so a FAILED raise
+        // (foreground-lock) is visible instead of a silent wrong-window click.
+        const activation = await this.ensureForegroundAtPoint(x, y);
+        await nut_js_1.mouse.setPosition(new nut_js_1.Point(x, y));
+        this.lastCursor = { x, y };
+        await this.delay(40);
+        const count = opts?.count ?? 1;
+        const btn = this.toNutButton(opts?.button);
+        for (let i = 0; i < count; i++) {
+            if (btn === nut_js_1.Button.RIGHT)
+                await nut_js_1.mouse.rightClick();
+            else if (btn === nut_js_1.Button.MIDDLE) {
+                // nut-js has no direct middleClick helper; press+release.
+                await nut_js_1.mouse.pressButton(nut_js_1.Button.MIDDLE);
+                await this.delay(30);
+                await nut_js_1.mouse.releaseButton(nut_js_1.Button.MIDDLE);
+            }
+            else {
+                await nut_js_1.mouse.click(nut_js_1.Button.LEFT);
+            }
+            if (i < count - 1)
+                await this.delay(60);
+        }
+        return activation;
+    }
+    async mouseMove(x, y) {
+        await nut_js_1.mouse.setPosition(new nut_js_1.Point(x, y));
+        this.lastCursor = { x, y };
+    }
+    async mouseMoveRelative(dx, dy) {
+        // nut-js `getPosition()` works reliably on Windows — prefer that over
+        // the cache. Fall back to the cache if the query fails.
+        try {
+            const pos = await nut_js_1.mouse.getPosition();
+            const nx = Math.round(pos.x + dx);
+            const ny = Math.round(pos.y + dy);
+            await nut_js_1.mouse.setPosition(new nut_js_1.Point(nx, ny));
+            this.lastCursor = { x: nx, y: ny };
+        }
+        catch {
+            if (this.lastCursor) {
+                const nx = this.lastCursor.x + dx;
+                const ny = this.lastCursor.y + dy;
+                await nut_js_1.mouse.setPosition(new nut_js_1.Point(nx, ny));
+                this.lastCursor = { x: nx, y: ny };
+            }
+        }
+    }
+    async mouseDrag(x1, y1, x2, y2) {
+        await nut_js_1.mouse.setPosition(new nut_js_1.Point(x1, y1));
+        this.lastCursor = { x: x1, y: y1 };
+        await this.delay(50);
+        await nut_js_1.mouse.pressButton(nut_js_1.Button.LEFT);
+        await this.delay(80);
+        const steps = Math.max(8, Math.floor(Math.hypot(x2 - x1, y2 - y1) / 18));
+        for (let i = 1; i <= steps; i++) {
+            const t = i / steps;
+            const nx = Math.round(x1 + (x2 - x1) * t);
+            const ny = Math.round(y1 + (y2 - y1) * t);
+            await nut_js_1.mouse.setPosition(new nut_js_1.Point(nx, ny));
+            this.lastCursor = { x: nx, y: ny };
+            await this.delay(10);
+        }
+        await nut_js_1.mouse.releaseButton(nut_js_1.Button.LEFT);
+    }
+    async mouseScroll(x, y, direction, amount = 3) {
+        await nut_js_1.mouse.setPosition(new nut_js_1.Point(x, y));
+        this.lastCursor = { x, y };
+        await this.delay(30);
+        // nut-js only exposes scrollUp/scrollDown natively. For horizontal,
+        // fall back to Shift+scroll which most apps interpret as horizontal.
+        if (direction === 'down')
+            await nut_js_1.mouse.scrollDown(amount);
+        else if (direction === 'up')
+            await nut_js_1.mouse.scrollUp(amount);
+        else {
+            // Horizontal: hold Shift, scroll vertically.
+            await nut_js_1.keyboard.pressKey(nut_js_1.Key.LeftShift);
+            try {
+                if (direction === 'left')
+                    await nut_js_1.mouse.scrollUp(amount);
+                else
+                    await nut_js_1.mouse.scrollDown(amount);
+            }
+            finally {
+                await nut_js_1.keyboard.releaseKey(nut_js_1.Key.LeftShift);
+            }
+        }
+    }
+    async mouseDown(button) {
+        await nut_js_1.mouse.pressButton(this.toNutButton(button));
+    }
+    async mouseUp(button) {
+        await nut_js_1.mouse.releaseButton(this.toNutButton(button));
+    }
+    // ─── INPUT (keyboard) ─────────────────────────────────────────────
+    async typeText(text) {
+        if (!text)
+            return;
+        await nut_js_1.keyboard.type(text);
+    }
+    async keyPress(combo) {
+        if (!combo)
+            return;
+        // Literal "+" — can't split on "+" since it IS the separator.
+        if (combo === '+') {
+            await nut_js_1.keyboard.type('+');
+            return;
+        }
+        const parts = combo.split('+').map(s => s.trim()).filter(Boolean);
+        if (parts.length === 0)
+            return;
+        // Convert "mod" → "ctrl" on Windows, leave the rest of the combo alone.
+        const normalized = parts.map(p => {
+            const l = p.toLowerCase();
+            if (l === 'mod' || l === 'cmd' || l === 'command' || l === 'meta')
+                return 'ctrl';
+            return p;
+        });
+        // Map every part to a nut-js Key enum value, or 'TYPE_CHAR' for printable chars
+        // like '*', '+', '.' that have no direct enum entry.
+        const mapped = normalized.map(p => this.mapKey(p));
+        // Single-key: either type it as a character or press+release the mapped key.
+        if (mapped.length === 1) {
+            if (mapped[0] === 'TYPE_CHAR') {
+                await nut_js_1.keyboard.type(normalized[0]);
+            }
+            else {
+                await nut_js_1.keyboard.pressKey(mapped[0]);
+                await this.delay(30);
+                await nut_js_1.keyboard.releaseKey(mapped[0]);
+            }
+            return;
+        }
+        // Combo: press each modifier (or type the printable char), then release in reverse.
+        for (let i = 0; i < mapped.length; i++) {
+            const k = mapped[i];
+            if (k === 'TYPE_CHAR') {
+                await nut_js_1.keyboard.type(normalized[i]);
+            }
+            else {
+                await nut_js_1.keyboard.pressKey(k);
+            }
+            await this.delay(30);
+        }
+        for (let i = mapped.length - 1; i >= 0; i--) {
+            const k = mapped[i];
+            if (k !== 'TYPE_CHAR') {
+                await nut_js_1.keyboard.releaseKey(k);
+            }
+            await this.delay(30);
+        }
+    }
+    async keyDown(key) {
+        const mapped = this.mapKey(key);
+        if (mapped === 'TYPE_CHAR') {
+            // Single printable char without modifier semantics — treat as type.
+            await nut_js_1.keyboard.type(key);
+            return;
+        }
+        await nut_js_1.keyboard.pressKey(mapped);
+    }
+    async keyUp(key) {
+        const mapped = this.mapKey(key);
+        if (mapped === 'TYPE_CHAR')
+            return; // no-op — typing isn't held
+        await nut_js_1.keyboard.releaseKey(mapped);
+    }
+    // ─── CLIPBOARD ────────────────────────────────────────────────────
+    async readClipboard() {
+        try {
+            const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', 'Get-Clipboard'], { timeout: CLIPBOARD_TIMEOUT_MS });
+            // Get-Clipboard tacks on a trailing CRLF — trim for consistency with macOS.
+            return stdout?.replace(/\r?\n$/, '') ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+    async writeClipboard(text) {
+        // Pack the command as UTF-16LE base64 so arbitrary characters (quotes,
+        // newlines, non-ASCII) survive without any escaping dance.
+        const utf16 = Buffer.from(`Set-Clipboard -Value '${text.replace(/'/g, "''")}'`, 'utf16le');
+        try {
+            await execFileAsync('powershell.exe', ['-NoProfile', '-EncodedCommand', utf16.toString('base64')], { timeout: CLIPBOARD_TIMEOUT_MS });
+        }
+        catch {
+            // Silent — clipboard is best-effort (same contract as macOS adapter).
+        }
+    }
+    // ─── APPS ─────────────────────────────────────────────────────────
+    /**
+     * Thin shim — delegates straight to `launchApp` with no alias resolution.
+     * The platform layer is alias-data-agnostic; alias resolution lives in
+     * the caller (the agent's `open_app` tool, the router's `handleOpenApp`).
+     * Callers that want UWP / executable / searchTerm hints must pass them
+     * via `launchApp` directly.
+     */
+    async openApp(name, opts) {
+        return this.launchApp(name, opts);
+    }
+    async launchApp(name, opts) {
+        // Reject control chars / backticks / $() that can escape PowerShell quoting
+        // regardless of how we serialize.
+        if (/[\r\n\t\x00-\x1f]/.test(name) || /[`$]/.test(name)) {
+            throw new Error('launchApp: illegal characters in app name');
+        }
+        // Snapshot existing windows ONCE before any spawn so the diff-and-poll
+        // helper can ignore them. Reused by the idempotency check below — saves
+        // a redundant `listWindows()` round-trip through the PS bridge.
+        let windowsBefore = [];
+        try {
+            windowsBefore = await this.listWindows();
+        }
+        catch {
+            // Non-fatal — empty before-set means everything looks "new".
+        }
+        // v0.8.3 — idempotency: if the app is already running AND caller didn't
+        // ask for a fresh instance, FOCUS the existing window instead of spawning
+        // another. This closes the "Outlook keeps opening" bug: a retry loop that
+        // launches Outlook every iteration used to spawn a new instance each time
+        // (Start-Process -FilePath outlook with Outlook already running launches
+        // a fresh window).
+        if (!opts?.alwaysNewInstance && !opts?.url) {
+            const existing = this.findExistingAppWindowIn(windowsBefore, name, opts?.uwpAppId);
+            if (existing) {
+                // Focus it so it surfaces like a launch would, then return its identity.
+                await this.focusWindow({ processId: existing.processId }).catch(() => { });
+                return { pid: existing.processId, title: existing.title, handle: existing.handle };
+            }
+        }
+        // Route 1: UWP apps via explorer shell:AppsFolder\<id>. This is the Windows-
+        // sanctioned way to launch UWP / Store apps and is rock-solid — Calculator,
+        // Notepad-Win11, Photos, etc. all work.
+        if (opts?.uwpAppId) {
+            const id = opts.uwpAppId;
+            // App ID format is `<PackageFamily>_<Hash>!<AppId>`. Valid characters are
+            // alphanumerics, dots, underscores, hyphens, and a single `!`. Reject anything
+            // else to keep the shell: path from interpreting metacharacters.
+            if (!/^[A-Za-z0-9_.\-]+![A-Za-z0-9_.\-]+$/.test(id)) {
+                throw new Error(`launchApp: illegal uwpAppId "${id}"`);
+            }
+            try {
+                const child = (0, child_process_1.spawn)('explorer.exe', [`shell:AppsFolder\\${id}`], {
+                    stdio: 'ignore', detached: true, windowsHide: true,
+                });
+                child.unref();
+            }
+            catch {
+                // Non-fatal — continue and look for the window anyway.
+            }
+            // Shorter primary budget so we have headroom for the Start-Menu
+            // fallback if shell:AppsFolder didn't surface a window — matches
+            // the router's strategy ladder.
+            const uwpResult = await this.findLaunchedWindow(name, windowsBefore, 4_000);
+            if (uwpResult.title)
+                return this.foregroundLaunched(uwpResult);
+            if (opts?.noStartMenuFallback)
+                return uwpResult; // {} — caller verifies
+            return this.foregroundLaunched(await this.launchViaStartMenuSearch(name, opts?.searchTerm, windowsBefore));
+        }
+        // Route 2: classic Start-Process via PowerShell with safely quoted args.
+        const args = ['-NoProfile', '-Command'];
+        const cmdParts = ['Start-Process'];
+        cmdParts.push('-FilePath', this.psQuote(name));
+        if (opts?.url && !/[\r\n\t\x00-\x1f"'`$]/.test(opts.url)) {
+            cmdParts.push('-ArgumentList', this.psQuote(opts.url));
+        }
+        if (opts?.cwd && !/[\r\n\t\x00-\x1f"'`$]/.test(opts.cwd)) {
+            cmdParts.push('-WorkingDirectory', this.psQuote(opts.cwd));
+        }
+        args.push(cmdParts.join(' '));
+        try {
+            const child = (0, child_process_1.spawn)('powershell.exe', args, {
+                stdio: 'ignore', detached: true, windowsHide: true,
+            });
+            child.unref();
+        }
+        catch {
+            // Fall through to the lookup — the app may already be running.
+        }
+        // Try the primary Start-Process result with a shorter budget so we have
+        // time for the Start-Menu fallback if it returns empty. Edge / VS Code /
+        // any binary not on PATH but Start-Menu-indexed will recover here.
+        const direct = await this.findLaunchedWindow(name, windowsBefore, 4_000);
+        if (direct.title)
+            return this.foregroundLaunched(direct);
+        if (opts?.noStartMenuFallback)
+            return direct; // {} — caller verifies (open_file)
+        // Route 3: Start Menu search fallback — universal for any app indexed by
+        // Windows. Press the Win key, type the app name, press Enter. This is
+        // the same pattern the router's zero-LLM fast path uses; ported here so
+        // every caller of launchApp (agent's open_app, MCP, REST) gets the
+        // reliability without duplicating router logic.
+        return this.foregroundLaunched(await this.launchViaStartMenuSearch(name, opts?.searchTerm, windowsBefore));
+    }
+    /**
+     * Bring a freshly-launched window to the foreground. A detached spawn opens
+     * the app BEHIND the current foreground (Windows foreground-lock), so without
+     * this `open_app("calc")` left Calculator in the background and every
+     * subsequent focused-window op (read_screen, find_element) targeted the wrong
+     * window. The idempotency path already focuses; this gives fresh launches the
+     * same contract. Best-effort — never throws, the launch already succeeded.
+     */
+    async foregroundLaunched(result) {
+        if (result?.pid) {
+            await this.focusWindow({ processId: result.pid, title: result.title }).catch(() => { });
+        }
+        return result;
+    }
+    /**
+     * Last-resort launch via Windows' own Start Menu search. Works for any
+     * app the user can find by name in the Start Menu (apps, settings panes,
+     * UWP without a known AppsFolder ID, third-party Win32 binaries with an
+     * App Paths entry). The keyboard primitives we use here go through the
+     * adapter directly, NOT through the safety layer — this is internal
+     * platform logic, not an agent action.
+     *
+     * Tuned to the same cadence as the router's startMenuSearch helper.
+     */
+    async launchViaStartMenuSearch(name, searchTermHint, windowsBefore) {
+        // Pick the term Windows Search will actually rank correctly. The alias's
+        // `searchTerm` (when provided) is the human-friendly name an end user
+        // would type — "Edge", "VS Code", "File Explorer". For names without an
+        // alias, fall back to stripping the file-system suffix off `name`:
+        // `msedge.exe` → `msedge`, `notepad.exe` → `notepad`, etc. Without this
+        // distinction, typing the binary name in Start Menu can surface the
+        // wrong app (e.g. "msedge" → Microsoft Store as the closest match).
+        const searchText = (searchTermHint && searchTermHint.trim())
+            ? searchTermHint.trim()
+            : name.replace(/\.(exe|com)$/i, '');
+        try {
+            // Close any in-progress Start Menu / search overlay so the Win key
+            // reliably opens a fresh one.
+            await this.keyPress('Escape').catch(() => { });
+            await this.delay(120);
+            await this.keyPress('Super');
+            await this.delay(600);
+            await this.typeText(searchText);
+            await this.delay(700);
+            await this.keyPress('Return');
+        }
+        catch {
+            // Keyboard layer flaky — caller will see empty result and decide.
+        }
+        // The post-launch predicate still uses the launched binary `name`
+        // because that's what the new window's processName will look like
+        // (msedge.exe → process "msedge"); the searchText only drives what
+        // Windows Search resolves to.
+        const win = await (0, launch_poll_1.waitForLaunchedWindow)(windowsBefore, () => this.listWindows(), (0, launch_poll_1.buildAppPredicate)(name), { timeoutMs: 4_000 });
+        return win
+            ? { pid: win.processId, title: win.title, handle: win.handle }
+            : {};
+    }
+    /**
+     * After a launch, wait for the new window to surface. Uses the shared
+     * `waitForLaunchedWindow` diff-and-poll helper so the budget is spent
+     * doing useful work (polling every 300ms) rather than a single fixed
+     * settle. Returns `{}` when the deadline elapses with no match — caller
+     * can interpret that as a real "this strategy didn't work" signal and
+     * try the next strategy.
+     *
+     * On Windows, neither the UWP shell:AppsFolder spawn nor the classic
+     * Start-Process spawn returns the eventual app's PID (we spawn explorer /
+     * powershell, not the target binary), so we don't pass `spawnPid`.
+     * The predicate matches by process name + title, same as the old
+     * single-shot logic — just polled.
+     */
+    async findLaunchedWindow(name, windowsBefore, timeoutMs) {
+        const win = await (0, launch_poll_1.waitForLaunchedWindow)(windowsBefore, () => this.listWindows(), (0, launch_poll_1.buildAppPredicate)(name), timeoutMs ? { timeoutMs } : undefined);
+        return win
+            ? { pid: win.processId, title: win.title, handle: win.handle }
+            : {};
+    }
+    /**
+     * v0.8.3 — check whether an app matching `name` or `uwpAppId` already has
+     * a visible top-level window. Used by `launchApp` to short-circuit when
+     * the user / agent asks to "open Outlook" but Outlook is already running.
+     *
+     * Match policy: case-insensitive process-name / title substring, which
+     * matches the same alias set the router uses. A `uwpAppId` like
+     * `Microsoft.WindowsCalculator_8wekyb3d8bbwe!App` is reduced to its App
+     * token (`App`, `Calculator`) and matched against window titles as a
+     * fallback.
+     *
+     * Returns `null` when no matching window is found — caller proceeds with
+     * a normal launch.
+     */
+    async findExistingAppWindow(name, uwpAppId) {
+        try {
+            const windows = await this.listWindows();
+            return this.findExistingAppWindowIn(windows, name, uwpAppId);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Same matching logic as `findExistingAppWindow` but takes an already-fetched
+     * window list. Lets `launchApp` reuse the snapshot it captures for the
+     * post-spawn diff-and-poll, avoiding a redundant PS-bridge round-trip.
+     */
+    findExistingAppWindowIn(windows, name, uwpAppId) {
+        if (windows.length === 0)
+            return null;
+        const target = name.trim().toLowerCase();
+        // Strip any trailing `.exe` so `outlook.exe` still matches `outlook`.
+        const targetStem = target.replace(/\.(exe|com|app)$/, '');
+        // Tier 1: exact processName match.
+        let hit = windows.find(w => w.processName.toLowerCase() === targetStem);
+        // Tier 2: processName substring (handles olk ↔ outlook etc.).
+        if (!hit)
+            hit = windows.find(w => w.processName.toLowerCase().includes(targetStem));
+        // Tier 3: reverse — targetStem contains processName (e.g. name="msedge.exe", proc="msedge").
+        if (!hit)
+            hit = windows.find(w => targetStem.includes(w.processName.toLowerCase()) && w.processName.length >= 3);
+        // Tier 4: title substring.
+        if (!hit)
+            hit = windows.find(w => w.title.toLowerCase().includes(targetStem));
+        // UWP fallback — check the AppsFolder id's last segment against titles.
+        if (!hit && uwpAppId) {
+            const uwpTail = uwpAppId.split('!').pop()?.toLowerCase() ?? '';
+            if (uwpTail)
+                hit = windows.find(w => w.title.toLowerCase().includes(uwpTail));
+        }
+        // Skip minimized windows — if the user hid it, they probably want a
+        // "fresh" focus, but we still return it so focusWindow can restore.
+        return hit ?? null;
+    }
+    /**
+     * PowerShell single-quoted string escape. Inside single quotes, the only
+     * special char is the single quote itself, which doubles to escape.
+     * This is the only safe way to pass a user-controlled string as a
+     * PowerShell argument.
+     */
+    psQuote(s) {
+        return `'${s.replace(/'/g, "''")}'`;
+    }
+    // ─── INTERNAL HELPERS ─────────────────────────────────────────────
+    normalizeWindow = (raw) => ({
+        title: raw?.title ?? '',
+        processName: raw?.processName ?? '',
+        processId: raw?.processId ?? 0,
+        bounds: raw?.bounds ?? { x: 0, y: 0, width: 0, height: 0 },
+        isMinimized: raw?.isMinimized ?? false,
+        handle: raw?.handle ?? raw?.processId,
+    });
+    normalizeElement = (raw) => {
+        const enabled = raw?.isEnabled ?? raw?.enabled;
+        return {
+            name: raw?.name ?? '',
+            controlType: (raw?.controlType ?? '').replace(/^ControlType\./, ''),
+            bounds: raw?.bounds ?? { x: 0, y: 0, width: 0, height: 0 },
+            value: raw?.value,
+            enabled,
+            focused: raw?.focused,
+            // Tranche 1A: richer state fields from ps-bridge.
+            selected: raw?.selected ?? raw?.isSelected,
+            disabled: enabled === false ? true : undefined,
+            busy: raw?.busy ?? raw?.isBusy,
+            offscreen: raw?.offscreen ?? raw?.isOffscreen,
+            expandable: raw?.expandable,
+            expanded: raw?.expanded,
+            automationId: raw?.automationId,
+            processId: raw?.processId ?? raw?.pid,
+        };
+    };
+    /**
+     * Flatten the UIA tree into a single list, matching the macOS adapter's
+     * contract. Drops purely structural unnamed nodes to keep the list useful.
+     */
+    flattenTree(node, acc) {
+        if (!node)
+            return;
+        // ConvertTo-UINode may return an array of children when it skipped an
+        // unnamed container — just recurse through those.
+        if (Array.isArray(node)) {
+            for (const n of node)
+                this.flattenTree(n, acc);
+            return;
+        }
+        if (node.controlType || node.name)
+            acc.push(this.normalizeElement(node));
+        if (Array.isArray(node.children)) {
+            for (const child of node.children)
+                this.flattenTree(child, acc);
+        }
+    }
+    /**
+     * Map a portable key token to the nut-js Key enum (or 'TYPE_CHAR' for
+     * printable ASCII symbols that don't have a direct enum entry).
+     */
+    mapKey(name) {
+        const direct = WIN_KEY_MAP[name] ?? WIN_KEY_MAP[name.toLowerCase()];
+        if (direct !== undefined)
+            return direct;
+        if (name.length === 1) {
+            const ch = name;
+            const upper = ch.toUpperCase();
+            // A-Z
+            if (upper >= 'A' && upper <= 'Z') {
+                const k = nut_js_1.Key[upper];
+                if (k !== undefined)
+                    return k;
+            }
+            // 0-9 → nut-js uses Num1..Num9, Num0 for the top-row digits.
+            if (upper >= '0' && upper <= '9') {
+                const k = nut_js_1.Key[`Num${upper}`];
+                if (k !== undefined)
+                    return k;
+            }
+            // Any other printable ASCII — ask keyboard.type() to handle it.
+            if (ch.charCodeAt(0) >= 32 && ch.charCodeAt(0) <= 126)
+                return 'TYPE_CHAR';
+        }
+        // Last resort: direct enum name match (e.g. "F13", "NumPad5").
+        const enumVal = nut_js_1.Key[name];
+        if (enumVal !== undefined)
+            return enumVal;
+        throw new Error(`Unknown key: "${name}"`);
+    }
+    delay(ms) {
+        return new Promise(r => setTimeout(r, ms));
+    }
+}
+exports.WindowsAdapter = WindowsAdapter;
+// Portable-token → nut-js Key lookup. Lowercase keys are checked as a
+// fallback so "Return"/"return", "Shift"/"shift", etc. all resolve.
+const WIN_KEY_MAP = {
+    // Modifiers
+    ctrl: nut_js_1.Key.LeftControl, control: nut_js_1.Key.LeftControl, Control: nut_js_1.Key.LeftControl,
+    shift: nut_js_1.Key.LeftShift, Shift: nut_js_1.Key.LeftShift,
+    alt: nut_js_1.Key.LeftAlt, Alt: nut_js_1.Key.LeftAlt, option: nut_js_1.Key.LeftAlt, opt: nut_js_1.Key.LeftAlt,
+    super: nut_js_1.Key.LeftSuper, Super: nut_js_1.Key.LeftSuper, win: nut_js_1.Key.LeftSuper, windows: nut_js_1.Key.LeftSuper, meta: nut_js_1.Key.LeftSuper,
+    // Navigation / editing
+    return: nut_js_1.Key.Enter, Return: nut_js_1.Key.Enter, enter: nut_js_1.Key.Enter, Enter: nut_js_1.Key.Enter,
+    tab: nut_js_1.Key.Tab, Tab: nut_js_1.Key.Tab,
+    escape: nut_js_1.Key.Escape, Escape: nut_js_1.Key.Escape, esc: nut_js_1.Key.Escape, Esc: nut_js_1.Key.Escape,
+    backspace: nut_js_1.Key.Backspace, Backspace: nut_js_1.Key.Backspace,
+    delete: nut_js_1.Key.Delete, Delete: nut_js_1.Key.Delete, forwarddelete: nut_js_1.Key.Delete,
+    space: nut_js_1.Key.Space, Space: nut_js_1.Key.Space,
+    home: nut_js_1.Key.Home, Home: nut_js_1.Key.Home,
+    end: nut_js_1.Key.End, End: nut_js_1.Key.End,
+    pageup: nut_js_1.Key.PageUp, PageUp: nut_js_1.Key.PageUp,
+    pagedown: nut_js_1.Key.PageDown, PageDown: nut_js_1.Key.PageDown,
+    insert: nut_js_1.Key.Insert, Insert: nut_js_1.Key.Insert,
+    // Arrows
+    left: nut_js_1.Key.Left, Left: nut_js_1.Key.Left,
+    right: nut_js_1.Key.Right, Right: nut_js_1.Key.Right,
+    up: nut_js_1.Key.Up, Up: nut_js_1.Key.Up,
+    down: nut_js_1.Key.Down, Down: nut_js_1.Key.Down,
+    // F-keys
+    f1: nut_js_1.Key.F1, F1: nut_js_1.Key.F1, f2: nut_js_1.Key.F2, F2: nut_js_1.Key.F2, f3: nut_js_1.Key.F3, F3: nut_js_1.Key.F3,
+    f4: nut_js_1.Key.F4, F4: nut_js_1.Key.F4, f5: nut_js_1.Key.F5, F5: nut_js_1.Key.F5, f6: nut_js_1.Key.F6, F6: nut_js_1.Key.F6,
+    f7: nut_js_1.Key.F7, F7: nut_js_1.Key.F7, f8: nut_js_1.Key.F8, F8: nut_js_1.Key.F8, f9: nut_js_1.Key.F9, F9: nut_js_1.Key.F9,
+    f10: nut_js_1.Key.F10, F10: nut_js_1.Key.F10, f11: nut_js_1.Key.F11, F11: nut_js_1.Key.F11, f12: nut_js_1.Key.F12, F12: nut_js_1.Key.F12,
+    // Symbol keys reachable as single chars in combos like "ctrl++" / "ctrl+-"
+    '=': nut_js_1.Key.Equal,
+    '+': nut_js_1.Key.Equal,
+    '-': nut_js_1.Key.Minus,
+    '_': nut_js_1.Key.Minus,
+    '`': nut_js_1.Key.Grave,
+};
+//# sourceMappingURL=windows.js.map