Native runtime architecture

The public TypeScript layer owns ergonomic types and fallbacks. The loader selects a platform-specific addon, validates its exports, and exposes Rust Node-application programming interface (API) implementations for performance-sensitive work.

How is an addon selected and validated?

Resolution considers operating system, CPU architecture, and supported hardware variants before trying packaged and extracted binary candidates. Embedded binaries are materialized in a controlled cache. validateNative checks the runtime surface so a mismatched binary fails near loading instead of at an unrelated call.

How do I keep bindings synchronized?

Module augmentation describes native exports to TypeScript, wrappers translate public inputs and outputs, and Rust functions implement the Node-API boundary. Synchronous and asynchronous variants must agree on names, data conversions, error shapes, and cancellation. Update all three layers and their contract tests together.

Which subsystems does the addon cover?

The addon covers terminal and pseudo-terminal (PTY) processes, filesystem scanning and text search, media/system utilities, and cancellable task primitives. Data crossing Node-API must have an explicit encoding and ownership rule; native tasks must release resources on both completion and cancellation.

PowerAssertion.start(options?) returns an idempotently stoppable session handle. Its PowerAssertionOptions fields are reason, idle, display, system, and user; an omitted set of mode flags defaults to idle-sleep prevention. The implementation uses IOKit on macOS, login1 and best-effort ScreenSaver inhibition on Linux, and a dedicated execution-state thread on Windows.

Read packages/natives for the TypeScript wrappers and loader, and crates/pi-natives/src for the Rust implementations.

Addon selection is a trust boundary: the loader accepts only a candidate for the current operating system, architecture, and declared variant, then validates the complete export surface. A missing or mismatched export is a startup error, not permission to mix binaries from another build. For diagnosis, record the selected candidate and host tuple, rebuild with bun scripts/ensure-dev-native.ts, and repeat the validation in a new process.