@xingwangzhe/force-rs 0.1.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-2026 王兴家 (Xingwangzhe)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+[English](./README.md) | [中文](./README_CN.md)
+
+# @xingwangzhe/force-rs
+
+Fast force-directed 3D graph layout powered by **Rust + Barnes-Hut octree**, designed as a build-time replacement for `d3-force-3d`.
+
+### Why this exists
+
+`d3-force-3d` is excellent for interactive visualizations, but at build time (SSG/SSR) with 47K+ nodes and 89K+ edges, the JS runtime becomes a bottleneck — hundreds of ticks at ~1s each is too slow. `force-rs` implements the **exact same force model** in Rust, achieving **~0.01s/tick** on 16 cores.
+
+### Force model (fully d3-force compatible)
+
+| Force          | Implementation                                           |
+|----------------|----------------------------------------------------------|
+| Many-body repulsion | Barnes-Hut octree, O(n log n), with `√(4/k)` correction |
+| Link (spring)  | Degree-biased strength: `1/min(deg, deg)`, bias = other's degree ratio |
+| Center (translational) | Shift centroid toward origin (same as d3-force `forceCenter`) |
+| Distance softening | Smooth `√(d_min² × d²)` below 1.0 (same as d3-force) |
+
+### Other features
+
+- **16-core** parallel via [Rayon](https://github.com/rayon-rs/rayon) — auto-fallback to sequential on single-core
+- **Compatible state format**: `[x, y, z, vx, vy, vz, ...alpha]` — same as d3-force
+- Built with [NAPI-RS](https://napi.rs/) for zero-copy Node.js interop
+
+## Installation
+
+```bash
+npm install @xingwangzhe/force-rs
+```
+
+## API
+
+### `simTick(state, links, n, options)`
+
+Execute one tick of force-directed simulation.
+
+```ts
+import { simTick } from '@xingwangzhe/force-rs';
+
+const opts = {
+  repulsion: 3000,      // many-body charge strength
+  linkDistance: 500,    // natural spring length
+  centerStrength: 0.005,// translational center gravity
+  theta: 0.8,           // Barnes-Hut approximation threshold
+  velocityDecay: 0.60,  // velocity damping per tick
+  alphaDecay: 0.02,     // cooling rate per tick
+};
+
+// state: n*6 + 1 floats [x0,y0,z0,vx0,vy0,vz0, ..., alpha]
+// links: 2*m u32 [src0,tgt0, src1,tgt1, ...]
+const newState = simTick(state, links, n, opts);
+```
+
+**ForceOptions:**
+
+| Field           | Type   | Description                            |
+|-----------------|--------|----------------------------------------|
+| `repulsion`      | number | Many-body charge strength              |
+| `linkDistance`   | number | Natural spring length                  |
+| `centerStrength` | number | Translational center gravity           |
+| `theta`          | number | Barnes-Hut approximation threshold     |
+| `velocityDecay`  | number | Velocity damping factor per tick       |
+| `alphaDecay`     | number | Alpha cooling rate per tick            |
+
+**Returns:** `Array<number>` — new state (same format as input, with updated alpha).
+
+## Usage Example
+
+```ts
+import { simTick } from '@xingwangzhe/force-rs';
+
+// 3 nodes: positions + velocities + alpha
+const state = [
+  0, 0, 0, 0, 0, 0,    // node 0
+  100, 0, 0, 0, 0, 0,  // node 1
+  0, 100, 0, 0, 0, 0,  // node 2
+  1.0                    // alpha
+];
+const links = [0, 1, 0, 2]; // node 0 connected to 1 and 2
+
+const opts = {
+  repulsion: 3000,
+  linkDistance: 500,
+  centerStrength: 0.005,
+  theta: 0.8,
+  velocityDecay: 0.60,
+  alphaDecay: 0.02,
+};
+
+let s = state;
+while (s[s.length - 1] > 0.001) {
+  s = simTick(s, links, 3, opts);
+}
+// s now contains converged 3D positions
+```
+
+## Real-world Performance
+
+| Platform | 47K nodes × 89K edges | Notes |
+|----------|----------------------|-------|
+| 16-core  | **~0.01s/tick**      | Rayon `par_iter` across 16 threads |
+| 1-core   | ~0.15s/tick          | Auto-fallback to sequential |
+
+Measured on AMD EPYC / Intel Xeon build servers. Barnes-Hut octree is custom-built in `src/lib.rs` (no external crate dependency for the tree structure).
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,12 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export interface ForceOptions {
+  repulsion: number
+  linkDistance: number
+  centerStrength: number
+  theta: number
+  velocityDecay: number
+  alphaDecay: number
+}
+
+export declare function simTick(state: Array<number>, links: Array<number>, n: number, opts: ForceOptions): Array<number>

package/index.js

@@ -0,0 +1,590 @@
+// prettier-ignore
+/* eslint-disable */
+// @ts-nocheck
+/* auto-generated by NAPI-RS */
+
+const { readFileSync } = require('fs')
+let nativeBinding = null
+const loadErrors = []
+
+const isMusl = () => {
+  let musl = false
+  if (process.platform === 'linux') {
+    musl = isMuslFromFilesystem()
+    if (musl === null) {
+      musl = isMuslFromReport()
+    }
+    if (musl === null) {
+      musl = isMuslFromChildProcess()
+    }
+  }
+  return musl
+}
+
+const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-')
+
+const isMuslFromFilesystem = () => {
+  try {
+    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
+  } catch {
+    return null
+  }
+}
+
+const isMuslFromReport = () => {
+  let report = null
+  if (process.report && typeof process.report.getReport === 'function') {
+    process.report.excludeNetwork = true
+    report = process.report.getReport()
+  }
+  if (!report) {
+    return null
+  }
+  if (report.header && report.header.glibcVersionRuntime) {
+    return false
+  }
+  if (Array.isArray(report.sharedObjects)) {
+    if (report.sharedObjects.some(isFileMusl)) {
+      return true
+    }
+  }
+  return false
+}
+
+const isMuslFromChildProcess = () => {
+  try {
+    return require('child_process').execSync('ldd --version', { encoding: 'utf8' }).includes('musl')
+  } catch (e) {
+    // If we reach this case, we don't know if the system is musl or not, so is better to just fallback to false
+    return false
+  }
+}
+
+function requireNative() {
+  if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
+    try {
+      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
+    } catch (err) {
+      loadErrors.push(err)
+    }
+  } else if (process.platform === 'android') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./force-rs.android-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-android-arm64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./force-rs.android-arm-eabi.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-android-arm-eabi')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Android ${process.arch}`))
+    }
+  } else if (process.platform === 'win32') {
+    if (process.arch === 'x64') {
+      if ((process.config && process.config.variables && process.config.variables.shlib_suffix === 'dll.a') || (process.config && process.config.variables && process.config.variables.node_target_type === 'shared_library')) {
+        try {
+        return require('./force-rs.win32-x64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-win32-x64-gnu')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-win32-x64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      } else {
+        try {
+        return require('./force-rs.win32-x64-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-win32-x64-msvc')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-win32-x64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      }
+    } else if (process.arch === 'ia32') {
+      try {
+        return require('./force-rs.win32-ia32-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-win32-ia32-msvc')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./force-rs.win32-arm64-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-win32-arm64-msvc')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Windows: ${process.arch}`))
+    }
+  } else if (process.platform === 'darwin') {
+    try {
+      return require('./force-rs.darwin-universal.node')
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    try {
+      const binding = require('@xingwangzhe/force-rs-darwin-universal')
+      const bindingPackageVersion = require('@xingwangzhe/force-rs-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      }
+      return binding
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    if (process.arch === 'x64') {
+      try {
+        return require('./force-rs.darwin-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-darwin-x64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./force-rs.darwin-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-darwin-arm64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on macOS: ${process.arch}`))
+    }
+  } else if (process.platform === 'freebsd') {
+    if (process.arch === 'x64') {
+      try {
+        return require('./force-rs.freebsd-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-freebsd-x64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./force-rs.freebsd-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-freebsd-arm64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on FreeBSD: ${process.arch}`))
+    }
+  } else if (process.platform === 'linux') {
+    if (process.arch === 'x64') {
+      if (isMusl()) {
+        try {
+          return require('./force-rs.linux-x64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-x64-musl')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./force-rs.linux-x64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-x64-gnu')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm64') {
+      if (isMusl()) {
+        try {
+          return require('./force-rs.linux-arm64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-arm64-musl')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./force-rs.linux-arm64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-arm64-gnu')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm') {
+      if (isMusl()) {
+        try {
+          return require('./force-rs.linux-arm-musleabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-arm-musleabihf')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./force-rs.linux-arm-gnueabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'loong64') {
+      if (isMusl()) {
+        try {
+          return require('./force-rs.linux-loong64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-loong64-musl')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./force-rs.linux-loong64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-loong64-gnu')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'riscv64') {
+      if (isMusl()) {
+        try {
+          return require('./force-rs.linux-riscv64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-riscv64-musl')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./force-rs.linux-riscv64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@xingwangzhe/force-rs-linux-riscv64-gnu')
+          const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'ppc64') {
+      try {
+        return require('./force-rs.linux-ppc64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-linux-ppc64-gnu')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 's390x') {
+      try {
+        return require('./force-rs.linux-s390x-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-linux-s390x-gnu')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Linux: ${process.arch}`))
+    }
+  } else if (process.platform === 'openharmony') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./force-rs.openharmony-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-openharmony-arm64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'x64') {
+      try {
+        return require('./force-rs.openharmony-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-openharmony-x64')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./force-rs.openharmony-arm.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@xingwangzhe/force-rs-openharmony-arm')
+        const bindingPackageVersion = require('@xingwangzhe/force-rs-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on OpenHarmony: ${process.arch}`))
+    }
+  } else {
+    loadErrors.push(new Error(`Unsupported OS: ${process.platform}, architecture: ${process.arch}`))
+  }
+}
+
+nativeBinding = requireNative()
+
+// NAPI_RS_FORCE_WASI is a tri-state flag:
+//   unset / any other value → native binding preferred, WASI is only a fallback
+//   'true'                   → force WASI fallback even if native loaded
+//   'error'                  → force WASI and throw if no WASI binding is found
+// Treating any non-empty string as truthy (the historical behavior) meant
+// NAPI_RS_FORCE_WASI=false, NAPI_RS_FORCE_WASI=0, etc. inadvertently triggered
+// the WASI path, causing ENOENT for packages shipped without a .wasi.cjs file.
+const forceWasi =
+  process.env.NAPI_RS_FORCE_WASI === 'true' || process.env.NAPI_RS_FORCE_WASI === 'error'
+
+if (!nativeBinding || forceWasi) {
+  let wasiBinding = null
+  let wasiBindingError = null
+  try {
+    wasiBinding = require('./force-rs.wasi.cjs')
+    nativeBinding = wasiBinding
+  } catch (err) {
+    if (forceWasi) {
+      wasiBindingError = err
+    }
+  }
+  if (!nativeBinding || forceWasi) {
+    try {
+      wasiBinding = require('@xingwangzhe/force-rs-wasm32-wasi')
+      nativeBinding = wasiBinding
+    } catch (err) {
+      if (forceWasi) {
+        if (!wasiBindingError) {
+          wasiBindingError = err
+        } else {
+          wasiBindingError.cause = err
+        }
+        loadErrors.push(err)
+      }
+    }
+  }
+  if (process.env.NAPI_RS_FORCE_WASI === 'error' && !wasiBinding) {
+    const error = new Error('WASI binding not found and NAPI_RS_FORCE_WASI is set to error')
+    error.cause = wasiBindingError
+    throw error
+  }
+}
+
+if (!nativeBinding) {
+  if (loadErrors.length > 0) {
+    const error = new Error(
+      `Cannot find native binding. ` +
+        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
+        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
+    )
+    // assign instead of the `new Error(message, { cause })` options form,
+    // which Node < 16.9 silently ignores
+    error.cause = loadErrors.reduce((err, cur) => {
+      cur.cause = err
+      return cur
+    })
+    throw error
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+module.exports = nativeBinding
+module.exports.simTick = nativeBinding.simTick

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@xingwangzhe/force-rs",
+  "version": "0.1.1",
+  "description": "Fast force-directed 3D graph layout powered by Rust + Barnes-Hut octree. Fully compatible with d3-force-3d force model (repulsion, spring with correct degree-biased strength, translational center gravity). Parallelized with Rayon — 47K nodes × 89K edges in ~0.01s/tick on 16 cores.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "xingwangzhe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xingwangzhe/force-rs.git"
+  },
+  "keywords": [
+    "force-layout",
+    "barnes-hut",
+    "d3-force",
+    "d3-force-3d",
+    "napi-rs",
+    "rust",
+    "graph-layout",
+    "force-directed",
+    "3d",
+    "octree"
+  ],
+  "files": [
+    "index.d.ts",
+    "index.js",
+    "force-rs.*.node"
+  ],
+  "napi": {
+    "binaryName": "force-rs",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "x86_64-unknown-linux-gnu",
+      "x86_64-unknown-linux-musl",
+      "aarch64-unknown-linux-gnu"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "test": "node --test force.test.mjs",
+    "lint": "oxlint",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm && bun run build"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.2.0",
+    "oxlint": "^1.72.0",
+    "typescript": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "@xingwangzhe/force-rs-darwin-x64": "0.1.1",
+    "@xingwangzhe/force-rs-darwin-arm64": "0.1.1",
+    "@xingwangzhe/force-rs-win32-x64-msvc": "0.1.1",
+    "@xingwangzhe/force-rs-linux-x64-gnu": "0.1.1",
+    "@xingwangzhe/force-rs-linux-x64-musl": "0.1.1",
+    "@xingwangzhe/force-rs-linux-arm64-gnu": "0.1.1"
+  }
+}