@linxiraos/pi-natives 1.2.1 → 1.3.1

package/README.md

@@ -10,6 +10,7 @@ Native Rust functionality via N-API.
 - **Audio**: Cross-platform low-latency microphone capture and gapless speaker playback
 - **WebRTC**: Native Opus media, SDP offer/answer negotiation, and data-channel events for live sessions
 - **File locking**: Process-owned cross-process locks with in-memory kernel names on Linux/Windows and `flock(2)` sidecars on other Unix platforms
+- **Local IPC**: `IpcServer`/`IpcConnection` over Unix sockets and Windows named pipes — owner-only access, single-instance binding with stale-endpoint takeover, newline or raw framing; `ipcEndpoint(dir, name)` names endpoints per platform
 - **PDF**: In-memory PDF-to-Markdown extraction with OCR-page classification via `pdf-inspector`
 - **Binary patches**: `applyBinaryPatch(oldPath, patchPath, outPath)` applies an HDiffPatch single-stream patch (HDIFFSF20, zstd or uncompressed), streaming from files; callers verify digests
 
@@ -40,13 +41,22 @@ const files = await find({
 
 // SIXEL encode for a terminal cell box (px), off the JS thread
 // (`encodeSixel` is the synchronous form)
-const sequence = await encodeSixelAsync(pngBytes, widthPx, heightPx);
+const backgroundRgb = 0x202040; // Actual terminal background, packed 0xRRGGBB
+const sequence = await encodeSixelAsync(pngBytes, widthPx, heightPx, backgroundRgb);
 
 // Extract PDF text and identify pages that still need OCR
 const pdf = await pdfToMarkdown(pdfBytes);
 console.log(pdf.markdown, pdf.pagesNeedingOcr);
 ```
 
+Both SIXEL encoder forms require the terminal background as a fourth argument,
+packed as a 24-bit `0xRRGGBB` number. When resizing images with alpha, RGB is
+premultiplied before Lanczos filtering so transparent pixels cannot darken or
+discolor visible edges. After resizing, the terminal background is composited
+without applying alpha twice. Fully transparent pixels remain transparent;
+unscaled images retain their existing blending path. Re-encode when the terminal
+background RGB changes.
+
 ### Lazy Windows path helpers
 
 Import `expandWindowsLongPath` and `getWindowsShortPath` from

package/THIRD-PARTY-NOTICES.txt

@@ -8,8 +8,8 @@ no rights in third-party code, fonts, data, or marks identified below.
 PYTHON DEPENDENCY DISTRIBUTION ROLE
 ===================================
 
-omp-rpc has no third-party runtime dependencies. robomp declares FastAPI,
-Uvicorn, HTTPX, Pydantic, pydantic-settings, python-dotenv, Click, and omp-rpc
+zeta-rpc has no third-party runtime dependencies. robomp declares FastAPI,
+Uvicorn, HTTPX, Pydantic, pydantic-settings, python-dotenv, Click, and zeta-rpc
 as ordinary installer-resolved dependencies. The Python wheels do not vendor
 those projects; each dependency remains a separately installed distribution
 carrying its own license metadata and files. Container/system assemblers must
@@ -79,9 +79,9 @@ uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
 b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
-cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
-printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
-truncate, uname, uniq, wc, whoami, yes.
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nl, nproc,
+paste, printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee,
+touch, tr, truncate, uname, uniq, wc, whoami, yes.
 
   Copyright (c) uutils developers
 

package/native/desktop-adapter.js

@@ -4,6 +4,7 @@ const REQUIRED_METHODS = [
 	"captureRegion",
 	"cancel",
 	"retire",
+	"setRunDeadline",
 	"observe",
 	"listApplications",
 	"openApplication",
@@ -15,12 +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

@@ -43,10 +43,29 @@ export declare class DesktopSession {
    * behind the worker, so it answers at once even while a request is stuck.
    */
   get screenState(): DesktopScreenState
+  /**
+   * Keeps the display awake from the next activity request until
+   * `releaseDisplayAwake()`, however long the session sits idle in between,
+   * instead of for the grace period after the last request. An agent calls
+   * this when it acts inside a turn.
+   */
+  holdDisplayUntilReleased(): void
+  /**
+   * Lets the display sleep now if a turn holds it, without waiting behind
+   * queued requests, and returns later activity to the grace period. Activity
+   * 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.
@@ -55,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.
@@ -66,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>>
@@ -91,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.
@@ -235,6 +276,85 @@ export declare class HighlightStream {
   push(chunk: string): string
 }
 
+/** One accepted or dialed IPC connection. */
+export declare class IpcConnection {
+  /**
+   * Dial `endpoint`. Rejects with code ENOENT (no endpoint), ECONNREFUSED
+   * (stale socket / no listener), ETIMEDOUT, EACCES (peer owned by another
+   * user, or permission), or the OS errno name.
+   */
+  static connect(endpoint: string, options: IpcConnectOptions): Promise<IpcConnection>
+  /**
+   * Begin delivery on a `lines` connection (throws `TypeError` on a `raw`
+   * one). Call `start`/`startRaw` exactly once. Frames received before
+   * start are buffered, never dropped. `onLine` gets each non-empty line
+   * (one trailing CR stripped, invalid UTF-8 replaced lossily). `onClose`
+   * fires exactly once, after the last frame — including after local
+   * `end()`/`destroy()`: `null` for an orderly close, otherwise
+   * `"<CODE>: <message>"`.
+   */
+  start(onLine: (line: string) => void, onClose: (reason: string | null) => void): void
+  /**
+   * Same as `start()` for a `raw` connection (throws `TypeError` on a
+   * `lines` one): `onChunk` gets each received chunk.
+   */
+  startRaw(onChunk: (chunk: Uint8Array) => void, onClose: (reason: string | null) => void): void
+  /**
+   * Send one frame. lines: a string without LF (`TypeError` otherwise);
+   * LF is appended. raw: string (UTF-8) or `Uint8Array` written as-is.
+   * Frames sent during one JS task are written together when it ends (a
+   * microtask), in order; `end()` writes them first. Returns false once
+   * unwritten bytes exceed 1 MiB (await `drained()` before sending more).
+   * After close: returns false and drops the frame.
+   */
+  send(frame: string | Uint8Array): boolean
+  /** Resolves when the write queue is empty, or the connection closed. */
+  drained(): Promise<void>
+  /**
+   * Graceful: write everything queued, then shut the write half (Unix) /
+   * close the pipe (Windows); onClose follows when the read side ends.
+   */
+  end(): void
+  /**
+   * Immediate close; queued writes are dropped; onClose(null) follows.
+   * Idempotent.
+   */
+  destroy(): void
+  /** Keep the event loop alive while delivering (default). */
+  ref(): void
+  /** Let the event loop exit while this connection is open. */
+  unref(): void
+  /** Whether the connection is closed (or `destroy()` was called). */
+  get closed(): boolean
+}
+
+/** Listening IPC endpoint. */
+export declare class IpcServer {
+  /**
+   * Bind and listen.
+   *
+   * Unix: creates the parent dir (0700) if missing; under an exclusive flock
+   * on `<path>.bind.lock`, rejects EADDRINUSE when a live server answers,
+   * otherwise replaces the stale socket file; the socket is chmod 0600 before
+   * `listen()`. Windows: first pipe instance (exists → EADDRINUSE), remote
+   * clients rejected, DACL granting only the current user.
+   * `onConnection` receives each accepted, peer-verified connection (not yet
+   * started).
+   */
+  static listen(endpoint: string, options: IpcListenOptions, onConnection: (connection: IpcConnection) => void): Promise<IpcServer>
+  /** The endpoint this server listens on. */
+  get endpoint(): string
+  /**
+   * Stop accepting. Unix: unlink the socket file if it is still the inode
+   * this server bound. Accepted connections are untouched. Idempotent.
+   */
+  close(): Promise<void>
+  /** Keep the event loop alive while listening (default). */
+  ref(): void
+  /** Let the event loop exit while listening. */
+  unref(): void
+}
+
 /** WebRTC peer that accepts 16 kHz mono PCM and renders remote Opus audio. */
 export declare class LiveWebRtcPeer {
   /**
@@ -1092,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
@@ -1104,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
@@ -1161,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. */
@@ -1240,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
@@ -1314,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.
@@ -1346,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. */
@@ -1702,13 +1881,17 @@ export interface EnclosingBoundaryOptions {
  * the calling thread.
  *
  * The input image is decoded and resized to the requested pixel dimensions
- * before encoding. Prefer [`encode_sixel_async`] unless the caller cannot
- * wait: the decode, resize and dither block the JS thread.
+ * (not resampled when it already has them), then partial alpha is composited
+ * against `background_rgb` (packed `0xRRGGBB`). Fully transparent pixels
+ * remain transparent. Encoding uses whole 6-pixel bands: a partial last band
+ * is dropped, see [`band_rows`]. Prefer
+ * [`encode_sixel_async`] unless the caller cannot wait: the decode, resize
+ * and dither block the JS thread.
  *
  * # Errors
  * Returns an error if decoding, resizing, or SIXEL encoding fails.
  */
-export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): string
+export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number, backgroundRgb: number): string
 
 /**
  * Same result as [`encode_sixel`], but the decode, resize and dither run on
@@ -1717,7 +1900,7 @@ export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, ta
  * # Errors
  * Rejects if decoding, resizing, or SIXEL encoding fails.
  */
-export declare function encodeSixelAsync(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): Promise<string>
+export declare function encodeSixelAsync(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number, backgroundRgb: number): Promise<string>
 
 /** Tokenizer encoding to use. */
 export declare enum Encoding {
@@ -1806,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>
 
@@ -1979,7 +2165,10 @@ export interface GrepOptions {
   pattern: string
   /** Directory or file to search: a host path or an absolute `scheme://` URL. */
   path: string
-  /** Glob filter for filenames (e.g., "*.ts"). */
+  /**
+   * Glob filter for file paths (e.g., "*.ts"); a matched directory selects
+   * every file under it.
+   */
   glob?: string
   /**
    * Match simple glob patterns at any depth (default: true; `*.ts` ->
@@ -2157,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
 }
 
 /**
@@ -2193,6 +2392,44 @@ export interface InlineSloppyRegion {
  */
 export declare function invalidateFsScanCache(path?: string | undefined | null): void
 
+/** Options for `IpcConnection.connect`. */
+export interface IpcConnectOptions {
+  /**
+   * `lines`: UTF-8 text frames delimited by LF; `raw`: byte chunks as
+   * received.
+   */
+  framing: "lines" | "raw"
+  /** Connect deadline. Default 3000 ms. Expiry rejects with code ETIMEDOUT. */
+  timeoutMs?: number
+  /** Max bytes of one received line (lines framing). Default 64 MiB. */
+  maxFrameBytes?: number
+}
+
+/**
+ * Platform endpoint for `name` scoped to directory `dir`.
+ *
+ * Unix: `<dir>/<stem>.sock`; when that path does not fit `sun_path` (104 bytes
+ * on macOS/BSD, 108 on Linux, including NUL), `/tmp/omp-<euid>/<hash16>.sock`.
+ * Windows: `\\.\pipe\omp-<stem>-<hash16(lowercase(resolve(dir)))>`.
+ * `stem` is `name` with every char outside `[A-Za-z0-9._-]` replaced by "_".
+ * Pure and deterministic: every process computes the same endpoint.
+ */
+export declare function ipcEndpoint(dir: string, name: string): string
+
+/** Options for `IpcServer.listen`. */
+export interface IpcListenOptions {
+  /**
+   * `lines`: UTF-8 text frames delimited by LF; `raw`: byte chunks as
+   * received.
+   */
+  framing: "lines" | "raw"
+  /**
+   * Max bytes of one received line (lines framing). Default 64 MiB.
+   * Exceeding closes that connection with reason "EMSGSIZE: …".
+   */
+  maxFrameBytes?: number
+}
+
 /** Kind enum of the backend selected by default for this build target. */
 export declare function isoBackend(): IsoBackendKind
 
@@ -2342,6 +2579,13 @@ export interface ListWorkspaceOptions {
    * to find them. Default: false.
    */
   collectAgentsMd?: boolean
+  /**
+   * Report unreadable directories instead of silently skipping them: an
+   * unreadable root fails the scan, and unreadable subdirectories are
+   * returned in `unreadableDirectories` while the walk continues. Default:
+   * false (startup discovery stays best-effort).
+   */
+  reportDirectoryErrors?: boolean
   /** Timeout in milliseconds for the operation. */
   timeoutMs?: number
   /** Abort signal for cancelling the operation. */
@@ -2359,6 +2603,11 @@ export interface ListWorkspaceResult {
   agentsMdFiles: Array<string>
   /** True when any output cap was hit. */
   truncated: boolean
+  /**
+   * Subdirectories whose contents could not be listed. Always empty unless
+   * `reportDirectoryErrors` is set.
+   */
+  unreadableDirectories: Array<WorkspaceDirectoryError>
 }
 
 /**
@@ -2592,6 +2841,23 @@ export interface NodeSpan {
 /** Decode notebook JSON into the editable cell-marker text. */
 export declare function notebookToEditableText(json: string, displayPath: string): 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. */
@@ -2620,6 +2886,23 @@ export declare function parseKey(data: string, kittyProtocolActive: boolean): st
  */
 export declare function parseKittySequence(data: string): ParsedKittyResult | null
 
+export interface ParseStatus {
+  /** Canonical language name only when parsing succeeded. */
+  language?: string
+  /** True when non-empty source parses without syntax errors. */
+  parsed: boolean
+}
+
+/** Options for checking source syntax without generating a summary. */
+export interface ParseStatusOptions {
+  /** Source code to parse; empty input is not parsed. */
+  code: string
+  /** Language alias; a non-blank value overrides path-based detection. */
+  lang?: string
+  /** File path used to infer language when `lang` is omitted or blank. */
+  path?: string
+}
+
 /** One hunk of a unified diff, matching jsdiff `structuredPatch` hunks. */
 export interface PatchHunk {
   /** 1-based first line of the hunk in the old text. */
@@ -2674,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
 }
 
 /**
@@ -3733,8 +4036,8 @@ export declare function visibleWidth(text: string, tabWidth: number): number
  * [`enclosing_block_boundaries`], [`block_range_at`] and [`node_chain_at`]
  * are synchronous and parse on the JS thread when their source is not
  * cached; awaiting this first makes that parse a cache hit. Resolves without
- * parsing when the language is unrecognized or the source is too large for
- * the cache to keep.
+ * parsing when the language is unrecognized or the source is over 2 MiB,
+ * where a typical tree would not fit the cache's memory budget.
  */
 export declare function warmBlockParse(options: BlockParseOptions): Promise<undefined>
 
@@ -3791,6 +4094,14 @@ export interface WorkProfile {
   sampleCount: number
 }
 
+/** A subdirectory the scan could not list. */
+export interface WorkspaceDirectoryError {
+  /** Forward-slash path relative to the scan root. */
+  path: string
+  /** Platform error, e.g. `Permission denied (os error 13)`. */
+  message: string
+}
+
 /**
  * Wrap text to a visible width, preserving ANSI escape codes across line
  * breaks.

package/native/index.js

@@ -31,6 +31,8 @@ export const EditSession = nativeBindings.EditSession;
 export const EditStore = nativeBindings.EditStore;
 export const FileLock = nativeBindings.FileLock;
 export const HighlightStream = nativeBindings.HighlightStream;
+export const IpcConnection = nativeBindings.IpcConnection;
+export const IpcServer = nativeBindings.IpcServer;
 export const LiveWebRtcPeer = nativeBindings.LiveWebRtcPeer;
 export const MacAppearanceObserver = nativeBindings.MacAppearanceObserver;
 export const NativeOAuthCallback = nativeBindings.NativeOAuthCallback;
@@ -56,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");
@@ -79,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");
@@ -95,6 +100,7 @@ export const hasMatch = nativeBindings.hasMatch ?? missingNativeExport("hasMatch
 export const highlightCode = nativeBindings.highlightCode ?? missingNativeExport("highlightCode");
 export const htmlToMarkdown = nativeBindings.htmlToMarkdown ?? missingNativeExport("htmlToMarkdown");
 export const invalidateFsScanCache = nativeBindings.invalidateFsScanCache ?? missingNativeExport("invalidateFsScanCache");
+export const ipcEndpoint = nativeBindings.ipcEndpoint ?? missingNativeExport("ipcEndpoint");
 export const isoBackend = nativeBindings.isoBackend ?? missingNativeExport("isoBackend");
 export const isoDiff = nativeBindings.isoDiff ?? missingNativeExport("isoDiff");
 export const isoIsUnavailableError = nativeBindings.isoIsUnavailableError ?? missingNativeExport("isoIsUnavailableError");
@@ -113,6 +119,7 @@ export const matchesLegacySequence = nativeBindings.matchesLegacySequence ?? mis
 export const mmrRerankIndices = nativeBindings.mmrRerankIndices ?? missingNativeExport("mmrRerankIndices");
 export const nodeChainAt = nativeBindings.nodeChainAt ?? missingNativeExport("nodeChainAt");
 export const notebookToEditableText = nativeBindings.notebookToEditableText ?? missingNativeExport("notebookToEditableText");
+export const parseCodeStatus = nativeBindings.parseCodeStatus ?? missingNativeExport("parseCodeStatus");
 export const parseKey = nativeBindings.parseKey ?? missingNativeExport("parseKey");
 export const parseKittySequence = nativeBindings.parseKittySequence ?? missingNativeExport("parseKittySequence");
 export const pdfToMarkdown = nativeBindings.pdfToMarkdown ?? missingNativeExport("pdfToMarkdown");

package/native/loader-state.js

@@ -65,8 +65,8 @@ function getNativesDir() {
 		if (path.isAbsolute(dir)) return path.normalize(dir);
 	}
 	const xdgDataHome = process.env.XDG_DATA_HOME;
-	if (xdgDataHome && fs.existsSync(path.join(xdgDataHome, "omp"))) {
-		return path.join(xdgDataHome, "omp", "natives");
+	if (xdgDataHome && fs.existsSync(path.join(xdgDataHome, "zeta"))) {
+		return path.join(xdgDataHome, "zeta", "natives");
 	}
 	return path.join(os.homedir(), ".zeta", "natives");
 }
@@ -499,13 +499,11 @@ export function extractEmbeddedAddons({ files, targetDir }) {
 	return writtenPaths;
 }
 
-function maybeExtractEmbeddedAddon(ctx, errors) {
+function maybeExtractEmbeddedAddon(ctx, errors, file = selectEmbeddedAddonFile(ctx.selectedVariant)) {
 	if (!ctx.isCompiledBinary || !embeddedAddon) return null;
 	if (embeddedAddon.platformTag !== ctx.platformTag || embeddedAddon.version !== ctx.packageVersion) return null;
-
-	const selectedEmbeddedFile = selectEmbeddedAddonFile(ctx.selectedVariant);
-	if (!selectedEmbeddedFile) return null;
-	const targetPath = path.join(ctx.versionedDir, selectedEmbeddedFile.filename);
+	if (!file) return null;
+	const targetPath = path.join(ctx.versionedDir, file.filename);
 
 	startupMarker("native:extractEmbeddedAddon:start");
 	try {
@@ -517,11 +515,11 @@ function maybeExtractEmbeddedAddon(ctx, errors) {
 	}
 
 	try {
-		extractEmbeddedAddons({ files: embeddedAddon.files, targetDir: ctx.versionedDir });
+		extractEmbeddedAddons({ files: [file], targetDir: ctx.versionedDir });
 		return targetPath;
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
-		errors.push(`embedded addon extraction (${selectedEmbeddedFile.filename}): ${message}`);
+		errors.push(`embedded addon extraction (${file.filename}): ${message}`);
 		return null;
 	}
 }
@@ -866,8 +864,16 @@ export function loadNative() {
 	const stagedCandidate = embeddedCandidate ? null : maybeStageNodeModulesAddon(ctx, errors);
 	const prepended = [embeddedCandidate, stagedCandidate].filter(c => typeof c === "string");
 	const runtimeCandidates = prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
+	const fallbackEmbeddedFile =
+		ctx.selectedVariant === "modern" && embeddedAddon
+			? embeddedAddon.files.find(file => file.variant === "baseline")
+			: null;
+	const fallbackEmbeddedPath = fallbackEmbeddedFile && path.join(ctx.versionedDir, fallbackEmbeddedFile.filename);
 
 	for (const candidate of runtimeCandidates) {
+		if (fallbackEmbeddedFile && candidate === fallbackEmbeddedPath) {
+			maybeExtractEmbeddedAddon(ctx, errors, fallbackEmbeddedFile);
+		}
 		try {
 			startupMarker(`native:require:${path.basename(candidate)}`);
 			const bindings = require_(candidate);

package/native/vcs.d.ts

@@ -81,6 +81,9 @@ export declare function detachGitDir(
 	signal?: AbortSignal,
 ): Promise<"no-git" | "independent" | "detached">;
 
+/** Preserve isolation-local Git objects in the source without changing its refs or index. */
+export declare function copyGitObjects(isolationRoot: string, sourceRoot: string): Promise<void>;
+
 /** Run Git's checkout hook in a new linked worktree and return its output and exit status. */
 export declare function runPostCheckoutHook(
 	worktreeRoot: string,

package/native/vcs.js

@@ -1,5 +1,6 @@
 import { $ } from "bun";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { loadNative } from "./loader-state.js";
 
 let native;
@@ -96,6 +97,58 @@ export function detachGitDir(worktreeRoot, sourceCommonDir, signal) {
 	return api().vcsDetachGitDir(worktreeRoot, sourceCommonDir, signal);
 }
 
+/**
+ * Publish `from` at `to` only once fully written: copy to a sibling temp name,
+ * then hard-link it into place (Git's own `finalize_object_file` strategy) so
+ * readers never see a partial file and an interrupted copy leaves only a
+ * `tmp_` file that `git gc` prunes. An existing `to` was itself published
+ * whole and holds the same content-addressed bytes, so it is kept.
+ */
+async function publishGitObjectFile(from, to) {
+	const tmp = path.join(path.dirname(to), `tmp_obj_omp_${crypto.randomUUID()}`);
+	try {
+		await fs.promises.copyFile(from, tmp, fs.constants.COPYFILE_EXCL);
+		try {
+			await fs.promises.link(tmp, to);
+		} catch (error) {
+			if (error?.code === "EEXIST") return;
+			// Filesystems without hard links: rename is still atomic, and any
+			// file it replaces holds identical content-addressed bytes.
+			if (error?.code !== "EPERM" && error?.code !== "ENOTSUP" && error?.code !== "EXDEV") throw error;
+			await fs.promises.rename(tmp, to);
+		}
+	} finally {
+		await fs.promises.rm(tmp, { force: true });
+	}
+}
+
+/**
+ * Keep objects created in an isolated Git repository reachable after its
+ * worktree is removed, without changing the destination's refs or index.
+ * Every file is published atomically; a pack is published before its index.
+ */
+export async function copyGitObjects(isolationRoot, sourceRoot) {
+	const from = path.join(requireGit(isolationRoot).info().commonDir, "objects");
+	const to = path.join(requireGit(sourceRoot).info().commonDir, "objects");
+	for (const entry of await fs.promises.readdir(from, { withFileTypes: true })) {
+		if (!entry.isDirectory() || !/^[0-9a-f]{2}$/.test(entry.name)) continue;
+		await fs.promises.mkdir(path.join(to, entry.name), { recursive: true });
+		for (const name of await fs.promises.readdir(path.join(from, entry.name))) {
+			if (!/^[0-9a-f]{38,62}$/.test(name)) continue;
+			await publishGitObjectFile(path.join(from, entry.name, name), path.join(to, entry.name, name));
+		}
+	}
+	const packs = (await fs.promises.readdir(path.join(from, "pack"))).filter(name => name.startsWith("pack-"));
+	await fs.promises.mkdir(path.join(to, "pack"), { recursive: true });
+	// The index must only become visible after the pack it describes.
+	for (const name of packs.filter(name => name.endsWith(".pack"))) {
+		await publishGitObjectFile(path.join(from, "pack", name), path.join(to, "pack", name));
+	}
+	for (const name of packs.filter(name => /\.(?:idx|rev|keep|promisor|mtimes)$/.test(name))) {
+		await publishGitObjectFile(path.join(from, "pack", name), path.join(to, "pack", name));
+	}
+}
+
 /**
  * Run Git's checkout hook in a newly created linked worktree, using the same
  * null old HEAD and branch-switch flag as `git worktree add`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-natives",
-	"version": "1.2.1",
+	"version": "1.3.1",
 	"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/",
@@ -32,14 +32,15 @@
 		"build": "bun ../../scripts/bazel-natives.ts host --dest native",
 		"build:bindings": "bun scripts/build-bindings.ts",
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'",
 		"gen:npm": "bun scripts/gen-npm-packages.ts",
 		"bench": "bun bench/grep.ts",
-		"bench:text": "bun bench/text.ts"
+		"bench:text": "bun bench/text.ts",
+		"bench:ipc": "bun bench/ipc.ts"
 	},
 	"devDependencies": {
 		"@napi-rs/cli": "3.7.2",
@@ -109,11 +110,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@linxiraos/pi-natives-linux-x64": "1.2.1",
-		"@linxiraos/pi-natives-linux-arm64": "1.2.1",
-		"@linxiraos/pi-natives-darwin-x64": "1.2.1",
-		"@linxiraos/pi-natives-darwin-arm64": "1.2.1",
-		"@linxiraos/pi-natives-win32-x64": "1.2.1",
-		"@linxiraos/pi-natives-win32-arm64": "1.2.1"
+		"@linxiraos/pi-natives-linux-x64": "1.3.1",
+		"@linxiraos/pi-natives-linux-arm64": "1.3.1",
+		"@linxiraos/pi-natives-darwin-x64": "1.3.1",
+		"@linxiraos/pi-natives-darwin-arm64": "1.3.1",
+		"@linxiraos/pi-natives-win32-x64": "1.3.1",
+		"@linxiraos/pi-natives-win32-arm64": "1.3.1"
 	}
 }