@oh-my-pi/pi-natives 9.6.4 → 9.8.0

package/README.md

@@ -11,7 +11,7 @@ Native Rust functionality via N-API.
 ## Usage
 
 ```typescript
-import { grep, find, PhotonImage, resize, SamplingFilter } from "@oh-my-pi/pi-natives";
+import { grep, find, PhotonImage, SamplingFilter, ImageFormat } from "@oh-my-pi/pi-natives";
 
 // Grep for a pattern
 const results = await grep({
@@ -29,9 +29,9 @@ const files = await find({
 });
 
 // Image processing
-using image = await PhotonImage.new_from_byteslice(bytes);
-using resized = await resize(image, 800, 600, SamplingFilter.Lanczos3);
-const pngBytes = await resized.get_bytes();
+const image = await PhotonImage.parse(bytes);
+const resized = await image.resize(800, 600, SamplingFilter.Lanczos3);
+const pngBytes = await resized.encode(ImageFormat.PNG, 100);
 ```
 
 ## Building

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "9.6.4",
+	"version": "9.8.0",
 	"description": "Native Rust functionality via N-API",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -17,6 +17,8 @@
 	],
 	"scripts": {
 		"build:native": "bun scripts/build-native.ts",
+		"dev:native": "bun scripts/build-native.ts --dev",
+		"embed:native": "bun scripts/embed-native.ts",
 		"check": "biome check . && tsgo -p tsconfig.json",
 		"fix": "biome check --write --unsafe .",
 		"test": "bun run build:native && bun test",
@@ -30,7 +32,7 @@
 		"directory": "packages/natives"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-utils": "9.6.4"
+		"@oh-my-pi/pi-utils": "9.8.0"
 	},
 	"devDependencies": {
 		"@types/node": "^25.0.10"

package/src/bindings.ts

@@ -0,0 +1,13 @@
+/**
+ * Base types for native bindings.
+ * Modules extend this interface via declaration merging.
+ */
+
+/** Callback type for threadsafe functions from N-API. */
+export type TsFunc<T> = (error: Error | null, value: T) => void;
+
+/**
+ * Native bindings interface.
+ * Extended by each module via declaration merging.
+ */
+export interface NativeBindings {}

package/src/clipboard/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Clipboard helpers backed by native arboard bindings.
+ */
+
+import { native } from "../native";
+
+export type { ClipboardImage } from "./types";
+
+export const { copyToClipboard, readImageFromClipboard } = native;

package/src/clipboard/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Types for clipboard operations.
+ */
+
+/** PNG-encoded clipboard image payload. */
+export interface ClipboardImage {
+	/** PNG image bytes. */
+	data: Uint8Array;
+	/** MIME type for the PNG payload. */
+	mimeType: string;
+}
+
+declare module "../bindings" {
+	/** Native clipboard operations exposed by the bindings layer. */
+	interface NativeBindings {
+		/**
+		 * Copy text to the system clipboard.
+		 * @param text - UTF-8 text to place on the clipboard.
+		 */
+		copyToClipboard(text: string): Promise<void>;
+		/**
+		 * Read an image from the clipboard.
+		 * @returns PNG payload or null when no image is available.
+		 */
+		readImageFromClipboard(): Promise<ClipboardImage | null>;
+	}
+}

package/src/embedded-addon.ts

@@ -0,0 +1,7 @@
+export interface EmbeddedAddon {
+	platform: string;
+	version: string;
+	filePath: string;
+}
+
+export const embeddedAddon: EmbeddedAddon | null = null;

package/src/find/index.ts

@@ -0,0 +1,35 @@
+/**
+ * File discovery API powered by globset + ignore crate.
+ */
+
+import * as path from "node:path";
+import { native } from "../native";
+import type { FindMatch, FindOptions, FindResult } from "./types";
+
+export type { FindMatch, FindOptions, FindResult } from "./types";
+
+/**
+ * Find files matching a glob pattern.
+ * Respects .gitignore by default.
+ */
+export async function find(options: FindOptions, onMatch?: (match: FindMatch) => void): Promise<FindResult> {
+	const searchPath = path.resolve(options.path);
+	const pattern = options.pattern || "*";
+
+	// Convert simple patterns to recursive globs if needed
+	const globPattern = pattern.includes("/") || pattern.startsWith("**") ? pattern : `**/${pattern}`;
+
+	// napi-rs ThreadsafeFunction passes (error, value) - skip callback on error
+	const cb = onMatch ? (err: Error | null, m: FindMatch) => !err && onMatch(m) : undefined;
+
+	return native.find(
+		{
+			...options,
+			path: searchPath,
+			pattern: globPattern,
+			hidden: options.hidden ?? false,
+			gitignore: options.gitignore ?? true,
+		},
+		cb,
+	);
+}

package/src/find/types.ts

@@ -2,30 +2,51 @@
  * Types for native find API.
  */
 
+import type { TsFunc } from "../bindings";
+
+/** Options for discovering files and directories. */
 export interface FindOptions {
-	/** Glob pattern to match (e.g., `*.ts`) */
+	/** Glob pattern to match (e.g., `*.ts`). */
 	pattern: string;
-	/** Directory to search */
+	/** Directory to search. */
 	path: string;
-	/** Filter by file type: "file", "dir", or "symlink" */
+	/** Filter by file type: "file", "dir", or "symlink". */
 	fileType?: "file" | "dir" | "symlink";
-	/** Include hidden files (default: false) */
+	/** Include hidden files (default: false). */
 	hidden?: boolean;
-	/** Maximum number of results */
+	/** Maximum number of results to return. */
 	maxResults?: number;
-	/** Respect .gitignore files (default: true) */
+	/** Respect .gitignore files (default: true). */
 	gitignore?: boolean;
-	/** Sort results by mtime (most recent first) before applying limit */
+	/** Sort results by mtime (most recent first) before applying limit. */
 	sortByMtime?: boolean;
 }
 
+/** A single filesystem match. */
 export interface FindMatch {
+	/** Relative path from the search root. */
 	path: string;
+	/** Resolved filesystem type for the match. */
 	fileType: "file" | "dir" | "symlink";
+	/** Modification time in milliseconds since epoch, if available. */
 	mtime?: number;
 }
 
+/** Result of a find operation. */
 export interface FindResult {
+	/** Matched filesystem entries. */
 	matches: FindMatch[];
+	/** Number of matches returned after limits are applied. */
 	totalMatches: number;
 }
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Find filesystem entries matching a glob pattern.
+		 * @param options Search options that control globbing and filters.
+		 * @param onMatch Optional callback for streaming matches as they are found.
+		 */
+		find(options: FindOptions, onMatch?: TsFunc<FindMatch>): Promise<FindResult>;
+	}
+}

