@reference-ui/rust

Rust-backed native tooling for reference-ui. This package ships a Node-API (N-API) native addon built with napi-rs plus TypeScript in js/ that loads the .node binary and provides higher-level APIs on top of those low-level bindings.

What lives here

| Piece | Role | | --- | --- | | Rust crate (reference-virtual-native) | Workspace features implemented in Rust (parsers, transforms, emitters). Built as a cdylib for Node and as rlib for tests and embedding. | | napi-rs | Binds selected Rust entrypoints to JavaScript via #[napi] on src/lib.rs (see What napi-rs does here). | | TypeScript (js/) | Loads the .node addon, wraps it with ergonomic/higher-level APIs (runtimes, builders, helpers), and ships bundled ESM/DTS per public subpath (tsup → dist/). |

New capabilities will typically add a src/<module>/ tree (and often a matching js/<module>/ surface) and extend lib.rs, package.json exports, and tsup.config.ts as needed.

Documentation

Feature-specific docs live under docs/ (e.g. Tasty: tasty-rs.md, tasty-js.md).

How it is bootstrapped

1. Install dependencies from the repo root (this package is part of the workspace).

2. Build the native addon so the .node binary exists for your platform:

   pnpm --filter @reference-ui/rust run build

   or only ensure the binary is present:

   pnpm --filter @reference-ui/rust run ensure-native

3. Run tests (Rust + Vitest):

   pnpm --filter @reference-ui/rust run test

package.json declares napi-rs targets (e.g. aarch64-apple-darwin, x86_64-unknown-linux-gnu). The compiled artifact is named virtual-native and is loaded from native/virtual-native.<triple>.node (see js/runtime/loader.ts).

What napi-rs does here

napi-rs generates Node-API bindings from Rust:

• #[napi] exports in src/lib.rs are included when the napi Cargo feature is enabled (it is on by default).
• build.rs calls napi_build::setup() when CARGO_FEATURE_NAPI is set so the linker produces a loadable addon.

From JavaScript, js/runtime/loader.ts resolves the package directory, finds the correct .node file for the current OS/arch, and require()s it (VirtualNativeBinding). Feature code in js/ then builds on that — thin direct exports in js/runtime/index.ts, richer layers under paths like js/tasty/.

Package entrypoints

Exports are defined in package.json and built from tsup.config.ts.

| Subpath | Role | | --- | --- | | @reference-ui/rust | Native addon: rewrites, scanners, and other functions exposed from lib.rs; loader helpers. | | @reference-ui/rust/tasty | Tasty runtime (TypeScript). | | @reference-ui/rust/tasty/browser | Tasty browser-oriented entry. | | @reference-ui/rust/tasty/build | Tasty build helpers (emit + filesystem). | | @reference-ui/rust/styletrace | Styletrace wrapper analysis for discovering exported JSX names linked to Reference primitives through style props. |

Additional exports entries will appear as new modules ship.

Layout

• src/lib.rs — N-API exports and crate re-exports.
• src/<module>/ — per-feature Rust code (e.g. tasty/, virtualrs/).
• js/<module>/ — per-feature TypeScript: wrappers and higher-level APIs over the native addon where applicable.

For details on a given feature, see docs/ or the module’s own notes under src/.