@mseep/clawdcursor 1.5.5

package/dist/platform/linux.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Linux PlatformAdapter — all Linux-specific code lives here.
+ *
+ * Strategy:
+ *   - Mouse + keyboard: nut-js directly (same approach as Windows).
+ *   - Screenshot: nut-js screen.grab() → sharp for PNG encode / resize.
+ *   - Screen size: xrandr --query; HiDPI via GDK_SCALE / QT_SCALE_FACTOR env.
+ *   - Windows: wmctrl -lG for listing; xdotool for active-window detection.
+ *   - A11y: AT-SPI bridge not yet implemented — graceful empty returns.
+ *   - Clipboard: xclip -selection clipboard (X11 assumption).
+ *   - openApp: spawn by name, falling back to xdg-open.
+ *
+ * All tool invocations tolerate missing binaries — if wmctrl/xclip/xdotool
+ * are not installed the adapter still loads and methods return empty defaults.
+ */
+import type { PlatformAdapter, ScreenSize, ScreenshotResult, WindowInfo, UiElement, PermissionStatus, PortableKeyCombo, Display, InvokeAction, MouseButton, ScrollDirection, WaitForElementQuery, WindowState } from './types';
+export declare class LinuxAdapter implements PlatformAdapter {
+    readonly platform: "linux";
+    /**
+     * Wayland-vs-X11 detection runs at init(). Wayland blocks many X11-era
+     * input primitives (global mouse coords, cross-window drag, synthetic
+     * modifier injection) — callers use this flag to decide whether to
+     * surface graceful "not supported on Wayland" errors instead of silently
+     * misfiring through nut-js.
+     */
+    readonly environment: 'wayland' | 'x11';
+    private screenSize;
+    private binaryCache;
+    private lastCursor;
+    /**
+     * Wayland input backend. On X11 this stays `kind:'none'` and all input
+     * flows through nut-js as before. On Wayland, ydotool takes over mouse +
+     * keyboard (if present); wtype is a keyboard-only fallback. Without
+     * either, we fall through to nut-js (which silently fails) and the
+     * adapter's permission probe reports input=false.
+     */
+    private wayland;
+    /**
+     * AT-SPI D-Bus a11y bridge state (Tranche 4b). The bridge is a
+     * self-contained Python script (scripts/linux/atspi-bridge.py) that
+     * wraps gi.repository.Atspi. We probe its availability at init —
+     * requires python3 + python3-gi + gir1.2-atspi-2.0. When unavailable
+     * every a11y method returns its pre-existing safe empty response so
+     * nothing regresses on boxes without AT-SPI.
+     */
+    private atspiAvailable;
+    private atspiScript;
+    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>;
+    private grabScreen;
+    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>;
+    private resolveWindowHandle;
+    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>;
+    /**
+     * Normalize one element record from the Python bridge into the shared
+     * UiElement shape used by the Windows + macOS adapters. Missing bounds
+     * default to zero; missing state flags pass through as undefined.
+     */
+    private normalizeAtspiElement;
+    private toNutButton;
+    mouseClick(x: number, y: number, opts?: {
+        button?: MouseButton;
+        count?: number;
+    }): Promise<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>;
+    private resolveModifier;
+    private resolveKey;
+    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; cross-OS name mapping (e.g.
+     * Windows-style "Notepad" → Linux "gedit") happens in the caller above
+     * (the agent's `open_app` tool, the router's `handleOpenApp`).
+     */
+    openApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+    }>;
+    launchApp(name: string, opts?: {
+        alwaysNewInstance?: boolean;
+        url?: string;
+        cwd?: string;
+        uwpAppId?: string;
+        searchTerm?: string;
+    }): Promise<{
+        pid?: number;
+        title?: string;
+        handle?: number | string;
+    }>;
+    /**
+     * After a launch, wait for the new window to surface using diff-and-poll.
+     * Replaces the previous fixed-delay-then-single-scan, which lost slow-
+     * starting apps (Electron-based apps, Java apps, Wine apps) and made the
+     * agent fall back to keyboard shortcuts that are blocked by safety.
+     *
+     * Linux's `spawn(name, …)` directly produces the target app's PID (unlike
+     * Windows / macOS where the spawn target is a launcher), so when `pid` is
+     * supplied the helper will preferentially match it — fastest and most
+     * reliable when the binary spawns its own window.
+     */
+    private findSpawnedWindow;
+    private spawnDetached;
+    private hasBinary;
+    private parseWmctrlOutput;
+    private withTimeout;
+    private delay;
+}