package/src/grep/types.ts

@@ -1,3 +1,8 @@
+/**
+ * Types for grep/search operations.
+ */
+
+import type { TsFunc } from "../bindings";
 import type { RequestOptions } from "../request-options";
 
 /** Options for searching files. */
@@ -28,32 +33,51 @@ export interface GrepOptions extends RequestOptions {
 	mode?: "content" | "filesWithMatches" | "count";
 }
 
+/** A context line returned around a match. */
 export interface ContextLine {
+	/** 1-indexed line number. */
 	lineNumber: number;
+	/** Line content (trimmed line ending). */
 	line: string;
 }
 
+/** A single grep match or per-file count entry. */
 export interface GrepMatch {
+	/** File path for the match (relative for directory searches). */
 	path: string;
+	/** 1-indexed line number (0 for count-only entries). */
 	lineNumber: number;
+	/** Matched line content (empty for count-only entries). */
 	line: string;
+	/** Context lines before the match. */
 	contextBefore?: ContextLine[];
+	/** Context lines after the match. */
 	contextAfter?: ContextLine[];
+	/** Whether the line was truncated. */
 	truncated?: boolean;
+	/** Per-file match count (count mode only). */
 	matchCount?: number;
 }
 
+/** Summary stats for a grep run. */
 export interface GrepSummary {
+	/** Total matches across all files. */
 	totalMatches: number;
+	/** Number of files with at least one match. */
 	filesWithMatches: number;
+	/** Number of files searched. */
 	filesSearched: number;
+	/** Whether the limit/offset stopped the search early. */
 	limitReached?: boolean;
 }
 
