@simular-ai/simulang-js 7.0.1 → 8.1.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ 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
+
+- `AccessibilityNode.fromPoint(x, y)` — element under a screen coordinate via the platform hit-test (UIA `ElementFromPoint` on Windows, `AXUIElementCopyElementAtPosition` on macOS, recursive AT-SPI `GetAccessibleAtPoint` on Linux). Coordinates are global desktop coordinates in OS-native units (physical pixels on Windows/Linux, logical points on macOS), the same space as `boundingBox()` and `MouseController`; returns an uncached, one-shot handle for reading properties such as `.boundingBox()` / `.overallDescription`, or `null` when the point has no accessible element (empty desktop, gaps, or — on Linux — outside the focused app). Throws only on a genuine backend failure.
+- `AccessibilityTree.findByDescription(description)` — every node whose `overallDescription` exactly equals `description` (pre-order depth-first)
+- `GroundingModel.checkAuth()`, `AskModel.checkAuth()`, and `SttModel.checkAuth()` — probe the provider's auth-check endpoint to validate credentials before launching any UI automation. Throws (and logs a warning) on rejection or transport failure; no-op for providers without an auth-check endpoint. Idiom: `try { model.checkAuth() } catch { process.exit(1) }`.
+
+### Changed
+
+- `GroundingModel.default()` / `AskModel.default()` / `SttModel.default()` now produce a per-candidate diagnostic when no provider has working credentials, naming each provider and explaining exactly why its credentials were unavailable (env var unset, env var empty, credentials file missing, …). The previous error misleadingly said "no provider advertises a VLM service" even when the provider was correctly configured but its API-key env var was unset.
+- Corrected the documented coordinate space across the API (`MouseController`, `Window.boundingBox()`, `AccessibilityNode.boundingBox()` / `fromPoint()`, `Screen.boundingBox()`, screenshots, and grounding output). Coordinates are in **OS-native units** — physical pixels on Windows/Linux and **logical points on macOS** (where one point spans two hardware pixels on a 2× display) — not uniformly "physical pixels" as previously stated. Behavior is unchanged; coordinates still round-trip between these APIs without conversion on a given OS.
+
+### Breaking
+
+- `Image.addGrid()` and `Screenshot.addGrid()` are renamed to `drawGrid()` to match the underlying `simulang-rs` API. Same signature and behavior; update call sites from `.addGrid(w, h)` to `.drawGrid(w, h)`.
+- `Screenshot.toGlobalPhysicalPixels()` is renamed to `Screenshot.toGlobalDesktopCoordinates()`. The old name implied physical pixels, but the result is in the canonical global-desktop space (OS-native units — logical points on macOS, physical pixels on Windows/Linux). Same signature and behavior; update call sites from `.toGlobalPhysicalPixels(...)` to `.toGlobalDesktopCoordinates(...)`.
+
 ## [7.0.1] - 2026-05-22
 
 ## [7.0.0] - 2026-05-22

package/examples/element_at_point.mjs

