@mseep/clawdcursor 1.5.5

package/dist/platform/wayland-backend.js

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * Wayland input routing via ydotool / wtype.
+ *
+ * The Linux adapter's nut-js path silently fails on most Wayland
+ * compositors because synthetic input events are blocked at the
+ * compositor layer unless injected through a privileged daemon.
+ * This module provides a minimal backend that routes mouse + keyboard
+ * operations through `ydotool` (requires `ydotoold` running with
+ * uinput access) or `wtype` (keyboard-only).
+ *
+ * Detection order at construction:
+ *   1. `ydotool` + socket reachable → preferred (mouse + keyboard)
+ *   2. `wtype` → keyboard-only fallback
+ *   3. neither → `none`; caller must return graceful error
+ *
+ * ydotool reference:
+ *   mousemove --absolute <x> <y>
+ *   click 0xC0                  (left)   0xC1 (right)   0xC2 (middle)
+ *   key <code>:1                (down)   <code>:0      (up)
+ *   type --delay 10 "text"
+ *   mousemove -x <dx> -y <dy>  (relative)
+ *
+ * All command construction goes through `execFile` (not shell), so
+ * there is NO shell interpolation of user text — clawdcursor typing
+ * a string with `$` or backticks is safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaylandBackend = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const TIMEOUT_MS = 5_000;
+/** Linux keycodes for the commonly-held modifiers + named keys we care about.
+ *  Source: /usr/include/linux/input-event-codes.h
+ *  Complete list isn't needed — covers the 90% case. Unknown keys fall back
+ *  to `ydotool type` (which synthesizes the codepoint).
+ */
+const LINUX_KEYCODES = {
+    // Modifiers
+    ctrl: 29, control: 29, leftctrl: 29,
+    rightctrl: 97,
+    shift: 42, leftshift: 42,
+    rightshift: 54,
+    alt: 56, option: 56, leftalt: 56,
+    rightalt: 100, altgr: 100,
+    super: 125, meta: 125, win: 125, cmd: 125,
+    rightsuper: 126,
+    // Navigation / editing
+    return: 28, enter: 28,
+    tab: 15,
+    escape: 1, esc: 1,
+    backspace: 14,
+    space: 57,
+    delete: 111,
+    home: 102,
+    end: 107,
+    pageup: 104,
+    pagedown: 109,
+    insert: 110,
+    capslock: 58,
+    // Arrows
+    left: 105,
+    right: 106,
+    up: 103,
+    down: 108,
+    // F-keys
+    f1: 59, f2: 60, f3: 61, f4: 62, f5: 63, f6: 64,
+    f7: 65, f8: 66, f9: 67, f10: 68, f11: 87, f12: 88,
+};
+/** Map an ASCII alphanumeric character to its Linux keycode. */
+function charToKeycode(ch) {
+    if (ch.length !== 1)
+        return null;
+    const lower = ch.toLowerCase();
+    // a-z → 30..56 skipping a few (30=a, 48=b, 46=c, 32=d, 18=e, 33=f, 34=g,
+    //   35=h, 23=i, 36=j, 37=k, 38=l, 50=m, 49=n, 24=o, 25=p, 16=q, 19=r,
+    //   31=s, 20=t, 22=u, 47=v, 17=w, 45=x, 21=y, 44=z)
+    const lettersMap = {
+        a: 30, b: 48, c: 46, d: 32, e: 18, f: 33, g: 34, h: 35, i: 23, j: 36,
+        k: 37, l: 38, m: 50, n: 49, o: 24, p: 25, q: 16, r: 19, s: 31, t: 20,
+        u: 22, v: 47, w: 17, x: 45, y: 21, z: 44,
+    };
+    if (lower in lettersMap)
+        return lettersMap[lower];
+    // 0-9 → 10..19 (0=11, 1=2, 2=3, ..., 9=10)  Wait — actually 1=2, 2=3, ..., 0=11.
+    const digitsMap = {
+        '1': 2, '2': 3, '3': 4, '4': 5, '5': 6, '6': 7, '7': 8, '8': 9, '9': 10, '0': 11,
+    };
+    if (lower in digitsMap)
+        return digitsMap[lower];
+    return null;
+}
+class WaylandBackend {
+    kind;
+    mod2code;
+    constructor(kind) {
+        this.kind = kind;
+        this.mod2code = {
+            mod: LINUX_KEYCODES.ctrl, // Linux "mod" resolves to Ctrl (same as clawdcursor's portable spec)
+            ctrl: LINUX_KEYCODES.ctrl,
+            control: LINUX_KEYCODES.ctrl,
+            shift: LINUX_KEYCODES.shift,
+            alt: LINUX_KEYCODES.alt,
+            option: LINUX_KEYCODES.alt,
+            super: LINUX_KEYCODES.super,
+            meta: LINUX_KEYCODES.super,
+            cmd: LINUX_KEYCODES.super,
+            command: LINUX_KEYCODES.super,
+            win: LINUX_KEYCODES.super,
+        };
+    }
+    static async detect(hasBinary) {
+        const [hasYd, hasWt] = await Promise.all([hasBinary('ydotool'), hasBinary('wtype')]);
+        if (hasYd)
+            return new WaylandBackend('ydotool');
+        if (hasWt)
+            return new WaylandBackend('wtype-keyboard-only');
+        return new WaylandBackend('none');
+    }
+    canMouse() { return this.kind === 'ydotool'; }
+    canKeyboard() { return this.kind === 'ydotool' || this.kind === 'wtype-keyboard-only'; }
+    // ── Mouse ───────────────────────────────────────────────────
+    async mouseMoveAbsolute(x, y) {
+        if (this.kind !== 'ydotool')
+            return;
+        await execFileAsync('ydotool', ['mousemove', '--absolute', '-x', String(x), '-y', String(y)], {
+            timeout: TIMEOUT_MS,
+        });
+    }
+    async mouseMoveRelative(dx, dy) {
+        if (this.kind !== 'ydotool')
+            return;
+        await execFileAsync('ydotool', ['mousemove', '-x', String(dx), '-y', String(dy)], {
+            timeout: TIMEOUT_MS,
+        });
+    }
+    /** `click` is a down+up in one ydotool call. For separate down/up, use mouseDown/mouseUp. */
+    async mouseClick(button = 'left', count = 1) {
+        if (this.kind !== 'ydotool')
+            return;
+        const code = button === 'left' ? '0xC0' : button === 'right' ? '0xC1' : '0xC2';
+        for (let i = 0; i < count; i++) {
+            await execFileAsync('ydotool', ['click', code], { timeout: TIMEOUT_MS });
+            if (i < count - 1)
+                await sleep(50);
+        }
+    }
+    async mouseDown(button = 'left') {
+        if (this.kind !== 'ydotool')
+            return;
+        // ydotool has `mousedown` on newer versions; fall back to the raw button
+        // code with :1 suffix which works on all versions.
+        const code = button === 'left' ? '0x110' : button === 'right' ? '0x111' : '0x112';
+        await execFileAsync('ydotool', ['key', `${code}:1`], { timeout: TIMEOUT_MS });
+    }
+    async mouseUp(button = 'left') {
+        if (this.kind !== 'ydotool')
+            return;
+        const code = button === 'left' ? '0x110' : button === 'right' ? '0x111' : '0x112';
+        await execFileAsync('ydotool', ['key', `${code}:0`], { timeout: TIMEOUT_MS });
+    }
+    async mouseScroll(direction, amount = 3) {
+        if (this.kind !== 'ydotool')
+            return;
+        // `ydotool mousemove --wheel` doesn't exist; use `ydotool scroll` if
+        // available, else fall back to button-code press (4/5 vertical, 6/7 horizontal).
+        try {
+            if (direction === 'up')
+                await execFileAsync('ydotool', ['scroll', String(-amount)], { timeout: TIMEOUT_MS });
+            else if (direction === 'down')
+                await execFileAsync('ydotool', ['scroll', String(amount)], { timeout: TIMEOUT_MS });
+            else {
+                // Horizontal: ydotool doesn't directly support; fall back to button codes.
+                const code = direction === 'left' ? '0x06' : '0x07';
+                for (let i = 0; i < amount; i++) {
+                    await execFileAsync('ydotool', ['key', `${code}:1`, `${code}:0`], { timeout: TIMEOUT_MS });
+                }
+            }
+        }
+        catch {
+            // scroll subcmd not supported on this ydotool build — try button codes.
+            const code = direction === 'up' ? '0x04' :
+                direction === 'down' ? '0x05' :
+                    direction === 'left' ? '0x06' : '0x07';
+            for (let i = 0; i < amount; i++) {
+                await execFileAsync('ydotool', ['key', `${code}:1`, `${code}:0`], { timeout: TIMEOUT_MS });
+            }
+        }
+    }
+    // ── Keyboard ────────────────────────────────────────────────
+    /**
+     * Press a key combo. On ydotool we map each component to a Linux
+     * keycode and emit paired down/up events. On wtype we use wtype's
+     * native combo syntax (e.g. `wtype -M ctrl -k s`).
+     */
+    async keyPress(combo) {
+        if (this.kind === 'none')
+            return;
+        // Special case: literal "+"
+        if (combo === '+') {
+            if (this.kind === 'ydotool') {
+                await execFileAsync('ydotool', ['type', '--', '+'], { timeout: TIMEOUT_MS });
+            }
+            else {
+                await execFileAsync('wtype', ['+'], { timeout: TIMEOUT_MS });
+            }
+            return;
+        }
+        const parts = combo.split('+').map(s => s.trim()).filter(Boolean);
+        if (parts.length === 0)
+            return;
+        if (this.kind === 'wtype-keyboard-only') {
+            // wtype: -M <mod> repeatable, then -k <keyname> or bare text.
+            const args = [];
+            const modsLower = parts.slice(0, -1).map(p => p.toLowerCase());
+            const key = parts[parts.length - 1];
+            for (const m of modsLower) {
+                const wm = wtypeModName(m);
+                if (wm) {
+                    args.push('-M', wm);
+                }
+            }
+            // wtype named keys (Return, Tab, etc.) go via `-k`.
+            const wtypeKey = wtypeKeyName(key);
+            if (wtypeKey) {
+                args.push('-k', wtypeKey);
+            }
+            else if (key.length === 1) {
+                args.push(key);
+            }
+            else {
+                // Unknown key — best-effort type the text.
+                args.push(key);
+            }
+            await execFileAsync('wtype', args, { timeout: TIMEOUT_MS }).catch(() => { });
+            return;
+        }
+        // ydotool path: press all modifier codes (down), tap main key, release modifiers.
+        const modCodes = [];
+        for (let i = 0; i < parts.length - 1; i++) {
+            const code = this.mod2code[parts[i].toLowerCase()];
+            if (typeof code === 'number')
+                modCodes.push(code);
+        }
+        const mainName = parts[parts.length - 1];
+        const mainCode = this.keyToCode(mainName);
+        try {
+            // Press modifiers
+            for (const c of modCodes) {
+                await execFileAsync('ydotool', ['key', `${c}:1`], { timeout: TIMEOUT_MS });
+            }
+            if (mainCode !== null) {
+                await execFileAsync('ydotool', ['key', `${mainCode}:1`, `${mainCode}:0`], {
+                    timeout: TIMEOUT_MS,
+                });
+            }
+            else if (mainName.length > 0) {
+                // No keycode mapping — type it as text (ydotool type handles the layout).
+                await execFileAsync('ydotool', ['type', '--', mainName], { timeout: TIMEOUT_MS });
+            }
+        }
+        finally {
+            // Release modifiers in reverse order
+            for (let i = modCodes.length - 1; i >= 0; i--) {
+                await execFileAsync('ydotool', ['key', `${modCodes[i]}:0`], { timeout: TIMEOUT_MS })
+                    .catch(() => { });
+            }
+        }
+    }
+    async keyDown(key) {
+        if (this.kind !== 'ydotool')
+            return;
+        const code = this.keyToCode(key.toLowerCase());
+        if (code === null)
+            return;
+        await execFileAsync('ydotool', ['key', `${code}:1`], { timeout: TIMEOUT_MS });
+    }
+    async keyUp(key) {
+        if (this.kind !== 'ydotool')
+            return;
+        const code = this.keyToCode(key.toLowerCase());
+        if (code === null)
+            return;
+        await execFileAsync('ydotool', ['key', `${code}:0`], { timeout: TIMEOUT_MS });
+    }
+    async typeText(text) {
+        if (this.kind === 'none' || !text)
+            return;
+        if (this.kind === 'ydotool') {
+            // Small delay so fast apps don't drop chars.
+            await execFileAsync('ydotool', ['type', '--delay', '10', '--', text], {
+                timeout: TIMEOUT_MS + text.length * 15,
+            });
+            return;
+        }
+        // wtype: positional arg
+        await execFileAsync('wtype', ['--', text], {
+            timeout: TIMEOUT_MS + text.length * 15,
+        });
+    }
+    // ── Internals ───────────────────────────────────────────────
+    keyToCode(name) {
+        const low = name.toLowerCase();
+        if (low in LINUX_KEYCODES)
+            return LINUX_KEYCODES[low];
+        if (low in this.mod2code)
+            return this.mod2code[low];
+        const ch = charToKeycode(name);
+        if (ch !== null)
+            return ch;
+        return null;
+    }
+}
+exports.WaylandBackend = WaylandBackend;
+function wtypeModName(m) {
+    if (m === 'ctrl' || m === 'control' || m === 'mod')
+        return 'ctrl';
+    if (m === 'shift')
+        return 'shift';
+    if (m === 'alt' || m === 'option')
+        return 'alt';
+    if (m === 'super' || m === 'cmd' || m === 'command' || m === 'meta' || m === 'win')
+        return 'logo';
+    return null;
+}
+function wtypeKeyName(k) {
+    const lo = k.toLowerCase();
+    const map = {
+        return: 'Return', enter: 'Return',
+        tab: 'Tab',
+        space: 'space',
+        escape: 'Escape', esc: 'Escape',
+        backspace: 'BackSpace',
+        delete: 'Delete',
+        home: 'Home', end: 'End',
+        pageup: 'Page_Up', pagedown: 'Page_Down',
+        insert: 'Insert',
+        left: 'Left', right: 'Right', up: 'Up', down: 'Down',
+        f1: 'F1', f2: 'F2', f3: 'F3', f4: 'F4', f5: 'F5', f6: 'F6',
+        f7: 'F7', f8: 'F8', f9: 'F9', f10: 'F10', f11: 'F11', f12: 'F12',
+    };
+    return map[lo] ?? null;
+}
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+//# sourceMappingURL=wayland-backend.js.map

