@zhuxe-js/native 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @zhuxe-js/native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional native accelerators for [`zhuxe-assistance`](https://www.npmjs.com/package/zhuxe-assistance). Moves the crypto hot path off pure JavaScript and onto a compiled backend, with transparent fallback so the client works everywhere regardless of what's installed.
+
+## How it works
+
+The same Rust core is shipped two ways, selected at load time. Callers never
+change – the client resolves the fastest available backend and degrades
+gracefully:
+
+| Backend  | What it is                               | Requires                              |
+| -------- | ---------------------------------------- | ------------------------------------- |
+| **napi** | Compiled Rust addon (fastest)            | Building from source (Rust toolchain) |
+| **wasm** | WebAssembly build of the same Rust core  | Nothing – ships inside this package   |
+| **js**   | Pure-JS / `node:crypto` (no accelerator) | Nothing – built into `zhuxe-assistance`        |
+
+If the native addon can't load, the WASM fallback is used; if that's disabled,
+the pure-JS path in `zhuxe-assistance` takes over. Installing this package is always
+safe: a missing or unsupported binary never breaks the client.
+
+## Install
+
+```bash
+npm install @zhuxe-js/native
+```
+
+The published package currently ships the WASM backend only – it works on any
+OS/arch with no toolchain. Prebuilt NAPI binaries are not on npm yet; to use
+the (faster) native addon, build it from source inside a repo checkout with a
+Rust toolchain installed:
+
+```bash
+npm run build:napi -w packages/native
+```
+
+## Backend selection
+
+The default (`auto`) tries the NAPI addon first, then the WASM build, then
+the pure-JS path. To pin a single backend, set `ZHUXE_NATIVE_BACKEND` before
+the process starts:
+
+```bash
+ZHUXE_NATIVE_BACKEND=napi   # only the native addon
+ZHUXE_NATIVE_BACKEND=wasm   # only the WebAssembly build
+ZHUXE_NATIVE_BACKEND=js     # disable the accelerator, use the pure-JS path
+```
+
+A pinned backend that is unavailable does not error – the client silently
+falls back to the pure-JS path.
+
+## One WASM artifact, Node and browser
+
+The WASM backend is a single `--target web` build under `wasm/pkg/` – the
+same artifact serves both environments:
+
+- **Node**: `zhuxe-assistance` loads it automatically (the glue is ESM, loaded via
+  `require(esm)` and initialised synchronously with the bundled `.wasm`
+  bytes). This needs Node 20.19+ / 22.12+; on older runtimes the client
+  silently falls back to the pure-JS path.
+- **Browser / bundler**: import it directly and initialise before use:
+
+```js
+import init, {
+    x25519ScalarMult,
+    xeddsaSign,
+    xeddsaVerify
+} from '@zhuxe-js/native/wasm/pkg/zhuxe_native_wasm.js'
+
+await init()
+const shared = x25519ScalarMult(privateKey, publicKey)
+```
+
+## Notes
+
+- **Optional by design.** The accelerator is a performance layer, not a
+  correctness dependency – outputs are byte-identical across all three
+  backends (verified by the cross-check tests).
+- **ABI-stable binaries.** The native addon is built with N-API, so one binary
+  per platform works across every supported Node version – no rebuild on Node
+  upgrades.
+- **WASM runs anywhere.** The bundled WebAssembly fallback runs on any platform
+  the native addon doesn't cover.
+- **The root import is the NAPI addon.** `require('@zhuxe-js/native')` resolves
+  to the compiled addon, so on the published wasm-only package it throws a
+  module-not-found error – that failure is exactly what makes `zhuxe-assistance` fall
+  through to the WASM build. To use the primitives directly, import the
+  `wasm/pkg` subpath shown above.
+
+See the main [`zhuxe-assistance`](../../README.md) docs for the client contract.

package/package.json

@@ -1,6 +1,65 @@
 {
-  "name": "@zhuxe-js/native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zhuxe-js/native",
+    "version": "0.1.0",
+    "description": "Native accelerators for zhuxe-assistance (Rust NAPI addon + WASM fallback)",
+    "license": "MIT",
+    "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/abay62096-dotcom/zhuxe.git",
+        "directory": "packages/native"
+    },
+    "keywords": [
+        "zhuxe",
+        "napi",
+        "wasm",
+        "x25519",
+        "xeddsa",
+        "curve25519",
+        "crypto"
+    ],
+    "types": "binding.d.ts",
+    "exports": {
+        ".": {
+            "types": "./binding.d.ts",
+            "default": "./binding.js"
+        },
+        "./wasm/*": "./wasm/*"
+    },
+    "files": [
+        "wasm/pkg"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "zhuxe-assistance": "^1.7.0"
+    },
+    "peerDependenciesMeta": {
+        "zhuxe-assistance": {
+            "optional": true
+        }
+    },
+    "engines": {
+        "node": ">=20.19.0"
+    },
+    "napi": {
+        "binaryName": "zhuxe-native",
+        "targets": [
+            "x86_64-pc-windows-msvc",
+            "x86_64-unknown-linux-gnu",
+            "x86_64-unknown-linux-musl",
+            "aarch64-unknown-linux-gnu",
+            "aarch64-apple-darwin",
+            "x86_64-apple-darwin"
+        ]
+    },
+    "scripts": {
+        "build:napi": "napi build --platform --release --js binding.js --dts binding.d.ts",
+        "build:napi:debug": "napi build --platform --js binding.js --dts binding.d.ts",
+        "build:wasm": "cargo build -p zhuxe-native-wasm --release --target wasm32-unknown-unknown --target-dir target && wasm-bindgen --target web --out-dir wasm/pkg target/wasm32-unknown-unknown/release/zhuxe_native_wasm.wasm && node -e \"require('node:fs').writeFileSync('wasm/pkg/package.json', JSON.stringify({ type: 'module' }) + '\\n')\""
+    },
+    "devDependencies": {
+        "@napi-rs/cli": "^3.0.0"
+    }
+}