@simular-ai/simulang-js 9.0.0 → 10.0.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [10.0.0] - 2026-07-03
+
+### Added
+
+- `Window.focused()` — the window that currently has keyboard focus, or `null` when nothing is focused (no windows open, focus on the desktop, or the frontmost app has no focused window). The read-side counterpart to the instance method `Window.focus()`. Backed by `GetForegroundWindow` (Windows), the frontmost app's `AXFocusedWindow` (macOS), and `_NET_ACTIVE_WINDOW` (Linux); throws only on genuine backend failures.
+- `ImageGenModel` for generating images from a text prompt through a provider's `image_gen` service. `generate(prompt, quality?, aspectRatio?, images?)` returns a `[image, description]` tuple — the generated `Image` and the model's text description. `quality` (`ImageQuality.Fast` / `.Pro`) and `aspectRatio` (`ImageAspectRatio.Square`, `.Landscape16x9`, …) are type-safe enums defaulting to `Fast` / `Square`. Optional reference images are downscaled / transcoded and size-checked against the model's configured limits before sending. Discover aliases with `ImageGenModel.availableAliases()`; the bundled `simular_cloud` provider advertises `simular_image_gen`.
+- `Image.drawBox(bounds, thickness, red, green, blue)` and `Screenshot.drawBox(...)` — paint the outline of an axis-aligned `BoundingBox` (e.g. the result of `Window.boundingBox()` or `AccessibilityNode.boundingBox()`) with an inset border `thickness` pixels wide in an opaque RGB color. On `Image` the box is in image pixels; on `Screenshot` it is in **global desktop** coordinates (converted to image pixels internally), so a grounding or element box can be passed straight in. Out-of-bounds pixels are clipped; throws on zero thickness or a degenerate box (`right <= left` / `bottom <= top`). Companion to `drawDot` for annotating bounding boxes.
+
+### Breaking
+
+- `Screenshot.drawDot(x, y, ...)` now interprets `(x, y)` as **global desktop** coordinates (the same space `Screenshot.ground` returns and `MouseController` consumes) rather than screenshot image pixels; the point is converted to image pixels internally, inverting the capture offset and any resampling. This lets a `Screenshot.ground` result or an element's `boundingBox()` corner be drawn without manual conversion. Update call sites that passed raw image-pixel coordinates to `Screenshot.drawDot` to pass global desktop coordinates instead. `Image.drawDot` is unchanged (still image pixels).
+
 ## [9.0.0] - 2026-06-29
 
 ### Added

package/index.d.ts

