@node-webrtc-rust/bindings 0.1.5 → 0.2.1

package/README.md

@@ -50,15 +50,62 @@ This produces a `node-webrtc-rust.<platform>.node` file in the current directory
 
 Set `WEBRTC_DEBUG=1` (or pass `debug: true` in `JsRTCConfiguration`) to emit `[webrtc-debug]` lines from native bindings and the Rust core. See the root README for details.
 
-## How it works
+## How native loading works
 
-The `index.js` loader resolves the native binding in this order:
+The root `@node-webrtc-rust/bindings` package ships **no binary** — only `index.js`, `index.d.ts`, and loader logic. The compiled addon lives in separate platform packages listed as **`optionalDependencies`**.
 
-1. Try requiring the platform-specific npm package (e.g., `@node-webrtc-rust/bindings-darwin-arm64`)
-2. Try loading a local `.node` file matching the current platform (dev builds)
-3. Try loading `node-webrtc-rust.node` (generic local build)
+### At `npm install`
 
-If none succeed, an error is thrown with instructions.
+The matching platform package is **installed during `npm install`**, not downloaded when your app first runs. Runtime `require()` only loads what is already in `node_modules`.
+
+When you install `@node-webrtc-rust/bindings`, npm:
+
+1. Installs the root package (loader only — no `.node`).
+2. **Attempts each `optionalDependency`** (e.g. `bindings-darwin-arm64`, `bindings-linux-x64-gnu`, …).
+3. Keeps only packages whose `"os"` / `"cpu"` fields match your machine; others are skipped.
+4. Does **not** fail the install if a non-matching or unavailable optional package is skipped — that is what “optional” means.
+
+On macOS arm64 you typically get:
+
+```text
+node_modules/@node-webrtc-rust/bindings/          ← loader (index.js)
+node_modules/@node-webrtc-rust/bindings-darwin-arm64/
+  node-webrtc-rust.darwin-arm64.node              ← actual native addon
+```
+
+Each platform package is a thin wrapper: its `"main"` field points directly at the `.node` file, so `require('@node-webrtc-rust/bindings-darwin-arm64')` loads the native module.
+
+**When the binary might be missing after install:**
+
+| Situation | Result |
+| --- | --- |
+| Normal install on a supported platform | Matching optional package is present |
+| `npm install --omit=optional` | No platform package — runtime fails unless a local `.node` exists |
+| Unsupported OS/arch | No matching optional package |
+| Publish/version mismatch for the optional pkg | Install may succeed; `require()` fails at runtime |
+
+### At runtime (`require('@node-webrtc-rust/bindings')`)
+
+`index.js` (auto-generated by NAPI-RS) picks the binary for the current process:
+
+1. **Detect platform** — `process.platform`, `process.arch`, and on Linux whether the libc is musl or glibc (`isMusl()`).
+2. **Local dev fallback** — if `node-webrtc-rust.<platform>.node` sits next to `index.js` (from `npm run build:local`), `require` that file directly.
+3. **Published path** — otherwise `require` the matching optional package (e.g. `@node-webrtc-rust/bindings-linux-x64-gnu`).
+4. **Re-export** — bind NAPI exports (`JsPeerConnection`, `JsConferenceRoom`, …) onto `module.exports`.
+
+If both paths fail, Node throws with the underlying `loadError`.
+
+```mermaid
+flowchart TD
+  A["require('@node-webrtc-rust/bindings')"] --> B[index.js]
+  B --> C{platform + arch + libc?}
+  C --> D{local .node beside index.js?}
+  D -->|yes| E["require('./node-webrtc-rust.*.node')"]
+  D -->|no| F["require('@node-webrtc-rust/bindings-…')"]
+  F --> G["platform pkg main → *.node"]
+  E --> H[Re-export NAPI symbols]
+  G --> H
+```
 
 ### TypeScript note
 

package/index.d.ts

@@ -172,7 +172,7 @@ export declare class JsLocalAudioTrack {
   get streamId(): string
   get enabled(): boolean
   set enabled(enabled: boolean)
-  /** Writes a PCM audio frame to the track. */
+  /** Writes interleaved stereo PCM; encoded to the negotiated RTP codec before send. */
   writeSample(data: Buffer, durationMs: number): Promise<void>
 }
 /** WebRTC peer connection exposed to JavaScript. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-webrtc-rust/bindings",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "NAPI-RS native bindings for node-webrtc-rust — WebRTC peer connections, data channels, and conference audio mixing",
   "keywords": [
     "webrtc",
@@ -58,13 +58,12 @@
     "@napi-rs/cli": "^2.18.0"
   },
   "optionalDependencies": {
-    "@node-webrtc-rust/bindings-win32-x64-msvc": "0.1.5",
-    "@node-webrtc-rust/bindings-darwin-x64": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-x64-gnu": "0.1.5",
-    "@node-webrtc-rust/bindings-darwin-arm64": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-arm64-gnu": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-arm64-musl": "0.1.4",
-    "@node-webrtc-rust/bindings-linux-x64-musl": "0.1.5"
+    "@node-webrtc-rust/bindings-darwin-arm64": "0.2.1",
+    "@node-webrtc-rust/bindings-darwin-x64": "0.2.1",
+    "@node-webrtc-rust/bindings-linux-arm64-gnu": "0.2.1",
+    "@node-webrtc-rust/bindings-linux-x64-gnu": "0.2.1",
+    "@node-webrtc-rust/bindings-linux-x64-musl": "0.2.1",
+    "@node-webrtc-rust/bindings-win32-x64-msvc": "0.2.1"
   },
   "engines": {
     "node": ">=18"