@oh-my-pi/pi-natives 17.4.2 → 18.0.1

package/native/desktop-adapter.d.ts

@@ -0,0 +1,28 @@
+interface AdaptedDesktopCapabilities {
+	readonly [key: string]: unknown;
+	readonly ax: boolean;
+	readonly backgroundWindowInput: boolean;
+	readonly deliveryModes: readonly string[];
+	readonly axPermission: string;
+}
+
+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[]; deliveryMode?: string },
+	): Promise<void>;
+	typeText(target: string, text: string, options?: { deliveryMode?: string }): Promise<void>;
+	keyChord(target: string, keys: string[], options?: { deliveryMode?: string }): Promise<void>;
+	close(): Promise<void>;
+}
+
+interface AdaptedDesktopSessionConstructor {
+	new (options: Record<string, unknown>): AdaptedDesktopSession;
+}
+
+export function adaptDesktopSession(NativeDesktopSession: unknown): AdaptedDesktopSessionConstructor;

package/native/desktop-adapter.js

@@ -0,0 +1,341 @@
+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,
+		deliveryModes: ["foreground"],
+		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 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.
+ */
+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 (options?.deliveryMode !== "foreground" && (target !== "desktop" || options?.deliveryMode !== undefined)) {
+				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 && frameSignature(capture) !== previous.signature) {
+					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 };
+				this.#capturedTargets.set(target, { native, 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),
+			);
+		}
+
+		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/desktop.js

@@ -1,10 +1,13 @@
+import { adaptDesktopSession } from "./desktop-adapter.js";
 import { loadNative } from "./loader-state.js";
 
+let DesktopSession;
+
 /**
  * Construct a desktop session without loading the native addon until the
  * computer worker receives its initialization message.
  */
 export function createDesktopSession(options) {
-	const { DesktopSession } = loadNative();
+	DesktopSession ??= adaptDesktopSession(loadNative().DesktopSession);
 	return new DesktopSession(options);
 }

package/native/index.d.ts

@@ -77,6 +77,24 @@ export declare class FileLock {
   release(): void
 }
 
