@simular-ai/simulib-js 5.4.3

package/CLAUDE.md

@@ -0,0 +1,78 @@
+# `@simular-ai/simulib-js`
+
+Node.js bindings for the Rust `simulib-rs` crate (via napi-rs). Cross-platform
+desktop automation: apps, windows, accessibility trees, mouse/keyboard,
+screenshots, clipboard, audio, and VLM/STT model access.
+
+This file ships in the npm tarball alongside `index.d.ts` and is versioned
+with it.
+
+## Where the API is documented
+
+Read **`index.d.ts`** first — it is the source of truth. Every class,
+function, and enum is fully typed (~1500 lines) and carries JSDoc covering
+idioms, lifecycle rules, platform quirks, and inter-API trade-offs that types
+alone can't express. The JSDoc is generated from doc comments,
+so the per-symbol guidance there is authoritative — trust it over any
+restatement elsewhere.
+
+## Mental model
+
+- Calls into the native module are **synchronous**. No Promises are returned;
+  `Result::Err` on the Rust side is translated to a thrown JS exception by
+  napi-rs, so JS callers `try`/`catch` as usual.
+- Many objects are **handles to platform resources** (windows, audio devices,
+  accessibility trees, file/directory handles). Their lifetime matters;
+  dropping them can free the underlying resource.
+- Coordinates are uniform across platforms: **top-left origin, global
+  physical pixels** (also called device pixels — the raw hardware pixels of
+  the display, not the logical / CSS / point units used in browsers and
+  some desktop UI frameworks). On a 2× HiDPI display, a 1920×1080-logical
+  screen is 3840×2160 in these coordinates. Image and screenshot dimensions
+  are likewise in physical pixels.
+
+## Live log viewer (optional)
+
+`@simular-ai/simulib-log-viewer` is a **human-facing aid**: a floating,
+always-on-top log window that lets the person running the script watch
+log records in real time when stdout is hidden behind the app
+being driven. Suggest it when the user is writing an interactive
+automation script and would benefit from live visibility; skip it for
+headless / CI / unattended runs (no human is there to watch the window,
+and it adds a window-spawning subprocess for no benefit). **Optional peer
+dependency — install it explicitly.**
+
+The window is **click-through by default**, so mouse input passes straight
+through to whatever is underneath and never interferes with the app being
+automated. On macOS it is also excluded from screen captures system-wide
+(via `NSWindowSharingNone`), so `screenshotFull` / `screenshotCropped` and
+any other capture tool won't include the viewer in the result. A global
+hotkey (`Ctrl+Shift+Option+L` on macOS, `Ctrl+Shift+Alt+L` everywhere
+else, also shown inside the window) toggles "grab mode": pressing it once
+turns click-through off, pauses execution, and makes the window draggable;
+pressing it again restores click-through and resumes.
+
+Wire it up via `initLogger` and respect the pause inside automation loops:
+
+```js
+import { initLogger } from '@simular-ai/simulib-js'
+import { LogWindow } from '@simular-ai/simulib-log-viewer'
+
+const win = new LogWindow()
+win.spawn()
+initLogger((rec) => win.log(`[${rec.level}] [${rec.target}] ${rec.message}`), 'info')
+
+// Yield while the user has paused the viewer (e.g. to drag it).
+await win.waitIfPaused()
+```
+
+The second argument to `initLogger` is a filter spec in the `RUST_LOG`
+environment-variable syntax used by Rust's `env_logger` / `log` crates —
+e.g. `'info'` for a global level, `'simulib_rs=debug,warn'` for per-module
+scoping. Omit it to inherit the value of the `RUST_LOG` env var (or fall
+back to `'error'` if it's unset). See `initLogger`'s JSDoc in
+`index.d.ts` for the full grammar.
+
+Other methods: `clear()` drops displayed messages, `isPaused` getter for a
+non-blocking check, `close()` to shut the viewer (also automatic on parent
+exit).

package/LICENSE

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

package/README.md

@@ -0,0 +1,75 @@
+# `@simular-ai/simulib-js`
+
+![CI](https://github.com/simular-ai/simulib-js/workflows/CI/badge.svg)
+
+Node.js bindings for [`simulib-rs`](https://github.com/simular-ai/simulib-rs), a Rust crate published by [Simular](https://simular.ai), built with [`napi-rs`](https://napi.rs/). Provides high-level primitives for desktop automation — keyboard and mouse input, screenshots, clipboard access, audio capture, accessibility-tree inspection, and more — exposed through idiomatic JavaScript. Ships TypeScript definitions auto-generated from the Rust source, so the types always match runtime behavior.
+
+## Install
+
+```bash
+npm install @simular-ai/simulib-js
+```
+
+Prebuilt native binaries are published for:
+
+| Platform | Architecture                        |
+| -------- | ----------------------------------- |
+| macOS    | `aarch64` (Apple Silicon), `x86_64` |
+| Windows  | `x86_64`, `aarch64`                 |
+| Linux    | `x86_64`, `aarch64` (glibc)         |
+
+Node.js **20 or newer** is required. If your platform isn't covered, see [Building from source](#building-from-source).
+
+### Optional — install the log viewer
+
+The [`log-window.mjs`](./examples/log-window.mjs) example uses [`@simular-ai/simulib-log-viewer`](https://github.com/simular-ai/simulib-log-viewer), which is declared as an **optional peer dependency** and **not** installed by default. Install it only if you want to run that example or use the same pattern in your own code:
+
+```bash
+npm install @simular-ai/simulib-log-viewer
+```
+
+## Usage
+
+Try the included [`google_search.mjs`](./examples/google_search.mjs) example — it opens Google in Chrome, enables the accessibility tree, takes a screenshot, and displays it:
+
+```bash
+# With the simulang CLI (no local install needed):
+npm install -g @simular-ai/simulang
+simulang run examples/google_search.mjs
+
+# Or directly with Node.js if you have simulib-js installed locally:
+node examples/google_search.mjs
+```
+
+## API documentation
+
+Browse the [API reference](https://docs.simular.ai/simulib-js/api/latest/) for more details. A bleeding-edge preview of HEAD on `main` is also published to [GitHub Pages](https://simular-ai.github.io/simulib-js/) between releases.
+
+## Using with Claude Code
+
+This package ships a short [`CLAUDE.md`](./CLAUDE.md) inside the npm tarball that points Claude Code at `index.d.ts` as the source of truth for the API and adds a few cross-cutting notes that types alone can't express (lifetime rules, coordinate system, etc.). Wire it into your project's `CLAUDE.md` with:
+
+```bash
+npx simulib-init-claude          # appends to <project>/CLAUDE.md (creates it if missing)
+npx simulib-init-claude --user   # appends to ~/.claude/CLAUDE.md instead
+npx simulib-init-claude --check  # report status, don't write
+```
+
+The added line is a single `@./node_modules/@simular-ai/simulib-js/CLAUDE.md` import inside a sentinel-delimited block — safe to re-run, no-op when already present.
+
+## Relationship to `simulang`
+
+[`@simular-ai/simulang`](https://github.com/simular-ai/simulang-cli) is a CLI that runs desktop automation scripts (`.ts`, `.js`, `.simulang`) using this package. It bundles `simulib-js` and re-exports the full API to scripts, so you can write and run automation scripts without a build step:
+
+```bash
+npm install -g @simular-ai/simulang
+simulang run my-script.js
+```
+
+`simulib-js` is the underlying primitive library; `simulang` is the batteries-included script runner built on top of it. If you are embedding desktop automation into your own Node.js application, depend on `simulib-js` directly. If you just want to run standalone automation scripts, `simulang` is the easier starting point.
+
+You can also point `simulang` at a local `simulib-js` checkout during development:
+
+```bash
+simulang run --simulib=/path/to/simulib-js my-script.js
+```

package/bin/init-claude.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Wire up Claude Code to read this package's CLAUDE.md by appending one
+// idempotent import line to <project>/CLAUDE.md (or ~/.claude/CLAUDE.md
+// with --user). Re-running is a no-op.
+//
+// Usage (after `npm install @simular-ai/simulib-js`):
+//   npx simulib-init-claude          # update <project>/CLAUDE.md
+//   npx simulib-init-claude --user   # update ~/.claude/CLAUDE.md
+//   npx simulib-init-claude --check  # report status, don't write
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PKG = '@simular-ai/simulib-js'
+const BEGIN = `<!-- ${PKG}:claude-import:begin -->`
+const END = `<!-- ${PKG}:claude-import:end -->`
+const BLOCK_RE = new RegExp(`${BEGIN}[\\s\\S]*?${END}\\n?`)
+
+/** @type {{ user: boolean, check: boolean, help: boolean }} */
+const flags = { user: false, check: false, help: false }
+for (const a of process.argv.slice(2)) {
+  if (a === '--user') flags.user = true
+  else if (a === '--check') flags.check = true
+  else if (a === '--help' || a === '-h') flags.help = true
+  else {
+    process.stderr.write(`Unknown flag: ${a}\n`)
+    process.exit(2)
+  }
+}
+
+if (flags.help) {
+  process.stdout.write(
+    `Usage: simulib-init-claude [--user] [--check]\n` +
+      `  Point Claude Code at ${PKG}/CLAUDE.md so it knows how to use this library.\n` +
+      `  --user   Target ~/.claude/CLAUDE.md instead of <project>/CLAUDE.md.\n` +
+      `  --check  Report status without writing.\n`,
+  )
+  process.exit(0)
+}
+
+// We live at <pkgRoot>/bin/init-claude.mjs in the package, so the doc is two
+// levels up — no need to walk the filesystem for it.
+const docPath = join(dirname(dirname(fileURLToPath(import.meta.url))), 'CLAUDE.md')
+
+/**
+ * Walk up from `start` looking for the consumer's package.json (i.e. one that
+ * isn't ours). Returns the directory or null if we hit the filesystem root.
+ * @param {string} start
+ */
+function findProjectRoot(start) {
+  for (let dir = start; ; dir = dirname(dir)) {
+    try {
+      /** @type {{ name?: string }} */
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+      if (pkg.name !== PKG) return dir
+    } catch {
+      // No readable package.json here — keep walking.
+    }
+    if (dirname(dir) === dir) return null
+  }
+}
+
+let targetMd, importLine
+if (flags.user) {
+  targetMd = join(homedir(), '.claude', 'CLAUDE.md')
+  // Absolute path — node_modules location isn't predictable from ~/.claude.
+  importLine = `@${docPath}`
+} else {
+  const projectRoot = findProjectRoot(process.cwd())
+  if (!projectRoot) {
+    process.stderr.write(`No project package.json found from ${process.cwd()}.\nRun inside a project, or use --user.\n`)
+    process.exit(1)
+  }
+  targetMd = join(projectRoot, 'CLAUDE.md')
+  const rel = relative(projectRoot, docPath)
+  // Project-relative path keeps the import portable across machines.
+  importLine = `@${rel.startsWith('.') ? rel : `./${rel}`}`
+}
+// Claude Code's @import resolver expects POSIX-style paths. On Windows,
+// path.relative / path.join produce backslashes — normalise here so the
+// resulting CLAUDE.md is identical on every OS.
+importLine = importLine.replaceAll('\\', '/')
+
+const block = `${BEGIN}\n${importLine}\n${END}\n`
+const existing = existsSync(targetMd) ? readFileSync(targetMd, 'utf8') : ''
+
+if (existing.includes(block)) {
+  process.stdout.write(`${PKG}: ${targetMd} already imports the doc — no change.\n`)
+  process.exit(0)
+}
+if (flags.check) {
+  process.stdout.write(`${PKG}: ${targetMd} would be ${existing ? 'updated' : 'created'}.\n`)
+  process.exit(0)
+}
+
+// Replace an existing block (handles import-line changes) or append a fresh
+// one after a blank line. Trimming trailing newlines normalises the spacing.
+const trimmed = existing.replace(/\n+$/, '')
+const next = BLOCK_RE.test(existing) ? existing.replace(BLOCK_RE, block) : trimmed ? `${trimmed}\n\n${block}` : block
+
+mkdirSync(dirname(targetMd), { recursive: true })
+writeFileSync(targetMd, next)
+process.stdout.write(`${PKG}: ${existing ? 'updated' : 'created'} ${targetMd}\n`)

package/bin/postinstall-hint.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Postinstall hint for `@simular-ai/simulib-js`. Prints exactly one line if
+// the user appears to be a Claude Code user, otherwise silent. Swallows all
+// errors — a broken hint must never break `npm install`.
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+function shouldPrint() {
+  // Skip when the maintainer is running `npm install` in this repo itself —
+  // `import.meta.url` only contains a `node_modules` segment when this
+  // package has been installed as a dependency of another project.
+  if (!import.meta.url.includes('/node_modules/')) return false
+  if (!process.stdout.isTTY) return false
+  if (process.env.CI) return false
+  if (process.env.npm_command === 'ci') return false
+  const loglevel = (process.env.npm_config_loglevel ?? '').toLowerCase()
+  if (loglevel === 'silent' || loglevel === 'error' || loglevel === 'warn') return false
+  if (!existsSync(join(homedir(), '.claude'))) return false
+  return true
+}
+
+try {
+  if (shouldPrint()) {
+    process.stdout.write(
+      '@simular-ai/simulib-js: Claude Code detected. Run `npx @simular-ai/simulib-js init-claude` to point it at the bundled API docs.\n',
+    )
+  }
+} catch {
+  // Never propagate failures from the hint.
+}

package/examples/README.md

@@ -0,0 +1,53 @@
+# Examples
+
+Runnable snippets demonstrating common `@simular-ai/simulib-js` APIs. All files are plain ESM JavaScript — no TypeScript or extra tooling needed.
+
+> Install the package first if you haven't already — see the [main README](../README.md#install).
+
+Run an example out of `node_modules`:
+
+```bash
+node node_modules/@simular-ai/simulib-js/examples/system.mjs
+```
+
+Or copy a file into your own project to tweak it:
+
+```bash
+cp node_modules/@simular-ai/simulib-js/examples/screenshot.mjs ./
+node screenshot.mjs
+```
+
+## What each example does
+
+| File                              | Description                                                                                                                                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `system.mjs`                      | Opens a URL in the default browser.                                                                                                                                                         |
+| `file-trait.mjs`                  | Writes a text file and reads it back.                                                                                                                                                       |
+| `clipboard.mjs`                   | Reads, writes, pastes, and clears the system clipboard.                                                                                                                                     |
+| `keyboard.mjs`                    | Synthesizes keyboard input (types a string and sends key events).                                                                                                                           |
+| `screenshot.mjs`                  | Captures the main screen, resizes and compresses the image, saves to disk.                                                                                                                  |
+| `google_search.mjs`               | End-to-end flow: launches Chrome, navigates, captures a screenshot.                                                                                                                         |
+| `accessibility.mjs`               | Lists windows, snapshots the foreground accessibility tree, queries actions.                                                                                                                |
+| `chrome_google_search_button.mjs` | Opens google.com in Chrome and locates the search button by _concept text_, using BoW Jaccard scoring over `overallDescription`.                                                            |
+| `open-app.mjs`                    | Opens an app, lists its windows, snapshots its accessibility tree.                                                                                                                          |
+| `loopback.mjs`                    | Plays an audio file while capturing system audio, then transcribes it.                                                                                                                      |
+| `logger.mjs`                      | Forwards Rust `log` records to a JS callback (env_logger-style filter spec).                                                                                                                |
+| `log-window.mjs`                  | Pipes Rust `log::*!` records into a floating, always-on-top log window. Requires the optional [`@simular-ai/simulib-log-viewer`](../README.md#3-optional--install-the-log-viewer) peer dep. |
+
+## Heads up — these examples affect your system
+
+Unlike a sandboxed library call, most of these examples perform **real actions** on your machine:
+
+- `keyboard.mjs` and `google_search.mjs` synthesize keystrokes — make sure the intended window is focused, or text will land somewhere unexpected.
+- `clipboard.mjs` overwrites your current clipboard contents (it restores them at the end).
+- `screenshot.mjs`, `google_search.mjs`, and `loopback.mjs` capture your screen or system audio.
+- `system.mjs` and `google_search.mjs` launch a browser window.
+
+### Required OS permissions
+
+On **macOS**, the first run of certain examples will prompt for permissions. Grant these in **System Settings → Privacy & Security**:
+
+- **Accessibility** — required for keyboard/mouse input and accessibility-tree reads (`keyboard.mjs`, `google_search.mjs`).
+- **Screen Recording** — required for screen capture and audio loopback (`screenshot.mjs`, `google_search.mjs`, `loopback.mjs`).
+
+The permission is granted to the process that launches Node (e.g. your terminal application), not to Node itself.

package/examples/accessibility.mjs

@@ -0,0 +1,45 @@
+// Run: node examples/accessibility.mjs
+// Tests AccessibilityTree: list windows, snapshot foreground, query actions.
+
+import { AccessibilityTree, AriaRole, ariaRoleToString, Window } from '@simular-ai/simulib-js'
+
+// 1. List all windows
+const windows = Window.all()
+console.log(`=== All visible windows (${windows.length}) ===`)
+windows.slice(0, 5).forEach((w) => console.log(`  pid=${w.pid} "${w.title}"`))
+console.log()
+
+// 2. Snapshot foreground window
+const tree = AccessibilityTree.fromForeground()
+console.log(`Bound to: "${tree.windowTitle}"`)
+
+const root = tree.snapshot()
+console.log(`Role: ${ariaRoleToString(root.role)}`)
+console.log(`Children: ${root.children.length}`)
+
+// Print the whole tree as an indented Playwright-style aria snapshot,
+// the same format as `WindowTrait::snapshot()` / the `print_ax_tree`
+// example in simulib-rs.
+/**
+ * @param {import('@simular-ai/simulib-js').AccessibilityNodeJs} node
+ * @param {number} [depth]
+ */
+function printSnapshot(node, depth = 0) {
+  const indent = '  '.repeat(depth)
+  let line = `${indent}- ${ariaRoleToString(node.role)}`
+  if (node.name) line += ` ${JSON.stringify(node.name)}`
+  if (node.value) line += `: ${JSON.stringify(node.value)}`
+  console.log(line)
+  for (const child of node.children) printSnapshot(child, depth + 1)
+}
+
+console.log('\n=== Snapshot ===')
+printSnapshot(root)
+
+// 3. Test actions on first button
+const firstButton = root.children.find((c) => c.role === AriaRole.Button && c.refId != null)
+if (firstButton && firstButton.refId != null) {
+  console.log(`\nFirst button: "${firstButton.name}" [ref=${firstButton.refId}]`)
+  console.log('Actions:', tree.getSupportedActions(firstButton.refId))
+  console.log('Bounds:', tree.getBounds(firstButton.refId))
+}

package/examples/chrome_google_search_button.mjs

@@ -0,0 +1,88 @@
+// Run: node examples/chrome_google_search_button.mjs
+//
+// Open Google Chrome on https://www.google.com and locate the main search
+// control by *concept text*, using `Instance.scoredSearch` — a thin binding
+// over `simulib_rs::Instance::scored_search` + `BowJaccard` paired-Jaccard
+// scoring against each node's `summary_with_context`.
+//
+// This is the JS analog of
+// `simulib-rs/examples/chrome_google_search_button.rs`.
+//
+// Requirements:
+//   - Windows or macOS
+//   - Google Chrome installed
+//   - On macOS: Accessibility permission granted to the process running Node.
+
+import {
+  AccessibilityTree,
+  App,
+  FocusPolicy,
+  TraversalOrder,
+  Visibility,
+  Window,
+  ariaRoleToString,
+} from '@simular-ai/simulib-js'
+
+/** Natural-language concept matched against each node's `overallDescription`. */
+const CONCEPT = 'Auf gut Glück'
+
+/** Match threshold (same default as the Rust example). */
+const MATCH_THRESHOLD = 0.75
+
+/** Upper bound on nodes visited so a pathological Chromium tree can't run unbounded. */
+const MAX_NODES_VISITED = 50_000
+
+const browser = process.platform === 'darwin' ? 'Google Chrome' : 'Chrome'
+
+/** @param {number} timeoutMs */
+async function waitForChromeForeground(timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      const title = AccessibilityTree.fromForeground().windowTitle.toLowerCase()
+      if (title.includes('chrome') || title.includes('chromium') || title.includes('谷歌')) {
+        return
+      }
+    } catch {
+      // ignore – the foreground app may not be accessible yet
+    }
+    await new Promise((r) => setTimeout(r, 200))
+  }
+  throw new Error(`Chrome did not become the foreground window within ${timeoutMs} ms`)
+}
+
+const instance = App.exactName(browser).open('https://www.google.com', FocusPolicy.Steal, Visibility.Show, true)
+console.log(`Opened ${browser} (pid=${instance.pid})`)
+
+await new Promise((r) => setTimeout(r, 2000))
+await waitForChromeForeground(45_000)
+
+// Chrome ships with its accessibility tree disabled by default for perf. Turn
+// it on for this process and give it a moment to populate.
+instance.enableAccessibility()
+await new Promise((r) => setTimeout(r, 3000))
+
+const matches = instance.scoredSearch(TraversalOrder.BreadthFirst, MAX_NODES_VISITED, false, CONCEPT, MATCH_THRESHOLD)
+
+const button = matches[0]
+if (!button) {
+  throw new Error(
+    `No node scored above ${MATCH_THRESHOLD} on concept ${JSON.stringify(CONCEPT)} ` +
+      `within ${MAX_NODES_VISITED} BFS nodes. Try another CONCEPT for your locale, ` +
+      `close overlays, or wait for the page to finish loading.`,
+  )
+}
+
+console.log(`Found accessibility node for concept ${JSON.stringify(CONCEPT)}:`)
+console.log(`  role:                ${ariaRoleToString(button.role)}`)
+console.log(`  name:                ${button.name}`)
+console.log(`  overallDescription:  ${button.overallDescription}`)
+console.log(`  supportedActions:    ${JSON.stringify(button.supportedActions())}`)
+// Action methods (`button.activate()`, `button.setValue(...)`, …) are
+// available directly on the returned `AccessibilityNode`.
+
+console.log('\nMinimizing Chrome window…')
+const [chromeWindow] = Window.allForPid(instance.pid)
+if (!chromeWindow) throw new Error('no windows found for instance')
+chromeWindow.minimize()
+console.log('Window should be minimized.')

package/examples/clipboard.mjs

@@ -0,0 +1,29 @@
+// Run: node examples/clipboard.mjs
+// This example reads and writes the clipboard.
+
+import { Clipboard } from '@simular-ai/simulib-js'
+
+console.log('Waiting three seconds...')
+await new Promise((resolve) => setTimeout(resolve, 3000))
+
+const clipboard = new Clipboard()
+
+const previous = clipboard.setString('Hello from simulib-js')
+const current = clipboard.getString()
+
+console.log('Previous clipboard:', previous)
+console.log('Current clipboard:', current)
+
+// Paste text by simulating Cmd/Ctrl+V.
+clipboard.pasteText('Pasted from simulib-js')
+
+clipboard.clear()
+
+const afterClear = clipboard.getString()
+console.log('After clear:', afterClear)
+
+// Restore previous clipboard content if it existed.
+if (previous !== null) {
+  console.log('Restored previous clipboard:')
+  clipboard.setString(previous)
+}

package/examples/file-trait.mjs

@@ -0,0 +1,8 @@
+// Run: node examples/file-trait.mjs
+// This example writes a file and reads it back.
+
+import { readFile, writeFile } from '@simular-ai/simulib-js'
+
+const writtenPath = writeFile('simulib-js-example.txt', 'hello from simulib-js', false)
+console.log('Wrote file:', writtenPath)
+console.log('Read file:', readFile(writtenPath))

package/examples/google_search.mjs

@@ -0,0 +1,59 @@
+// Run: node examples/google_search.mjs
+// This example opens Google in Chrome.
+
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import {
+  App,
+  KeyboardController,
+  Key,
+  Direction,
+  FocusPolicy,
+  Visibility,
+  Screen,
+  enableAccessibilityForFrontmostApp,
+  screenshotFull,
+} from '@simular-ai/simulib-js'
+
+const browser = process.platform === 'darwin' ? 'Google Chrome' : 'Chrome'
+const imageViewer = process.platform === 'darwin' ? 'Preview' : 'Chrome'
+const modifierKey = process.platform === 'darwin' ? Key.Meta : Key.Control
+
+// Open a URL in Chrome
+App.exactName(browser).open('https://google.com', FocusPolicy.Steal, Visibility.Show, true)
+console.log('Launched Google Chrome')
+
+// Wait two seconds to give Chrome time to start
+console.log('Waiting two seconds...')
+await new Promise((resolve) => setTimeout(resolve, 2000))
+
+const foreground = new KeyboardController()
+
+// Independent of keyboard layout
+foreground.keyUnicode('z', Direction.Click)
+await new Promise((resolve) => setTimeout(resolve, 1000))
+
+// Open the accessibility menu
+foreground.key(modifierKey, Direction.Press)
+foreground.keyUnicode('l', Direction.Click)
+foreground.key(modifierKey, Direction.Release)
+await new Promise((resolve) => setTimeout(resolve, 500))
+foreground.text('chrome://accessibility')
+foreground.key(Key.Return, Direction.Click)
+await new Promise((resolve) => setTimeout(resolve, 2000))
+
+// Enable the accessibility tree for Chrome
+enableAccessibilityForFrontmostApp()
+await new Promise((resolve) => setTimeout(resolve, 5000))
+
+// Take a screenshot of the entire screen and save it to a file
+const screenshot = screenshotFull(true, Screen.mainScreen())
+const path = join(tmpdir(), 'screenshot.png')
+screenshot.save(path)
+const fileUrl = pathToFileURL(path).toString()
+
+// Open the screenshot in the image viewer
+App.exactName(imageViewer).open(fileUrl, FocusPolicy.Steal, Visibility.Show, true)
+
+console.log('Done!')

package/examples/keyboard.mjs

@@ -0,0 +1,23 @@
+// Run: node examples/keyboard.mjs
+// This example uses the keyboard controller to type text.
+// Ensure a text field is focused (e.g. in a text editor or browser) before running.
+
+import { KeyboardController, Key, Direction, keyFromString } from '@simular-ai/simulib-js'
+
+const keyboard = new KeyboardController()
+
+// Wait two seconds
+await new Promise((resolve) => setTimeout(resolve, 2000))
+
+// Type a string. Works regardless of keyboard layout; supports Unicode (e.g. ❤️).
+keyboard.text('Hello from simulib-js ❤️')
+
+// Send individual key events, e.g. press Enter.
+keyboard.key(Key.Return, Direction.Click)
+
+// Or parse a key from a string.
+const key = keyFromString('Return')
+keyboard.key(key, Direction.Click)
+
+// Wait two seconds
+await new Promise((resolve) => setTimeout(resolve, 2000))