@linxiraos/pi-natives 1.1.26 → 1.2.0

package/README.md

@@ -10,6 +10,8 @@ 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`
+- **Binary patches**: `applyBinaryPatch(oldPath, patchPath, outPath)` applies an HDiffPatch single-stream patch (HDIFFSF20, zstd or uncompressed), streaming from files; callers verify digests
 
 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 +21,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 +38,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
@@ -71,7 +78,7 @@ crates/pi-natives/       # Rust source (workspace member)
 native/                  # Core loader files and local/CI native build outputs
   index.js               # Public native export surface
   loader-state.js        # Platform, ISA variant, and addon resolution
-  embedded-addon.js      # Standalone binary embed stub/generated metadata
+  embedded-addon.js      # Null embed stub; binary builds replace it in memory
   pi_natives.<platform>-<arch>-modern.node   # x64 modern ISA (local/CI artifact)
   pi_natives.<platform>-<arch>-baseline.node # x64 baseline ISA (local/CI artifact)
   pi_natives.<platform>-<arch>.node          # non-x64 build artifact

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/embedded-addon.js

@@ -1,6 +1,5 @@
-
-// AUTOGENERATED FILE -- DO NOT EDIT DIRECTLY
-// See scripts/embed-native.ts
+// Always null on disk. Standalone binary builds replace this module in memory
+// with the target's manifest and one zstd frame per addon (scripts/embed-native.ts).
 
 /** @typedef {"modern" | "baseline" | "default"} EmbeddedAddonVariant */
 
@@ -8,15 +7,8 @@
  * @typedef {Object} EmbeddedAddonFile
  * @property {EmbeddedAddonVariant} variant
  * @property {string} filename
- * @property {number} size
- * @property {string=} filePath
- */
-
-/**
- * @typedef {Object} EmbeddedAddonArchive
- * @property {"tar.gz"} format
- * @property {string} filename
- * @property {string} filePath
+ * @property {number} size Decompressed `.node` size in bytes.
+ * @property {string} zstdPath Embedded zstd frame holding the addon bytes.
  */
 
 /**
@@ -24,7 +16,6 @@
  * @property {string} platformTag
  * @property {string} version
  * @property {EmbeddedAddonFile[]} files
- * @property {EmbeddedAddonArchive=} archive
  */
 
 /** @type {EmbeddedAddon|null} */