+/**
+ * Stateful incremental syntax highlighter for streamed code.
+ *
+ * Carries syntect parser state across [`HighlightStream::push`] calls so
+ * chunked highlighting of a growing buffer is byte-identical to highlighting
+ * the concatenated text in one call. Feed newline-terminated complete lines;
+ * only the final push may omit the trailing newline. An unresolved language
+ * echoes input unchanged.
+ */
+export declare class HighlightStream {
+  /** Create a stream for `lang`; an unknown language yields a passthrough. */
+  constructor(lang: string | undefined | null, colors: HighlightColors)
+  /** Whether the language resolved to a grammar; `false` means passthrough. */
+  get supported(): boolean
+  /** Highlight the next chunk and advance parser state. */
+  push(chunk: string): string
+}
+
 /** WebRTC peer that accepts 16 kHz mono PCM and renders remote Opus audio. */
 export declare class LiveWebRtcPeer {
   /**
@@ -234,6 +252,48 @@ export declare class Shell {
   liveBackgroundJobCount(): Promise<number>
 }
 
+/**
+ * Dedicated writer thread for one terminal fd.
+ *
+ * Constructed by the TUI's `ProcessTerminal` around stdout. The fd is
+ * `dup(2)`'d at construction and closed on drop, so later manipulation of the
+ * original descriptor does not affect the pump.
+ */
+export declare class TtyWriter {
+  /**
+   * Start a pump thread for `fd` (typically 1). Fails on non-Unix hosts and
+   * when the descriptor cannot be duplicated.
+   */
+  constructor(fd: number)
+  /**
+   * Enqueue terminal output; never blocks. Returns the total bytes now
+   * pending (including this chunk).
+   *
+   * Reads the JS string as UTF-16 through the thread's scratch arena and
+   * transcodes it with `xutf` straight into the shared back buffer, so a
+   * warm writer costs no per-call heap allocation.
+   */
+  write(data: string): number
+  /** Bytes accepted but not yet written to the terminal. */
+  pending(): number
+  /** True once a write failed (dead PTY); queued output has been dropped. */
+  get dead(): boolean
+  /**
+   * Block the calling thread until the queue drains, the writer dies, or
+   * `timeout_ms` elapses. Returns true when fully drained. Exit paths only.
+   */
+  flushSync(timeoutMs: number): boolean
+  /**
+   * Flush (bounded by `flush_timeout_ms`), stop the pump thread, and join it.
+   *
+   * A pump stuck in a blocked `write(2)` (stalled-but-alive PTY consumer)
+   * cannot be joined without freezing the caller: when the bounded flush
+   * times out the thread is detached instead and its dup'd fd is leaked —
+   * closing it under a blocked write would race kernel fd reuse.
+   */
+  stop(flushTimeoutMs: number): void
+}
+
 /**
  * Install the bounded Tokio runtime napi-rs adopts for async exports and the
  * bounded Rayon global pool used by native parallel iterators.
@@ -279,7 +339,7 @@ export declare function __ompInstallTokioRuntime(): void
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV17_4_2(): void
+export declare function __piNativesV18_0_1(): void
 
 /**
  * Apply ast-grep rewrite rules to matching files; honors `dryRun` and returns
@@ -1399,6 +1459,31 @@ export declare enum MacOSAppearance {
   Light = 'light'
 }
 
+/**
+ * Return the autocorrection macOS chooses for one completed-word range.
+ *
+ * Returns `null` when no confident correction exists or the service is
+ * unavailable.
+ * On macOS, the lookup runs on the dedicated spelling thread.
+ */
+export declare function macOSAutocorrectWord(text: string, start: number, length: number): Promise<string | null>
+
+/**
+ * Find every misspelled word using the active macOS dictionaries.
+ *
+ * Returns an empty list when Apple's spelling service is unavailable.
+ * On macOS, the check runs on the dedicated spelling thread.
+ */
+export declare function macOSCheckSpelling(text: string): Promise<Array<SpellingRange>>
+
+/**
+ * Return macOS dictionary completions for one partial-word range.
+ *
+ * Returns an empty list when Apple's spelling service is unavailable.
+ * On macOS, the lookup runs on the dedicated spelling thread.
+ */
+export declare function macOSCompleteWord(text: string, start: number, length: number): Promise<Array<string>>
+
 /**
  * Options for starting a macOS power assertion.
  *
@@ -1423,6 +1508,17 @@ export interface MacOSPowerAssertionOptions {
   display?: boolean
 }
 
+/** Whether the host can use Apple's native spelling service. */
+export declare function macOSSpellCheckerAvailable(): boolean
+
+/**
+ * Return macOS replacement guesses for one misspelled-word range.
+ *
+ * Returns an empty list when Apple's spelling service is unavailable.
+ * On macOS, the lookup runs on the dedicated spelling thread.
+ */
+export declare function macOSSpellingGuesses(text: string, start: number, length: number): Promise<Array<string>>
+
 /** A single match in the content. */
 export interface Match {
   /** 1-indexed line number. */
@@ -1952,6 +2048,14 @@ export interface SnapcompactRenderOptions {
  */
 export declare function snapcompactSupportedChars(font: string, chars: string): string
 
+/** A misspelled span measured in JavaScript/UTF-16 code units. */
+export interface SpellingRange {
+  /** Inclusive UTF-16 start offset. */
+  start: number
+  /** UTF-16 length of the misspelled span. */
+  length: number
+}
+
 /**
  * Unified-diff hunks with jsdiff
  * `structuredPatch(_, _, oldText, newText, _, _, { context }).hunks`

package/native/index.js

@@ -1,4 +1,5 @@
 import { loadNative } from "./loader-state.js";
+import { adaptDesktopSession } from "./desktop-adapter.js";
 
 /**
  * Native addon entrypoint.
@@ -18,18 +19,20 @@ const nativeBindings = loadNative();
 // classes
 export const AudioCapture = nativeBindings.AudioCapture;
 export const AudioPlayback = nativeBindings.AudioPlayback;
-export const DesktopSession = nativeBindings.DesktopSession;
+export const DesktopSession = adaptDesktopSession(nativeBindings.DesktopSession);
 export const FileLock = nativeBindings.FileLock;
+export const HighlightStream = nativeBindings.HighlightStream;
 export const LiveWebRtcPeer = nativeBindings.LiveWebRtcPeer;
 export const MacAppearanceObserver = nativeBindings.MacAppearanceObserver;
 export const MacOSPowerAssertion = nativeBindings.MacOSPowerAssertion;
 export const Process = nativeBindings.Process;
 export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
+export const TtyWriter = nativeBindings.TtyWriter;
 
 // functions
 export const __ompInstallTokioRuntime = nativeBindings.__ompInstallTokioRuntime;
-export const __piNativesV17_4_2 = nativeBindings.__piNativesV17_4_2;
+export const __piNativesV18_0_1 = nativeBindings.__piNativesV18_0_1;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
 export const astMatch = nativeBindings.astMatch;
@@ -63,6 +66,11 @@ export const isoResolve = nativeBindings.isoResolve;
 export const isoStart = nativeBindings.isoStart;
 export const isoStop = nativeBindings.isoStop;
 export const listWorkspace = nativeBindings.listWorkspace;
+export const macOSAutocorrectWord = nativeBindings.macOSAutocorrectWord;
+export const macOSCheckSpelling = nativeBindings.macOSCheckSpelling;
+export const macOSCompleteWord = nativeBindings.macOSCompleteWord;
+export const macOSSpellCheckerAvailable = nativeBindings.macOSSpellCheckerAvailable;
+export const macOSSpellingGuesses = nativeBindings.macOSSpellingGuesses;
 export const matchesKey = nativeBindings.matchesKey;
 export const matchesKittySequence = nativeBindings.matchesKittySequence;
 export const matchesLegacySequence = nativeBindings.matchesLegacySequence;

package/native/loader-state.js

@@ -648,6 +648,27 @@ function maybeStageNodeModulesAddon(ctx, errors) {
 	return stagedPath;
 }
 
+
+/**
+ * Before version sentinels were exported, published native addons still shared
+ * this stable core ABI. Let those on-disk addons bridge a package-version bump
+ * when they expose the signature; keep every versioned addon and a current
+ * on-disk file paired with resident old exports on the strict path below.
+ */
+function isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedSentinel) {
+	if (diskHasExpectedSentinel) return false;
+	if (Object.keys(bindings).some(key => /^__piNativesV[A-Za-z0-9_]+$/.test(key))) return false;
+	return (
+		typeof bindings.countTokens === "function" &&
+		typeof bindings.executeShell === "function" &&
+		typeof bindings.visibleWidth === "function" &&
+		typeof bindings.DesktopSession === "function" &&
+		typeof bindings.DesktopSession.prototype?.capture === "function" &&
+		typeof bindings.DesktopSession.prototype?.execute === "function" &&
+		typeof bindings.DesktopSession.prototype?.close === "function"
+	);
+}
+
 export function validateLoadedBindings(ctx, bindings, candidate) {
 	// In workspace dev (running out of `packages/natives/native/` rather than a
 	// `node_modules` install or a compiled bundle) the local `.node` only gains
@@ -680,6 +701,7 @@ export function validateLoadedBindings(ctx, bindings, candidate) {
 		// The successful require above normally guarantees readability. If the
 		// file disappears concurrently, retain the safe reinstall diagnosis.
 	}
+	if (isCompatiblePreSentinelNativeAddon(bindings, diskHasExpectedSentinel)) return;
 	if (residentSentinel && diskHasExpectedSentinel) {
 		const residentVersion = residentSentinel.slice("__piNativesV".length).replace(/_/g, ".");
 		throw new Error(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "17.4.2",
+	"version": "18.0.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://omp.sh",
@@ -68,6 +68,8 @@
 		"native/clipboard.d.ts",
 		"native/desktop.js",
 		"native/desktop.d.ts",
+		"native/desktop-adapter.js",
+		"native/desktop-adapter.d.ts",
 		"native/loader-state.js",
 		"native/loader-state.d.ts",
 		"native/embedded-addon.js",
@@ -90,10 +92,10 @@
 		}
 	},
 	"optionalDependencies": {
-		"@oh-my-pi/pi-natives-linux-x64": "17.4.2",
-		"@oh-my-pi/pi-natives-linux-arm64": "17.4.2",
-		"@oh-my-pi/pi-natives-darwin-x64": "17.4.2",
-		"@oh-my-pi/pi-natives-darwin-arm64": "17.4.2",
-		"@oh-my-pi/pi-natives-win32-x64": "17.4.2"
+		"@oh-my-pi/pi-natives-linux-x64": "18.0.1",
+		"@oh-my-pi/pi-natives-linux-arm64": "18.0.1",
+		"@oh-my-pi/pi-natives-darwin-x64": "18.0.1",
+		"@oh-my-pi/pi-natives-darwin-arm64": "18.0.1",
+		"@oh-my-pi/pi-natives-win32-x64": "18.0.1"
 	}
 }