@@ -0,0 +1,75 @@
+// Run: node examples/element_at_point.mjs
+// Optionally pass coordinates: node examples/element_at_point.mjs 400 300
+//
+// Demonstrates the element-picker primitives:
+//   1. AccessibilityNode.fromPoint(x, y) — hit-test the element under a
+//      screen coordinate (used per-poll to draw a hover highlight). The
+//      returned node is already actionable (activate / setValue / …).
+//   2. AccessibilityTree.findByDescription(desc) — the picker's grounding
+//      check: is this element's overallDescription unique in the window?
+//      `isUnique` is just `matches.length === 1`.
+
+import {
+  AccessibilityNode,
+  AccessibilityTree,
+  MouseController,
+  Window,
+  ariaRoleToString,
+} from '@simular-ai/simulang-js'
+
+// Coordinates: explicit args, or the live cursor location.
+const args = process.argv.slice(2)
+const [x, y] = args.length >= 2 ? [Number(args[0]), Number(args[1])] : new MouseController().location()
+
+// 1. Hit-test — cheap, resolves a single element. Returns null when the
+//    point has no accessible element (empty desktop, gaps, etc.).
+const t0 = Date.now()
+const node = AccessibilityNode.fromPoint(x, y)
+if (!node) {
+  console.log(`=== No accessible element at (${x}, ${y}) (${Date.now() - t0}ms) ===`)
+  process.exit(0)
+}
+const description = node.overallDescription
+console.log(`=== Element at (${x}, ${y}) — fromPoint in ${Date.now() - t0}ms ===`)
+console.log(`role:        ${ariaRoleToString(node.role)}`)
+console.log(`name:        ${JSON.stringify(node.name)}`)
+console.log(`value:       ${JSON.stringify(node.value)}`)
+console.log(`description: ${JSON.stringify(description)}`)
+console.log('bounds:     ', node.boundingBox())
+// The fromPoint node is already actionable — no tree round-trip to click it.
+console.log('actions:    ', node.supportedActions())
+
+// 2. Uniqueness of the description across the whole window (the picker's
+//    grounding check). This walks the *entire* tree computing
+//    summary_with_context per node, so it is far heavier than fromPoint —
+//    especially on macOS, where every attribute read is a live AX IPC.
+console.log('\n=== findByDescription on foreground window (app-scoped) ===')
+const t1 = Date.now()
+const tree = AccessibilityTree.fromForeground()
+const matches = tree.findByDescription(description)
+console.log(`matches:  ${matches.length} (in ${Date.now() - t1}ms)`)
+console.log(`isUnique: ${matches.length === 1}`)
+if (matches.length > 1) {
+  console.log(
+    'Not a stable grounding key — the cursor is over a generic/nameless ' +
+      'container whose description many siblings share.',
+  )
+}
+
+// 3. Window-scoped uniqueness: resolve the window under the cursor and check
+//    uniqueness WITHIN that window only (cross-platform: AXWindow subtree on
+//    macOS, the HWND subtree on Windows). This is what the element picker
+//    should use so a description shared across other windows of the same app
+//    doesn't count against it.
+console.log('\n=== findByDescription on hovered window (window-scoped) ===')
+const window = Window.fromPoint(x, y)
+if (!window) {
+  console.log(`No window under (${x}, ${y}).`)
+} else {
+  console.log(`window:   ${JSON.stringify(window.title)} (pid ${window.pid})`)
+  const t2 = Date.now()
+  const windowTree = AccessibilityTree.fromWindow(window)
+  const windowMatches = windowTree.findByDescription(description)
+  console.log(`matches:  ${windowMatches.length} (in ${Date.now() - t2}ms)`)
+  console.log(`isUnique: ${windowMatches.length === 1}`)
+}

package/index.d.ts

