@native-dom/native-core

Rust native DOM storage, parsing, serialization, selector, and mutation bindings for native-dom.

This package is the N-API boundary used by @native-dom/runtime. It is not intended to expose a complete browser DOM directly to application code; it exposes compact native operations that the TypeScript runtime wraps into browser-compatible objects.

Responsibilities

• Arena-style DocumentStore with generational NodeId values.
• Parent, child, and sibling links for DOM tree traversal.
• Element attributes, text, comments, document fragments, document types, and template content.
• HTML document and fragment parsing through html5ever.
• Serialization for node HTML, children HTML, and text content.
• Selector parsing, query, matches(), and closest() support for the runtime.
• Id, class, and tag indexes used by lookup and query fast paths.
• N-API class NativeDocument and parseHtmlDocumentNative().

Public Binding Shape

import { parseHtmlDocumentNative } from "@native-dom/native-core";

const document = parseHtmlDocumentNative("<main id='app'>Hello</main>");
const app = document.elementById(document.body(), "app");

console.log(app == null ? null : document.textContent(app));

Most consumers should use @native-dom/runtime instead of calling these bindings directly.

Development

pnpm --filter @native-dom/native-core build:native:debug
pnpm --filter @native-dom/native-core build:native
pnpm --filter @native-dom/native-core test
pnpm --filter @native-dom/native-core typecheck
pnpm --filter @native-dom/native-core test:binding

Useful lower-level commands:

cargo test -p native_dom_native_core
cargo fmt --all -- --check

Packaging

This package is built with napi-rs.

The root package ships:

• index.js, the generated CommonJS loader.
• index.d.ts, the generated TypeScript declarations.
• Optional platform packages generated under npm/*.

Supported prebuilt targets:

• aarch64-apple-darwin
• x86_64-apple-darwin
• x86_64-pc-windows-msvc
• aarch64-pc-windows-msvc
• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu
• aarch64-unknown-linux-musl

Generated platform package directories can be refreshed with:

pnpm --filter @native-dom/native-core create-npm-dirs

Move built artifacts into those package directories with:

pnpm --filter @native-dom/native-core artifacts

Release

Native core uses the repository's unified release stream. Normal releases are cut from the repository root with:

pnpm release

The command prompts for the next version, updates native-core and JS package metadata together, runs napi version --npm-dir npm to sync generated platform package versions, runs cargo check -p native_dom_native_core to refresh Cargo.lock, commits as release: native-dom v<version>, and creates both native-core-v<version> and packages-v<version> tags on the same commit.

Run the normal release gate before releasing:

pnpm release:unified:check

The release:native-core script remains available for recovery-only native releases. The Native Core GitHub Actions workflow runs a single-platform check on pull requests and main. The full target matrix runs only for native-core-v<version> tags or manual workflow dispatch, then runs smoke checks on representative platforms and Node versions, moves artifacts into the generated platform packages, and publishes @native-dom/native-core plus the optional platform packages to npm.

Publishing uses npm trusted publishing with GitHub Actions OIDC. The publish job uses the GitHub-hosted native-core.yml workflow, id-token: write, Node 24, and npm ^11.5.1; it does not require an npm automation token.

Before the first release, configure a GitHub Actions trusted publisher on npm for every package that the napi release publishes. For the current package metadata, use:

npm trust github @native-dom/native-core --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-darwin-arm64 --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-darwin-x64 --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-linux-arm64-gnu --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-linux-arm64-musl --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-linux-x64-gnu --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-linux-x64-musl --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-win32-arm64-msvc --repo Dunqing/native-dom --file native-core.yml --yes
npm trust github @native-dom/native-core-win32-x64-msvc --repo Dunqing/native-dom --file native-core.yml --yes

The --repo value must exactly match the GitHub repository in each package's repository.url. If the project is published from a different GitHub repository, update the package metadata and trusted publisher entries together.

After the trusted publishers are verified, set npm package publishing access to require 2FA and disallow tokens, then revoke any old automation token.