Natives Binding Contract (TypeScript Side)

This document defines the TypeScript-side contract that sits between @oh-my-pi/pi-natives callers and the loaded N-API addon.

It focuses on three pieces:

contract shape (NativeBindings + module augmentation),
wrapper behavior (src/<module>/index.ts),
public export surface (src/index.ts).

Implementation files

packages/natives/src/bindings.ts
packages/natives/src/native.ts
packages/natives/src/index.ts
packages/natives/src/clipboard/types.ts
packages/natives/src/clipboard/index.ts
packages/natives/src/glob/types.ts
packages/natives/src/glob/index.ts
packages/natives/src/grep/types.ts
packages/natives/src/grep/index.ts
packages/natives/src/highlight/types.ts
packages/natives/src/highlight/index.ts
packages/natives/src/html/types.ts
packages/natives/src/html/index.ts
packages/natives/src/image/types.ts
packages/natives/src/image/index.ts
packages/natives/src/keys/types.ts
packages/natives/src/keys/index.ts
packages/natives/src/ps/types.ts
packages/natives/src/ps/index.ts
packages/natives/src/pty/types.ts
packages/natives/src/pty/index.ts
packages/natives/src/shell/types.ts
packages/natives/src/shell/index.ts
packages/natives/src/system-info/types.ts
packages/natives/src/system-info/index.ts
packages/natives/src/text/types.ts
packages/natives/src/text/index.ts
packages/natives/src/work/types.ts
packages/natives/src/work/index.ts

Contract model

packages/natives/src/bindings.ts defines the base contract:

NativeBindings (base interface, currently includes cancelWork(id: number): void)
Cancellable (timeoutMs?: number, signal?: AbortSignal)
TsFunc<T> callback shape used by N-API threadsafe callbacks

Each module adds its own fields by declaration merging:

// packages/natives/src/<module>/types.ts
declare module "../bindings" {
	interface NativeBindings {
		grep(options: GrepOptions, onMatch?: TsFunc<GrepMatch>): Promise<GrepResult>;
	}
}

This keeps one aggregate binding interface without a monolithic central type file.

Declaration-merging lifecycle and state transitions

1) Compile-time type assembly

bindings.ts provides the base NativeBindings symbol.
Every src/<module>/types.ts augments NativeBindings.
src/native.ts imports all ./<module>/types files for side effects so the merged contract is in scope where NativeBindings is used.

State transition: Base contract → Merged contract.

2) Runtime addon load and validation gate

src/native.ts loads candidate .node binaries.
Loaded object is treated as NativeBindings and immediately passed through validateNative(...).
validateNative verifies required export keys by typeof bindings[name] === "function".

State transition: Untrusted addon object → Validated native binding object (or hard failure).

3) Wrapper invocation

Module wrappers in src/<module>/index.ts call native.<export>.
Wrappers adapt defaults and callback shape ((err, value) to value-only callback patterns in JS APIs).
src/index.ts re-exports module wrappers/types as the public package API.

State transition: Validated raw bindings → Ergonomic public API.

Wrapper responsibilities

Wrappers are intentionally thin; they do not re-implement native logic.

Primary responsibilities:

Argument normalization/defaulting
- glob() resolves options.path to absolute path and defaults hidden, gitignore, recursive.
- hasMatch() fills default flags (ignoreCase, multiline) before native call.
Callback adaptation
- grep(), glob(), executeShell() convert TsFunc<T> (error, value) into user callback receiving only successful values.
Environment or policy behavior around native calls
- Clipboard wrapper adds OSC52/Termux/headless handling and treats copy as best effort.
Public naming and re-export curation
- searchContent() maps to native export search.

Public export surface organization

packages/natives/src/index.ts is the canonical public barrel. It groups exports by capability domain:

Search/text: grep, glob, text, highlight
Execution/process/terminal: shell, pty, ps, keys
System/media/conversion: image, html, clipboard, system-info, work

Maintainer rule: if a wrapper is not re-exported from src/index.ts, it is not part of the intended public package surface.

JS API ↔ native export mapping (representative)

