@linxiraos/pi-natives 1.1.26 → 1.1.27

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
+- **PDF**: In-memory PDF-to-Markdown extraction with OCR-page classification via `pdf-inspector`
 
 General-purpose image processing (decode/resize/encode for files and buffers)
 lives in [`Bun.Image`](https://bun.com/docs/runtime/image) on the JS side; this
@@ -19,7 +20,7 @@ that terminal protocol.
 ## Usage
 
 ```typescript
-import { grep, find, encodeSixel } from "@linxiraos/pi-natives";
+import { encodeSixelAsync, grep, pdfToMarkdown } from "@linxiraos/pi-natives";
 
 // Grep for a pattern
 const results = await grep({
@@ -36,8 +37,13 @@ const files = await find({
 	fileType: "file",
 });
 
-// SIXEL encode for a terminal cell box (px)
-const sequence = encodeSixel(pngBytes, widthPx, heightPx);
+// SIXEL encode for a terminal cell box (px), off the JS thread
+// (`encodeSixel` is the synchronous form)
+const sequence = await encodeSixelAsync(pngBytes, widthPx, heightPx);
+
+// Extract PDF text and identify pages that still need OCR
+const pdf = await pdfToMarkdown(pdfBytes);
+console.log(pdf.markdown, pdf.pagesNeedingOcr);
 ```
 
 ### Lazy Windows path helpers

package/native/desktop-adapter.d.ts

@@ -1,28 +1,4 @@
-interface AdaptedDesktopCapabilities {
-	readonly [key: string]: unknown;
-	readonly ax: boolean;
-	readonly backgroundWindowInput: boolean;
-	readonly takeover: boolean;
-	readonly axPermission: string;
-}
+import type { DesktopSession } from "./index.js";
 
-interface AdaptedDesktopSession {
-	readonly capabilities: AdaptedDesktopCapabilities;
-	listWindows(): Promise<Array<Record<string, unknown>>>;
-	capture(target: string, caps?: unknown): Promise<Record<string, unknown>>;
-	click(
-		target: string,
-		x: number,
-		y: number,
-		options?: { button?: string; count?: number; modifiers?: string[]; takeover?: boolean },
-	): Promise<void>;
-	typeText(target: string, text: string, options?: { takeover?: boolean }): Promise<void>;
-	keyChord(target: string, keys: string[], options?: { takeover?: boolean }): Promise<void>;
-	close(): Promise<void>;
-}
-
-interface AdaptedDesktopSessionConstructor {
-	new (options: Record<string, unknown>): AdaptedDesktopSession;
-}
-
-export function adaptDesktopSession(NativeDesktopSession: unknown): AdaptedDesktopSessionConstructor;
+/** Return the current native ABI, or a constructor that rejects an outdated addon on first desktop use. */
+export function adaptDesktopSession(NativeDesktopSession: unknown): typeof DesktopSession;

package/native/desktop-adapter.js

@@ -1,404 +1,36 @@
-const LEGACY_ERROR_CODES = {
-	DESKTOP_INVALID_OPTIONS: "InvalidTarget",
-	DESKTOP_INVALID_ACTION: "InvalidTarget",
-	DESKTOP_BACKEND_UNAVAILABLE: null,
-	DESKTOP_PERMISSION_DENIED: "PermissionDenied",
-	DESKTOP_CAPTURE_FAILED: "CaptureFailed",
-	DESKTOP_INPUT_FAILED: "InputFailed",
-	DESKTOP_DEADLINE_EXCEEDED: "Timeout",
-	DESKTOP_LAYOUT_CHANGED: "InvalidCoordinateFrame",
-	DESKTOP_COORDINATE_OUT_OF_BOUNDS: "InvalidCoordinateFrame",
-	DESKTOP_SESSION_CLOSED: "Closed",
-	DESKTOP_WORKER_FAILED: "Internal",
-};
-
-const ADAPTED_SESSION_CLASSES = new WeakMap();
-
-function desktopError(code, message) {
-	return new Error(`${code}: ${message}`);
-}
-
-function normalizeError(error, fallbackCode) {
-	if (!(error instanceof Error)) return desktopError(fallbackCode, String(error));
-	if (/^[A-Z][A-Za-z]+: /.test(error.message)) return error;
-
-	const match = /^(DESKTOP_[A-Z_]+):\s*(.*)$/.exec(error.message);
-	if (match === null) return desktopError(fallbackCode, error.message);
-	const code = LEGACY_ERROR_CODES[match[1]] ?? fallbackCode;
-	return desktopError(code, match[2]);
-}
-
-function normalizeCapabilities(capabilities) {
-	return {
-		...capabilities,
-		ax: false,
-		backgroundWindowInput: false,
-		takeover: true,
-		axPermission: "unavailable",
-	};
-}
-
-function legacyPoint(point) {
-	return { x: Math.round(point.x), y: Math.round(point.y) };
-}
-
-function captureCapsKey(caps) {
-	return `${caps?.maxWidth ?? ""}:${caps?.maxHeight ?? ""}`;
-}
-
-function legacyButton(button) {
-	return button === "middle" ? "wheel" : button;
-}
-function sourceDimensions(capture) {
-	if (capture.sourceWidth !== undefined && capture.sourceHeight !== undefined) {
-		return { sourceWidth: capture.sourceWidth, sourceHeight: capture.sourceHeight };
-	}
-	const displays = Array.isArray(capture.displays) ? capture.displays : [];
-	if (displays.length === 0) {
-		return { sourceWidth: capture.width, sourceHeight: capture.height };
-	}
-	const minX = Math.min(...displays.map(display => display.x));
-	const minY = Math.min(...displays.map(display => display.y));
-	const maxX = Math.max(...displays.map(display => display.x + display.width));
-	const maxY = Math.max(...displays.map(display => display.y + display.height));
-	const nativeScale = Math.max(1, ...displays.map(display => display.scale ?? 1));
-	return {
-		sourceWidth: Math.max(1, Math.round((maxX - minX) * nativeScale)),
-		sourceHeight: Math.max(1, Math.round((maxY - minY) * nativeScale)),
-	};
-}
-
-function displaysEqual(a, b) {
-	if (a === b) return true;
-	if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i++) {
-		const x = a[i];
-		const y = b[i];
-		if (
-			x === y ||
-			(x?.id === y?.id &&
-				x?.x === y?.x &&
-				x?.y === y?.y &&
-				x?.width === y?.width &&
-				x?.height === y?.height &&
-				x?.scale === y?.scale &&
-				x?.pixelX === y?.pixelX &&
-				x?.pixelY === y?.pixelY &&
-				x?.pixelWidth === y?.pixelWidth &&
-				x?.pixelHeight === y?.pixelHeight)
-		) {
-			continue;
-		}
-		return false;
-	}
-	return true;
-}
-
-// Field-by-field frame comparison: the JSON.stringify signature allocated a
-// full string over the display list on every capture and every input action.
-// A rolling hash would risk collisions where string equality had none, so
-// compare the same fields directly instead.
-function sameFrame(a, b) {
-	if (a === b) return true;
-	if (!a || !b) return false;
-	return a.target === b.target && a.width === b.width && a.height === b.height && displaysEqual(a.displays, b.displays);
-}
-
-// Lightweight projection of the fields sameFrame reads: the stored capture
-// must NOT retain the full screenshot (`data: Uint8Array`, multi-MB per
-// target) after callers finish with it.
-function frameIdentity(capture) {
-	const displays = Array.isArray(capture.displays) ? capture.displays.map(displayOf) : capture.displays;
-	return { target: capture.target, width: capture.width, height: capture.height, displays };
-}
-
-function displayOf(display) {
-	return {
-		id: display?.id,
-		x: display?.x,
-		y: display?.y,
-		width: display?.width,
-		height: display?.height,
-		scale: display?.scale,
-		pixelX: display?.pixelX,
-		pixelY: display?.pixelY,
-		pixelWidth: display?.pixelWidth,
-		pixelHeight: display?.pixelHeight,
-	};
-}
-
-function frameSignature(capture) {
-	return JSON.stringify({
-		target: capture.target,
-		width: capture.width,
-		height: capture.height,
-		displays: capture.displays?.map(display => ({
-			id: display.id,
-			x: display.x,
-			y: display.y,
-			width: display.width,
-			height: display.height,
-			scale: display.scale,
-			pixelX: display.pixelX,
-			pixelY: display.pixelY,
-			pixelWidth: display.pixelWidth,
-			pixelHeight: display.pixelHeight,
-		})),
-	});
-}
-
-/**
- * Adapt the pre-parity desktop addon ABI used by pull-request CI artifacts to
- * the current session contract. Released addons exposed capture/execute/close;
- * current addons already expose the complete API and pass through unchanged.
- */
+const REQUIRED_METHODS = [
+	"click",
+	"capture",
+	"captureRegion",
+	"cancel",
+	"retire",
+	"observe",
+	"listApplications",
+	"openApplication",
+	"menuItems",
+	"menuSelect",
+	"holdKeys",
+	"holdMouse",
+	"acquireControl",
+	"releaseControl",
+	"controlState",
+	"bringToCurrentSpace",
+];
+
+/** Require the current desktop ABI; partial legacy emulation cannot preserve input ownership. */
 export function adaptDesktopSession(NativeDesktopSession) {
-	if (typeof NativeDesktopSession?.prototype?.click === "function") return NativeDesktopSession;
-	const cached = ADAPTED_SESSION_CLASSES.get(NativeDesktopSession);
-	if (cached) return cached;
-
-	class DesktopSession {
-		#native;
-		#nativeDesktopSession;
-		#options;
-		#sessions;
-		#closed = false;
-		#capturedTargets = new Map();
-
-		constructor(options) {
-			try {
-				this.#nativeDesktopSession = NativeDesktopSession;
-				this.#options = options;
-				this.#native = new NativeDesktopSession(options);
-				this.#sessions = new Map([[captureCapsKey(), this.#native]]);
-			} catch (error) {
-				throw normalizeError(error, "Internal");
-			}
-		}
-
-		get capabilities() {
-			return normalizeCapabilities(this.#native.capabilities);
-		}
-
-		#ensureOpen() {
-			if (this.#closed) throw desktopError("Closed", "desktop session is closed");
-		}
-
-		#nativeForCapturedTarget(target) {
-			const capture = this.#capturedTargets.get(target);
-			if (capture) return capture.native;
-			throw desktopError(
-				"InvalidCoordinateFrame",
-				`no capture of '${target}' yet — take a screenshot of this target first`,
-			);
-		}
-
-		#sessionForCapture(caps) {
-			const key = captureCapsKey(caps);
-			const existing = this.#sessions.get(key);
-			if (existing) return existing;
-			try {
-				const native = new this.#nativeDesktopSession({
-					...this.#options,
-					maxWidth: caps?.maxWidth,
-					maxHeight: caps?.maxHeight,
-				});
-				this.#sessions.set(key, native);
-				return native;
-			} catch (error) {
-				throw normalizeError(error, "CaptureFailed");
-			}
-		}
-
-		#ensureForeground(target, options) {
-			if (target !== "desktop" && options?.takeover !== true) {
-				throw desktopError(
-					"BackgroundUnavailable",
-					"the installed native addon supports foreground input only",
-				);
-			}
-		}
-
-		async #execute(actions, target, native = this.#native, fallbackCode = "InputFailed") {
-			try {
-				const capture = await native.execute(Array.isArray(actions) ? actions : [actions], target);
-				const previous = this.#capturedTargets.get(target);
-				if (capture && previous?.native === native && !sameFrame(capture, previous.capture)) {
-					this.#capturedTargets.delete(target);
-				}
-			} catch (error) {
-				throw normalizeError(error, fallbackCode);
-			}
-		}
-
-		async listDisplays() {
-			this.#ensureOpen();
-			throw desktopError("CaptureFailed", "the installed native addon does not expose display enumeration");
-		}
-
-		async listWindows() {
-			this.#ensureOpen();
-			if (typeof this.#native.listWindows !== "function") {
-				throw desktopError("CaptureFailed", "the installed native addon does not expose window enumeration");
-			}
-			try {
-				return await this.#native.listWindows();
-			} catch (error) {
-				throw normalizeError(error, "CaptureFailed");
-			}
-		}
-
-		async capture(target, caps) {
-			this.#ensureOpen();
-			if (target !== "desktop" && !/^\d+$/.test(target)) {
-				throw desktopError("InvalidTarget", `invalid window target '${target}'`);
-			}
-			if (target !== "desktop" && typeof this.#native.listWindows !== "function") {
-				throw desktopError("CaptureFailed", "the installed native addon does not support window capture");
-			}
-			try {
-				const native = this.#sessionForCapture(caps);
-				const capture = await native.capture(target);
-				const adapted = { ...capture, ...sourceDimensions(capture), target };
-				// Store only the comparison fields, not the screenshot bytes:
-				// `adapted` carries the full PNG `data` (multi-MB per target).
-				// Keep the string signature for any external reader of the
-				// stored shape.
-				this.#capturedTargets.set(target, { native, capture: frameIdentity(adapted), signature: frameSignature(adapted) });
-				return adapted;
-			} catch (error) {
-				throw normalizeError(error, "CaptureFailed");
-			}
-		}
-
-		async click(target, x, y, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			const native = this.#nativeForCapturedTarget(target);
-			const count = Math.max(1, options?.count ?? 1);
-			const button = legacyButton(options?.button ?? "left");
-			const point = { x: Math.round(x), y: Math.round(y), keys: options?.modifiers ?? [] };
-			const actions =
-				count === 2 && button === "left"
-					? [{ type: "double_click", ...point }]
-					: Array.from({ length: count }, () => ({ type: "click", ...point, button }));
-			await this.#execute(actions, target, native);
-		}
-
-		async moveMouse(target, x, y, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			await this.#execute(
-				{ type: "move", x: Math.round(x), y: Math.round(y), keys: options?.modifiers ?? [] },
-				target,
-				this.#nativeForCapturedTarget(target),
-			);
-		}
-
-		async drag(target, path, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			await this.#execute(
-				{ type: "drag", path: path.map(legacyPoint), keys: options?.modifiers ?? [] },
-				target,
-				this.#nativeForCapturedTarget(target),
-			);
-		}
-
-		async scroll(target, x, y, dx, dy, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			await this.#execute(
-				{
-					type: "scroll",
-					x: Math.round(x),
-					y: Math.round(y),
-					scroll_x: Math.round(dx),
-					scroll_y: Math.round(dy),
-					keys: options?.modifiers ?? [],
-				},
-				target,
-				this.#nativeForCapturedTarget(target),
+	const prototype = NativeDesktopSession?.prototype;
+	const missing = REQUIRED_METHODS.filter(method => typeof prototype?.[method] !== "function");
+	if (missing.length === 0) {
+		return NativeDesktopSession;
+	}
+	// The shared native entrypoint is also imported by non-desktop tools. Keep
+	// their imports usable, but never emulate the new ABI with unsafe fallbacks.
+	return class UnsupportedDesktopSession {
+		constructor() {
+			throw new Error(
+				`Unsupported: desktop native addon is outdated (missing ${missing.join(", ")}). Update the native addon or run bun run build:native from the repository root.`,
 			);
 		}
-
-		async typeText(target, text, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			await this.#execute({ type: "type", text }, target, this.#capturedTargets.get(target)?.native ?? this.#native);
-		}
-
-		async keyChord(target, keys, options) {
-			this.#ensureOpen();
-			this.#ensureForeground(target, options);
-			await this.#execute({ type: "keypress", keys }, target, this.#capturedTargets.get(target)?.native ?? this.#native);
-		}
-
-		async raiseWindow() {
-			this.#ensureOpen();
-			throw desktopError("BackgroundUnavailable", "the installed native addon does not support window control");
-		}
-
-		async axSnapshot() {
-			this.#ensureOpen();
-			throw desktopError("AxUnsupported", "accessibility is unavailable in the installed native addon");
-		}
-
-		async axQuery() {
-			return this.axSnapshot();
-		}
-
-		async axElementAt() {
-			return this.axSnapshot();
-		}
-
-		async axFocused() {
-			return this.axSnapshot();
-		}
-
-		async axNode() {
-			return this.axSnapshot();
-		}
-
-		async axAttributes() {
-			return this.axSnapshot();
-		}
-
-		async axChildren() {
-			return this.axSnapshot();
-		}
-
-		async axParent() {
-			return this.axSnapshot();
-		}
-
-		async axPerform() {
-			return this.axSnapshot();
-		}
-
-		async axSetValue() {
-			return this.axSnapshot();
-		}
-
-		async axFocus() {
-			return this.axSnapshot();
-		}
-
-		async axClick() {
-			return this.axSnapshot();
-		}
-
-		async close() {
-			if (this.#closed) return;
-			this.#closed = true;
-			try {
-				await Promise.all([...this.#sessions.values()].map(native => native.close()));
-			} catch (error) {
-				throw normalizeError(error, "Internal");
-			}
-		}
-	}
-
-	ADAPTED_SESSION_CLASSES.set(NativeDesktopSession, DesktopSession);
-	return DesktopSession;
+	};
 }

package/native/index.d.ts

@@ -31,10 +31,42 @@ export declare class AudioPlayback {
 /** Persistent, serialized native desktop capture/input/accessibility session. */
 export declare class DesktopSession {
   constructor(options?: DesktopSessionOptions | undefined | null)
+  /**
+   * Asks the worker when it is idle, so permissions are read live. While
+   * another operation holds the worker, answers from the snapshot of the
+   * latest capabilities read or capture instead of blocking the JS thread
+   * behind it.
+   */
   get capabilities(): DesktopCapabilities
   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>
+  /**
+   * Capture and accessibility share one serialized request. Neither a failed
+   * snapshot nor an abandoned reply replaces the last delivered input frame.
+   */
+  observe(target: string, caps?: CaptureCaps | undefined | null, axOptions?: AxSnapshotOptions | undefined | null): Promise<DesktopObservation>
+  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>
+  /**
+   * Native ownership only. Human approval is required by the host before
+   * calling this method.
+   */
+  acquireControl(): Promise<DesktopControlState>
+  releaseControl(): void
+  controlState(): DesktopControlState
+  /** Retire queued work from a completed helper without revoking task control. */
+  retire(): 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>
@@ -58,6 +90,11 @@ export declare class DesktopSession {
   axSetValue(reference: string, value: string): Promise<undefined>
   axFocus(reference: string): Promise<undefined>
   axClick(reference: string, opts?: PointerOptions | undefined | null): Promise<undefined>
+  /**
+   * Immediately cancel operations submitted before this call. Later
+   * operations may proceed.
+   */
+  cancel(): void
   close(): Promise<undefined>
 }
 
@@ -722,6 +759,29 @@ export declare function appleFmCancel(handle: number): void
  */
 export declare function appleFmGenerate(request: string, onEvent: (err: null | Error, event: string) => void): number
 
+/**
+ * Installed application identity with currently observable process
+ * information.
+ */
+export interface Application {
+  id: string
+  name: string
+  path: string
+  running: boolean
+  pid?: number
+}
+
+/** Controls whether launching an application deliberately activates it. */
+export interface ApplicationOpenOptions {
+  activate?: boolean
+}
+
+/** Filters the native application inventory without requiring screen access. */
+export interface ApplicationQuery {
+  query?: string
+  runningOnly?: boolean
+}
+
 /**
  * Apply ast-grep rewrite rules to matching files; honors `dryRun` and returns
  * a promise.
@@ -1013,6 +1073,15 @@ export interface AxSnapshotOptions {
   all?: boolean
 }
 
+export interface BlockParseOptions {
+  /** Source code to parse. */
+  code: string
+  /** Language alias (e.g. "rust", "typescript") used before path inference. */
+  lang?: string
+  /** File path used to infer language by extension when `lang` is omitted. */
+  path?: string
+}
+
 export interface BlockRange {
   /** 1-indexed inclusive first line of the resolved block. */
   startLine: number
@@ -1045,6 +1114,14 @@ export interface CaptureCaps {
   maxHeight?: number
 }
 
+/** Rectangle in pixels of the most recent full screenshot of the same target. */
+export interface CaptureRegion {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
 /** Clipboard image payload encoded as PNG bytes. */
 export interface ClipboardImage {
   /** PNG-encoded image bytes. */
@@ -1100,7 +1177,7 @@ export declare function cosineSimilarityPairs(vectors: Float64Array, count: numb
 export declare function countTokens(input: string | string[], encoding?: Encoding | undefined | null): number
 
 /**
- * Decode one complete SIXEL control string into a PNG.
+ * Decode one complete SIXEL control string into a PNG on the calling thread.
  *
  * The decoder is deliberately bounded before handing the stream to
  * `icy_sixel`: raster declarations, repeats, and row advances are scanned
@@ -1109,6 +1186,12 @@ export declare function countTokens(input: string | string[], encoding?: Encodin
  */
 export declare function decodeSixelToPng(bytes: Uint8Array): Uint8Array
 
+/**
+ * Same result as [`decode_sixel_to_png`], but the decode runs on the native
+ * blocking pool instead of the JS thread.
+ */
+export declare function decodeSixelToPngAsync(bytes: Uint8Array): Promise<Uint8Array>
+
 export interface DesktopCapabilities {
   backend: string
   displayServer?: string
@@ -1121,6 +1204,15 @@ export interface DesktopCapabilities {
    * target and post real input).
    */
   takeover: boolean
+  applications: boolean
+  menus: boolean
+  heldInput: boolean
+  spaces: boolean
+  /**
+   * Native global Escape cancellation while input/control ownership is held.
+   * Wayland requires the host interrupt action instead.
+   */
+  globalEscape: boolean
   capturePermission: string
   inputPermission: string
   axPermission: string
@@ -1138,12 +1230,24 @@ export interface DesktopCapture {
    * unscaled.
    */
   sourceHeight: number
+  /** Dimensions of the full screenshot coordinate frame used by pointer input. */
+  coordinateWidth: number
+  coordinateHeight: number
+  /**
+   * Region in the full screenshot's coordinates; zoom pixels are not input
+   * coordinates.
+   */
+  region?: CaptureRegion
   target: string
   displays: Array<DesktopDisplay>
   backend: string
   displayServer?: string
 }
 
+export interface DesktopControlState {
+  active: boolean
+}
+
 /**
  * Monitor geometry in both global logical desktop coordinates and composite
  * screenshot pixels.
@@ -1163,6 +1267,24 @@ export interface DesktopDisplay {
   isPrimary: boolean
 }
 
+/**
+ * One immediate child of a native application menu. Paths contain the actual
+ * native labels, including ellipses; selection accepts normalized labels.
+ */
+export interface DesktopMenuItem {
+  title: string
+  path: Array<string>
+  enabled: boolean
+  checked: boolean
+  hasSubmenu: boolean
+  shortcut?: string
+}
+
+export interface DesktopObservation {
+  capture: DesktopCapture
+  accessibility: AxSnapshot
+}
+
 export interface DesktopPoint {
   x: number
   y: number
@@ -1520,16 +1642,27 @@ export interface EnclosingBoundaryOptions {
 }
 
 /**
- * Encode image bytes into a SIXEL escape sequence for terminal rendering.
+ * Encode image bytes into a SIXEL escape sequence for terminal rendering, on
+ * the calling thread.
  *
  * The input image is decoded and resized to the requested pixel dimensions
- * before encoding.
+ * before encoding. 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
 
+/**
+ * Same result as [`encode_sixel`], but the decode, resize and dither run on
+ * the native blocking pool, so they never stall the JavaScript event loop.
+ *
+ * # Errors
+ * Rejects if decoding, resizing, or SIXEL encoding fails.
+ */
+export declare function encodeSixelAsync(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): Promise<string>
+
 /** Tokenizer encoding to use. */
 export declare enum Encoding {
   /** GPT-4o / o1 / GPT-5 (default). */
@@ -1957,6 +2090,14 @@ export interface HighlightColors {
   deleted?: string
 }
 
+export interface HoldOptions {
+  /** Duration in seconds, from zero through 100. */
+  duration: number
+  button?: string
+  keys?: Array<string>
+  takeover?: boolean
+}
+
 /**
  * Convert HTML source to Markdown with optional preprocessing.
  *
@@ -2066,10 +2207,13 @@ export interface IsoProbeResult {
 }
 
 /**
- * Pick the best backend available right now. `preferred` is treated as
- * a hint — see [`pi_iso::resolve`] for the exact priority rules.
+ * Pick the best backend available right now.
+ *
+ * `preferred` is treated as a hint — see [`pi_iso::resolve`] for the exact
+ * priority rules. Backend probes may spawn CLIs, so they run on the native
+ * blocking pool.
  */
-export declare function isoResolve(preferred?: IsoBackendKind | undefined | null): IsoResolveResult
+export declare function isoResolve(preferred?: IsoBackendKind | undefined | null): Promise<IsoResolveResult>
 
 /** Outcome of [`iso_resolve`]. */
 export interface IsoResolveResult {
@@ -2457,6 +2601,8 @@ export interface PointerOptions {
   button?: string
   count?: number
   modifiers?: Array<string>
+  /** Arbitrary keys held for the duration of a drag. */
+  keys?: Array<string>
   /**
    * Briefly activate the target window and post real input instead of the
    * default background delivery.
@@ -2627,10 +2773,11 @@ export declare function renderMermaidAscii(text: string, options?: MermaidRender
  * Render one snapcompact frame on a libuv worker: print pre-normalized text
  * onto a `size`-wide bitmap and encode it as PNG.
  *
- * The bitmap height hugs the rows the text actually occupies
- * (`usedRows * lineRepeat * cellHeight`), so a partially filled frame never
- * pays for blank padding rows. The glyph grid holds `floor(size/cellWidth) *
- * floor(size/cellHeight/lineRepeat)` characters; input beyond that is ignored.
+ * The bitmap height hugs the rows the text occupies
+ * (`usedRows * lineRepeat * cellHeight`), with a 64px floor for vision
+ * processors that reject smaller dimensions. The glyph grid holds
+ * `floor(size/cellWidth) * floor(size/cellHeight/lineRepeat)` characters;
+ * input beyond that is ignored.
  * Native-cell bitmap-font shapes encode as indexed PNG; stretched bitmap-font
  * shapes (target cell != font cell) encode as RGB. TrueType shapes encode RGB
  * directly from grayscale coverage.
@@ -3108,8 +3255,8 @@ export declare function sliceWithWidth(line: string, startCol: number, length: n
 export interface SnapcompactRenderOptions {
   /**
    * Frame width in pixels; also bounds the grid rows
-   * (`floor(size/cellHeight/lineRepeat)`). Output height hugs the rows the
-   * text actually uses instead of padding to a square.
+   * (`floor(size/cellHeight/lineRepeat)`). Output height hugs the used rows
+   * with a 64px floor, rather than padding every frame to a square.
    */
   size: number
   /**
@@ -3496,6 +3643,18 @@ export interface VectorTopK {
  */
 export declare function visibleWidth(text: string, tabWidth: number): number
 
+/**
+ * Parse `options.code` into the shared tree cache on the native blocking
+ * pool.
+ *
+ * [`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.
+ */
+export declare function warmBlockParse(options: BlockParseOptions): Promise<undefined>
+
 /**
  * Warm syntax grammars, scope matchers, and the regexes of commonly
  * highlighted languages on the native worker pool.

package/native/index.js

@@ -58,6 +58,7 @@ export const copyToClipboard = nativeBindings.copyToClipboard ?? missingNativeEx
 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 detectMacOSAppearance = nativeBindings.detectMacOSAppearance ?? missingNativeExport("detectMacOSAppearance");
 export const deviceCheckGenerateToken = nativeBindings.deviceCheckGenerateToken ?? missingNativeExport("deviceCheckGenerateToken");
 export const diffLineRuns = nativeBindings.diffLineRuns ?? missingNativeExport("diffLineRuns");
@@ -70,6 +71,7 @@ export const editGrammar = nativeBindings.editGrammar ?? missingNativeExport("ed
 export const editInspect = nativeBindings.editInspect ?? missingNativeExport("editInspect");
 export const enclosingBlockBoundaries = nativeBindings.enclosingBlockBoundaries ?? missingNativeExport("enclosingBlockBoundaries");
 export const encodeSixel = nativeBindings.encodeSixel ?? missingNativeExport("encodeSixel");
+export const encodeSixelAsync = nativeBindings.encodeSixelAsync ?? missingNativeExport("encodeSixelAsync");
 export const execReplace = nativeBindings.execReplace ?? missingNativeExport("execReplace");
 export const executeShell = nativeBindings.executeShell ?? missingNativeExport("executeShell");
 export const expandWindowsLongPath = nativeBindings.expandWindowsLongPath ?? missingNativeExport("expandWindowsLongPath");
@@ -138,6 +140,7 @@ export const vcsJoinPatches = nativeBindings.vcsJoinPatches ?? missingNativeExpo
 export const vcsValidateHunkSelections = nativeBindings.vcsValidateHunkSelections ?? missingNativeExport("vcsValidateHunkSelections");
 export const vectorIndexTopK = nativeBindings.vectorIndexTopK ?? missingNativeExport("vectorIndexTopK");
 export const visibleWidth = nativeBindings.visibleWidth ?? missingNativeExport("visibleWidth");
+export const warmBlockParse = nativeBindings.warmBlockParse ?? missingNativeExport("warmBlockParse");
 export const warmHighlighter = nativeBindings.warmHighlighter ?? missingNativeExport("warmHighlighter");
 export const wrapTextWithAnsi = nativeBindings.wrapTextWithAnsi ?? missingNativeExport("wrapTextWithAnsi");
 

package/native/vcs.d.ts

@@ -81,6 +81,12 @@ export declare function detachGitDir(
 	signal?: AbortSignal,
 ): Promise<"no-git" | "independent" | "detached">;
 
+/** Run Git's checkout hook in a new linked worktree and return its output and exit status. */
+export declare function runPostCheckoutHook(
+	worktreeRoot: string,
+	head: string,
+): Promise<{ exitCode: number; stdout: Uint8Array; stderr: Uint8Array }>;
+
 /** Join patch fragments, preserving each part's trailing newline. */
 export declare function joinPatches(parts: string[]): string;
 

package/native/vcs.js

@@ -1,3 +1,4 @@
+import { $ } from "bun";
 import * as fs from "node:fs";
 import { loadNative } from "./loader-state.js";
 
@@ -95,6 +96,19 @@ export function detachGitDir(worktreeRoot, sourceCommonDir, signal) {
 	return api().vcsDetachGitDir(worktreeRoot, sourceCommonDir, signal);
 }
 
+/**
+ * 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`.
+ */
+export async function runPostCheckoutHook(worktreeRoot, head) {
+	const nullOid = "0".repeat(head.length);
+	const result = await $`git hook run --ignore-missing post-checkout -- ${nullOid} ${head} 1`
+		.cwd(worktreeRoot)
+		.quiet()
+		.nothrow();
+	return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+}
+
 /** Join patch fragments, preserving each part's trailing newline. */
 export function joinPatches(parts) {
 	return api().vcsJoinPatches(parts);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-natives",
-	"version": "1.1.26",
+	"version": "1.1.27",
 	"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/",
@@ -111,11 +111,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@linxiraos/pi-natives-linux-x64": "1.1.26",
-		"@linxiraos/pi-natives-linux-arm64": "1.1.26",
-		"@linxiraos/pi-natives-darwin-x64": "1.1.26",
-		"@linxiraos/pi-natives-darwin-arm64": "1.1.26",
-		"@linxiraos/pi-natives-win32-x64": "1.1.26",
-		"@linxiraos/pi-natives-win32-arm64": "1.1.26"
+		"@linxiraos/pi-natives-linux-x64": "1.1.27",
+		"@linxiraos/pi-natives-linux-arm64": "1.1.27",
+		"@linxiraos/pi-natives-darwin-x64": "1.1.27",
+		"@linxiraos/pi-natives-darwin-arm64": "1.1.27",
+		"@linxiraos/pi-natives-win32-x64": "1.1.27",
+		"@linxiraos/pi-natives-win32-arm64": "1.1.27"
 	}
 }