+/** Full grep result including matches and summary counts. */
 export interface GrepResult extends GrepSummary {
+	/** Matches or per-file counts, depending on mode. */
 	matches: GrepMatch[];
 }
 
+/** Options for searching in-memory content. */
 export interface SearchOptions {
 	/** Regex pattern to search for */
 	pattern: string;
@@ -73,22 +97,35 @@ export interface SearchOptions {
 	mode?: "content" | "count";
 }
 
+/** A single content match. */
 export interface SearchMatch {
+	/** 1-indexed line number. */
 	lineNumber: number;
+	/** Matched line content. */
 	line: string;
+	/** Context lines before the match. */
 	contextBefore?: ContextLine[];
+	/** Context lines after the match. */
 	contextAfter?: ContextLine[];
+	/** Whether the line was truncated. */
 	truncated?: boolean;
 }
 
+/** Result of searching in-memory content. */
 export interface SearchResult {
+	/** All matches found. */
 	matches: SearchMatch[];
+	/** Total number of matches (may exceed `matches.length`). */
 	matchCount: number;
+	/** Whether the limit was reached. */
 	limitReached: boolean;
+	/** Error message, if any. */
 	error?: string;
 }
 
+/** Legacy alias for WASM match output. */
 export type WasmMatch = SearchMatch;
+/** Legacy alias for WASM search output. */
 export type WasmSearchResult = SearchResult;
 
 /** Options for fuzzy file path search. */
@@ -120,3 +157,21 @@ export interface FuzzyFindResult {
 	/** Total number of matches found (may exceed `matches.length`). */
 	totalMatches: number;
 }
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/** Fuzzy file path search for autocomplete. */
+		fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult>;
+		/** Search files for a regex pattern. */
+		grep(options: GrepOptions, onMatch?: TsFunc<GrepMatch>): Promise<GrepResult>;
+		/** Search in-memory content for a regex pattern. */
+		search(content: string | Uint8Array, options: SearchOptions): SearchResult;
+		/** Quick check if content matches a pattern. */
+		hasMatch(
+			content: string | Uint8Array,
+			pattern: string | Uint8Array,
+			ignoreCase: boolean,
+			multiline: boolean,
+		): boolean;
+	}
+}

package/src/highlight/index.ts

@@ -4,48 +4,6 @@
 
 import { native } from "../native";
 
-/**
- * Theme colors for syntax highlighting.
- * Each color should be an ANSI escape sequence (e.g., "\x1b[38;2;255;0;0m").
- */
-export interface HighlightColors {
-	comment: string;
-	keyword: string;
-	function: string;
-	variable: string;
-	string: string;
-	number: string;
-	type: string;
-	operator: string;
-	punctuation: string;
-	/** Color for diff inserted lines (+). Optional, defaults to no coloring. */
-	inserted?: string;
-	/** Color for diff deleted lines (-). Optional, defaults to no coloring. */
-	deleted?: string;
-}
-
-/**
- * Highlight code with syntax coloring.
- *
- * @param code - The source code to highlight
- * @param lang - Optional language identifier (e.g., "rust", "typescript", "python")
- * @param colors - Theme colors as ANSI escape sequences
- * @returns Highlighted code as a single string with ANSI color codes
- */
-export function highlightCode(code: string, lang: string | undefined, colors: HighlightColors): string {
-	return native.highlightCode(code, lang, colors);
-}
+export type { HighlightColors } from "./types";
 
-/**
- * Check if a language is supported for highlighting.
- */
-export function supportsLanguage(lang: string): boolean {
-	return native.supportsLanguage(lang);
-}
-
-/**
- * Get list of all supported languages.
- */
-export function getSupportedLanguages(): string[] {
-	return native.getSupportedLanguages();
-}
+export const { highlightCode, supportsLanguage, getSupportedLanguages } = native;

