@elizaos/plugin-computeruse 2.0.3-beta.2 → 2.0.3-beta.3

package/dist/platform/coords.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Coordinate translation between display-local and OS-global pixel space (WS5).
+ *
+ * Contract:
+ *   - Every public mouse-bearing action accepts `{displayId, x, y}` where
+ *     `(x, y)` is LOCAL to that display (top-left = 0,0, units = pixels of the
+ *     display's logical bounds).
+ *   - This module translates to the OS-global space the input drivers expect.
+ *
+ * Why local-first:
+ *   - The model sees each display independently (one capture, no virtual
+ *     desktop stitching). Local coords match what the model just looked at.
+ *   - Virtual-desktop coords are a perpetual DPI / negative-origin bug source.
+ *
+ * Per-OS behavior of the input drivers we wrap (nutjs / xdotool / cliclick /
+ * PowerShell `SetCursorPos`):
+ *   - Linux/X11: drivers expect global pixel coords matching xrandr origins.
+ *     Translation = display.x + local.x. No DPI conversion.
+ *   - Windows:   `SetCursorPos` and nutjs both take physical pixel coords
+ *     when the process is PerMonitorV2 DPI aware. Translation = display.x +
+ *     local.x. No multiplier here — caller is responsible for declaring
+ *     dpiAwareness.
+ *   - macOS:     Quartz event coords are in points (logical), not backing-
+ *     store pixels. Translation = display.x + local.x with no scale multiply
+ *     IF the local coords are also in points. We document the local coord
+ *     space as "logical pixels" matching the capture's render at logical
+ *     resolution; for retina captures the screenshot is upsampled to backing-
+ *     store pixels and the model is expected to scale clicks back down
+ *     before sending. The translator divides by scaleFactor when local
+ *     coords were sourced from a backing-store-resolution screenshot.
+ */
+export interface LocalPoint {
+    displayId: number;
+    x: number;
+    y: number;
+}
+export interface GlobalPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Resolve a LocalPoint to a GlobalPoint the input driver can act on.
+ *
+ * `coordSource` describes the coordinate reference:
+ *   - `"logical"` (default) — local coords are in logical pixels matching the
+ *     display's `bounds[2..3]`. No scale conversion is applied.
+ *   - `"backing"` — local coords were taken against a capture rendered at
+ *     `bounds * scaleFactor` (e.g. raw retina PNG). They are divided by
+ *     scaleFactor before translation. macOS-only relevant.
+ */
+export declare function localToGlobal(point: LocalPoint, coordSource?: "logical" | "backing"): GlobalPoint;
+/**
+ * As `localToGlobal`, but tolerates a missing displayId by defaulting to the
+ * primary display. Logs nothing — callers should warn before using this.
+ */
+export declare function localToGlobalDefault(point: {
+    displayId?: number;
+    x: number;
+    y: number;
+}, coordSource?: "logical" | "backing"): GlobalPoint;
+/**
+ * Inverse: given an OS-global point, return the (displayId, x, y) of the
+ * display containing it. Returns null if no display contains the point.
+ * Useful for translating OS-reported cursor positions back to local coords.
+ */
+export declare function globalToLocal(point: GlobalPoint): LocalPoint | null;
+/**
+ * Validate a local point is inside its display's bounds. Returns the clamped
+ * point — never throws. Use this before sending to drivers that crash on
+ * out-of-bounds coords on some Linux versions.
+ */
+export declare function clampToDisplay(point: LocalPoint): LocalPoint;
+//# sourceMappingURL=coords.d.ts.map

package/dist/platform/coords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coords.d.ts","sourceRoot":"","sources":["../../src/platform/coords.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,WAAW,GAAE,SAAS,GAAG,SAAqB,GAC7C,WAAW,CAUb;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACnD,WAAW,GAAE,SAAS,GAAG,SAAqB,GAC7C,WAAW,CASb;AAuBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAS5D"}

package/dist/platform/desktop.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cross-platform desktop automation — mouse, keyboard, scroll, drag.
+ *
+ * Ported from coasty-ai/open-computer-use desktop-automation.ts (Apache 2.0)
+ * and eliza sandbox-routes.ts performClick/performType/performKeypress.
+ *
+ * Platform backends:
+ *   macOS  — cliclick (preferred, brew install cliclick) or AppleScript fallback
+ *   Linux  — xdotool (required: sudo apt install xdotool)
+ *   Windows — PowerShell with user32.dll P/Invoke
+ *
+ * All coordinate inputs are validated via validateInt() to prevent injection.
+ */
+/**
+ * Read the current OS cursor position (legacy shell driver). Returns global
+ * logical pixels. Windows uses `System.Windows.Forms.Cursor` (must Add-Type the
+ * assembly first or the type is unresolved); macOS uses `cliclick p:.`; Linux
+ * uses `xdotool getmouselocation`.
+ */
+export declare function legacyGetCursorPosition(): {
+    x: number;
+    y: number;
+};
+export declare function desktopClick(x: number, y: number): void;
+export declare function desktopClickWithModifiers(x: number, y: number, modifiers: string[]): void;
+export declare function desktopDoubleClick(x: number, y: number): void;
+export declare function desktopRightClick(x: number, y: number): void;
+export declare function desktopMouseMove(x: number, y: number): void;
+export declare function desktopDrag(x1: number, y1: number, x2: number, y2: number): void;
+export declare function desktopScroll(x: number, y: number, direction: "up" | "down" | "left" | "right", amount?: number): void;
+export declare function desktopType(text: string): void;
+/**
+ * Press a single key by name (e.g. "Return", "Tab", "Escape", "F5").
+ */
+export declare function desktopKeyPress(key: string): void;
+/**
+ * Press a key combination like "ctrl+c", "cmd+shift+s", "alt+F4".
+ * Modifier names: ctrl, shift, alt, cmd/meta/super.
+ *
+ * Ported from open-computer-use desktopKeyCombo().
+ */
+export declare function desktopKeyCombo(combo: string): void;
+/**
+ * Windows fast-path for `set_value` (#9170 — trycua/cua `set_value`): use UI
+ * Automation `ValuePattern.SetValue` on the element under (x,y) to set its value
+ * directly, without synthesizing keystrokes. Returns `true` if the element
+ * exposed ValuePattern and was set; `false` (incl. on any error) so the caller
+ * falls back to the universal focus → select-all → type path.
+ *
+ * Uses `Add-Type -AssemblyName` (signed framework assemblies), not a
+ * runtime-compiled inline class. Real actuation is exercised by the interactive
+ * real-driver lane; this box's session can't host a ValuePattern control to
+ * probe it (see #9170).
+ */
+export declare function win32TrySetValueByPattern(x: number, y: number, value: string): boolean;
+//# sourceMappingURL=desktop.d.ts.map

package/dist/platform/desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../../src/platform/desktop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+JH;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BlE;AAID,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAwCvD;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,SAAS,EAAE,MAAM,EAAE,GAClB,IAAI,CAmHN;AAID,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAmD7D;AAID,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAuC5D;AAID,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CA6B3D;AAID,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,IAAI,CAgEN;AAID,wBAAgB,aAAa,CAC3B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,MAAM,SAAI,GACT,IAAI,CAwDN;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqC9C;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAgFjD;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAuHnD;AA8DD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,GACZ,OAAO,CAsBT"}

package/dist/platform/displays.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Multi-monitor display enumeration (WS5).
+ *
+ * Returns the live set of physical displays attached to the host, in a
+ * single, OS-agnostic shape:
+ *
+ *   { id, bounds: [x, y, w, h], scaleFactor, primary, name }
+ *
+ * Notes on `id`:
+ *   - macOS    — `CGDirectDisplayID` (32-bit unsigned). Stable across reboots.
+ *   - Windows  — `Screen.DeviceName` hash → small integer. We expose a 0-based
+ *                index because PowerShell `System.Windows.Forms.Screen` does
+ *                not surface a kernel handle, and the device name (e.g.
+ *                `\\.\DISPLAY1`) is a string. The index is stable for a given
+ *                process but may shift across hot-plug events.
+ *   - Linux X  — `xrandr --listmonitors` ordinal. Stable per process.
+ *   - Linux W  — compositor-specific output id (Hyprland/Sway). Best effort.
+ *
+ * Coordinate space:
+ *   `bounds` is in OS-global pixel space. On macOS, that means scaled
+ *   "points" by default — we record the backing-store scale factor in
+ *   `scaleFactor` so callers can translate to pixel-perfect coords when
+ *   composing captures.
+ *
+ * This module never executes input. It is read-only.
+ */
+export interface DisplayInfo {
+    /** OS-stable identifier or a 0-based fallback index. */
+    id: number;
+    /** [x, y, width, height] in OS-global pixel space. */
+    bounds: [number, number, number, number];
+    /** Backing-store scale factor. 1 on Linux, 1..N on HiDPI macOS/Windows. */
+    scaleFactor: number;
+    /** Whether this is the primary display. */
+    primary: boolean;
+    /** Human-readable name (e.g. `eDP-1`, `Built-in Retina Display`). */
+    name: string;
+}
+/**
+ * Error thrown when the host has no usable display surface. Headless Linux
+ * (no `DISPLAY` and no `WAYLAND_DISPLAY`), CI containers without an X
+ * server, and macOS/Windows hosts that report zero active displays all
+ * surface as this typed error so callers can distinguish "no monitors" from
+ * a transient enumeration failure.
+ */
+export declare class NoDisplayError extends Error {
+    readonly code: "NO_DISPLAY";
+    constructor(message: string);
+}
+/**
+ * List all attached displays. Cached to avoid spamming xrandr / PowerShell on
+ * burst calls (provider runs every turn; see {@link CACHE_MS}).
+ *
+ * Returns a single-display fallback when the OS reports nothing — most
+ * callers want a sensible default, not an empty array. Use `isHeadless()`
+ * or `assertHasDisplays()` to distinguish the truly-headless case from a
+ * single attached monitor.
+ */
+export declare function listDisplays(): DisplayInfo[];
+/** Force a fresh enumeration, ignoring cache. */
+export declare function refreshDisplays(): DisplayInfo[];
+/** Convenience: the primary display, or the first one if none is flagged. */
+export declare function getPrimaryDisplay(): DisplayInfo;
+/** Look up a display by id, or null if unknown. */
+export declare function findDisplay(id: number): DisplayInfo | null;
+/**
+ * Detect a truly headless host. Returns true when:
+ *   - Linux: neither `DISPLAY` nor `WAYLAND_DISPLAY` is set, AND no
+ *     compositor / X server enumeration tool reports anything.
+ *   - macOS / Windows: enumeration via system_profiler / PowerShell yields
+ *     zero displays.
+ * The single-display fallback returned by `listDisplays()` does NOT count as
+ * a real display for this check.
+ */
+export declare function isHeadless(): boolean;
+/**
+ * Capture-path guard: throws `NoDisplayError` on a truly headless host.
+ * Callers that hit "no monitor" should surface this typed error rather than
+ * returning an empty buffer or a generic `Error`.
+ */
+export declare function assertHasDisplays(): void;
+export declare function parseXrandrMonitors(output: string): DisplayInfo[];
+export declare function parseHyprlandMonitors(output: string): DisplayInfo[];
+export declare function parseSwayOutputs(output: string): DisplayInfo[];
+export declare function parseDarwinDisplays(output: string): DisplayInfo[];
+export declare function parseSystemProfilerDisplays(output: string): DisplayInfo[];
+export declare function parseWindowsScreens(output: string): DisplayInfo[];
+/**
+ * Asynchronously populate the display cache via the warm PowerShell host
+ * (Windows only). Lets the service pre-seed the cache at init without the
+ * blocking ~10-16s cold `powershell.exe` spawn that the sync
+ * {@link listDisplays} path would otherwise pay on the first turn. No-op (and
+ * never throws) when the host is unavailable — the sync path remains the
+ * fallback. Override the resulting TTL with `COMPUTERUSE_DISPLAYS_CACHE_MS`.
+ */
+export declare function warmDisplaysCache(): Promise<void>;
+//# sourceMappingURL=displays.d.ts.map

package/dist/platform/displays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"displays.d.ts","sourceRoot":"","sources":["../../src/platform/displays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAQ5C;AAED,iDAAiD;AACjD,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAG/C;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,WAAW,CAU/C;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAQpC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAMxC;AAuCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA+BjE;AAiED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA2BnE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA4B9D;AAsBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAuCjE;AAyED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAiDzE;AAgBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAiCjE;AAkCD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAYvD"}

package/dist/platform/driver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Driver-selection seam for desktop input + screenshot capture.
+ *
+ * Default = `nutjs` (cross-platform native bindings via @nut-tree-fork/nut-js).
+ * Set `ELIZA_COMPUTERUSE_DRIVER=legacy` to fall back to the per-OS shell
+ * drivers (cliclick/xdotool/PowerShell). The legacy drivers also activate
+ * automatically when the nutjs native module fails to load.
+ *
+ * Each exported function dispatches to the chosen backend. Callers (the
+ * service, actions, tests) use these wrappers; the underlying `desktop.ts`
+ * and `screenshot.ts` modules remain importable for the legacy code path.
+ */
+import type { ScreenRegion } from "../types.js";
+export type DriverName = "nutjs" | "legacy";
+export declare function selectedDriver(): DriverName;
+export declare function driverClick(x: number, y: number): Promise<void>;
+export declare function driverClickWithModifiers(x: number, y: number, modifiers: string[]): Promise<void>;
+export declare function driverDoubleClick(x: number, y: number): Promise<void>;
+export declare function driverRightClick(x: number, y: number): Promise<void>;
+export declare function driverMiddleClick(x: number, y: number): Promise<void>;
+export declare function driverMouseDown(x: number, y: number, button?: "left" | "middle" | "right"): Promise<void>;
+export declare function driverMouseUp(x: number, y: number, button?: "left" | "middle" | "right"): Promise<void>;
+export declare function driverMouseMove(x: number, y: number): Promise<void>;
+export declare function driverGetCursorPosition(): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function driverDrag(x1: number, y1: number, x2: number, y2: number): Promise<void>;
+export declare function driverDragPath(path: Array<{
+    x: number;
+    y: number;
+}>): Promise<void>;
+export declare function driverScroll(x: number, y: number, direction: "up" | "down" | "left" | "right", amount?: number): Promise<void>;
+export declare function driverType(text: string): Promise<void>;
+export declare function driverKeyPress(key: string): Promise<void>;
+/**
+ * Set the value of the UI element at (x,y) (#9170 — trycua/cua `set_value`).
+ * On Windows, first try UI Automation `ValuePattern.SetValue` (direct, no
+ * keystrokes — best for text inputs / combo boxes). Universal fallback (all
+ * platforms, incl. elements without ValuePattern): click to focus, select-all,
+ * then type the value — composed of the already-verified click/key-combo/type
+ * primitives. `value` is validated by the underlying type primitive.
+ */
+export declare function driverSetValue(x: number, y: number, value: string): Promise<void>;
+export declare function driverKeyCombo(combo: string): Promise<void>;
+export declare function driverKeyDown(key: string): Promise<void>;
+export declare function driverKeyUp(key: string): Promise<void>;
+export declare function driverCaptureScreenshot(region?: ScreenRegion): Promise<Buffer>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/platform/driver.d.ts.map

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

package/dist/platform/file-ops.d.ts

@@ -0,0 +1,27 @@
+import type { FileActionResult } from "../types.js";
+export declare function readFile(targetPath: string, encoding?: BufferEncoding): Promise<FileActionResult>;
+export declare function writeFile(targetPath: string, content: string): Promise<FileActionResult>;
+export declare function editFile(targetPath: string, oldText: string, newText: string): Promise<FileActionResult>;
+export declare function appendFile(targetPath: string, content: string): Promise<FileActionResult>;
+export declare function deleteFile(targetPath: string): Promise<FileActionResult>;
+export declare function fileExists(targetPath: string): Promise<FileActionResult>;
+export declare function listDirectory(targetPath: string): Promise<FileActionResult>;
+export declare function deleteDirectory(targetPath: string): Promise<FileActionResult>;
+/**
+ * Read raw bytes as base64 (#9170 — cua `read_bytes`). Optional byte `offset` /
+ * `length` window for chunked transfer of a sandbox guest file. Unlike `readFile`
+ * (text, truncated to 10k chars) this is binary-safe and returns the exact bytes.
+ */
+export declare function readBytes(targetPath: string, offset?: number, length?: number): Promise<FileActionResult>;
+/**
+ * Write base64-encoded bytes to a file (#9170 — cua `write_bytes`), creating
+ * parent directories. Binary-safe counterpart to `writeFile`.
+ */
+export declare function writeBytes(targetPath: string, base64: string): Promise<FileActionResult>;
+/** Create a directory (recursive) (#9170 — cua `create_dir`). */
+export declare function createDirectory(targetPath: string): Promise<FileActionResult>;
+/** Whether a path exists AND is a directory (#9170 — cua `directory_exists`). */
+export declare function directoryExists(targetPath: string): Promise<FileActionResult>;
+/** File/dir size in bytes (#9170 — cua `get_file_size`). */
+export declare function getFileSize(targetPath: string): Promise<FileActionResult>;
+//# sourceMappingURL=file-ops.d.ts.map

package/dist/platform/file-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-ops.d.ts","sourceRoot":"","sources":["../../src/platform/file-ops.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,aAAa,CAAC;AAG/D,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,cAAuB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAmB3B;AAED,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAED,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CA8B3B;AAED,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAED,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAmB3B;AAED,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAmB3B;AASD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAwB3B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,iEAAiE;AACjE,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAwB3B;AAED,4DAA4D;AAC5D,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAmB3B"}

package/dist/platform/helpers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared platform utilities for computer-use plugin.
+ *
+ * Ported from coasty-ai/open-computer-use desktop-automation.ts
+ * and eliza sandbox-routes.ts (Apache 2.0 / MIT).
+ */
+export declare function commandExists(cmd: string): boolean;
+/** Reset the {@link commandExists} memo (test-only / PATH change). */
+export declare function clearCommandExistsCache(): void;
+/**
+ * Run a command via execFileSync (no shell) with timeout.
+ * Throws on non-zero exit or timeout.
+ */
+export declare function runCommand(command: string, args: string[], timeout: number): string;
+/**
+ * Run a command via execFileSync, returning the raw Buffer stdout.
+ */
+export declare function runCommandBuffer(command: string, args: string[], timeout: number): void;
+/**
+ * Run a shell command string (uses shell). Use sparingly — prefer runCommand.
+ */
+export declare function runShellCommand(cmd: string, timeout: number): string;
+/**
+ * Coerce a value to a safe integer to prevent shell injection via coordinates.
+ * Ported from open-computer-use desktop-automation.ts validateInt().
+ */
+export declare function validateInt(val: unknown): number;
+/**
+ * Validate and clamp coordinates within screen bounds.
+ */
+export declare function validateCoordinate(x: number, y: number, maxX: number, maxY: number): [number, number];
+/**
+ * Validate a window/process identifier before interpolating it into a
+ * platform shell command (AppleScript / PowerShell). Rejects anything that
+ * is not a decimal integer or `0x`-prefixed hex, preventing escape out of
+ * the surrounding script literal.
+ */
+export declare function validateWindowId(windowId: string): string;
+/**
+ * Validate text input length to prevent abuse.
+ */
+export declare function validateText(text: string, maxLength?: number): string;
+/**
+ * Safely escape a string for use inside an AppleScript double-quoted literal.
+ * Ported from open-computer-use desktop-automation.ts.
+ */
+export declare function escapeAppleScript(value: string): string;
+/**
+ * Validate a key name for xdotool. Must be a known key name or a single
+ * printable ASCII character.
+ */
+export declare function safeXdotoolKey(key: string): string;
+export declare function validateKeypress(keys: string, maxLength?: number): string;
+export declare function canonicalKeyName(key: string): string;
+export declare function toCliclickKeyName(key: string): string;
+export declare function toXdotoolKeyName(key: string): string;
+export declare function toWindowsSendKey(key: string): string;
+export type PlatformOS = "darwin" | "linux" | "win32";
+export declare function currentPlatform(): PlatformOS;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/platform/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/platform/helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAalD;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,GACd,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMpE;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAYhD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,CAAC,MAAM,EAAE,MAAM,CAAC,CAIlB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,MAAM,CAQnE;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AA8DD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBlD;AAOD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAetE;AAoCD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMpD;AAmBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAmBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMpD;AAmBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMpD;AAID,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD,wBAAgB,eAAe,IAAI,UAAU,CAM5C"}

package/dist/platform/launch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Open a target (file / URL / folder) and launch applications (#9170 M12).
+ *
+ * trycua/cua exposes `open(target)` and `launch(app, args) -> pid`. Eliza had
+ * neither as a COMPUTER_USE verb. These are real desktop automation (the agent
+ * opening a document or starting an app), so they live in the COMPUTER_USE
+ * action and pass through the approval manager like every other non-read verb.
+ *
+ * Implementation notes:
+ *   - `open` shells the OS default-handler (`open` / `xdg-open` / `start`), so a
+ *     URL opens in the browser, a file in its default app, a folder in the file
+ *     manager — exactly the OS double-click behavior.
+ *   - `launch` spawns the executable DETACHED and returns its pid so the caller
+ *     can track / focus it. The child is unref'd so it outlives the agent turn.
+ */
+/** Result of a launch — the spawned process id (and the resolved command). */
+export interface LaunchResult {
+    pid: number;
+    command: string;
+    args: string[];
+}
+/**
+ * Open a file / URL / folder with the OS default handler. Resolves once the
+ * launcher returns (the launcher exits immediately; the opened app keeps
+ * running). Rejects on a non-zero launcher exit.
+ */
+export declare function openTarget(target: string): Promise<void>;
+/**
+ * Launch an application detached and return its pid. `app` is an executable
+ * name/path (or, on macOS, an app-bundle name launched via `open -a`). The
+ * child is unref'd so it survives the agent turn.
+ */
+export declare function launchApp(app: string, args?: string[]): Promise<LaunchResult>;
+/** Result of a kill — the resolved target and how it was addressed. */
+export interface KillResult {
+    target: string;
+    /** Numeric pid when the target was a pid; omitted for a process-name kill. */
+    pid?: number;
+    killed: true;
+}
+/**
+ * Terminate a running application by pid (all-digits) or process name
+ * (#9170 — trycua/cua `kill_app`). Pairs with `launchApp`. Destructive, so it
+ * routes through the approval manager like every other non-read verb. Uses
+ * `execFile` (no shell) so the target can't inject a command.
+ *
+ *   - Windows: `taskkill /F /PID <n>` or `/F /IM <name>.exe`.
+ *   - macOS / Linux: `kill -9 <pid>` or `pkill -f <name>`.
+ *
+ * Rejects when the target does not exist (non-zero exit) so the caller gets
+ * clear feedback rather than a silent no-op.
+ */
+export declare function killApp(target: string): Promise<KillResult>;
+//# sourceMappingURL=launch.d.ts.map

package/dist/platform/launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/platform/launch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BxD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,YAAY,CAAC,CA6CvB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAwC3D"}

package/dist/platform/normalized-coords.d.ts

@@ -0,0 +1,46 @@
+import type { ScreenRegion } from "../types.js";
+/** Upper bound of each normalized axis (inclusive). 0 = left/top, 1000 = right/bottom. */
+export declare const NORMALIZED_COORD_MAX = 1000;
+/** A point in the 0–1000 normalized coordinate space. */
+export interface NormalizedPoint {
+    nx: number;
+    ny: number;
+}
+/** A box in the 0–1000 normalized coordinate space (inclusive corners). */
+export interface NormalizedBox {
+    nx0: number;
+    ny0: number;
+    nx1: number;
+    ny1: number;
+}
+/** A pixel point in some display/capture space. */
+export interface PixelPoint {
+    x: number;
+    y: number;
+}
+/** The pixel extent a normalized point is measured against. */
+export interface PixelBounds {
+    width: number;
+    height: number;
+}
+/** Clamp a normalized point into [0, 1000] on both axes. */
+export declare function clampNormalized(point: NormalizedPoint): NormalizedPoint;
+/**
+ * Map a pixel point in `bounds` to the 0–1000 normalized space. The input is
+ * clamped to the bounds first, so an off-screen coordinate maps to the nearest
+ * edge rather than escaping the canonical range.
+ */
+export declare function toNormalized(point: PixelPoint, bounds: PixelBounds): NormalizedPoint;
+/**
+ * Map a normalized point back to a pixel point in `bounds`. Rounds to the nearest
+ * pixel and clamps into the bounds. Round-trips with {@link toNormalized} to
+ * within one pixel (the quantization error of the 1000-bucket grid).
+ */
+export declare function fromNormalized(point: NormalizedPoint, bounds: PixelBounds): PixelPoint;
+/** Map a pixel rectangle (`ScreenRegion`) to a normalized box. */
+export declare function boxToNormalized(region: ScreenRegion, bounds: PixelBounds): NormalizedBox;
+/** Map a normalized box back to a pixel `ScreenRegion` (non-negative width/height). */
+export declare function boxFromNormalized(box: NormalizedBox, bounds: PixelBounds): ScreenRegion;
+/** The pixel center of a normalized box — the click target a grounded element resolves to. */
+export declare function normalizedBoxCenter(box: NormalizedBox, bounds: PixelBounds): PixelPoint;
+//# sourceMappingURL=normalized-coords.d.ts.map

package/dist/platform/normalized-coords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized-coords.d.ts","sourceRoot":"","sources":["../../src/platform/normalized-coords.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAOD,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAKvE;AAcD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,GAClB,eAAe,CAKjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,WAAW,GAClB,UAAU,CAKZ;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,WAAW,GAClB,aAAa,CAOf;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,WAAW,GAClB,YAAY,CAMd;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,WAAW,GAClB,UAAU,CAKZ"}

package/dist/platform/nut-driver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cross-platform desktop driver backed by @nut-tree-fork/nut-js.
+ *
+ * Wraps native libnut bindings into the same input surface exposed by
+ * the legacy per-OS shell drivers in `desktop.ts` and `screenshot.ts`.
+ * Selected at runtime via `ELIZA_COMPUTERUSE_DRIVER=nutjs` (default) — the
+ * legacy shell drivers remain the fallback when the env var is set to
+ * `legacy` or when the native module fails to load.
+ *
+ * Native module loading: nut-js ships prebuilt binaries via `libnut`. We
+ * load it eagerly at module init and surface a clean diagnostic if the
+ * binary is missing for the current arch (`isAvailable()` reports false).
+ */
+import type { ScreenRegion } from "../types.js";
+export declare function isAvailable(): boolean;
+export declare function loadFailureReason(): string | null;
+export declare function nutClick(x: number, y: number): Promise<void>;
+export declare function nutClickWithModifiers(x: number, y: number, modifiers: string[]): Promise<void>;
+export declare function nutDoubleClick(x: number, y: number): Promise<void>;
+export declare function nutRightClick(x: number, y: number): Promise<void>;
+export declare function nutMiddleClick(x: number, y: number): Promise<void>;
+export declare function nutMouseMove(x: number, y: number): Promise<void>;
+/**
+ * Press (and hold) a mouse button at `(x, y)` without releasing it. Pairs with
+ * `nutMouseUp` to express hold-drags, marquee selection, and press-and-hold
+ * gestures that a single `click` cannot. The caller is responsible for the
+ * matching release.
+ */
+export declare function nutMouseDown(x: number, y: number, button?: "left" | "middle" | "right"): Promise<void>;
+/** Release a previously-held mouse button at `(x, y)`. See {@link nutMouseDown}. */
+export declare function nutMouseUp(x: number, y: number, button?: "left" | "middle" | "right"): Promise<void>;
+/** Clamp a requested scroll amount to a safe per-notch count (1..20). Pure. */
+export declare function clampScrollNotches(amount: number): number;
+/**
+ * Interpolated integer waypoints from (x1,y1) to (x2,y2) over `steps` moves
+ * (excludes the start, includes the end). Pure — exported for unit tests.
+ */
+export declare function interpolateDragSteps(x1: number, y1: number, x2: number, y2: number, steps?: number): Array<{
+    x: number;
+    y: number;
+}>;
+export declare function nutDrag(x1: number, y1: number, x2: number, y2: number): Promise<void>;
+/**
+ * Densify a polyline by interpolating integer waypoints along every segment so
+ * a held-button drag traces curves/corners instead of teleporting corner to
+ * corner. Includes the very first point and every segment endpoint. Pure —
+ * exported for unit tests.
+ *
+ * `perSegmentSteps` controls how many intermediate points are inserted between
+ * consecutive vertices (≥1; the endpoint is always included).
+ */
+export declare function densifyDragPath(path: Array<{
+    x: number;
+    y: number;
+}>, perSegmentSteps?: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Press the left button at the first point, move through every interpolated
+ * waypoint with the button held, then release at the last point. Backs
+ * multi-point `drag(path)` and AOSP swipe paths. Requires ≥2 points.
+ */
+export declare function nutDragPath(path: Array<{
+    x: number;
+    y: number;
+}>): Promise<void>;
+export declare function nutGetCursorPosition(): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function nutScroll(x: number, y: number, direction: "up" | "down" | "left" | "right", amount: number): Promise<void>;
+export declare function nutType(text: string): Promise<void>;
+export declare function nutKeyPress(key: string): Promise<void>;
+/** Press (and hold) a single key without releasing it. Pairs with `nutKeyUp`
+ * to express press-and-hold (e.g. holding Shift while issuing other input). */
+export declare function nutKeyDown(key: string): Promise<void>;
+/** Release a previously-held key. See {@link nutKeyDown}. */
+export declare function nutKeyUp(key: string): Promise<void>;
+export declare function nutKeyCombo(combo: string): Promise<void>;
+export declare function nutCaptureScreenshot(region?: ScreenRegion): Promise<Buffer>;
+export declare function nutScreenSize(): Promise<{
+    width: number;
+    height: number;
+}>;
+//# sourceMappingURL=nut-driver.d.ts.map

package/dist/platform/nut-driver.d.ts.map

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

package/dist/platform/permissions.d.ts

@@ -0,0 +1,33 @@
+import type { PermissionType } from "../types.js";
+type PermissionErrorOptions = {
+    permissionType: PermissionType;
+    operation: string;
+    message: string;
+    details?: string;
+};
+export type PermissionDeniedError = Error & {
+    permissionDenied: true;
+    permissionType: PermissionType;
+    operation: string;
+    details?: string;
+};
+export declare function createPermissionDeniedError(options: PermissionErrorOptions): PermissionDeniedError;
+export declare function isPermissionDeniedError(value: unknown): value is PermissionDeniedError;
+export declare function classifyPermissionDeniedError(error: unknown, fallback: {
+    permissionType: PermissionType;
+    operation: string;
+}): PermissionDeniedError | null;
+export interface PermissionProbeResult {
+    /** True if the OS reports the permission is granted for this process. */
+    readonly granted: boolean;
+    /**
+     * `null` when the OS doesn't expose a probe (Linux desktop, headless, etc.)
+     * — caller should treat this as "unknown, attempt the operation and rely on
+     * runtime classification".
+     */
+    readonly probed: boolean;
+    readonly details?: string;
+}
+export declare function probePermission(permissionType: PermissionType): PermissionProbeResult;
+export {};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/platform/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/platform/permissions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,KAAK,sBAAsB,GAAG;IAC5B,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG;IAC1C,gBAAgB,EAAE,IAAI,CAAC;IACvB,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAkCF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAUvB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,qBAAqB,CAQhC;AAcD,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE;IACR,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB,GACA,qBAAqB,GAAG,IAAI,CAiF9B;AASD,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAmCD,wBAAgB,eAAe,CAC7B,cAAc,EAAE,cAAc,GAC7B,qBAAqB,CA2BvB"}