@mseep/clawdcursor 1.5.5

package/dist/platform/ps-runner.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * PSRunner — Persistent PowerShell UIA bridge.
+ *
+ * Keeps one powershell.exe alive for the entire session.
+ * UI Automation assemblies are loaded once at startup (~800ms).
+ * Each subsequent command costs only the actual work — no 200-500ms spawn overhead.
+ *
+ * Protocol: newline-delimited JSON on stdin/stdout.
+ *   Send: {"cmd":"invoke-element","processId":123,...}\n
+ *   Recv: {"success":true,...}\n
+ *
+ * Commands are serialized (one at a time), queued if a call is in-flight.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.psRunner = exports.PSRunner = void 0;
+const child_process_1 = require("child_process");
+const readline = __importStar(require("readline"));
+const path = __importStar(require("path"));
+const paths_1 = require("../paths");
+const BRIDGE_SCRIPT = path.join((0, paths_1.getPackageRoot)(), 'scripts', 'ps-bridge.ps1');
+const READY_TIMEOUT = 12000; // initial PS startup + assembly load
+const CALL_TIMEOUT = 20000; // per command (reduced from 45s — PSRunner is fast enough)
+const MAX_QUEUE_SIZE = 100; // backpressure — reject if queue exceeds this
+class PSRunner {
+    proc = null;
+    rl = null;
+    ready = false;
+    dead = false;
+    queue = [];
+    current = null;
+    startPromise = null;
+    async start() {
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = this._start().catch(err => {
+            this.startPromise = null;
+            throw err;
+        });
+        return this.startPromise;
+    }
+    _start() {
+        // Capture reject so the exit handler can settle the startup promise even
+        // when the PS bridge exits before it outputs {"ready":true}.  Without
+        // this, clearTimeout(readyTimer) in the exit handler would leave
+        // startPromise as a zombie — never resolved, never rejected — causing
+        // every subsequent `await this.startPromise` to hang forever.
+        let startReject;
+        return new Promise((resolve, reject) => {
+            startReject = reject;
+            this.dead = false;
+            this.ready = false;
+            this.proc = (0, child_process_1.spawn)('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-ExecutionPolicy', 'Bypass',
+                '-File', BRIDGE_SCRIPT,
+            ], { stdio: ['pipe', 'pipe', 'pipe'] });
+            this.rl = readline.createInterface({ input: this.proc.stdout });
+            const readyTimer = setTimeout(() => {
+                reject(new Error('PSRunner: timed out waiting for bridge ready'));
+            }, READY_TIMEOUT);
+            this.rl.on('line', (line) => {
+                line = line.trim();
+                if (!line)
+                    return;
+                let data;
+                try {
+                    data = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (!this.ready) {
+                    if (data.ready) {
+                        this.ready = true;
+                        clearTimeout(readyTimer);
+                        console.log('[PSBridge] Ready — UIA assemblies loaded');
+                        resolve();
+                    }
+                    else if (data.error) {
+                        clearTimeout(readyTimer);
+                        reject(new Error(`PSRunner startup: ${data.error}`));
+                    }
+                    return;
+                }
+                // Deliver to in-flight call
+                const call = this.current;
+                this.current = null;
+                if (call) {
+                    clearTimeout(call.timer);
+                    if (data.error)
+                        call.reject(new Error(data.error));
+                    else
+                        call.resolve(data);
+                }
+                this._drain();
+            });
+            this.proc.stderr.on('data', (chunk) => {
+                const msg = chunk.toString().trim();
+                if (msg)
+                    console.error(`[PSBridge] ${msg}`);
+            });
+            this.proc.on('exit', (code) => {
+                const pending = this.current ? [this.current, ...this.queue] : [...this.queue];
+                this.dead = true;
+                this.ready = false;
+                this.startPromise = null;
+                clearTimeout(readyTimer);
+                if (pending.length > 0) {
+                    console.error(`[PSBridge] Process exited (code ${code}) with ${pending.length} pending command(s) — will restart on next call`);
+                }
+                this.current = null;
+                this.queue = [];
+                const err = new Error(`PSRunner exited (code ${code})`);
+                // Reject the startup promise if the bridge never signalled ready.
+                // Previously this was omitted: clearTimeout(readyTimer) disabled the
+                // 12-second safety net but no rejection was issued, leaving
+                // startPromise as an unsettled zombie.  Any awaiter (e.g.
+                // getActiveWindow inside key_press) would then hang forever.
+                startReject(err);
+                for (const c of pending) {
+                    clearTimeout(c.timer);
+                    c.reject(err);
+                }
+            });
+        });
+    }
+    async run(command) {
+        // Auto-start or auto-restart
+        if (!this.startPromise || this.dead) {
+            if (this.dead)
+                console.log('[PSBridge] Restarting crashed bridge process...');
+            this.dead = false;
+            await this.start();
+        }
+        else {
+            await this.startPromise;
+        }
+        return new Promise((resolve, reject) => {
+            if (this.queue.length >= MAX_QUEUE_SIZE) {
+                reject(new Error(`PSRunner queue full (${MAX_QUEUE_SIZE}) — backpressure. Try again later.`));
+                return;
+            }
+            const call = {
+                command,
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    if (this.current === call)
+                        this.current = null;
+                    console.error(`[PSBridge] Command timeout after ${CALL_TIMEOUT}ms: ${String(command.cmd)}`);
+                    reject(new Error(`PSRunner timeout: ${String(command.cmd)}`));
+                    this._drain();
+                }, CALL_TIMEOUT),
+            };
+            this.queue.push(call);
+            this._drain();
+        });
+    }
+    _drain() {
+        if (this.current || this.queue.length === 0 || !this.proc || this.dead)
+            return;
+        this.current = this.queue.shift();
+        try {
+            const line = JSON.stringify(this.current.command) + '\n';
+            this.proc.stdin.write(line);
+        }
+        catch (err) {
+            const call = this.current;
+            this.current = null;
+            clearTimeout(call.timer);
+            call.reject(err);
+            this._drain();
+        }
+    }
+    stop() {
+        if (this.proc) {
+            try {
+                this.proc.stdin.write('EXIT\n');
+            }
+            catch { }
+            setTimeout(() => { try {
+                this.proc?.kill();
+            }
+            catch { } }, 500);
+        }
+        this.ready = false;
+        this.dead = true;
+    }
+}
+exports.PSRunner = PSRunner;
+// Singleton — shared across all AccessibilityBridge instances
+exports.psRunner = new PSRunner();
+//# sourceMappingURL=ps-runner.js.map