package/dist/platform/wayland-backend.js.map

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

package/dist/platform/windows.d.ts

@@ -0,0 +1,232 @@
+/**
+ * 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.
+ */
+import type { PlatformAdapter, ScreenSize, ScreenshotResult, WindowInfo, UiElement, PermissionStatus, PortableKeyCombo, Display, InvokeAction, MouseButton, ScrollDirection, WaitForElementQuery, WindowState, FocusActivation } from './types';
+export declare class WindowsAdapter implements PlatformAdapter {
+    readonly platform: "win32";
+    private screenSize;
+    init(): Promise<void>;
+    shutdown(): Promise<void>;
+    checkPermissions(): Promise<PermissionStatus>;
+    requestPermissions(): Promise<PermissionStatus>;
+    getScreenSize(): Promise<ScreenSize>;
+    listDisplays(): Promise<Display[]>;
+    screenshot(opts?: {
+        maxWidth?: number;
+        displayIndex?: number;
+    }): Promise<ScreenshotResult>;
+    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>;
+    maximizeWindow(): Promise<void>;
+    setWindowState(state: WindowState, query?: {
+        processName?: string;
+        processId?: number;
+        title?: string;
+    }): Promise<boolean>;
+    setWindowBounds(bounds: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    }, query?: {
+        processName?: string;
+        processId?: number;
+        title?: string;
+    }): Promise<boolean>;
+    /**
+     * Internal helper — resolve a focusWindow-style query to a single
+     * WindowInfo. Same precedence the public `focusWindow` uses.
+     */
+    private resolveWindow;
+    getUiTree(processId?: number): Promise<UiElement[]>;
+    findElements(query: {
+        name?: string;
+        controlType?: string;
+        processId?: number;
+    }): Promise<UiElement[]>;
+    getFocusedElement(): Promise<UiElement | null>;
+    invokeElement(query: {
+        name?: string;
+        controlType?: string;
+        processId?: number;
+        action?: InvokeAction;
+        value?: string;
+    }): Promise<{
+        success: boolean;
+        bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        data?: Record<string, unknown>;
+    }>;
+    waitForElement(query: WaitForElementQuery, timeoutMs: number): Promise<UiElement | null>;
+    /** Cursor cache for mouseMoveRelative — last known target. */
+    private lastCursor;
+    /**
+     * 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.
+     */
+    private ensureForegroundAtPoint;
+    private toNutButton;
+    mouseClick(x: number, y: number, opts?: {
+        button?: MouseButton;
+        count?: number;
+    }): Promise<FocusActivation | void>;
+    mouseMove(x: number, y: number): Promise<void>;
+    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>;
+    mouseDown(button?: MouseButton): Promise<void>;
+    mouseUp(button?: MouseButton): Promise<void>;
+    typeText(text: string): Promise<void>;
+    keyPress(combo: PortableKeyCombo): Promise<void>;
+    keyDown(key: PortableKeyCombo): Promise<void>;
+    keyUp(key: PortableKeyCombo): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
+    /**
+     * 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.
+     */
+    openApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+    }>;
+    launchApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+        url?: string;
+        cwd?: string;
+        /**
+         * UWP AppsFolder ID, e.g. `Microsoft.WindowsCalculator_8wekyb3d8bbwe!App`.
+         * Launches via `explorer.exe shell:AppsFolder\<id>` which works for
+         * Store / UWP apps where `Start-Process -FilePath <exe>` silently fails.
+         * Takes precedence over `name` when provided.
+         */
+        uwpAppId?: string;
+        /**
+         * Human-friendly term for the Start-Menu-search fallback. See the
+         * `PlatformAdapter` interface doc for why this matters — typing the
+         * binary name in Start Menu can surface the wrong app.
+         */
+        searchTerm?: string;
+        /** Skip the Start-Menu search fallback; return {} if no window surfaces. */
+        noStartMenuFallback?: boolean;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+        handle?: number | string;
+    }>;
+    /**
+     * 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.
+     */
+    private foregroundLaunched;
+    /**
+     * 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.
+     */
+    private launchViaStartMenuSearch;
+    /**
+     * 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.
+     */
+    private findLaunchedWindow;
+    /**
+     * 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.
+     */
+    private findExistingAppWindow;
+    /**
+     * 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.
+     */
+    private findExistingAppWindowIn;
+    /**
+     * 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.
+     */
+    private psQuote;
+    private normalizeWindow;
+    private normalizeElement;
+    /**
+     * Flatten the UIA tree into a single list, matching the macOS adapter's
+     * contract. Drops purely structural unnamed nodes to keep the list useful.
+     */
+    private flattenTree;
+    /**
+     * 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).
+     */
+    private mapKey;
+    private delay;
+}