npm - @simular-ai/simulang-js - Versions diffs - 8.0.0 → 8.1.0 - Mend

@simular-ai/simulang-js 8.0.0 → 8.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [8.1.0] - 2026-06-23
+### Added
+- `AccessibilityNode.parent()`, `ancestors()`, direct/strict ancestry checks, and `lowestCommonAncestor(other)` for navigating accessibility-tree relationships. `parent()` returns `null` when a node has no parent, `ancestors()` stops only when the parent chain is fully resolved, and both throw on lookup failure; `lowestCommonAncestor` returns a `[node, level]` tuple where `level` is from the reached parentless node, returns `null` only for resolved unrelated trees, and throws if either parent chain cannot be resolved.
+- `Window.screenshot(hideCursor)` — captures just this window's pixels from its own backing store (macOS `ScreenCaptureKit` window filter / Windows `Windows.Graphics.Capture`), so occluding windows don't bleed through and hardware-accelerated content (Chrome, Electron, D3D apps) is captured correctly; off-display or minimized windows throw.
+- `Window.ground(model, concept)` — locate a concept within this window and return its global desktop coordinates (sugar for `screenshot(true).ground(model, concept)`); restricting the search to the window's bounds is faster and more accurate than grounding a full-screen screenshot.
+- `AccessibilityNode.url` — the node's raw hyperlink target as a `string`, or `null` when the node isn't a link, has no target, or the platform doesn't expose it.
+- `Image.drawDot(x, y, radius, red, green, blue)` and `Screenshot.drawDot(...)` — paint a filled opaque RGB disc at an image-pixel coordinate (companion to `drawGrid`; `radius` 0 paints a single pixel, out-of-bounds points are no-ops). Handy for annotating grounding results.
+### Changed
+- Frame-relative input on a `Window` (`moveMouse`, `click`) now throws when the target point maps off every connected display, instead of letting the OS silently clamp the cursor to a screen edge and click the wrong location.
 ## [8.0.0] - 2026-06-05
 ### Added

package/index.d.ts CHANGED Viewed