The Rust side uses N-API export names (typically via #[napi(js_name = ...)]) that must match these binding keys.

Category	Public JS API (wrapper)	Native binding key	Return type	Async?
Grep	`grep(options, onMatch?)`	`grep`	`Promise<GrepResult>`	Yes
Grep	`searchContent(content, options)`	`search`	`SearchResult`	No
Grep	`hasMatch(content, pattern, opts?)`	`hasMatch`	`boolean`	No
Grep	`fuzzyFind(options)`	`fuzzyFind`	`Promise<FuzzyFindResult>`	Yes
Glob	`glob(options, onMatch?)`	`glob`	`Promise<GlobResult>`	Yes
Glob	`invalidateFsScanCache(path?)`	`invalidateFsScanCache`	`void`	No
Shell	`executeShell(options, onChunk?)`	`executeShell`	`Promise<ShellExecuteResult>`	Yes
Shell	`Shell`	`Shell`	class constructor	N/A
PTY	`PtySession`	`PtySession`	class constructor	N/A
Text	`truncateToWidth(...)`	`truncateToWidth`	`string`	No
Text	`sliceWithWidth(...)`	`sliceWithWidth`	`SliceWithWidthResult`	No
Text	`visibleWidth(text)`	`visibleWidth`	`number`	No
Highlight	`highlightCode(code, lang, colors)`	`highlightCode`	`string`	No
HTML	`htmlToMarkdown(html, options?)`	`htmlToMarkdown`	`Promise<string>`	Yes
System	`getSystemInfo()`	`getSystemInfo`	`SystemInfo`	No
Work	`getWorkProfile(lastSeconds)`	`getWorkProfile`	`WorkProfile`	No
Process	`killTree(pid, signal)`	`killTree`	`number`	No
Process	`listDescendants(pid)`	`listDescendants`	`number[]`	No
Clipboard	`copyToClipboard(text)`	`copyToClipboard`	`Promise<void>` (best effort wrapper behavior)	Yes
Clipboard	`readImageFromClipboard()`	`readImageFromClipboard`	`Promise<ClipboardImage \| null>`	Yes
Keys	`parseKey(data, kittyProtocolActive)`	`parseKey`	`string \| null`	No

Sync vs async contract differences

The contract mixes sync and async APIs; wrappers preserve native call style rather than forcing one model:

Promise-based async exports for I/O or long-running work (grep, glob, htmlToMarkdown, executeShell, clipboard, image operations).
Synchronous exports for deterministic in-memory transforms/parsers (search, hasMatch, highlighting, text width/slicing, key parsing, process queries).
Constructor exports for stateful runtime objects (Shell, PtySession, PhotonImage).

Implication for maintainers: changing sync ↔ async for an existing export is a breaking API and contract change across wrappers and callers.

Object and enum typing patterns

Object patterns (`#[napi(object)]`-style JS objects)

TS models object-shaped native values as interfaces, for example:

GrepResult, SearchResult, GlobResult
SystemInfo, WorkProfile
ClipboardImage, ParsedKittyResult

These are structural contracts at compile time; runtime shape correctness is owned by native implementation.

Enum patterns

Numeric native enums are represented as const enum values in TS:

FileType (1=file, 2=dir, 3=symlink)
ImageFormat (0=PNG, 1=JPEG, 2=WEBP, 3=GIF)
SamplingFilter, Ellipsis, KeyEventType

Callers see named enum members; the binding boundary passes numbers.

How mismatches are caught

Mismatch detection happens at two layers:

Compile-time TypeScript contract checks
- Wrappers call native.<name> against merged NativeBindings.
- Missing/renamed binding keys break TS type-checking in wrappers.
Runtime validation in validateNative
- After load, native.ts checks required exports and throws if any are missing.
- Error message includes missing keys and rebuild instruction.

This catches the common stale-binary drift: wrapper/type exists but loaded .node lacks the export.

Failure behavior and caveats

Load/validation failures (hard failures)

Addon load failure or unsupported platform throws during module init in native.ts.
Missing required exports throws before wrappers are usable.

Effect: package fails fast rather than deferring failure to first call.

Wrapper-level behavior differences

Some wrappers intentionally soften failures (copyToClipboard is best effort and swallows native failure).
Streaming callbacks ignore callback error payloads and only forward successful value events.

Type-level caveats (runtime stricter than TS)

TS optional fields do not guarantee semantic validity; native layer can still reject malformed values.
const enum typing does not prevent out-of-range numeric values from untyped callers at runtime.
validateNative checks only presence/function-ness of required exports, not deep argument/return-shape compatibility.
bindings.ts includes cancelWork(id) in the base interface, but current runtime validation list does not enforce that key.

Maintainer checklist for binding changes

When adding/changing an export, update all of:

src/<module>/types.ts (augmentation + contract types)
src/<module>/index.ts (wrapper behavior)
src/native.ts imports for the module types (if new module)
validateNative required export checks
src/index.ts public re-exports

Skipping any step creates either compile-time drift or runtime load-time failure.

Natives Binding Contract (TypeScript Side) ​

Implementation files ​

Contract model ​

Declaration-merging lifecycle and state transitions ​

1) Compile-time type assembly ​

2) Runtime addon load and validation gate ​

3) Wrapper invocation ​

Wrapper responsibilities ​

Public export surface organization ​

JS API ↔ native export mapping (representative) ​

Sync vs async contract differences ​

Object and enum typing patterns ​

Object patterns (#[napi(object)]-style JS objects) ​

Enum patterns ​

How mismatches are caught ​

Failure behavior and caveats ​

Load/validation failures (hard failures) ​

Wrapper-level behavior differences ​

Type-level caveats (runtime stricter than TS) ​

Maintainer checklist for binding changes ​