package/src/highlight/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for syntax highlighting.
+ */
+
+/**
+ * Theme colors for syntax highlighting.
+ * Each color should be an ANSI escape sequence (e.g., "\x1b[38;2;255;0;0m").
+ */
+export interface HighlightColors {
+	/** ANSI color for comments. */
+	comment: string;
+	/** ANSI color for keywords. */
+	keyword: string;
+	/** ANSI color for function names. */
+	function: string;
+	/** ANSI color for variables and identifiers. */
+	variable: string;
+	/** ANSI color for string literals. */
+	string: string;
+	/** ANSI color for numeric literals. */
+	number: string;
+	/** ANSI color for type identifiers. */
+	type: string;
+	/** ANSI color for operators. */
+	operator: string;
+	/** ANSI color for punctuation tokens. */
+	punctuation: string;
+	/** Color for diff inserted lines (+). */
+	inserted?: string;
+	/** Color for diff deleted lines (-). */
+	deleted?: string;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Highlight code with syntax coloring.
+		 * @param code Source code to highlight.
+		 * @param lang Language name, extension, or null for plain text.
+		 * @param colors ANSI color palette for semantic scopes.
+		 * @returns Highlighted code with ANSI color codes.
+		 */
+		highlightCode(code: string, lang: string | null | undefined, colors: HighlightColors): string;
+		/**
+		 * Check if a language is supported for highlighting.
+		 * @param lang Language name or extension to test.
+		 * @returns True when highlighting is available.
+		 */
+		supportsLanguage(lang: string): boolean;
+		/**
+		 * Get list of all supported languages.
+		 * @returns Syntect language names supported by the native highlighter.
+		 */
+		getSupportedLanguages(): string[];
+	}
+}

package/src/html/types.ts

@@ -2,9 +2,23 @@
  * Types for HTML to Markdown conversion.
  */
 
+/** Options controlling HTML preprocessing and output. */
 export interface HtmlToMarkdownOptions {
-	/** Remove navigation elements, forms, headers, footers */
+	/** Remove navigation elements, forms, headers, and footers. */
 	cleanContent?: boolean;
-	/** Skip images during conversion */
+	/** Skip images during conversion. */
 	skipImages?: boolean;
 }
+
+declare module "../bindings" {
+	/** Native HTML utilities exposed by the Rust bindings. */
+	interface NativeBindings {
+		/**
+		 * Convert HTML to Markdown.
+		 * @param html HTML source to convert.
+		 * @param options Optional conversion settings.
+		 * @returns Markdown output.
+		 */
+		htmlToMarkdown(html: string, options?: HtmlToMarkdownOptions | null): Promise<string>;
+	}
+}

package/src/image/index.ts

@@ -2,112 +2,12 @@
  * Image processing via native bindings.
  */
 
-import { type NativePhotonImage, native } from "../native";
+import { native } from "../native";
 
-const images = new Map<number, NativePhotonImage>();
-let nextHandle = 1;
+export { ImageFormat, type PhotonImageConstructor, SamplingFilter } from "./types";
 
-function registerImage(image: NativePhotonImage): number {
-	const handle = nextHandle++;
-	images.set(handle, image);
-	return handle;
-}
+/** PhotonImage class for image manipulation. Use PhotonImage.parse() to create instances. */
+export const PhotonImage = native.PhotonImage;
 