@@ -644,6 +644,21 @@ export declare class Image {
    * captured rect.
    */
   drawDot(x: number, y: number, radius: number, red: number, green: number, blue: number): void
+  /**
+   * Draws the outline of the axis-aligned rectangle `bounds` on the image.
+   * Useful for visualizing bounding boxes returned from grounding, element /
+   * layout queries, ground-truth annotations, etc.
+   *
+   * `bounds` is in image-pixel coordinates and covers `[left, right) ×
+   * [top, bottom)` (`right` / `bottom` exclusive, matching a `BoundingBox`).
+   * The border is `thickness` pixels wide, drawn inset within that range so
+   * nothing is painted outside it, in the opaque RGB `(red, green, blue)`
+   * color. Pixels that fall outside the image bounds are silently clipped, so
+   * it is safe to call with a box that extends past the image. Throws when
+   * `thickness` is `0` or `bounds` is degenerate (`right <= left` or
+   * `bottom <= top`).
+   */
+  drawBox(bounds: BoundingBox, thickness: number, red: number, green: number, blue: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -691,6 +706,79 @@ export declare class Image {
   ground(model: GroundingModel, concept: string): [number, number]
 }
 
+/**
+ * A model for generating images from a text prompt (with optional reference
+ * images), speaking Simular's `v1/image-gen` wire contract.
+ *
+ * This targets a dedicated Simular endpoint rather than an `OpenAI`-compatible
+ * one; the endpoint picks the concrete backend model from the [`ImageQuality`]
+ * argument, so the resolved model `name` is nominal (used only for `name`).
+ * Reference images are downscaled / transcoded and size-checked against the
+ * model's configured image limits before sending, exactly as the VLM/LLM image
+ * paths do.
+ */
+export declare class ImageGenModel {
+  /**
+   * First image-gen model advertised by the first capable provider in the
+   * loaded configuration whose credentials are currently available.
+   * Providers that advertise the service but lack working credentials are
+   * skipped. Throws only if no provider is left after that filter.
+   */
+  static default(): ImageGenModel
+  /**
+   * Resolve a model alias against the loaded configuration.
+   *
+   * The alias is looked up across every loaded provider in alphabetical
+   * order; the first provider that advertises this alias wins. Throws if the
+   * alias is unknown.
+   */
+  static byAlias(alias: string): ImageGenModel
+  /** Convenience shim for the bundled Simular image-gen alias. */
+  static simularImageGen(): ImageGenModel
+  /**
+   * Every image-gen model alias advertised by the loaded configuration,
+   * deduplicated and sorted alphabetically. Use to discover what `byAlias`
+   * will accept on the current machine.
+   */
+  static availableAliases(): Array<string>
+  /**
+   * The model identifier from provider configuration. Nominal — the
+   * endpoint selects the concrete model from the [`ImageQuality`] argument.
+   */
+  get name(): string
+  /**
+   * Check that provider credentials work. Throws (and logs a warning) if they
+   * do not.
+   *
+   * Call right after creating the model so a bad key fails fast:
+   *
+   * ```ts
+   * try { model.checkAuth() } catch { process.exit(1) }
+   * ```
+   */
+  checkAuth(): void
+  /**
+   * Generate an image from `prompt`.
+   *
+   * - `prompt`: a description of the image to generate.
+   * - `quality`: selects the model tier; defaults to `ImageQuality.Fast`.
+   * - `aspectRatio`: the output shape; defaults to `ImageAspectRatio.Square`.
+   * - `images`: reference images (count capped by the model's configured
+   *   `max_images_per_request` image limit) that condition the result; each is
+   *   downscaled / transcoded to a supported format and size-checked before
+   *   sending. Pass `null` / omit for none.
+   *
+   * Returns a `[image, description]` tuple: the first generated [`Image`] and
+   * the model's text description (an empty string when the model returns none).
+   */
+  generate(
+    prompt: string,
+    quality?: ImageQuality | undefined | null,
+    aspectRatio?: ImageAspectRatio | undefined | null,
+    images?: Array<Image> | undefined | null,
+  ): [Image, string]
+}
+
 /** Represents an opened application instance. */
 export declare class Instance {
   /** Get the process ID of the opened application (returns 0 when unknown). */
@@ -1124,20 +1212,39 @@ export declare class Screenshot {
    */
   drawGrid(width: number, height: number): void
   /**
-   * Paints a filled disc on the image. Useful for visualizing point
-   * coordinates returned from grounding, layout queries, etc.
+   * Paints a filled disc on the screenshot. Useful for visualizing point
+   * coordinates returned from grounding, element / 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).
+   * `x` / `y` are **global desktop** coordinates (the same space
+   * `Screenshot.ground` returns and `MouseController` consumes), which are
+   * converted to image pixels — inverting the capture offset and any
+   * resampling — before drawing. So a `ground(...)` result or an element's
+   * `boundingBox()` corner can be passed straight in. `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.
+   * Coordinates that map outside the image bounds silently produce no pixel,
+   * so the helper is safe to call even for points that fall outside the
+   * captured region.
    */
   drawDot(x: number, y: number, radius: number, red: number, green: number, blue: number): void
+  /**
+   * Draws the outline of the axis-aligned rectangle `bounds` on the
+   * screenshot. Useful for visualizing bounding boxes returned from grounding,
+   * element / window `boundingBox()` queries, ground-truth annotations, etc.
+   *
+   * `bounds` is in **global desktop** coordinates (the same space element /
+   * window `boundingBox()` and grounding results use); its corners are
+   * converted to image pixels — inverting the capture offset and any
+   * resampling — before drawing, so an element's `boundingBox()` can be passed
+   * straight in. It covers `[left, right) × [top, bottom)` (`right` / `bottom`
+   * exclusive). The border is `thickness` pixels wide, drawn inset, in the
+   * opaque RGB `(red, green, blue)` color. Pixels that map outside the image
+   * bounds are silently clipped. Throws when `thickness` is `0` or `bounds` is
+   * degenerate (`right <= left` or `bottom <= top`).
+   */
+  drawBox(bounds: BoundingBox, thickness: number, red: number, green: number, blue: number): void
   /**
    * Compress the image by converting it to JPEG with the specified quality.
    *
@@ -1341,6 +1448,24 @@ export declare class Window {
    * - **Linux**: always `null` (no per-point window hit-test).
    */
   static fromPoint(x: number, y: number): Window | null
+  /**
+   * The window that currently has keyboard focus, if any.
+   *
+   * Returns `null` when nothing is focused (e.g. no windows open, focus is on
+   * the desktop, or the frontmost app has no focused window) rather than
+   * treating that as an error. Throwing is reserved for genuine backend
+   * failures.
+   *
+   * Platform notes:
+   * - **Windows**: `GetForegroundWindow` — the top-level window of the
+   *   foreground thread. Never throws; `null` only when there is no
+   *   foreground window at all.
+   * - **macOS**: the frontmost running application's `AXFocusedWindow`
+   *   attribute. `null` when there is no frontmost app, or the frontmost app
+   *   has no focused window (e.g. all its windows are minimized).
+   * - **Linux**: EWMH `_NET_ACTIVE_WINDOW` root-window property.
+   */
+  static focused(): Window | null
   /** Window title (may be empty). */
   get title(): string
   /** Process ID that owns this window. */
@@ -1700,6 +1825,37 @@ export declare enum FocusPolicy {
 
 export declare function hasScreenCapturePermission(): boolean
 
+/** Aspect ratio of the generated image. */
+export declare enum ImageAspectRatio {
+  /** `1:1` square. Default. */
+  Square = 0,
+  /** `16:9` widescreen landscape. */
+  Landscape16x9 = 1,
+  /** `9:16` tall portrait. */
+  Portrait9x16 = 2,
+  /** `4:3` landscape. */
+  Landscape4x3 = 3,
+  /** `3:4` portrait. */
+  Portrait3x4 = 4,
+  /** `3:2` landscape. */
+  Landscape3x2 = 5,
+  /** `2:3` portrait. */
+  Portrait2x3 = 6,
+}
+
+/**
+ * Output image quality / model tier for [`ImageGenModel.generate`].
+ *
+ * The image-gen endpoint selects the underlying model from this value, so it
+ * is a per-request parameter rather than a config-resolved model name.
+ */
+export declare enum ImageQuality {
+  /** Faster, cheaper tier. Default. */
+  Fast = 0,
+  /** Higher-fidelity tier. */
+  Pro = 1,
+}
+
 /**
  * Initialize the logger.
  *

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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.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 !== '9.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 9.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '10.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 10.0.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -596,6 +596,7 @@ module.exports.Directory = nativeBinding.Directory
 module.exports.File = nativeBinding.File
 module.exports.GroundingModel = nativeBinding.GroundingModel
 module.exports.Image = nativeBinding.Image
+module.exports.ImageGenModel = nativeBinding.ImageGenModel
 module.exports.Instance = nativeBinding.Instance
 module.exports.KeyboardController = nativeBinding.KeyboardController
 module.exports.LoopbackSource = nativeBinding.LoopbackSource
@@ -617,6 +618,8 @@ module.exports.Direction = nativeBinding.Direction
 module.exports.enableAccessibilityForFrontmostApp = nativeBinding.enableAccessibilityForFrontmostApp
 module.exports.FocusPolicy = nativeBinding.FocusPolicy
 module.exports.hasScreenCapturePermission = nativeBinding.hasScreenCapturePermission
+module.exports.ImageAspectRatio = nativeBinding.ImageAspectRatio
+module.exports.ImageQuality = nativeBinding.ImageQuality
 module.exports.initLogger = nativeBinding.initLogger
 module.exports.Key = nativeBinding.Key
 module.exports.keyFromString = nativeBinding.keyFromString

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simular-ai/simulang-js",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Node.js bindings for simulang-rs",
   "main": "wrapped.js",
   "types": "./wrapped.d.ts",
@@ -91,11 +91,11 @@
     "@napi-rs/cli": "^3.7.2",
     "@oxc-node/core": "^0.1.0",
     "@taplo/cli": "^0.7.0",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.0.1",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
     "npm-run-all2": "^9.0.2",
-    "oxlint": "^1.70.0",
+    "oxlint": "^1.71.0",
     "prettier": "^3.8.4",
     "tinybench": "^6.0.0",
     "typedoc": "^0.28.19",
@@ -105,7 +105,7 @@
     "vitest": "^4.1.9"
   },
   "lint-staged": {
-    "*.@(js|ts|tsx)": [
+    "*.@(js|mjs|cjs|ts|tsx)": [
       "oxlint --fix"
     ],
     "*.@(js|ts|tsx|yml|yaml|md|json)": [
@@ -123,11 +123,11 @@
     "arrowParens": "always"
   },
   "optionalDependencies": {
-    "@simular-ai/simulang-js-win32-x64-msvc": "9.0.0",
-    "@simular-ai/simulang-js-win32-arm64-msvc": "9.0.0",
-    "@simular-ai/simulang-js-darwin-x64": "9.0.0",
-    "@simular-ai/simulang-js-darwin-arm64": "9.0.0",
-    "@simular-ai/simulang-js-linux-x64-gnu": "9.0.0",
-    "@simular-ai/simulang-js-linux-arm64-gnu": "9.0.0"
+    "@simular-ai/simulang-js-win32-x64-msvc": "10.0.0",
+    "@simular-ai/simulang-js-win32-arm64-msvc": "10.0.0",
+    "@simular-ai/simulang-js-darwin-x64": "10.0.0",
+    "@simular-ai/simulang-js-darwin-arm64": "10.0.0",
+    "@simular-ai/simulang-js-linux-x64-gnu": "10.0.0",
+    "@simular-ai/simulang-js-linux-arm64-gnu": "10.0.0"
   }
 }

package/sai.js

@@ -589,7 +589,7 @@ function readFile(params) {
 
 function writeToFile(params) {
   const { text, path = 'SimularActionResult.txt', overwrite = false } = params
-  const append = overwrite ? false : true
+  const append = !overwrite
   return binding().writeFile(path, text, append)
 }
 
@@ -630,7 +630,7 @@ function stateSatisfies(params) {
     const { text, imageBase64 } = pageContent()
     return StateSatisfiesModel.default().stateSatisfies(condition, text, imageBase64)
   } catch (error) {
-    throw new Error(`Failed to check state condition: ${error}`)
+    throw new Error(`Failed to check state condition: ${error}`, { cause: error })
   }
 }