@@ -61,6 +61,13 @@ export declare class AccessibilityNode {
   get automationId(): string
   /** Whether the node accepts user input. */
   get isEnabled(): boolean
+  /**
+   * Hyperlink target of this node, or `null` when the node is not a link,
+   * the link has no target, or the platform backend does not expose the
+   * target through the accessibility API. The string is the raw URL as
+   * reported by the platform (no parsing or normalisation).
+   */
+  get url(): string | null
   /**
    * Live bounding box of the element on the global desktop, in the canonical
    * coordinate space (OS-native units; see
@@ -74,6 +81,31 @@ export declare class AccessibilityNode {
    * simulang-rs's convention of treating walk failures as "no children").
    */
   children(): Array<AccessibilityNode>
+  /**
+   * Direct parent node, or `null` if this node has no parent. Parent lookup
+   * failures throw.
+   */
+  parent(): AccessibilityNode | null
+  /**
+   * Parent chain for this node, nearest parent first, excluding this node.
+   * Stops when a node has no parent; parent lookup failures throw.
+   */
+  ancestors(): Array<AccessibilityNode>
+  /** Whether this node is the direct parent of `other`. */
+  isParentOf(other: AccessibilityNode): boolean
+  /** Whether this node is a direct child of `other`. */
+  isChildOf(other: AccessibilityNode): boolean
+  /** Whether this node is a strict ancestor of `other`. */
+  isAncestorOf(other: AccessibilityNode): boolean
+  /** Whether this node is a strict descendant of `other`. */
+  isDescendantOf(other: AccessibilityNode): boolean
+  /**
+   * Lowest shared ancestor for this node and `other`, plus that ancestor's
+   * level from the reached parentless node (`parentless = 0`, its children
+   * `= 1`). Returns `null` when both chains resolve and no shared ancestor
+   * exists; lookup failures throw.
+   */
+  lowestCommonAncestor(other: AccessibilityNode): [AccessibilityNode, number] | null
   /**
    * Render this node's accessibility subtree as an indented
    * Playwright-style aria snapshot string.
@@ -595,6 +627,21 @@ export declare class Image {
    * Grid squares have the specified `width` and `height`.
    */
   drawGrid(width: number, height: number): void
+  /**
+   * Paints a filled disc on the image. Useful for visualizing point
+   * coordinates returned from grounding, layout queries, etc.
+   *
+   * `x` / `y` are image-pixel coordinates of the disc's centre. `radius`
+   * is the disc radius in pixels (`0` paints a single pixel at the
+   * centre). `(red, green, blue)` is the fill color; alpha is always 255
+   * (opaque replacement of the underlying pixel).
+   *
+   * Coordinates that fall outside the image bounds (negative, or past the
+   * width / height) silently produce no pixel, so the helper is safe to
+   * call with the raw output of a grounding model even at the edge of the
+   * captured rect.
+   */
+  drawDot(x: number, y: number, radius: number, red: number, green: number, blue: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -1072,6 +1119,21 @@ export declare class Screenshot {
    * Grid squares have the specified `width` and `height`.
    */
   drawGrid(width: number, height: number): void
+  /**
+   * Paints a filled disc on the image. Useful for visualizing point
+   * coordinates returned from grounding, layout queries, etc.
+   *
+   * `x` / `y` are image-pixel coordinates of the disc's centre. `radius`
+   * is the disc radius in pixels (`0` paints a single pixel at the
+   * centre). `(red, green, blue)` is the fill color; alpha is always 255
+   * (opaque replacement of the underlying pixel).
+   *
+   * Coordinates that fall outside the image bounds (negative, or past the
+   * width / height) silently produce no pixel, so the helper is safe to
+   * call with the raw output of a grounding model even at the edge of the
+   * captured rect.
+   */
+  drawDot(x: number, y: number, radius: number, red: number, green: number, blue: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -1292,6 +1354,16 @@ export declare class Window {
    * top-left of [`Window.boundingBox`], which includes the title bar and
    * other OS chrome.
    *
+   * Two validation passes run before any input is synthesized, and either
+   * failing throws:
+   * 1. `(x, y)` must lie inside the window frame (`[0, width) × [0,
+   *    height)`).
+   * 2. The resulting global point must fall on at least one connected
+   *    display. Windows dragged partly off-screen can map an in-frame
+   *    point to a coordinate the OS would silently clamp to a display
+   *    edge — erroring out is strictly more useful than moving the cursor
+   *    somewhere unintended and clicking the wrong thing.
+   *
    * Does **not** focus the window. Call [`Window.focus`] (or
    * [`Instance.focus`]) first if the click target requires the window
    * to be active.
@@ -1310,7 +1382,9 @@ export declare class Window {
    * Move the cursor to `(x, y)` inside this window and synthesise a
    * mouse button event. Sugar for `moveMouse(x, y); button(...)`.
    *
-   * Coordinates are window-frame-relative (see [`Window.moveMouse`]).
+   * Coordinates are window-frame-relative (see [`Window.moveMouse`]), and
+   * are subject to the same bounds / on-screen validation: an off-frame or
+   * off-screen target throws instead of clicking the wrong location.
    * Does not focus the window.
    */
   click(x: number, y: number, button: Button, direction: Direction): void
@@ -1333,6 +1407,43 @@ export declare class Window {
    * [`AccessibilityTree.snapshot`] instead.
    */
   snapshot(): string
+  /**
+   * Capture just this window's pixels.
+   *
+   * Reads from the window's own backing store, so overlapping windows do
+   * **not** bleed through and the whole window is captured even where it is
+   * occluded or extends past a display edge — partially off-screen and
+   * multi-display-spanning windows are captured in full. The window must be
+   * on-screen at capture time: a minimized or fully off-display window
+   * throws, because there is nothing to capture.
+   */
+  screenshot(hideCursor: boolean): Screenshot
+  /**
+   * Locate `concept` inside this window's pixels and return its **global
+   * desktop coordinates** `[x, y]` in OS-native units (may be negative on
+   * multi-monitor setups; see [`MouseController`]), ready to feed straight
+   * into [`MouseController.moveMouse`] / click helpers.
+   *
+   * Sugar for `screenshot(true).ground(model, concept)` — the cursor is
+   * hidden because it can occlude or distract the model. Restricts the
+   * model's search to this window's bounds, which is both faster (fewer
+   * pixels to upload) and more accurate (no risk of grounding onto a
+   * concept that happens to be elsewhere on the screen) than grounding a
+   * full-screen screenshot.
+   *
+   * Drop down to [`Window.screenshot`] + [`Screenshot.ground`] directly
+   * when you want to keep the cursor visible, reuse the screenshot across
+   * multiple `ground` calls, or shrink / compress the image before
+   * sending it.
+   *
+   * The screenshot includes any portion of the window that's past the
+   * desktop edge (the capture reads the window's own backing store, not a
+   * display rectangle). A `concept` the model locates in that off-screen
+   * region returns coordinates the OS won't route a click to;
+   * [`Window.moveMouse`] catches this and errors out instead of clicking
+   * the nearest on-screen point.
+   */
+  ground(model: GroundingModel, concept: string): [number, number]
   /**
    * Search this window's accessibility subtree by *concept text*, using
    * bag-of-words paired-Jaccard scoring against each node's

package/index.js CHANGED Viewed

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-android-arm64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-android-arm64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-android-arm-eabi')
         const bindingPackageVersion = require('@simular-ai/simulang-js-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-win32-x64-gnu')
         const bindingPackageVersion = require('@simular-ai/simulang-js-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-win32-x64-msvc')
         const bindingPackageVersion = require('@simular-ai/simulang-js-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-win32-ia32-msvc')
         const bindingPackageVersion = require('@simular-ai/simulang-js-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-win32-arm64-msvc')
         const bindingPackageVersion = require('@simular-ai/simulang-js-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('@simular-ai/simulang-js-darwin-universal')
       const bindingPackageVersion = require('@simular-ai/simulang-js-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-darwin-x64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-darwin-arm64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-freebsd-x64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-freebsd-arm64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-x64-musl')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-x64-gnu')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-arm64-musl')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-arm64-gnu')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-arm-musleabihf')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-loong64-musl')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-loong64-gnu')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-riscv64-musl')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('@simular-ai/simulang-js-linux-riscv64-gnu')
           const bindingPackageVersion = require('@simular-ai/simulang-js-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-linux-ppc64-gnu')
         const bindingPackageVersion = require('@simular-ai/simulang-js-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-linux-s390x-gnu')
         const bindingPackageVersion = require('@simular-ai/simulang-js-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-openharmony-arm64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-openharmony-x64')
         const bindingPackageVersion = require('@simular-ai/simulang-js-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('@simular-ai/simulang-js-openharmony-arm')
         const bindingPackageVersion = require('@simular-ai/simulang-js-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '8.0.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 8.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '8.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 8.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -525,23 +525,33 @@ function requireNative() {
 nativeBinding = requireNative()
-if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+// 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('./simulang-js.wasi.cjs')
     nativeBinding = wasiBinding
   } catch (err) {
-    if (process.env.NAPI_RS_FORCE_WASI) {
+    if (forceWasi) {
       wasiBindingError = err
     }
   }
-  if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+  if (!nativeBinding || forceWasi) {
     try {
       wasiBinding = require('@simular-ai/simulang-js-wasm32-wasi')
       nativeBinding = wasiBinding
     } catch (err) {
-      if (process.env.NAPI_RS_FORCE_WASI) {
+      if (forceWasi) {
         if (!wasiBindingError) {
           wasiBindingError = err
         } else {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@simular-ai/simulang-js",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Node.js bindings for simulang-rs",
   "main": "wrapped.js",
   "types": "./wrapped.d.ts",
@@ -82,21 +82,21 @@
     "prepare": "husky"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.7.0",
+    "@napi-rs/cli": "^3.7.2",
     "@oxc-node/core": "^0.1.0",
     "@taplo/cli": "^0.7.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.3",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.5",
-    "npm-run-all2": "^9.0.1",
-    "oxlint": "^1.67.0",
-    "prettier": "^3.8.2",
+    "lint-staged": "^17.0.7",
+    "npm-run-all2": "^9.0.2",
+    "oxlint": "^1.70.0",
+    "prettier": "^3.8.4",
     "tinybench": "^6.0.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-frontmatter": "^1.3.1",
-    "typedoc-plugin-markdown": "^4.11.0",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.9"
   },
   "lint-staged": {
     "*.@(js|ts|tsx)": [
@@ -117,11 +117,11 @@
     "arrowParens": "always"
   },
   "optionalDependencies": {
-    "@simular-ai/simulang-js-win32-x64-msvc": "8.0.0",
-    "@simular-ai/simulang-js-win32-arm64-msvc": "8.0.0",
-    "@simular-ai/simulang-js-darwin-x64": "8.0.0",
-    "@simular-ai/simulang-js-darwin-arm64": "8.0.0",
-    "@simular-ai/simulang-js-linux-x64-gnu": "8.0.0",
-    "@simular-ai/simulang-js-linux-arm64-gnu": "8.0.0"
+    "@simular-ai/simulang-js-win32-x64-msvc": "8.1.0",
+    "@simular-ai/simulang-js-win32-arm64-msvc": "8.1.0",
+    "@simular-ai/simulang-js-darwin-x64": "8.1.0",
+    "@simular-ai/simulang-js-darwin-arm64": "8.1.0",
+    "@simular-ai/simulang-js-linux-x64-gnu": "8.1.0",
+    "@simular-ai/simulang-js-linux-arm64-gnu": "8.1.0"
   }
 }