@boxlite-ai/boxlite 0.1.0

package/dist/computerbox.d.ts

@@ -0,0 +1,271 @@
+/**
+ * ComputerBox - Desktop environment with web access.
+ *
+ * Provides a minimal, elegant API for running isolated desktop environments
+ * that can be viewed from a browser, with full GUI automation support.
+ */
+import { SimpleBox, type SimpleBoxOptions } from './simplebox';
+/**
+ * Options for creating a ComputerBox.
+ */
+export interface ComputerBoxOptions extends Omit<SimpleBoxOptions, 'image' | 'cpus' | 'memoryMib'> {
+    /** Number of CPU cores (default: 2) */
+    cpus?: number;
+    /** Memory in MiB (default: 2048) */
+    memoryMib?: number;
+    /** Port for HTTP desktop GUI (default: 3000) */
+    guiHttpPort?: number;
+    /** Port for HTTPS desktop GUI (default: 3001) */
+    guiHttpsPort?: number;
+}
+/**
+ * Screenshot result containing image data and metadata.
+ */
+export interface Screenshot {
+    /** Base64-encoded PNG image data */
+    data: string;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Image format (always 'png') */
+    format: 'png';
+}
+/**
+ * Desktop environment accessible via web browser.
+ *
+ * Auto-starts a full desktop environment with web interface.
+ * Access the desktop by opening the URL in your browser.
+ *
+ * **Note**: Uses HTTPS with self-signed certificate - your browser will show
+ * a security warning. Click "Advanced" and "Proceed" to access the desktop.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const desktop = new ComputerBox();
+ * try {
+ *   await desktop.waitUntilReady();
+ *   const screenshot = await desktop.screenshot();
+ *   console.log('Desktop ready!');
+ * } finally {
+ *   await desktop.stop();
+ * }
+ * ```
+ *
+ * ## Example with custom settings
+ *
+ * ```typescript
+ * const desktop = new ComputerBox({
+ *   memoryMib: 4096,
+ *   cpus: 4
+ * });
+ * try {
+ *   await desktop.waitUntilReady();
+ *   await desktop.mouseMove(100, 200);
+ *   await desktop.leftClick();
+ * } finally {
+ *   await desktop.stop();
+ * }
+ * ```
+ */
+export declare class ComputerBox extends SimpleBox {
+    /**
+     * Create and auto-start a desktop environment.
+     *
+     * @param options - ComputerBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox({
+     *   cpus: 2,
+     *   memoryMib: 2048,
+     *   guiHttpPort: 3000,
+     *   guiHttpsPort: 3001
+     * });
+     * ```
+     */
+    constructor(options?: ComputerBoxOptions);
+    /**
+     * Execute a command and throw ExecError if it fails.
+     *
+     * @param label - Label for error messages (e.g., 'mouseMove(100, 200)')
+     * @param cmd - Command to execute
+     * @param args - Command arguments
+     * @returns The execution result (for methods that need to parse output)
+     * @throws {ExecError} If command exits with non-zero code
+     */
+    private execOrThrow;
+    /**
+     * Wait until the desktop environment is fully loaded and ready.
+     *
+     * @param timeout - Maximum time to wait in seconds (default: 60)
+     *
+     * @throws {TimeoutError} If desktop doesn't become ready within timeout period
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox();
+     * try {
+     *   await desktop.waitUntilReady(60);
+     *   console.log('Desktop is ready!');
+     * } finally {
+     *   await desktop.stop();
+     * }
+     * ```
+     */
+    waitUntilReady(timeout?: number): Promise<void>;
+    /**
+     * Capture a screenshot of the desktop.
+     *
+     * @returns Promise resolving to screenshot data with base64 PNG, dimensions, and format
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox();
+     * try {
+     *   await desktop.waitUntilReady();
+     *   const screenshot = await desktop.screenshot();
+     *   console.log(`Screenshot: ${screenshot.width}x${screenshot.height}`);
+     *   // Save screenshot.data (base64 PNG) to file or process it
+     * } finally {
+     *   await desktop.stop();
+     * }
+     * ```
+     */
+    screenshot(): Promise<Screenshot>;
+    /**
+     * Move mouse cursor to absolute coordinates.
+     *
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     *
+     * @example
+     * ```typescript
+     * await desktop.mouseMove(100, 200);
+     * ```
+     */
+    mouseMove(x: number, y: number): Promise<void>;
+    /**
+     * Click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.leftClick();
+     * ```
+     */
+    leftClick(): Promise<void>;
+    /**
+     * Click right mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.rightClick();
+     * ```
+     */
+    rightClick(): Promise<void>;
+    /**
+     * Click middle mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.middleClick();
+     * ```
+     */
+    middleClick(): Promise<void>;
+    /**
+     * Double-click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.doubleClick();
+     * ```
+     */
+    doubleClick(): Promise<void>;
+    /**
+     * Triple-click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.tripleClick();
+     * ```
+     */
+    tripleClick(): Promise<void>;
+    /**
+     * Drag mouse from start position to end position with left button held.
+     *
+     * @param startX - Starting X coordinate
+     * @param startY - Starting Y coordinate
+     * @param endX - Ending X coordinate
+     * @param endY - Ending Y coordinate
+     *
+     * @example
+     * ```typescript
+     * await desktop.leftClickDrag(100, 100, 200, 200);
+     * ```
+     */
+    leftClickDrag(startX: number, startY: number, endX: number, endY: number): Promise<void>;
+    /**
+     * Get the current mouse cursor position.
+     *
+     * @returns Promise resolving to [x, y] coordinates
+     *
+     * @example
+     * ```typescript
+     * const [x, y] = await desktop.cursorPosition();
+     * console.log(`Cursor at: ${x}, ${y}`);
+     * ```
+     */
+    cursorPosition(): Promise<[number, number]>;
+    /**
+     * Type text using the keyboard.
+     *
+     * @param text - Text to type
+     *
+     * @example
+     * ```typescript
+     * await desktop.type('Hello, World!');
+     * ```
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Press a special key or key combination.
+     *
+     * @param keySequence - Key or key combination (e.g., 'Return', 'ctrl+c', 'alt+Tab')
+     *
+     * @example
+     * ```typescript
+     * await desktop.key('Return');
+     * await desktop.key('ctrl+c');
+     * await desktop.key('alt+Tab');
+     * ```
+     */
+    key(keySequence: string): Promise<void>;
+    /**
+     * Scroll at a specific position.
+     *
+     * @param x - X coordinate where to scroll
+     * @param y - Y coordinate where to scroll
+     * @param direction - Scroll direction: 'up', 'down', 'left', or 'right'
+     * @param amount - Number of scroll units (default: 3)
+     *
+     * @example
+     * ```typescript
+     * await desktop.scroll(500, 300, 'down', 5);
+     * ```
+     */
+    scroll(x: number, y: number, direction: 'up' | 'down' | 'left' | 'right', amount?: number): Promise<void>;
+    /**
+     * Get the screen resolution.
+     *
+     * @returns Promise resolving to [width, height] in pixels
+     *
+     * @example
+     * ```typescript
+     * const [width, height] = await desktop.getScreenSize();
+     * console.log(`Screen: ${width}x${height}`);
+     * ```
+     */
+    getScreenSize(): Promise<[number, number]>;
+}
+//# sourceMappingURL=computerbox.d.ts.map

