@simular-ai/simulang-js 6.0.1 → 8.0.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to `@simular-ai/simulang-js` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [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
+
+### Added
+
+- `Instance.windows()` — enumerate visible top-level windows belonging to a specific opened application (companion to the global `Window.all()` / `Window.allForPid()` enumerators).
+- `Window.boundingBox()` — live bounding box of a window in global physical pixels (`right` / `bottom` exclusive, Playwright / DOM convention).
+- `Screen.boundingBox()` — live bounding box of a screen in global physical pixels (matches `Window.boundingBox()` shape; secondary monitors may report negative `left` / `top`).
+- `Instance.close()`, `Instance.kill()`, and `Instance.isRunning()` — request graceful exit, force-terminate, or poll whether the underlying process is still running.
+- `Screen.all()`, `Screen.fromWindow(window)`, and `Window.screen()` — enumerate connected displays and find the screen a specific window lives on (multi-monitor support). Matches the OS-native algorithm (`NSWindow.screen` on macOS, `MonitorFromWindow` on Windows); throws when the window has no measurable overlap with any display.
+- `Window.focus()` — bring a specific window to the foreground.
+- `Window.moveMouse()`, `Window.button()`, `Window.click()`, `Window.scroll()` — frame-relative mouse input on a window. Coordinates are relative to the window's `boundingBox()` top-left (i.e. include the title bar / chrome); the caller is responsible for focusing the window first if needed.
+
+### Changed
+
+- Clarified that mouse coordinates in `MouseController` are in the **global virtual desktop** (top-left of the primary monitor at `(0, 0)`, physical pixels, may be **negative** on secondary monitors arranged to the left of / above the primary). The previous "current screen" wording was wrong on multi-monitor setups.
+
+### Breaking
+
+- `Screen.dimensions()` is removed; use `Screen.boundingBox()` and read its `right - left` / `bottom - top` (or the `left` / `top` origin). The previous `[x, y, width, height]` tuple shape was redundant with `Window.boundingBox()` and the accessibility-tree `BoundingBox`, and a single canonical shape is friendlier for AI agents driving the API.
+
+## [6.0.1] - 2026-05-16
+
+### Added
+
+- `AskModel` (`AskModel.default()`, `AskModel.byAlias()`, `AskModel.availableAliases()`, `ask()`) — JS bindings for the `ask` LLM primitive (OpenAI-compatible chat completions, optional vision via `Image` attachments).
+
+## [6.0.0] - 2026-05-15
+
+### Added
+
+- `setPauseHook(fn | null)` on the JS wrapper — synchronous hook invoked before every exported call; used by `@simular-ai/simulang-log-viewer` for pause/grab behavior without wrapping each API by hand.
+- Default stderr logging on `import '@simular-ai/simulang-js'` — `initLogger` auto-installs unless overridden; filter follows `RUST_LOG` or `simulang_rs=info,warn`.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Simular AI
+Copyright (c) 2026 Simular LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -73,3 +73,7 @@ You can also point `simulang` at a local `simulang-js` checkout during developme
 ```bash
 simulang run --simulang-js=/path/to/simulang-js my-script.js
 ```
+
+## Changelog
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for version history and unreleased API changes.

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,9 @@ export declare class AccessibilityNode {
   /** Whether the node accepts user input. */
   get isEnabled(): boolean
   /**
-   * Live bounding box of the element in global physical pixels.
+   * 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
@@ -87,7 +109,13 @@ export declare class AccessibilityNode {
    *                           against each node's `overallDescription`
    * - `threshold`           – minimum score to keep a node
    */
-  scoredSearch(order: TraversalOrder, maxNodes: number, collapseStructural: boolean, query: string, threshold: number): Array<AccessibilityNode>
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
   /** Invoke / click the element (button, link, menu item). */
   activate(): void
   /** Set the text value of the element (textbox, combobox, …). */
@@ -112,22 +140,58 @@ export declare class AccessibilityNode {
  * ref-based actions for desktop automation (Windows UIA).
  */
 export declare class AccessibilityTree {
-  /** Create an accessibility tree bound to the current foreground window. */
+  /**
+   * Create an accessibility tree bound to the current foreground window.
+   *
+   * The foreground window is resolved **once** at construction time and
+   * the resulting identifier (HWND on Windows, PID on macOS) is stored
+   * — subsequent snapshots target that same window even if the user
+   * alt-tabs away.
+   */
   static fromForeground(): AccessibilityTree
-  /** Create an accessibility tree bound to the first visible window of a process. */
+  /**
+   * Create an accessibility tree bound to the first visible window of a
+   * process. The window is selected at construction time; subsequent
+   * snapshots target that same window.
+   */
   static fromPid(pid: number): AccessibilityTree
   /**
    * Create an accessibility tree from a platform-specific window identifier.
    * 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
-  /** Get the window handle as an integer ID. */
+  /**
+   * Get the window handle as an integer ID.
+   * On Windows this is the HWND; on macOS it is the PID.
+   */
   get windowId(): number
   /**
    * Take a snapshot of the window's accessibility tree.
    *
+   * Re-resolves the root through `Window::node()` so each call sees
+   * current data. On Windows the resolve issues a single
+   * `BuildUpdatedCache` IPC; the recursive walk over children and
+   * properties then stays entirely in-process, ~40× faster than
+   * walking a live `cached: false` root.
+   *
    * `visible_only` (default `false`) controls whether nodes whose
    * non-standard `AXVisible` attribute reads `false` are dropped from
    * the result.
@@ -183,7 +247,23 @@ export declare class AccessibilityTree {
    * Clears existing refs; returned nodes carry `refId` values usable
    * with action methods (`activate`, `setValue`, …).
    */
-  find(order: TraversalOrder, role?: AriaRole | undefined | null, name?: string | undefined | null, visibleOnly?: boolean | undefined | null, maxResults?: number | undefined | null, collapseStructural?: boolean | undefined | null): Array<AccessibilityNodeJs>
+  find(
+    order: TraversalOrder,
+    role?: AriaRole | undefined | null,
+    name?: string | undefined | null,
+    visibleOnly?: boolean | undefined | null,
+    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. */
@@ -214,7 +294,12 @@ export declare class App {
    * When `wait_for_load_complete` is true, this blocks for a short, fixed
    * delay to allow the app or URL to become responsive before returning.
    */
-  open(url: string | undefined | null, focusPolicy: FocusPolicy, visibility: Visibility, waitForLoadComplete: boolean): Instance
+  open(
+    url: string | undefined | null,
+    focusPolicy: FocusPolicy,
+    visibility: Visibility,
+    waitForLoadComplete: boolean,
+  ): Instance
 }
 
 /**
@@ -248,6 +333,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.
@@ -464,16 +560,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)`.
    */
@@ -489,7 +594,7 @@ export declare class Image {
    *
    * Grid squares have the specified `width` and `height`.
    */
-  addGrid(width: number, height: number): void
+  drawGrid(width: number, height: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -547,6 +652,8 @@ export declare class Instance {
   isFocused(): boolean
   /** Brings the instance to the foreground and gives it focus. */
   focus(): boolean
+  /** Returns all visible top-level windows belonging to this instance. */
+  windows(): Array<Window>
   content(): string
   /** Returns true if the instance has an accessibility tree. */
   isAccessible(): boolean
@@ -564,6 +671,19 @@ export declare class Instance {
    * instance, we should disable the accessibility tree to save resources.
    */
   disableAccessibility(): void
+  /**
+   * Request the application to exit gracefully. Returns when the request has
+   * been dispatched, not when the process has actually terminated; poll
+   * [`Self::is_running`] if you need to wait.
+   */
+  close(): void
+  /**
+   * Force-terminate immediately. The application gets no chance to save state
+   * or run cleanup handlers.
+   */
+  kill(): void
+  /** `true` if the underlying process is still running. Cheap, non-blocking. */
+  isRunning(): boolean
   /**
    * Search this application's accessibility tree by *concept text*, using
    * bag-of-words paired-Jaccard scoring against each node's
@@ -588,7 +708,13 @@ export declare class Instance {
    * methods (`activate`, `setValue`, …) directly on them, walk children
    * with `.children()`, or render a snapshot with `.snapshot()`.
    */
-  scoredSearch(order: TraversalOrder, maxNodes: number, collapseStructural: boolean, query: string, threshold: number): Array<AccessibilityNode>
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
 }
 
 /**
@@ -687,12 +813,35 @@ export declare class LoopbackSource {
 }
 
 /**
- * Contains functions to control the mouse and to get the location of
- * the cursor. A cartesian coordinate system is used for specifying
- * coordinates. The origin is located in the top-left corner of the
- * current screen, with positive values extending along the axes down
- * and to the right of the origin point and it is measured in pixels.
- * The same coordinate system is used on all operating systems.
+ * Contains functions to control the mouse and to get the cursor position.
+ *
+ * # Canonical coordinate space
+ *
+ * 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**.
+ *
+ * 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:
+ *
+ * - **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()
@@ -708,14 +857,14 @@ export declare class MouseController {
    * You can specify absolute coordinates or relative from the current
    * position.
    *
-   * If you use absolute coordinates, the top left corner of your
-   * monitor screen is x=0 y=0. Move the cursor down the screen by
-   * increasing the y and to the right by increasing x coordinate.
+   * 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.
    *
-   * If you use relative coordinates, a positive x value moves the
-   * mouse cursor `x` pixels to the right. A negative value for `x`
-   * moves the mouse cursor to the left. A positive value of y moves
-   * the mouse cursor down, a negative one moves the mouse cursor up.
+   * With relative coordinates, a positive `x` moves the cursor `x`
+   * pixels to the right; a positive `y` moves it down.
    */
   moveMouse(x: number, y: number, coordinate: Coordinate): void
   /**
@@ -725,7 +874,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]
 }
 
@@ -859,22 +1011,55 @@ export declare class SamplesBuffer {
   transcribe(model: SttModel): string
 }
 
-/** Represents a physical display/screen. */
+/** Represents a connected display/screen on the global desktop. */
 export declare class Screen {
-  /** Returns the screen identifier for the main screen. */
+  /** Returns the main / primary screen. */
   static mainScreen(): Screen
   /**
-   * Returns the screen identifier for the screen on which the mouse
-   * is located. If the mouse is not on any screen, the main screen
-   * is returned.
+   * Returns the screen on which the mouse cursor is located.
+   * Falls back to the main screen if the cursor is not on any
+   * connected display.
    */
   static fromCurrentMouseLocation(): Screen
   /**
-   * Returns the dimensions of the screen in pixels.
+   * Returns the screen the given window is on.
+   *
+   * "On" is the connected display that contains the largest area of
+   * [`Window.boundingBox`] — the same heuristic the OS uses to decide
+   * a window's "owning" screen, so the result matches what the system
+   * considers the window's screen (the one its window controls render
+   * on, the one full-screen mode targets, etc.).
+   *
+   * Throws if the window has no measurable overlap with any connected
+   * display — for example when the window is fully off-screen,
+   * minimised to an off-screen state, or on a virtual desktop with no
+   * attached display. There is no "correct" screen to pick in that
+   * case; callers that prefer a fallback can wrap in `try` / `catch`
+   * and call [`Screen.mainScreen`].
+   */
+  static fromWindow(window: Window): Screen
+  /**
+   * All currently connected displays.
+   *
+   * Order is platform-defined; do not rely on it. The result is a
+   * snapshot — connect / disconnect events that happen during the
+   * call are not signalled.
+   */
+  static all(): Array<Screen>
+  /**
+   * Live bounding box of the screen on the global desktop.
+   *
+   * 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
+   * [`Window.boundingBox`].
    *
-   * The return value is `[x, y, width, height]`.
+   * For just the size, read `right - left` and `bottom - top` on the
+   * returned box.
    */
-  dimensions(): [number, number, number, number]
+  boundingBox(): BoundingBox
 }
 
 /** Represents a screenshot capture. */
@@ -886,7 +1071,7 @@ export declare class Screenshot {
    *
    * Grid squares have the specified `width` and `height`.
    */
-  addGrid(width: number, height: number): void
+  drawGrid(width: number, height: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -916,23 +1101,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.
    *
-   * 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).
+   * 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 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)`.
    */
@@ -940,8 +1129,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 {
   /**
@@ -990,6 +1180,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
 }
@@ -1015,10 +1216,52 @@ 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 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.
+   */
+  boundingBox(): BoundingBox
+  /**
+   * The screen this window currently lives on.
+   *
+   * "Lives on" is the connected display that contains the largest
+   * area of [`Window.boundingBox`] — the same heuristic the OS uses
+   * to decide a window's "owning" screen, so the result matches what
+   * the system considers the window's screen (the one its window
+   * controls render on, the one full-screen mode targets, etc.).
+   *
+   * Throws if the window has no measurable overlap with any connected
+   * display. Callers that prefer a fallback can wrap in
+   * `try` / `catch` and call [`Screen.mainScreen`]. Equivalent to
+   * `Screen.fromWindow(window)`.
+   */
+  screen(): Screen
   /** Minimize the window (hide to taskbar / Dock). */
   minimize(): void
   /** Maximize / zoom the window. */
@@ -1028,6 +1271,57 @@ export declare class Window {
    * pressing Alt+F4 / Cmd+W).
    */
   close(): void
+  /**
+   * Bring this window to the foreground and give it keyboard focus.
+   *
+   * Platform notes:
+   * - **macOS**: activates the owning application and raises the
+   *   window via the accessibility `AXRaise` action.
+   * - **Windows**: `SetForegroundWindow` + `BringWindowToTop`.
+   *   Subject to the foreground-lock rules — may silently downgrade
+   *   to a taskbar flash if the foreground process hasn't granted
+   *   permission.
+   * - **Linux**: EWMH `_NET_ACTIVE_WINDOW` client message to the WM.
+   */
+  focus(): boolean
+  /**
+   * Move the cursor to a point inside this window.
+   *
+   * `(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.
+   *
+   * Does **not** focus the window. Call [`Window.focus`] (or
+   * [`Instance.focus`]) first if the click target requires the window
+   * to be active.
+   */
+  moveMouse(x: number, y: number): void
+  /**
+   * Press / release a mouse button at the cursor's current location.
+   *
+   * Provided for ergonomic parity with [`Window.moveMouse`] — combine
+   * the two for press / drag / release patterns. Takes no coordinate
+   * argument: pair with `moveMouse` when you need to control where the
+   * press lands.
+   */
+  button(button: Button, direction: Direction): void
+  /**
+   * 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`]).
+   * Does not focus the window.
+   */
+  click(x: number, y: number, button: Button, direction: Direction): void
+  /**
+   * Scroll the wheel by `(deltaX, deltaY)` ticks at the cursor's
+   * current location. Positive `deltaY` scrolls down; positive
+   * `deltaX` scrolls right. Does not reposition the cursor first —
+   * pair with [`Window.moveMouse`] if you need scrolling to happen at
+   * a specific point inside the window.
+   */
+  scroll(deltaX: number, deltaY: number): void
   /**
    * Render the window's accessibility subtree as an indented
    * Playwright-style aria snapshot.
@@ -1065,7 +1359,13 @@ export declare class Window {
    * methods (`activate`, `setValue`, …) directly on them, walk children
    * with `.children()`, or render a snapshot with `.snapshot()`.
    */
-  scoredSearch(order: TraversalOrder, maxNodes: number, collapseStructural: boolean, query: string, threshold: number): Array<AccessibilityNode>
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
 }
 
 export interface AccessibilityNodeJs {
@@ -1178,7 +1478,7 @@ export declare enum AriaRole {
   TreeItem = 84,
   Treegrid = 85,
   Video = 86,
-  Window = 87
+  Window = 87,
 }
 
 /**
@@ -1212,20 +1512,20 @@ export declare enum Button {
   ScrollUp = 5,
   ScrollDown = 6,
   ScrollLeft = 7,
-  ScrollRight = 8
+  ScrollRight = 8,
 }
 
 /** Specifies if coordinates are relative or absolute. */
 export declare enum Coordinate {
   Abs = 0,
-  Rel = 1
+  Rel = 1,
 }
 
 /** The direction of a button event. */
 export declare enum Direction {
   Press = 0,
   Release = 1,
-  Click = 2
+  Click = 2,
 }
 
 /** Enables the accessibility tree for the frontmost application. */
@@ -1239,7 +1539,7 @@ export declare enum FocusPolicy {
    */
   DoNotSteal = 0,
   /** Allow the launched app to become active/frontmost. */
-  Steal = 1
+  Steal = 1,
 }
 
 export declare function hasScreenCapturePermission(): boolean
@@ -1283,7 +1583,10 @@ export declare function hasScreenCapturePermission(): boolean
  * on forever. The callback itself runs on the Node main thread; the
  * non-blocking dispatch from Rust is what creates the recursion risk.
  */
-export declare function initLogger(cb?: (((arg: JsLogRecord) => unknown)) | undefined | null, spec?: string | undefined | null): void
+export declare function initLogger(
+  cb?: ((arg: JsLogRecord) => unknown) | undefined | null,
+  spec?: string | undefined | null,
+): void
 
 /** A single log entry forwarded to the JS callback. */
 export interface JsLogRecord {
@@ -1651,14 +1954,19 @@ export declare enum Key {
   /** Use `key_unicode` to provide the character. */
   Unicode = 290,
   /** Use `key_other` to provide the raw key value. */
-  Other = 291
+  Other = 291,
 }
 
 /** Convert a string representation into a `Key`. */
 export declare function keyFromString(value: string): Key
 
 /** Legacy helper used by Electron to open an app or URL. */
-export declare function legacyOpen(app: string | undefined | null, url: string | undefined | null, focusPolicy: FocusPolicy, visibility: Visibility): void
+export declare function legacyOpen(
+  app: string | undefined | null,
+  url: string | undefined | null,
+  focusPolicy: FocusPolicy,
+  visibility: Visibility,
+): void
 
 /** Legacy helper used by Electron to capture a screenshot as base64. */
 export declare function legacyTakeScreenshot(needsCompression: boolean, shrinkTo1080P: boolean): string
@@ -1672,7 +1980,13 @@ export declare function legacyTakeScreenshot(needsCompression: boolean, shrinkTo
 export declare function readFile(path: string): string
 
 /** Takes the screenshot of a cropped region of the workspace. */
-export declare function screenshotCropped(x: number, y: number, width: number, height: number, hideCursor: boolean): Screenshot
+export declare function screenshotCropped(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  hideCursor: boolean,
+): Screenshot
 
 /** Takes the screenshot of the entire selected screen */
 export declare function screenshotFull(hideCursor: boolean, screen: Screen): Screenshot
@@ -1682,7 +1996,7 @@ export declare enum TraversalOrder {
   /** Pre-order depth-first (each node before its descendants). */
   DepthFirst = 0,
   /** Level-order breadth-first (parents before children). */
-  BreadthFirst = 1
+  BreadthFirst = 1,
 }
 
 /** Visibility behavior when opening an application. */
@@ -1690,7 +2004,7 @@ export declare enum Visibility {
   /** Launch hidden when supported by the platform. */
   Hidden = 0,
   /** Launch in a visible state. */
-  Show = 1
+  Show = 1,
 }
 
 /**

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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      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.`)
       }
       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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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 !== '6.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 6.0.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         return binding
       } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simular-ai/simulang-js",
-  "version": "6.0.1",
+  "version": "8.0.0",
   "description": "Node.js bindings for simulang-rs",
   "main": "wrapped.js",
   "types": "./wrapped.d.ts",
@@ -36,6 +36,7 @@
     "index.js",
     "wrapped.d.ts",
     "wrapped.js",
+    "CHANGELOG.md",
     "CLAUDE.md",
     "bin/init-claude.mjs",
     "bin/postinstall-hint.mjs",
@@ -77,25 +78,25 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit && tsc --noEmit -p __test__/tsconfig.json && tsc --noEmit -p benchmark/tsconfig.json && tsc --noEmit -p bin/tsconfig.json && tsc --noEmit -p examples/tsconfig.json",
     "preversion": "napi build --platform && npm run typecheck && git add .",
-    "version": "napi version",
+    "version": "napi version && node scripts/stamp-changelog.mjs",
     "prepare": "husky"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.6.1",
+    "@napi-rs/cli": "^3.7.0",
     "@oxc-node/core": "^0.1.0",
     "@taplo/cli": "^0.7.0",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.9.1",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.2",
-    "npm-run-all2": "^8.0.4",
-    "oxlint": "^1.63.0",
+    "lint-staged": "^17.0.5",
+    "npm-run-all2": "^9.0.1",
+    "oxlint": "^1.67.0",
     "prettier": "^3.8.2",
     "tinybench": "^6.0.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-frontmatter": "^1.3.1",
     "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.7"
   },
   "lint-staged": {
     "*.@(js|ts|tsx)": [
@@ -116,11 +117,11 @@
     "arrowParens": "always"
   },
   "optionalDependencies": {
-    "@simular-ai/simulang-js-win32-x64-msvc": "6.0.1",
-    "@simular-ai/simulang-js-win32-arm64-msvc": "6.0.1",
-    "@simular-ai/simulang-js-darwin-x64": "6.0.1",
-    "@simular-ai/simulang-js-darwin-arm64": "6.0.1",
-    "@simular-ai/simulang-js-linux-x64-gnu": "6.0.1",
-    "@simular-ai/simulang-js-linux-arm64-gnu": "6.0.1"
+    "@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"
   }
 }