@linxiraos/pi-natives 1.3.0 → 1.3.2

package/native/desktop-adapter.js

@@ -4,6 +4,7 @@ const REQUIRED_METHODS = [
 	"captureRegion",
 	"cancel",
 	"retire",
+	"setRunDeadline",
 	"observe",
 	"listApplications",
 	"openApplication",
@@ -15,14 +16,21 @@ const REQUIRED_METHODS = [
 	"releaseControl",
 	"controlState",
 	"bringToCurrentSpace",
+	"axSelectText",
 	"holdDisplayUntilReleased",
 	"releaseDisplayAwake",
 ];
 
+/** Getters the computer worker reads; without `escapeStops` it would read every run as stopped by the user's Escape. */
+const REQUIRED_GETTERS = ["escapeStops"];
+
 /** Require the current desktop ABI; partial legacy emulation cannot preserve input ownership. */
 export function adaptDesktopSession(NativeDesktopSession) {
 	const prototype = NativeDesktopSession?.prototype;
-	const missing = REQUIRED_METHODS.filter(method => typeof prototype?.[method] !== "function");
+	const missing = [
+		...REQUIRED_METHODS.filter(method => typeof prototype?.[method] !== "function"),
+		...REQUIRED_GETTERS.filter(getter => !prototype || !(getter in prototype)),
+	];
 	if (missing.length === 0) {
 		return NativeDesktopSession;
 	}

package/native/desktop.d.ts

@@ -2,3 +2,12 @@ import type { DesktopSession, DesktopSessionOptions } from "./index.js";
 
 /** Construct a desktop session, loading the native addon on first use. */
 export declare function createDesktopSession(options: DesktopSessionOptions): DesktopSession;
+
+/** Physical-Escape stops counted under `key`, loading the native addon on first use. */
+export declare function desktopEscapeStops(key: string): number;
+
+/** Drop the stop count kept under `key`. */
+export declare function forgetDesktopEscapeStops(key: string): void;
+
+/** Invalidate this process's event taps before it exits (see the native doc). */
+export declare function closeDesktopEventTaps(): void;

package/native/desktop.js

@@ -1,5 +1,5 @@
 import { adaptDesktopSession } from "./desktop-adapter.js";
-import { loadNative } from "./loader-state.js";
+import { loadNative, missingNativeExport } from "./loader-state.js";
 
 let DesktopSession;
 
@@ -11,3 +11,22 @@ export function createDesktopSession(options) {
 	DesktopSession ??= adaptDesktopSession(loadNative().DesktopSession);
 	return new DesktopSession(options);
 }
+
+// A stale workspace addon lacks the Escape exports; fall back to the stub
+// `native/index.js` exports in their place, which names the rebuild.
+
+/** Physical-Escape stops counted under `key`, loading the native addon on first use. */
+export function desktopEscapeStops(key) {
+	return (loadNative().desktopEscapeStops ?? missingNativeExport("desktopEscapeStops"))(key);
+}
+
+/** Drop the stop count kept under `key`. */
+export function forgetDesktopEscapeStops(key) {
+	(loadNative().forgetDesktopEscapeStops ?? missingNativeExport("forgetDesktopEscapeStops"))(key);
+}
+
+/** Invalidate this process's event taps before it exits (see the native doc). A stale
+ * workspace addon without the export holds no such taps. */
+export function closeDesktopEventTaps() {
+	loadNative().closeDesktopEventTaps?.();
+}

package/native/index.d.ts

@@ -56,10 +56,16 @@ export declare class DesktopSession {
    * outside a turn keeps its grace. An agent calls this when its turn ends.
    */
   releaseDisplayAwake(): void
+  /**
+   * How many times the user's physical Escape has stopped takeover input in
+   * this session, or under its `escapeStopKey`. Host cancels, retirement and
+   * release never count, so a rise tells the host the user stopped the work.
+   */
+  get escapeStops(): number
   listDisplays(): Promise<Array<DesktopDisplay>>
   listWindows(): Promise<Array<DesktopWindow>>
   listApplications(options?: ApplicationQuery | undefined | null): Promise<Array<Application>>
-  openApplication(id: string, options?: ApplicationOpenOptions | undefined | null): Promise<Application>
+  openApplication(id: string, options?: ApplicationOpenOptions | undefined | null): Promise<OpenedApplication>
   /**
    * Capture and accessibility share one serialized request. Neither a failed
    * snapshot nor an abandoned reply replaces the last delivered input frame.
@@ -68,8 +74,8 @@ export declare class DesktopSession {
   menuItems(target: string, path?: Array<string> | undefined | null): Promise<Array<DesktopMenuItem>>
   menuSelect(target: string, path: Array<string>): Promise<undefined>
   bringToCurrentSpace(windowId: string): Promise<undefined>
-  holdKeys(target: string, keys: Array<string>, options: HoldOptions): Promise<undefined>
-  holdMouse(target: string, x: number, y: number, options: HoldOptions): Promise<undefined>
+  holdKeys(target: string, keys: Array<string>, options: HoldOptions): Promise<DesktopFocusReturn | undefined | null>
+  holdMouse(target: string, x: number, y: number, options: HoldOptions): Promise<DesktopFocusReturn | undefined | null>
   /**
    * Native ownership only. Human approval is required by the host before
    * calling this method.
@@ -79,18 +85,24 @@ export declare class DesktopSession {
   controlState(): DesktopControlState
   /** Retire queued work from a completed helper without revoking task control. */
   retire(): void
+  /**
+   * Sets when the current run ends, `remaining_ms` from now; each run sets
+   * it before its first call. On macOS, input waiting for the user to pause
+   * in its app gives up shortly before it.
+   */
+  setRunDeadline(remainingMs: number): void
   capture(target: string, caps?: CaptureCaps | undefined | null): Promise<DesktopCapture>
   /**
    * Capture a fresh native-detail region without replacing the full input
    * coordinate frame.
    */
   captureRegion(target: string, region: CaptureRegion, caps?: CaptureCaps | undefined | null): Promise<DesktopCapture>
-  click(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<undefined>
-  moveMouse(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<undefined>
-  drag(target: string, path: Array<DesktopPoint>, opts?: PointerOptions | undefined | null): Promise<undefined>
-  scroll(target: string, x: number, y: number, dx: number, dy: number, opts?: PointerOptions | undefined | null): Promise<undefined>
-  typeText(target: string, text: string, opts?: PointerOptions | undefined | null): Promise<undefined>
-  keyChord(target: string, keys: Array<string>, opts?: PointerOptions | undefined | null): Promise<undefined>
+  click(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  moveMouse(target: string, x: number, y: number, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  drag(target: string, path: Array<DesktopPoint>, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  scroll(target: string, x: number, y: number, dx: number, dy: number, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  typeText(target: string, text: string, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  keyChord(target: string, keys: Array<string>, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
   raiseWindow(windowId: string): Promise<undefined>
   axSnapshot(target: string, opts?: AxSnapshotOptions | undefined | null): Promise<AxSnapshot>
   axQuery(target: string, query: AxQuery): Promise<Array<AxNode>>
@@ -104,10 +116,26 @@ export declare class DesktopSession {
   axAttributes(reference: string): Promise<Array<[string, string]>>
   axChildren(reference: string): Promise<Array<AxNode>>
   axParent(reference: string): Promise<AxNode | undefined | null>
-  axPerform(reference: string, action: string): Promise<undefined>
+  /**
+   * Performs `action` on the element; with `menu`, chooses that item path
+   * in the menu the action opens, which closes it.
+   */
+  axPerform(reference: string, action: string, menu?: Array<string> | undefined | null): Promise<undefined>
   axSetValue(reference: string, value: string): Promise<undefined>
+  /**
+   * Selects `text` in the element's value by accessibility, or places a
+   * caret at its start or end, without focus change or keystrokes.
+   */
+  axSelectText(reference: string, text: string, opts?: AxSelectTextOptions | undefined | null): Promise<AxTextSelection>
   axFocus(reference: string): Promise<undefined>
-  axClick(reference: string, opts?: PointerOptions | undefined | null): Promise<undefined>
+  axClick(reference: string, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  /**
+   * Types `text` into the element: native text fields take it by AX
+   * insertion, other elements as keystrokes once they hold keyboard focus.
+   */
+  axType(reference: string, text: string, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
+  /** Presses a key chord in the element once it holds keyboard focus. */
+  axKeyChord(reference: string, keys: Array<string>, opts?: PointerOptions | undefined | null): Promise<DesktopFocusReturn | undefined | null>
   /**
    * Immediately cancel operations submitted before this call. Later
    * operations may proceed.
@@ -1184,6 +1212,16 @@ export interface AxQuery {
   limit?: number
 }
 
+/** Where `axSelectText` looks for its text and what it selects there. */
+export interface AxSelectTextOptions {
+  /** Text that must directly precede the match. */
+  prefix?: string
+  /** Text that must directly follow the match. */
+  suffix?: string
+  /** `text` (default) selects the match; `start` and `end` place a caret. */
+  select?: string
+}
+
 export interface AxSnapshot {
   text: string
   nodeCount: number
@@ -1196,6 +1234,19 @@ export interface AxSnapshotOptions {
   all?: boolean
 }
 
+/** The selection read back after `axSelectText`, in UTF-16 code units. */
+export interface AxTextSelection {
+  start: number
+  length: number
+  /** The selected text, empty for a caret. */
+  text: string
+  /**
+   * Whether the element is focused in its app: typing and AX insertion
+   * act on the focused element.
+   */
+  focused: boolean
+}
+
 export interface BlockParseOptions {
   /** Source code to parse. */
   code: string
@@ -1253,6 +1304,15 @@ export interface ClipboardImage {
   mimeType: string
 }
 
+/**
+ * Invalidates this process's event taps; for a host about to
+ * exit, after which no desktop session here sees the user's input again. A
+ * macOS tap that dies with its process while the user types makes
+ * `WindowServer` deliver their key again; Bun's `process.exit` runs no native
+ * exit hook, so the host calls this from its exit handler.
+ */
+export declare function closeDesktopEventTaps(): void
+
 /** A context line (before or after a match). */
 export interface ContextLine {
   /** 1-indexed line number in the source file. */
@@ -1332,8 +1392,10 @@ export interface DesktopCapabilities {
   heldInput: boolean
   spaces: boolean
   /**
-   * Native global Escape cancellation while input/control ownership is held.
-   * Wayland requires the host interrupt action instead.
+   * Native global Escape cancellation of takeover input (`takeover: true`,
+   * held control, desktop/display-level input, raises, activating launches).
+   * Without held control, background window input never watches the user's
+   * keys; it and Wayland stop only through the host interrupt.
    */
   globalEscape: boolean
   capturePermission: string
@@ -1406,6 +1468,20 @@ export interface DesktopDisplay {
   isPrimary: boolean
 }
 
+/**
+ * Where focus ended after a takeover input call, as `WindowServer` reports
+ * it. Input calls resolve to it on macOS when they took over; other
+ * backends and background delivery resolve to `null`.
+ */
+export interface DesktopFocusReturn {
+  /** Whether the takeover handed focus back to the app front before it. */
+  handedBack: boolean
+  /** The process front before the takeover. */
+  previousPid?: number
+  /** The process front once the takeover ended; absent when unreadable. */
+  frontPid?: number
+}
+
 /**
  * One immediate child of a native application menu. Paths contain the actual
  * native labels, including ellipses; selection accepts normalized labels.
@@ -1438,8 +1514,19 @@ export interface DesktopScreenState {
   displayAsleep: boolean
 }
 
+/**
+ * Physical-Escape stops counted under `key` by every desktop session created
+ * with it, including closed ones, until the key is forgotten.
+ */
+export declare function desktopEscapeStops(key: string): number
+
 export interface DesktopSessionOptions {
   display?: string
+  /**
+   * Sessions created with the same key share one physical-Escape stop
+   * count, which `desktopEscapeStops` reads after they close.
+   */
+  escapeStopKey?: string
 }
 
 /** One capturable top-level window in global logical desktop coordinates. */
@@ -1902,6 +1989,9 @@ export declare enum FileType {
   Symlink = 3
 }
 
+/** Drops the stop count kept under `key` once no session will use it again. */
+export declare function forgetDesktopEscapeStops(key: string): void
+
 /** Fuzzy file path search for autocomplete. */
 export declare function fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult>
 
@@ -2256,6 +2346,16 @@ export interface HoldOptions {
   button?: string
   keys?: Array<string>
   takeover?: boolean
+  /**
+   * With `takeover`, hand focus back to the user's app even after their
+   * input during the hold; see `PointerOptions.returnFocus`.
+   */
+  returnFocus?: boolean
+  /**
+   * Refuse a background left hold that starts on a control that opens a
+   * menu; see `PointerOptions.refuseMenu`.
+   */
+  refuseMenu?: boolean
 }
 
 /**
@@ -2744,6 +2844,20 @@ export declare function notebookToEditableText(json: string, displayPath: string
 /** Check syntax through the shared parse cache without constructing a summary. */
 export declare function parseCodeStatus(options: ParseStatusOptions): ParseStatus
 
+/**
+ * An opened application: its [`Application`] fields and the window it
+ * shows. On macOS `window` is its frontmost window once one is on screen;
+ * other platforms report none.
+ */
+export interface OpenedApplication {
+  id: string
+  name: string
+  path: string
+  running: boolean
+  pid?: number
+  window?: DesktopWindow
+}
+
 /** Parsed Kitty keyboard protocol sequence result for a Kitty input sequence. */
 export interface ParsedKittyResult {
   /** Primary codepoint associated with the key. */
@@ -2843,6 +2957,26 @@ export interface PointerOptions {
    * default background delivery.
    */
   takeover?: boolean
+  /**
+   * With `takeover`, hand focus back to the user's app even if they typed
+   * or clicked during the action; only a third app they switched to keeps
+   * it. The host sets this when it reruns a refused background action.
+   */
+  returnFocus?: boolean
+  /**
+   * Item path to choose in the menu a click opens, matched like a menu-bar
+   * path, e.g. a context menu's `["Add to", "Fonts"]`; the call opens the
+   * menu, presses the item and returns with the menu closed.
+   */
+  menu?: Array<string>
+  /**
+   * Refuse a background left click that lands on a control that opens a
+   * menu (on macOS a menu button or popup button), or a drag that starts on
+   * one, with `BackgroundUnavailable` before anything is sent. The host sets
+   * this when the user refuses foreground takeover: an open menu takes their
+   * keyboard.
+   */
+  refuseMenu?: boolean
 }
 
 /**

package/native/index.js

@@ -58,11 +58,13 @@ export const astEdit = nativeBindings.astEdit ?? missingNativeExport("astEdit");
 export const astGrep = nativeBindings.astGrep ?? missingNativeExport("astGrep");
 export const astMatch = nativeBindings.astMatch ?? missingNativeExport("astMatch");
 export const blockRangeAt = nativeBindings.blockRangeAt ?? missingNativeExport("blockRangeAt");
+export const closeDesktopEventTaps = nativeBindings.closeDesktopEventTaps ?? missingNativeExport("closeDesktopEventTaps");
 export const copyToClipboard = nativeBindings.copyToClipboard ?? missingNativeExport("copyToClipboard");
 export const cosineSimilarityPairs = nativeBindings.cosineSimilarityPairs ?? missingNativeExport("cosineSimilarityPairs");
 export const countTokens = nativeBindings.countTokens ?? missingNativeExport("countTokens");
 export const decodeSixelToPng = nativeBindings.decodeSixelToPng ?? missingNativeExport("decodeSixelToPng");
 export const decodeSixelToPngAsync = nativeBindings.decodeSixelToPngAsync ?? missingNativeExport("decodeSixelToPngAsync");
+export const desktopEscapeStops = nativeBindings.desktopEscapeStops ?? missingNativeExport("desktopEscapeStops");
 export const detectMacOSAppearance = nativeBindings.detectMacOSAppearance ?? missingNativeExport("detectMacOSAppearance");
 export const deviceCheckGenerateToken = nativeBindings.deviceCheckGenerateToken ?? missingNativeExport("deviceCheckGenerateToken");
 export const diffLineRuns = nativeBindings.diffLineRuns ?? missingNativeExport("diffLineRuns");
@@ -81,6 +83,7 @@ export const executeShell = nativeBindings.executeShell ?? missingNativeExport("
 export const expandWindowsLongPath = nativeBindings.expandWindowsLongPath ?? missingNativeExport("expandWindowsLongPath");
 export const extractInlineSloppyRegions = nativeBindings.extractInlineSloppyRegions ?? missingNativeExport("extractInlineSloppyRegions");
 export const extractSegments = nativeBindings.extractSegments ?? missingNativeExport("extractSegments");
+export const forgetDesktopEscapeStops = nativeBindings.forgetDesktopEscapeStops ?? missingNativeExport("forgetDesktopEscapeStops");
 export const fuzzyFind = nativeBindings.fuzzyFind ?? missingNativeExport("fuzzyFind");
 export const getSupportedLanguages = nativeBindings.getSupportedLanguages ?? missingNativeExport("getSupportedLanguages");
 export const getWindowsShortPath = nativeBindings.getWindowsShortPath ?? missingNativeExport("getWindowsShortPath");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-natives",
-	"version": "1.3.0",
+	"version": "1.3.2",
 	"description": "Native Rust bindings for PDF conversion, audio, WebRTC, grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://linxira-os.github.io/zeta/",
@@ -110,11 +110,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@linxiraos/pi-natives-linux-x64": "1.3.0",
-		"@linxiraos/pi-natives-linux-arm64": "1.3.0",
-		"@linxiraos/pi-natives-darwin-x64": "1.3.0",
-		"@linxiraos/pi-natives-darwin-arm64": "1.3.0",
-		"@linxiraos/pi-natives-win32-x64": "1.3.0",
-		"@linxiraos/pi-natives-win32-arm64": "1.3.0"
+		"@linxiraos/pi-natives-linux-x64": "1.3.2",
+		"@linxiraos/pi-natives-linux-arm64": "1.3.2",
+		"@linxiraos/pi-natives-darwin-x64": "1.3.2",
+		"@linxiraos/pi-natives-darwin-arm64": "1.3.2",
+		"@linxiraos/pi-natives-win32-x64": "1.3.2",
+		"@linxiraos/pi-natives-win32-arm64": "1.3.2"
 	}
 }