package/dist/platform/ps-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ps-runner.js","sourceRoot":"","sources":["../../src/platform/ps-runner.ts"],"names":[],"mappings":"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"}

package/dist/platform/types.d.ts

@@ -0,0 +1,397 @@
+/**
+ * PlatformAdapter — single contract for all platform-specific operations.
+ *
+ * Replaces scattered `if (IS_MAC) ... else ...` branching across 34 files.
+ * Each platform implements this interface; business logic stays platform-free.
+ *
+ * Tranche 1A (v0.8.1-alpha): adds the primitives needed to unblock the
+ * Tranche 1B / 2 MCP tools (mouseDown/mouseUp, keyDown/keyUp, middle click,
+ * horizontal scroll, window-state / bounds control, display enumeration,
+ * waitForElement, widened invokeElement actions, UI-element state flags).
+ * Every change is ADDITIVE — existing signatures kept so no caller breaks.
+ */
+export interface ScreenSize {
+    /** Physical pixels (what screenshots are captured at). */
+    physicalWidth: number;
+    physicalHeight: number;
+    /** Logical pixels (what mouse coordinates use). */
+    logicalWidth: number;
+    logicalHeight: number;
+    /** Physical / logical (e.g. 2.0 on Retina, 1.0 on standard). */
+    dpiRatio: number;
+}
+/**
+ * A physical display. `getScreenSize()` returns the primary display only —
+ * `listDisplays()` returns every connected display so callers can target a
+ * specific one for screenshots or mouse coordinates.
+ */
+export interface Display {
+    /** Index (0 = primary). Stable per boot. */
+    index: number;
+    /** Human label (e.g. "Display 1", "Built-in Retina Display"). */
+    label: string;
+    /** Whether this is the primary / main display. */
+    primary: boolean;
+    /** Logical bounds — mouse-coordinate space. Can be negative for left-of-primary. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Physical (pixel) dimensions. */
+    physicalSize: {
+        width: number;
+        height: number;
+    };
+    /** Physical / logical scale. */
+    dpiRatio: number;
+}
+export interface ScreenshotResult {
+    /** PNG image buffer. */
+    buffer: Buffer;
+    /** Image dimensions (may differ from screen size if resized). */
+    width: number;
+    height: number;
+    /** Multiplier to convert image coords back to physical screen coords. */
+    scaleFactor: number;
+}
+export interface WindowInfo {
+    title: string;
+    processName: string;
+    processId: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    isMinimized: boolean;
+    /** Platform-opaque handle for re-targeting. */
+    handle?: number | string;
+}
+export interface UiElement {
+    name: string;
+    controlType: string;
+    /** Platform subrole when present (macOS AX exposes e.g. "AXSecureTextField",
+     *  "AXSearchField"); used to detect secureness and refine the role. */
+    subrole?: string;
+    /** Whether this is a password/secure field — its `value` is withheld. */
+    secure?: boolean;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Optional structured value (e.g. text field contents). */
+    value?: string;
+    /** Whether the element is enabled and interactable. */
+    enabled?: boolean;
+    /** Whether the element currently has keyboard focus. */
+    focused?: boolean;
+    /** Whether the element is currently selected (list items, tabs, radios). */
+    selected?: boolean;
+    /** Element is in a disabled (grayed-out) state. Opposite of `enabled`. */
+    disabled?: boolean;
+    /** Element is marked busy (e.g. progress in-flight). */
+    busy?: boolean;
+    /** Element is off-screen / scrolled out of view. */
+    offscreen?: boolean;
+    /** Element supports expand/collapse (has an ExpandCollapse a11y pattern). */
+    expandable?: boolean;
+    /** Current expand state when `expandable` is true. */
+    expanded?: boolean;
+    /** Platform-opaque automation identifier (UIA AutomationId, AX identifier, AT-SPI name). */
+    automationId?: string;
+    /** Owning-process id when known. */
+    processId?: number;
+    /**
+     * Human-readable description of the element when its primary `name` is
+     * empty. UIA exposes this via `LocalizedControlType` / `HelpText`; AX
+     * exposes it via `AXDescription` / `AXRoleDescription`; AT-SPI exposes
+     * it via the `description` attribute. Many third-party macOS apps (Xcode
+     * in particular) put their visible text in `AXDescription` rather than
+     * `AXTitle`, so `name` arrives empty and the element looks anonymous to
+     * the agent. Consumers should fall back through `name → description →
+     * value → controlType` when rendering. Adapters populate when available;
+     * undefined is acceptable (back-compat).
+     *
+     * Added 0.9.4 for issue #101 bug 5.
+     */
+    description?: string;
+}
+export interface PermissionStatus {
+    /** Can we send keyboard/mouse events to other apps? */
+    input: boolean;
+    /** Can we read window contents / accessibility tree? */
+    accessibility: boolean;
+    /** Can we capture the screen? */
+    screenRecording: boolean;
+}
+/** Pointer button — extended in Tranche 1A to include middle click. */
+export type MouseButton = 'left' | 'right' | 'middle';
+/**
+ * Result of the pre-click foreground promotion (Win32 WindowFromPoint +
+ * SetForegroundWindow). `activated:false` means the OS refused to bring the
+ * window at the click point to the foreground (foreground-lock) — the click
+ * likely landed on a DIFFERENT window than intended, so the caller must warn
+ * and not blindly send keystrokes next. `title`/`processName` identify the
+ * window that was actually promoted/clicked.
+ */
+export interface FocusActivation {
+    activated: boolean;
+    title?: string;
+    processName?: string;
+    reason?: string;
+}
+/**
+ * Scroll direction — extended in Tranche 1A to include horizontal. Windows
+ * and macOS native wheel APIs support both axes; Linux X11 uses xdotool
+ * buttons 6/7 or nut-js's `scrollLeft/scrollRight`; Wayland is iffy on
+ * horizontal and degrades gracefully.
+ */
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+/**
+ * Canonical window state verbs. `setWindowState('close')` is a polite
+ * close request (WM_CLOSE / AXCloseAction / wmctrl -c) — the app MAY
+ * prompt the user (e.g. "Save changes?") and refuse. Callers must not
+ * assume the window was actually closed.
+ */
+export type WindowState = 'maximize' | 'minimize' | 'normal' | 'close';
+/**
+ * Invoke-element action union. Expanded in Tranche 1A to cover the UIA
+ * ExpandCollapse / Toggle / Selection patterns that `ps-bridge.ps1`
+ * already implements on Windows and that `invoke-element.jxa` now
+ * implements on macOS. Linux returns `{success:false}` until the
+ * AT-SPI bridge lands.
+ */
+export type InvokeAction = 'click' | 'focus' | 'set-value' | 'get-value' | 'expand' | 'collapse' | 'toggle' | 'select';
+export interface WaitForElementQuery {
+    name?: string;
+    controlType?: string;
+    processId?: number;
+    /** Poll interval in ms (default 250). */
+    intervalMs?: number;
+}
+/**
+ * Platform-agnostic interface every supported OS implements.
+ *
+ * Business logic uses this interface and never touches `process.platform`.
+ */
+export interface PlatformAdapter {
+    /** OS family this adapter handles. */
+    readonly platform: 'darwin' | 'win32' | 'linux';
+    /**
+     * Optional environment hint — Linux sets this to 'wayland' or 'x11' so
+     * callers can surface graceful "not supported on Wayland" errors for
+     * known-broken primitives (cursor queries, some global hotkeys).
+     * Undefined on Windows and macOS.
+     */
+    readonly environment?: 'wayland' | 'x11';
+    /** One-time setup (warm caches, start helpers). */
+    init(): Promise<void>;
+    /** Cleanup on shutdown. */
+    shutdown(): Promise<void>;
+    checkPermissions(): Promise<PermissionStatus>;
+    requestPermissions(): Promise<PermissionStatus>;
+    /** Get the primary display geometry. */
+    getScreenSize(): Promise<ScreenSize>;
+    /**
+     * List ALL connected displays. Tranche 1A primitive — unblocks
+     * multi-monitor-aware screenshot and mouse targeting. Primary display
+     * is always at index 0.
+     */
+    listDisplays(): Promise<Display[]>;
+    /**
+     * Capture the full screen as PNG. Optionally resize to maxWidth.
+     * `displayIndex` (Tranche 1A) selects a specific display — 0 (default)
+     * is primary. Passing an out-of-range index falls back to primary.
+     */
+    screenshot(opts?: {
+        maxWidth?: number;
+        displayIndex?: number;
+    }): Promise<ScreenshotResult>;
+    /** Capture a region of the screen. */
+    screenshotRegion(x: number, y: number, w: number, h: number): Promise<ScreenshotResult>;
+    listWindows(): Promise<WindowInfo[]>;
+    getActiveWindow(): Promise<WindowInfo | null>;
+    focusWindow(query: {
+        processName?: string;
+        processId?: number;
+        title?: string;
+    }): Promise<boolean>;
+    /**
+     * Legacy shim — preserved for back-compat. New code should call
+     * `setWindowState('maximize')`. Default behavior unchanged.
+     */
+    maximizeWindow(): Promise<void>;
+    /**
+     * Canonical window-state control. Semantics (Tranche 1A):
+     *   - 'maximize' — full-working-area size
+     *   - 'minimize' — hide to taskbar/Dock
+     *   - 'normal'   — restore from minimized/maximized to previous bounds
+     *   - 'close'    — polite close request; app may prompt / refuse
+     *
+     * Target: the currently-focused window unless `query` is supplied.
+     * Returns true when the request was accepted, NOT when the state
+     * transition completed.
+     */
+    setWindowState(state: WindowState, query?: {
+        processName?: string;
+        processId?: number;
+        title?: string;
+    }): Promise<boolean>;
+    /**
+     * Set the foreground (or matched) window's logical-pixel bounds.
+     * Returns true when the request was accepted. No-op where the WM
+     * refuses programmatic move/resize (some tiling Linux WMs).
+     */
+    setWindowBounds(bounds: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    }, query?: {
+        processName?: string;
+        processId?: number;
+        title?: string;
+    }): Promise<boolean>;
+    getUiTree(processId?: number): Promise<UiElement[]>;
+    findElements(query: {
+        name?: string;
+        controlType?: string;
+        processId?: number;
+    }): Promise<UiElement[]>;
+    getFocusedElement(): Promise<UiElement | null>;
+    /**
+     * Invoke an accessibility action on a named element. Action union
+     * widened in Tranche 1A. Platforms that don't support a given action
+     * return `{ success:false }` — no throw.
+     */
+    invokeElement(query: {
+        name?: string;
+        controlType?: string;
+        processId?: number;
+        action?: InvokeAction;
+        value?: string;
+    }): Promise<{
+        success: boolean;
+        bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /** Action-specific payload, e.g. `{ value }` for get-value, `{ toggleState }` for toggle. */
+        data?: Record<string, unknown>;
+    }>;
+    /**
+     * Poll for an element to appear. Returns the first matching element or
+     * null when `timeoutMs` elapses. Useful for waiting out transient UI
+     * (dialogs, spinners). Tranche 1A primitive — lifted from
+     * `action-router.ts`'s internal `waitForElement` helper.
+     */
+    waitForElement(query: WaitForElementQuery, timeoutMs: number): Promise<UiElement | null>;
+    /** All coords are in LOGICAL pixels (mouse coordinate space).
+     *  Returns a FocusActivation describing the window brought to the foreground
+     *  at the click point (when the platform verifies it) so callers can WARN on
+     *  a failed/ wrong-window activation; void/undefined when not verifiable. */
+    mouseClick(x: number, y: number, opts?: {
+        button?: MouseButton;
+        count?: number;
+    }): Promise<FocusActivation | void>;
+    mouseMove(x: number, y: number): Promise<void>;
+    /**
+     * Move relative to the current cursor position. On Wayland where
+     * cursor-position queries are blocked, implementations SHOULD cache
+     * the last target from `mouseMove`/`mouseClick` and offset from there;
+     * if no cache is available, they return without error and log a
+     * graceful-degradation warning.
+     */
+    mouseMoveRelative(dx: number, dy: number): Promise<void>;
+    mouseDrag(x1: number, y1: number, x2: number, y2: number): Promise<void>;
+    mouseScroll(x: number, y: number, direction: ScrollDirection, amount?: number): Promise<void>;
+    /**
+     * Press a button without releasing. Pairs with `mouseUp`. Enables:
+     *   - Hold modifier + click (Ctrl+click, Shift+click selection)
+     *   - Multi-point drags (mouseDown at A, mouseMove through path, mouseUp at B)
+     *   - Press-and-hold gestures
+     */
+    mouseDown(button?: MouseButton): Promise<void>;
+    /** Release a previously-pressed button. No-op if nothing pressed. */
+    mouseUp(button?: MouseButton): Promise<void>;
+    typeText(text: string): Promise<void>;
+    keyPress(combo: PortableKeyCombo): Promise<void>;
+    /**
+     * Press a key without releasing. Pairs with `keyUp`. Enables:
+     *   - Hold shift while clicking
+     *   - Gaming-style chord input
+     *   - OS shortcuts that require precise down/up timing
+     *
+     * `key` accepts the same tokens as `keyPress` (e.g. "shift", "Return",
+     * "F5", "a"). macOS implementation uses `System Events` "key down"; Win
+     * and Linux use nut-js `keyboard.pressKey`.
+     */
+    keyDown(key: PortableKeyCombo): Promise<void>;
+    /** Release a previously-pressed key. No-op if not currently down. */
+    keyUp(key: PortableKeyCombo): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
+    /**
+     * Convenience wrapper around `launchApp`. Platform adapters keep this
+     * alias-data-agnostic — they DO NOT consult `APP_ALIASES`. Cross-OS
+     * name mapping (e.g. Windows "Notepad" → mac "TextEdit") and UWP /
+     * executable / searchTerm hints belong in the caller (the agent's
+     * `open_app` tool, the router's `handleOpenApp`), which resolves the
+     * alias and forwards the data through `launchApp` opts.
+     */
+    openApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+    }>;
+    launchApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+        url?: string;
+        cwd?: string;
+        /** Windows UWP AppsFolder ID. Ignored on macOS and Linux. */
+        uwpAppId?: string;
+        /**
+         * Human-friendly term used when the platform falls back to its native
+         * search launcher (Windows Start Menu, macOS Spotlight). When omitted,
+         * the launcher uses `name` with the `.exe` / `.app` suffix stripped —
+         * which works for most apps but fails for cases like `msedge.exe`
+         * where the binary name isn't indexed (Windows Search would surface
+         * Microsoft Store as the closest match instead of Microsoft Edge).
+         * `APP_ALIASES` provides a curated `searchTerm` per app for this.
+         */
+        searchTerm?: string;
+        /**
+         * Skip the Start-Menu / search-launcher fallback (Windows). When the
+         * direct launch doesn't surface a window, return `{}` instead of typing
+         * the name into the OS search box. Used by `open_file` for a path, where
+         * the fallback would type "explorer" and open File Explorer at **Home**
+         * instead of the requested folder — a false "Opened" with a side effect.
+         */
+        noStartMenuFallback?: boolean;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+        handle?: number | string;
+    }>;
+}
+/**
+ * Portable key combo spec — uses semantic modifiers, not platform names.
+ *
+ * "mod" resolves to Cmd on macOS, Ctrl on Windows/Linux.
+ * "alt" stays "alt" on Windows/Linux, becomes "option" on macOS at the OS level.
+ *
+ * Examples:
+ *   "mod+s"       — save (Cmd+S on mac, Ctrl+S elsewhere)
+ *   "mod+shift+t" — reopen tab
+ *   "Return"      — single key
+ *   "shift+Tab"   — modifier + key
+ */
+export type PortableKeyCombo = string;

package/dist/platform/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * PlatformAdapter — single contract for all platform-specific operations.
+ *
+ * Replaces scattered `if (IS_MAC) ... else ...` branching across 34 files.
+ * Each platform implements this interface; business logic stays platform-free.
+ *
+ * Tranche 1A (v0.8.1-alpha): adds the primitives needed to unblock the
+ * Tranche 1B / 2 MCP tools (mouseDown/mouseUp, keyDown/keyUp, middle click,
+ * horizontal scroll, window-state / bounds control, display enumeration,
+ * waitForElement, widened invokeElement actions, UI-element state flags).
+ * Every change is ADDITIVE — existing signatures kept so no caller breaks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/platform/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/platform/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}