-function getImage(handle: number): NativePhotonImage {
-	const image = images.get(handle);
-	if (!image) {
-		throw new Error("Image already freed");
-	}
-	return image;
-}
-
-export const SamplingFilter = native.SamplingFilter;
-export type SamplingFilter = (typeof SamplingFilter)[keyof typeof SamplingFilter];
-
-/**
- * Image handle for async operations.
- */
-export class PhotonImage {
-	#handle: number;
-	#freed = false;
-
-	private constructor(handle: number) {
-		this.#handle = handle;
-	}
-
-	/** @internal */
-	static _create(handle: number): PhotonImage {
-		if (!images.has(handle)) {
-			throw new Error("Invalid image handle");
-		}
-		return new PhotonImage(handle);
-	}
-
-	/**
-	 * Load an image from encoded bytes (PNG, JPEG, WebP, GIF).
-	 */
-	static async new_from_byteslice(bytes: Uint8Array): Promise<PhotonImage> {
-		const image = await native.PhotonImage.newFromByteslice(bytes);
-		const handle = registerImage(image);
-		return new PhotonImage(handle);
-	}
-
-	/** @internal */
-	_getHandle(): number {
-		if (this.#freed) throw new Error("Image already freed");
-		return this.#handle;
-	}
-
-	#native(): NativePhotonImage {
-		if (this.#freed) throw new Error("Image already freed");
-		return getImage(this.#handle);
-	}
-
-	/** Get image width in pixels. */
-	get_width(): number {
-		return this.#native().getWidth();
-	}
-
-	/** Get image height in pixels. */
-	get_height(): number {
-		return this.#native().getHeight();
-	}
-
-	/** Export as PNG bytes. */
-	async get_bytes(): Promise<Uint8Array> {
-		return this.#native().getBytes();
-	}
-
-	/** Export as JPEG bytes with specified quality (0-100). */
-	async get_bytes_jpeg(quality: number): Promise<Uint8Array> {
-		return this.#native().getBytesJpeg(quality);
-	}
-
-	/** Release native resources. */
-	free() {
-		if (this.#freed) return;
-		this.#freed = true;
-		images.delete(this.#handle);
-	}
-
-	/** Alias for free() to support using-declarations. */
-	[Symbol.dispose](): void {
-		this.free();
-	}
-}
-
-/**
- * Resize an image to the specified dimensions.
- * Returns a new PhotonImage (original is not modified).
- */
-export async function resize(image: PhotonImage, width: number, height: number, filter: number): Promise<PhotonImage> {
-	const nativeImage = getImage(image._getHandle());
-	const resized = await nativeImage.resize(width, height, filter);
-	const handle = registerImage(resized);
-	return PhotonImage._create(handle);
-}
-
-/**
- * Terminate image resources (no-op for native bindings).
- */
-export function terminate(): void {}
+/** PhotonImage instance type. */
+export type PhotonImage = import("./types").PhotonImage;

package/src/image/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Types for image processing.
+ */
+
+/** Output format for image encoding. */
+export const enum ImageFormat {
+	/** PNG encoded bytes. */
+	PNG = 0,
+	/** JPEG encoded bytes. */
+	JPEG = 1,
+	/** WebP encoded bytes. */
+	WEBP = 2,
+	/** GIF encoded bytes. */
+	GIF = 3,
+}
+
+/** Sampling filter for resize operations. */
+export const enum SamplingFilter {
+	/** Nearest-neighbor sampling (fast, low quality). */
+	Nearest = 1,
+	/** Triangle filter (linear interpolation). */
+	Triangle = 2,
+	/** Catmull-Rom filter with sharper edges. */
+	CatmullRom = 3,
+	/** Gaussian filter for smoother results. */
+	Gaussian = 4,
+	/** Lanczos3 filter for high-quality downscaling. */
+	Lanczos3 = 5,
+}
+
+/** Image container for native image operations. */
+export interface PhotonImage {
+	/** Image width in pixels. */
+	get width(): number;
+	/** Image height in pixels. */
+	get height(): number;
+	/**
+	 * Encode the image using the requested format and quality.
+	 * Returns the encoded image bytes.
+	 */
+	encode(format: ImageFormat, quality: number): Promise<Uint8Array>;
+	/**
+	 * Resize the image to the requested dimensions with the filter.
+	 * Returns a new image instance.
+	 */
+	resize(width: number, height: number, filter: SamplingFilter): Promise<PhotonImage>;
+}
+
+/** Static entrypoints for creating `PhotonImage` instances. */
+export interface PhotonImageConstructor {
+	/** Parse image bytes (PNG, JPEG, WebP, GIF) into a native image. */
+	parse(bytes: Uint8Array): Promise<PhotonImage>;
+	/** Instance prototype reference. */
+	prototype: PhotonImage;
+}
+
+declare module "../bindings" {
+	/** Native bindings for image operations. */
+	interface NativeBindings {
+		/** Sampling filters exposed by the native module. */
+		SamplingFilter: typeof SamplingFilter;
+		/** Photon image constructor exposed by the native module. */
+		PhotonImage: PhotonImageConstructor;
+	}
+}