@@ -16,6 +16,26 @@ export declare class AccessibilityNode {
   static fromFocusedApplication(): AccessibilityNode
   /** Root node of the application identified by `pid`. */
   static fromPid(pid: number): AccessibilityNode
+  /**
+   * Element at screen coordinates (`x`, `y`) via the platform hit-test
+   * (Windows UIA `ElementFromPoint`, macOS
+   * `AXUIElementCopyElementAtPosition`, Linux recursive AT-SPI
+   * `GetAccessibleAtPoint`).
+   *
+   * `(x, y)` are global desktop coordinates in the canonical coordinate space
+   * (OS-native units; see [`MouseController`])
+   * — the same space `.boundingBox()` and `MouseController` use, so a
+   * `boundingBox()` corner or cursor `location()` can be passed straight in.
+   * Returns an **uncached** handle suitable for one-shot reads of properties
+   * such as `.boundingBox()` or `.overallDescription`; it is not registered
+   * for ref-based action methods (`activate`, `setValue`, …).
+   *
+   * Returns `null` when the point has no accessible element (empty
+   * desktop, gaps between controls, or — on Linux — a point outside the
+   * focused application). Throws only on a genuine accessibility-backend
+   * failure.
+   */
+  static fromPoint(x: number, y: number): AccessibilityNode | null
   /** Cross-platform ARIA role. */
   get role(): AriaRole
   /** Accessible name (title / label). */
@@ -42,7 +62,16 @@ export declare class AccessibilityNode {
   /** Whether the node accepts user input. */
   get isEnabled(): boolean
   /**
-   * Live bounding box of the element in global physical pixels.
+   * 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
+   * [`MouseController`]).
    * `right` and `bottom` are exclusive (Playwright / DOM convention).
    */
   boundingBox(): BoundingBox
@@ -52,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.
@@ -138,6 +192,22 @@ export declare class AccessibilityTree {
    * On Windows this is an HWND; on macOS it is a PID.
    */
   static fromHwnd(hwnd: number): AccessibilityTree
+  /**
+   * Create an accessibility tree scoped to a single window.
+   *
+   * Unlike [`AccessibilityTree.fromForeground`] / [`fromPid`] — which on
+   * macOS scope to the whole application (every window plus the app menu
+   * bar) — this scopes to exactly the given window's subtree on **both**
+   * Windows and macOS. Use it to measure "is this element unique within
+   * this window", or to snapshot / act on one window of a multi-window
+   * app.
+   *
+   * The window is resolved once at construction; subsequent snapshots
+   * target that same window. On macOS the underlying `AXWindow` handle can
+   * go stale if the window is destroyed and recreated (as an `HWND` can on
+   * Windows).
+   */
+  static fromWindow(window: Window): AccessibilityTree
   /** Get the window title. */
   get windowTitle(): string
   /**
@@ -217,6 +287,15 @@ export declare class AccessibilityTree {
     maxResults?: number | undefined | null,
     collapseStructural?: boolean | undefined | null,
   ): Array<AccessibilityNodeJs>
+  /**
+   * Find every node whose `overallDescription`
+   * (`AXNodeSynthetic::summary_with_context`) is **exactly** equal to
+   * `description`, walked in pre-order depth-first.
+   *
+   * Clears existing refs; returned nodes carry `refId` values usable
+   * with the action methods (`activate`, `setValue`, …).
+   */
+  findByDescription(description: string): Array<AccessibilityNodeJs>
 }
 
 /** Represents an application that can be opened. */
@@ -286,6 +365,17 @@ export declare class AskModel {
   static availableAliases(): Array<string>
   /** The wire-level model identifier sent in the request body. */
   get name(): string
+  /**
+   * Check that the API key works. Throws if it doesn't.
+   *
+   * Call right after creating the model so a bad key fails fast,
+   * before any UI automation has had a chance to steal focus:
+   *
+   * ```ts
+   * try { model.checkAuth() } catch { process.exit(1) }
+   * ```
+   */
+  checkAuth(): void
   /**
    * Ask the model a question, optionally grounded in accessibility text
    * and/or images.
@@ -502,16 +592,25 @@ export declare class GroundingModel {
   static availableAliases(): Array<string>
   /** The wire-level model identifier sent in the request body. */
   get name(): string
+  /**
+   * Check that the API key works. Throws if it doesn't.
+   *
+   * Call right after creating the model so a bad key fails fast,
+   * before any UI automation has had a chance to steal focus:
+   *
+   * ```ts
+   * try { model.checkAuth() } catch { process.exit(1) }
+   * ```
+   */
+  checkAuth(): void
   /**
    * Locate `concept` on `target` and return zero-based pixel coordinates
    * `[x, y]`:
    *
    * * If `target` is an `Image`, coordinates are in **image-space**.
-   *   Normalized model outputs are scaled linearly onto
-   *   `[0, width - 1]` and `[0, height - 1]`.
-   * * If `target` is a `Screenshot`, coordinates are in **global physical
-   *   screen space** — suitable to feed directly into primitives that
-   *   expect global screen coordinates (e.g. `moveTo`, `clickAt`).
+   * * If `target` is a `Screenshot`, coordinates are in the **global desktop
+   *   space** in OS-native units (may be negative on multi-monitor setups;
+   *   see [`MouseController`]).
    *
    * Equivalent to `target.ground(model, concept)`.
    */
@@ -527,7 +626,22 @@ export declare class Image {
    *
    * Grid squares have the specified `width` and `height`.
    */
-  addGrid(width: number, height: number): void
+  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.
    *
@@ -746,20 +860,35 @@ export declare class LoopbackSource {
 }
 
 /**
- * Mouse cursor control and queries.
+ * Contains functions to control the mouse and to get the cursor position.
+ *
+ * # Canonical coordinate space
  *
- * Absolute coordinates live in the **global virtual desktop** — top-left
- * origin at `(0, 0)` on the primary monitor, physical pixels, and the
- * same coordinate space used by `Window.boundingBox()`, `Screen`, and
- * screenshots.
+ * This is the reference description of the coordinate space used throughout
+ * the library. `Window.boundingBox()`, `AccessibilityNode.boundingBox()`,
+ * `AccessibilityNode.fromPoint()`, screenshots, and grounding-model output
+ * all live in this same space, so coordinates round-trip between them
+ * **without conversion**.
  *
- * Monitors arranged to the left of or above the primary display
- * contribute **negative** coordinates, so callers should not assume
- * `x, y >= 0`. Use [`Screen.all`] / [`Screen.fromWindow`] (or
- * [`Window.moveMouse`] for window-frame-relative input) to discover
- * where the addressable region actually is.
+ * Absolute coordinates live on the **global desktop**: top-left origin at
+ * `(0, 0)` on the primary monitor, with the OS's native units. The unit is
+ * **not** the same on every OS:
  *
- * The same coordinate system is used on all operating systems.
+ * - **Windows** and **Linux** use **physical pixels** (raw hardware pixels).
+ * - **macOS** uses **logical points** — on a 2× Retina display one point spans
+ *   two hardware pixels, so coordinates are half the physical-pixel count.
+ *
+ * Within a single OS every function speaks that OS's unit, so the
+ * round-trip guarantee holds; only code that crosses into a *different*
+ * coordinate system (e.g. an Electron overlay measured in CSS pixels) needs to
+ * account for the per-OS unit. These are also the native units the OS
+ * input/accessibility APIs expect, so they are *not* the browser logical/CSS
+ * pixel.
+ *
+ * Monitors arranged to the left of or above the primary display contribute
+ * **negative** coordinates, so callers should not assume `x, y >= 0`. Use
+ * [`Screen.all`] / [`Screen.fromWindow`] to discover where the
+ * addressable region actually is.
  */
 export declare class MouseController {
   constructor()
@@ -775,11 +904,11 @@ export declare class MouseController {
    * You can specify absolute coordinates or relative from the current
    * position.
    *
-   * With absolute coordinates, `(x, y)` is in the global virtual
-   * desktop described on [`MouseController`]: top-left of the
-   * primary monitor is `(0, 0)`, physical pixels, and secondary
-   * monitors arranged above / to the left of the primary may have
-   * **negative** coordinates.
+   * With absolute coordinates, `(x, y)` is in the global desktop space
+   * described on [`MouseController`]: top-left of the primary monitor is
+   * `(0, 0)`, OS-native units (physical pixels on Windows/Linux, logical
+   * points on macOS), and secondary monitors arranged above / to the left
+   * of the primary may have negative coordinates.
    *
    * With relative coordinates, a positive `x` moves the cursor `x`
    * pixels to the right; a positive `y` moves it down.
@@ -792,7 +921,10 @@ export declare class MouseController {
    * ones up/left.
    */
   scroll(deltaX: number, deltaY: number): void
-  /** Get the location of the mouse in pixels. */
+  /**
+   * Get the location of the mouse in the canonical global-desktop space
+   * (OS-native units; see [`MouseController`]).
+   */
   location(): [number, number]
 }
 
@@ -926,7 +1058,7 @@ export declare class SamplesBuffer {
   transcribe(model: SttModel): string
 }
 
-/** Represents a physical display/screen in the global virtual desktop. */
+/** Represents a connected display/screen on the global desktop. */
 export declare class Screen {
   /** Returns the main / primary screen. */
   static mainScreen(): Screen
@@ -962,9 +1094,10 @@ export declare class Screen {
    */
   static all(): Array<Screen>
   /**
-   * Live bounding box of the screen in the global virtual desktop.
+   * Live bounding box of the screen on the global desktop.
    *
-   * Top-left of the primary monitor is `(0, 0)`, physical pixels.
+   * Top-left of the primary monitor is `(0, 0)`, in the canonical coordinate
+   * space (OS-native units; see [`MouseController`]).
    * Monitors arranged to the left of or above the primary display
    * contribute **negative** `left` / `top`. `right` and `bottom` are
    * exclusive (Playwright / DOM convention), matching
@@ -985,7 +1118,22 @@ export declare class Screenshot {
    *
    * Grid squares have the specified `width` and `height`.
    */
-  addGrid(width: number, height: number): void
+  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.
    *
@@ -1015,23 +1163,27 @@ export declare class Screenshot {
    */
   base64(): string
   /**
-   * Converts a point in this screenshot to global physical pixel
-   * coordinates.
+   * Converts a point in this screenshot to global desktop coordinates.
+   *
+   * The result is in the library's canonical coordinate space (OS-native
+   * units; see [`MouseController`]), so it can be fed straight to
+   * `MouseController.moveMouse` without conversion.
    *
-   * Screenshots may represent only part of a display, and displays may
-   * use different scale factors. Use this to map `(x, y)` to the
-   * corresponding global physical pixel position (for example, when
-   * moving the mouse to the same on-screen point).
+   * Screenshots may represent only part of a display, and the captured
+   * region may have been resampled to a different image size, so this
+   * rescales `(x, y)` from image space back to the captured region (for
+   * example, when moving the mouse to the same on-screen point).
    *
    * See `ScreenshotCoordinateType` for how `coord_type` affects
    * interpretation of `(x, y)`.
    */
-  toGlobalPhysicalPixels(x: number, y: number, coordType: ScreenshotCoordinateType): [number, number]
+  toGlobalDesktopCoordinates(x: number, y: number, coordType: ScreenshotCoordinateType): [number, number]
   /**
    * Locate `concept` on this screenshot using the given grounding model and
-   * return the corresponding **global physical pixel coordinates** `[x, y]`.
-   * The output can be fed directly to primitives that expect global screen
-   * coordinates.
+   * return the corresponding **global desktop coordinates** `[x, y]` in
+   * OS-native units (may be negative on multi-monitor setups; see
+   * [`MouseController`]). The output can be fed
+   * directly to primitives that expect global screen coordinates.
    *
    * Equivalent to `model.ground(screenshot, concept)`.
    */
@@ -1039,8 +1191,9 @@ export declare class Screenshot {
 }
 
 /**
- * Describes how `(x, y)` coordinates passed to
- * `Screenshot.toGlobalPhysicalPixels` should be interpreted.
+ * How a screenshot-relative `(x, y)` coordinate is expressed: as absolute
+ * screenshot-image pixels or normalized to a fixed range. Construct one with
+ * [`ScreenshotCoordinateType.absolute`] or [`ScreenshotCoordinateType.normalized`].
  */
 export declare class ScreenshotCoordinateType {
   /**
@@ -1089,6 +1242,17 @@ export declare class SttModel {
   static availableAliases(): Array<string>
   /** The wire-level model identifier sent in the request body. */
   get name(): string
+  /**
+   * Check that the API key works. Throws if it doesn't.
+   *
+   * Call right after creating the model so a bad key fails fast,
+   * before any UI automation has had a chance to steal focus:
+   *
+   * ```ts
+   * try { model.checkAuth() } catch { process.exit(1) }
+   * ```
+   */
+  checkAuth(): void
   /** Transcribe a single audio chunk and return the recognised text. */
   transcribe(audio: SamplesBuffer): string
 }
@@ -1114,12 +1278,32 @@ export declare class Window {
   static allForPid(pid: number): Array<Window>
   /** All visible top-level windows across every process. */
   static all(): Array<Window>
+  /**
+   * The top-level window at screen coordinates `(x, y)`, or `null` when no
+   * window sits under the point.
+   *
+   * `(x, y)` are global desktop coordinates in the canonical coordinate
+   * space (OS-native units; see [`MouseController`]) — the same space
+   * `Window.boundingBox`, `AccessibilityNode.fromPoint`, and
+   * `MouseController.location` use, so a cursor `location()` can be passed
+   * straight in.
+   *
+   * Platform notes:
+   * - **macOS**: returns the containing `AXWindow` of the element under the
+   *   cursor — the window itself, not the whole application.
+   * - **Windows**: returns the top-level window (`GA_ROOT`) of whatever
+   *   control sits under the cursor.
+   * - **Linux**: always `null` (no per-point window hit-test).
+   */
+  static fromPoint(x: number, y: number): Window | null
   /** Window title (may be empty). */
   get title(): string
   /** Process ID that owns this window. */
   get pid(): number
   /**
-   * Live bounding box of the window in global virtual-desktop pixels.
+   * Live bounding box of the window on the global desktop, in the canonical
+   * coordinate space (OS-native units; see
+   * [`MouseController`]).
    * `right` and `bottom` are exclusive (Playwright / DOM convention).
    * Coordinates can be negative when the window sits on a monitor that
    * is arranged to the left of / above the primary display.
@@ -1165,9 +1349,20 @@ export declare class Window {
   /**
    * Move the cursor to a point inside this window.
    *
-   * `(x, y)` are **window-frame-relative** physical pixels — `(0, 0)`
-   * is the top-left of [`Window.boundingBox`], which includes the
-   * title bar and other OS chrome.
+   * `(x, y)` are **window-frame-relative**, in OS-native units (physical
+   * pixels on Windows/Linux, logical points on macOS) — `(0, 0)` is the
+   * 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
@@ -1187,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
@@ -1210,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

@@ -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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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 !== '7.0.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 7.0.1 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

@@ -1,6 +1,6 @@
 {
   "name": "@simular-ai/simulang-js",
-  "version": "7.0.1",
+  "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.6.1",
+    "@napi-rs/cli": "^3.7.2",
     "@oxc-node/core": "^0.1.0",
     "@taplo/cli": "^0.7.0",
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.3",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.4",
-    "npm-run-all2": "^8.0.4",
-    "oxlint": "^1.63.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.5"
+    "vitest": "^4.1.9"
   },
   "lint-staged": {
     "*.@(js|ts|tsx)": [
@@ -117,11 +117,11 @@
     "arrowParens": "always"
   },
   "optionalDependencies": {
-    "@simular-ai/simulang-js-win32-x64-msvc": "7.0.1",
-    "@simular-ai/simulang-js-win32-arm64-msvc": "7.0.1",
-    "@simular-ai/simulang-js-darwin-x64": "7.0.1",
-    "@simular-ai/simulang-js-darwin-arm64": "7.0.1",
-    "@simular-ai/simulang-js-linux-x64-gnu": "7.0.1",
-    "@simular-ai/simulang-js-linux-arm64-gnu": "7.0.1"
+    "@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"
   }
 }