@trycua/cua-driver 0.31.0 → 0.32.0

package/README.md

@@ -110,7 +110,7 @@ retry. Refresh stale tokens from the same exact window.
 Window IDs are `bigint`; do not convert them to `number`.
 
 See the [migration guide](../docs/native-window-sdk-migration.md) for input and
-return-type changes, and the [complete Python and TypeScript examples](https://cua.ai/docs/how-to-guides/driver/use-sdk-in-process)
+return-type changes, and the [complete Python and TypeScript examples](https://cua.ai/docs/cua-driver/guides/use-the-sdk)
 for discovery, token selection, verification, and shutdown.
 
 ## Authorization integrations
@@ -127,7 +127,7 @@ content-free action, refusal, grant, and session events. The observer cannot
 change authorization or tool results. Use
 `createConfiguredWithHostIntegrations` when the application needs both.
 
-See the [SDK reference](https://cua.ai/docs/reference/cua-driver/sdk-reference)
+See the [SDK reference](https://cua.ai/docs/cua-driver/guides/use-the-sdk#constructors)
 for complete examples and the callback trust rules.
 
 `CuaDriver.connect(socketPath)` remains available while existing applications

package/dist/native/cua_driver_contract.d.ts

@@ -600,6 +600,10 @@ export type DragInput = {
     fromY: number;
     toX: number;
     toY: number;
+    /**
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
+     */
     target?: ActionTarget;
     /**
      * Deprecated flat desktop target retained for wire compatibility.
@@ -709,7 +713,13 @@ export declare enum EscalationReason {
     Other = 4
 }
 export type EscalateSessionInput = {
+    /**
+     * Public label of the legacy capture-scope session to escalate.
+     */
     session: string;
+    /**
+     * Why the window-scoped attempt failed and desktop capture is needed.
+     */
     reason: EscalationReason;
     /**
      * Optional bounded diagnostic detail. Never use secrets or page content.
@@ -725,6 +735,9 @@ export declare const EscalateSessionInput: Readonly<{
     defaults: () => Partial<EscalateSessionInput>;
 }>;
 export type GetAgentCursorStateInput = {
+    /**
+     * Public label of the session whose cursor to inspect.
+     */
     session: string;
 };
 /**
@@ -869,6 +882,10 @@ export declare const GetWindowStateInput: Readonly<{
 }>;
 export type HotkeyInput = {
     keys: Array<string>;
+    /**
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
+     */
     target?: ActionTarget;
     /**
      * Deprecated flat desktop target retained for wire compatibility.
@@ -894,8 +911,18 @@ export declare const HotkeyInput: Readonly<{
  * trimming surrounding whitespace and otherwise remain case-sensitive.
  */
 export type InvokeMenuInput = {
+    /**
+     * Process ID of the application that owns the menu.
+     */
     pid: number;
+    /**
+     * Window ID from list_windows whose menu is invoked.
+     */
     windowId: bigint;
+    /**
+     * Menu labels from the top-level menu to the item, e.g. `["File", "Save As..."]`
+     * (1 to 16 labels).
+     */
     path: Array<string>;
     /**
      * For multi-call work, prefer a short public session label and repeat it on every call that
@@ -1068,10 +1095,18 @@ export declare const ListWindowsOutput: Readonly<{
     defaults: () => Partial<ListWindowsOutput>;
 }>;
 export type MoveCursorInput = {
+    /**
+     * Destination X: window-local screenshot pixels for a window target, native
+     * get_desktop_state screenshot pixels for the desktop.
+     */
     x: number;
+    /**
+     * Destination Y, in the same space as `x`.
+     */
     y: number;
     /**
-     * Preferred per-call target. New callers should set this field.
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
      */
     target?: ActionTarget;
     /**
@@ -1100,8 +1135,17 @@ export declare enum VisualRegionKind {
  * Optional, model-neutral controls for one bounded parse.
  */
 export type ParseVisualRegionsOptions = {
+    /**
+     * Region kinds to return (`text`, `icon`). Omit for all kinds.
+     */
     kinds?: Array<VisualRegionKind>;
+    /**
+     * Drop regions below this confidence (0 to 1).
+     */
     minConfidence?: number;
+    /**
+     * Return at most this many regions.
+     */
     maxRegions?: number;
 };
 /**
@@ -1118,6 +1162,9 @@ export declare const ParseVisualRegionsOptions: Readonly<{
  * resolves it to the exact pixels and action-coordinate transform.
  */
 export type ParseVisualRegionsInput = {
+    /**
+     * `capture_id` of a screenshot returned by get_window_state or get_desktop_state.
+     */
     captureId: string;
     options: ParseVisualRegionsOptions;
 };
@@ -1532,6 +1579,10 @@ export declare const PredicateOutcome: Readonly<{
 }>;
 export type PressKeyInput = {
     key: string;
+    /**
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
+     */
     target?: ActionTarget;
     /**
      * Deprecated flat desktop target retained for wire compatibility.
@@ -1566,6 +1617,10 @@ export type ScrollInput = {
     x: number;
     y: number;
     direction: ScrollDirection;
+    /**
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
+     */
     target?: ActionTarget;
     /**
      * Deprecated flat desktop target retained for wire compatibility.
@@ -1625,7 +1680,13 @@ export declare const SessionStateOutput: Readonly<{
     defaults: () => Partial<SessionStateOutput>;
 }>;
 export type SetAgentCursorEnabledInput = {
+    /**
+     * Public label of the session that owns the cursor.
+     */
     session: string;
+    /**
+     * `true` shows the session's agent cursor overlay; `false` hides it.
+     */
     enabled: boolean;
 };
 /**
@@ -1649,15 +1710,53 @@ export declare const SetAgentCursorEnabledOutput: Readonly<{
     defaults: () => Partial<SetAgentCursorEnabledOutput>;
 }>;
 export type SetAgentCursorMotionInput = {
+    /**
+     * Public label of the session that owns the cursor. Omitted or null motion fields keep
+     * their current value.
+     */
     session: string;
+    /**
+     * Path control-point offset from the start, as a fraction of the distance. Clamped to
+     * 0..1 (default 0.3).
+     */
     startHandle?: number;
+    /**
+     * Path control-point offset from the end, as a fraction of the distance. Clamped to 0..1
+     * (default 0.3).
+     */
     endHandle?: number;
+    /**
+     * Sideways arc deflection as a fraction of the distance. Clamped to 0..1 (default 0.25).
+     */
     arcSize?: number;
+    /**
+     * Arc asymmetry: positive puts the apex near the destination, negative near the start.
+     * Clamped to -1..1 (default 0).
+     */
     arcFlow?: number;
+    /**
+     * Post-arrival spring damping: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1
+     * (default 0.72).
+     */
     spring?: number;
+    /**
+     * Fixed glide duration in milliseconds. 0 (the default) uses speed-based timing. Clamped
+     * to 0..5000.
+     */
     glideDurationMs?: number;
+    /**
+     * Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80).
+     */
     dwellAfterClickMs?: number;
+    /**
+     * Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to
+     * 0..60000 (default 15000).
+     */
     idleHideMs?: number;
+    /**
+     * Minimum turning radius of the glide path, in points; smaller turns tighter. Clamped to
+     * 1..1000 (default 80).
+     */
     turnRadius?: number;
 };
 /**
@@ -1681,8 +1780,18 @@ export declare const SetAgentCursorMotionOutput: Readonly<{
     defaults: () => Partial<SetAgentCursorMotionOutput>;
 }>;
 export type SetAgentCursorThemeInput = {
+    /**
+     * Public label of the session that owns the cursor.
+     */
     session: string;
+    /**
+     * Id of an installed cursor theme (see `cua-driver cursor-theme list`).
+     */
     themeId: string;
+    /**
+     * Theme animation policy: `on` uses the theme's reduced-motion frames, `off` always
+     * animates, `auto` (default) leaves the choice to the host.
+     */
     reducedMotion: CursorReducedMotion;
 };
 /**
@@ -1706,11 +1815,29 @@ export declare const SetAgentCursorThemeOutput: Readonly<{
     defaults: () => Partial<SetAgentCursorThemeOutput>;
 }>;
 export type SetWindowFrameInput = {
+    /**
+     * Process ID that owns the window.
+     */
     pid: number;
+    /**
+     * Window ID from list_windows.
+     */
     windowId: bigint;
+    /**
+     * New left edge in the desktop coordinate space reported by list_windows.
+     */
     x: number;
+    /**
+     * New top edge in the desktop coordinate space reported by list_windows.
+     */
     y: number;
+    /**
+     * New width, in the same units as list_windows bounds.
+     */
     width: number;
+    /**
+     * New height, in the same units as list_windows bounds.
+     */
     height: number;
     /**
      * For multi-call work, prefer a short public session label and repeat it on every call that
@@ -1806,6 +1933,10 @@ export declare const StatePredicate: Readonly<{
 }>;
 export type TypeTextInput = {
     text: string;
+    /**
+     * Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the
+     * primary desktop (`kind="desktop"`, `display_id="primary"`).
+     */
     target?: ActionTarget;
     /**
      * Deprecated flat desktop target retained for wire compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycua/cua-driver",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Rust-backed Cua Driver SDK and embedded Node host",
   "type": "module",
   "license": "MIT",
@@ -48,11 +48,11 @@
     "@ubjs/node": "0.31.0-3"
   },
   "optionalDependencies": {
-    "@trycua/cua-driver-darwin-arm64": "0.31.0",
-    "@trycua/cua-driver-darwin-x64": "0.31.0",
-    "@trycua/cua-driver-linux-arm64-gnu": "0.31.0",
-    "@trycua/cua-driver-linux-x64-gnu": "0.31.0",
-    "@trycua/cua-driver-win32-arm64-msvc": "0.31.0",
-    "@trycua/cua-driver-win32-x64-msvc": "0.31.0"
+    "@trycua/cua-driver-darwin-arm64": "0.32.0",
+    "@trycua/cua-driver-darwin-x64": "0.32.0",
+    "@trycua/cua-driver-linux-arm64-gnu": "0.32.0",
+    "@trycua/cua-driver-linux-x64-gnu": "0.32.0",
+    "@trycua/cua-driver-win32-arm64-msvc": "0.32.0",
+    "@trycua/cua-driver-win32-x64-msvc": "0.32.0"
   }
 }