package/dist/computerbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computerbox.d.ts","sourceRoot":"","sources":["../lib/computerbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;IAChG,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IAEd,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IAEf,kCAAkC;IAClC,MAAM,EAAE,KAAK,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,WAAY,SAAQ,SAAS;IACxC;;;;;;;;;;;;;;OAcG;gBACS,OAAO,GAAE,kBAAuB;IAqC5C;;;;;;;;OAQG;YACW,WAAW;IAQzB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,OAAO,GAAE,MAAwC,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtF;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;IAqBvC;;;;;;;;;;OAUG;IACG,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9F;;;;;;;;;;OAUG;IACG,cAAc,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAsBjD;;;;;;;;;OASG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,MAAM,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlH;;;;;;;;;;OAUG;IACG,aAAa,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAUjD"}

package/dist/computerbox.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * ComputerBox - Desktop environment with web access.
+ *
+ * Provides a minimal, elegant API for running isolated desktop environments
+ * that can be viewed from a browser, with full GUI automation support.
+ */
+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.ComputerBox = void 0;
+const simplebox_1 = require("./simplebox");
+const errors_1 = require("./errors");
+const constants = __importStar(require("./constants"));
+/**
+ * Desktop environment accessible via web browser.
+ *
+ * Auto-starts a full desktop environment with web interface.
+ * Access the desktop by opening the URL in your browser.
+ *
+ * **Note**: Uses HTTPS with self-signed certificate - your browser will show
+ * a security warning. Click "Advanced" and "Proceed" to access the desktop.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const desktop = new ComputerBox();
+ * try {
+ *   await desktop.waitUntilReady();
+ *   const screenshot = await desktop.screenshot();
+ *   console.log('Desktop ready!');
+ * } finally {
+ *   await desktop.stop();
+ * }
+ * ```
+ *
+ * ## Example with custom settings
+ *
+ * ```typescript
+ * const desktop = new ComputerBox({
+ *   memoryMib: 4096,
+ *   cpus: 4
+ * });
+ * try {
+ *   await desktop.waitUntilReady();
+ *   await desktop.mouseMove(100, 200);
+ *   await desktop.leftClick();
+ * } finally {
+ *   await desktop.stop();
+ * }
+ * ```
+ */
+class ComputerBox extends simplebox_1.SimpleBox {
+    /**
+     * Create and auto-start a desktop environment.
+     *
+     * @param options - ComputerBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox({
+     *   cpus: 2,
+     *   memoryMib: 2048,
+     *   guiHttpPort: 3000,
+     *   guiHttpsPort: 3001
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        const { cpus = constants.COMPUTERBOX_CPUS, memoryMib = constants.COMPUTERBOX_MEMORY_MIB, guiHttpPort = constants.COMPUTERBOX_GUI_HTTP_PORT, guiHttpsPort = constants.COMPUTERBOX_GUI_HTTPS_PORT, env = {}, ports = [], ...restOptions } = options;
+        // Merge default and user environment variables
+        const defaultEnv = {
+            DISPLAY: constants.COMPUTERBOX_DISPLAY_NUMBER,
+            DISPLAY_SIZEW: constants.COMPUTERBOX_DISPLAY_WIDTH.toString(),
+            DISPLAY_SIZEH: constants.COMPUTERBOX_DISPLAY_HEIGHT.toString(),
+            SELKIES_MANUAL_WIDTH: constants.COMPUTERBOX_DISPLAY_WIDTH.toString(),
+            SELKIES_MANUAL_HEIGHT: constants.COMPUTERBOX_DISPLAY_HEIGHT.toString(),
+            SELKIES_UI_SHOW_SIDEBAR: 'false',
+        };
+        // Merge default and user ports
+        const defaultPorts = [
+            { hostPort: guiHttpPort, guestPort: constants.COMPUTERBOX_GUI_HTTP_PORT },
+            { hostPort: guiHttpsPort, guestPort: constants.COMPUTERBOX_GUI_HTTPS_PORT },
+        ];
+        super({
+            ...restOptions,
+            image: constants.COMPUTERBOX_IMAGE,
+            cpus,
+            memoryMib,
+            env: { ...defaultEnv, ...env },
+            ports: [...defaultPorts, ...ports],
+        });
+    }
+    /**
+     * Execute a command and throw ExecError if it fails.
+     *
+     * @param label - Label for error messages (e.g., 'mouseMove(100, 200)')
+     * @param cmd - Command to execute
+     * @param args - Command arguments
+     * @returns The execution result (for methods that need to parse output)
+     * @throws {ExecError} If command exits with non-zero code
+     */
+    async execOrThrow(label, cmd, ...args) {
+        const result = await this.exec(cmd, ...args);
+        if (result.exitCode !== 0) {
+            throw new errors_1.ExecError(label, result.exitCode, result.stderr);
+        }
+        return result;
+    }
+    /**
+     * Wait until the desktop environment is fully loaded and ready.
+     *
+     * @param timeout - Maximum time to wait in seconds (default: 60)
+     *
+     * @throws {TimeoutError} If desktop doesn't become ready within timeout period
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox();
+     * try {
+     *   await desktop.waitUntilReady(60);
+     *   console.log('Desktop is ready!');
+     * } finally {
+     *   await desktop.stop();
+     * }
+     * ```
+     */
+    async waitUntilReady(timeout = constants.DESKTOP_READY_TIMEOUT) {
+        const startTime = Date.now();
+        while (true) {
+            const elapsed = (Date.now() - startTime) / 1000;
+            if (elapsed > timeout) {
+                throw new errors_1.TimeoutError(`Desktop did not become ready within ${timeout} seconds`);
+            }
+            try {
+                const result = await this.exec('xwininfo', '-tree', '-root');
+                const expectedSize = `${constants.COMPUTERBOX_DISPLAY_WIDTH}x${constants.COMPUTERBOX_DISPLAY_HEIGHT}`;
+                if (result.stdout.includes('xfdesktop') && result.stdout.includes(expectedSize)) {
+                    return;
+                }
+                // Wait before retrying
+                await new Promise(resolve => setTimeout(resolve, constants.DESKTOP_READY_RETRY_DELAY * 1000));
+            }
+            catch (error) {
+                // Desktop not ready yet, retry
+                await new Promise(resolve => setTimeout(resolve, constants.DESKTOP_READY_RETRY_DELAY * 1000));
+            }
+        }
+    }
+    /**
+     * Capture a screenshot of the desktop.
+     *
+     * @returns Promise resolving to screenshot data with base64 PNG, dimensions, and format
+     *
+     * @example
+     * ```typescript
+     * const desktop = new ComputerBox();
+     * try {
+     *   await desktop.waitUntilReady();
+     *   const screenshot = await desktop.screenshot();
+     *   console.log(`Screenshot: ${screenshot.width}x${screenshot.height}`);
+     *   // Save screenshot.data (base64 PNG) to file or process it
+     * } finally {
+     *   await desktop.stop();
+     * }
+     * ```
+     */
+    async screenshot() {
+        const pythonCode = `
+from PIL import ImageGrab
+import io
+import base64
+img = ImageGrab.grab()
+buffer = io.BytesIO()
+img.save(buffer, format="PNG")
+print(base64.b64encode(buffer.getvalue()).decode("utf-8"))
+`.trim();
+        const result = await this.execOrThrow('screenshot()', 'python3', '-c', pythonCode);
+        return {
+            data: result.stdout.trim(),
+            width: constants.COMPUTERBOX_DISPLAY_WIDTH,
+            height: constants.COMPUTERBOX_DISPLAY_HEIGHT,
+            format: 'png',
+        };
+    }
+    /**
+     * Move mouse cursor to absolute coordinates.
+     *
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     *
+     * @example
+     * ```typescript
+     * await desktop.mouseMove(100, 200);
+     * ```
+     */
+    async mouseMove(x, y) {
+        await this.execOrThrow(`mouseMove(${x}, ${y})`, 'xdotool', 'mousemove', x.toString(), y.toString());
+    }
+    /**
+     * Click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.leftClick();
+     * ```
+     */
+    async leftClick() {
+        await this.execOrThrow('leftClick()', 'xdotool', 'click', '1');
+    }
+    /**
+     * Click right mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.rightClick();
+     * ```
+     */
+    async rightClick() {
+        await this.execOrThrow('rightClick()', 'xdotool', 'click', '3');
+    }
+    /**
+     * Click middle mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.middleClick();
+     * ```
+     */
+    async middleClick() {
+        await this.execOrThrow('middleClick()', 'xdotool', 'click', '2');
+    }
+    /**
+     * Double-click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.doubleClick();
+     * ```
+     */
+    async doubleClick() {
+        await this.execOrThrow('doubleClick()', 'xdotool', 'click', '--repeat', '2', '--delay', '100', '1');
+    }
+    /**
+     * Triple-click left mouse button at current position.
+     *
+     * @example
+     * ```typescript
+     * await desktop.tripleClick();
+     * ```
+     */
+    async tripleClick() {
+        await this.execOrThrow('tripleClick()', 'xdotool', 'click', '--repeat', '3', '--delay', '100', '1');
+    }
+    /**
+     * Drag mouse from start position to end position with left button held.
+     *
+     * @param startX - Starting X coordinate
+     * @param startY - Starting Y coordinate
+     * @param endX - Ending X coordinate
+     * @param endY - Ending Y coordinate
+     *
+     * @example
+     * ```typescript
+     * await desktop.leftClickDrag(100, 100, 200, 200);
+     * ```
+     */
+    async leftClickDrag(startX, startY, endX, endY) {
+        await this.execOrThrow('leftClickDrag()', 'xdotool', 'mousemove', startX.toString(), startY.toString(), 'mousedown', '1', 'sleep', '0.1', 'mousemove', endX.toString(), endY.toString(), 'sleep', '0.1', 'mouseup', '1');
+    }
+    /**
+     * Get the current mouse cursor position.
+     *
+     * @returns Promise resolving to [x, y] coordinates
+     *
+     * @example
+     * ```typescript
+     * const [x, y] = await desktop.cursorPosition();
+     * console.log(`Cursor at: ${x}, ${y}`);
+     * ```
+     */
+    async cursorPosition() {
+        const result = await this.execOrThrow('cursorPosition()', 'xdotool', 'getmouselocation', '--shell');
+        let x;
+        let y;
+        for (const line of result.stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('X=')) {
+                x = parseInt(trimmed.slice(2), 10);
+            }
+            else if (trimmed.startsWith('Y=')) {
+                y = parseInt(trimmed.slice(2), 10);
+            }
+        }
+        if (x !== undefined && y !== undefined) {
+            return [x, y];
+        }
+        throw new errors_1.ParseError('Failed to parse cursor position from xdotool output');
+    }
+    /**
+     * Type text using the keyboard.
+     *
+     * @param text - Text to type
+     *
+     * @example
+     * ```typescript
+     * await desktop.type('Hello, World!');
+     * ```
+     */
+    async type(text) {
+        await this.execOrThrow('type()', 'xdotool', 'type', '--', text);
+    }
+    /**
+     * Press a special key or key combination.
+     *
+     * @param keySequence - Key or key combination (e.g., 'Return', 'ctrl+c', 'alt+Tab')
+     *
+     * @example
+     * ```typescript
+     * await desktop.key('Return');
+     * await desktop.key('ctrl+c');
+     * await desktop.key('alt+Tab');
+     * ```
+     */
+    async key(keySequence) {
+        await this.execOrThrow('key()', 'xdotool', 'key', keySequence);
+    }
+    /**
+     * Scroll at a specific position.
+     *
+     * @param x - X coordinate where to scroll
+     * @param y - Y coordinate where to scroll
+     * @param direction - Scroll direction: 'up', 'down', 'left', or 'right'
+     * @param amount - Number of scroll units (default: 3)
+     *
+     * @example
+     * ```typescript
+     * await desktop.scroll(500, 300, 'down', 5);
+     * ```
+     */
+    async scroll(x, y, direction, amount = 3) {
+        const directionMap = {
+            up: '4',
+            down: '5',
+            left: '6',
+            right: '7',
+        };
+        const button = directionMap[direction.toLowerCase()];
+        if (!button) {
+            throw new Error(`Invalid scroll direction: ${direction}`);
+        }
+        await this.execOrThrow('scroll()', 'xdotool', 'mousemove', x.toString(), y.toString(), 'click', '--repeat', amount.toString(), button);
+    }
+    /**
+     * Get the screen resolution.
+     *
+     * @returns Promise resolving to [width, height] in pixels
+     *
+     * @example
+     * ```typescript
+     * const [width, height] = await desktop.getScreenSize();
+     * console.log(`Screen: ${width}x${height}`);
+     * ```
+     */
+    async getScreenSize() {
+        const result = await this.execOrThrow('getScreenSize()', 'xdotool', 'getdisplaygeometry');
+        const parts = result.stdout.trim().split(/\s+/);
+        if (parts.length === 2) {
+            return [parseInt(parts[0], 10), parseInt(parts[1], 10)];
+        }
+        throw new errors_1.ParseError('Failed to parse screen size from xdotool output');
+    }
+}
+exports.ComputerBox = ComputerBox;
+//# sourceMappingURL=computerbox.js.map

package/dist/computerbox.js.map

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