platform/computer-use/src/api.md

Computer Use is an independent persistent JavaScript REPL. Use cua_repl directly;
Code Mode is not required. Variables and bound objects survive calls and Turns within
the current Host process. A fresh REPL after restart has no variables from history;
follow the current Computer Use state supplied with the model request.
`cua.computer.target` identifies the selected desktop platform (`mac`, `linux`, `windows`).
In WSL it defaults to the Windows host; shell commands may still run in Linux.

A fresh REPL has no bound targets. The entry points below emit API documentation
and inventory or initial target state. Browser IDs come only from
configured providers; when none are configured, use native browser windows through
getApp. The API does not expose driver administration such as start_session.

Entry points (selection emits initial state):
- `await cua.getState({emit?})`: app and configured browser inventory, including inventory errors.
- `await cua.listApps({emit?})`, `await cua.listWindows({emit?})`.
- `const app = await cua.getApp("Name / bundle ID / app path")` or `getApp({windowId})`.
  macOS launches a missing app. Windows getApp selects an already open window;
  use `await cua.computer.launch_app({app: appId})` with an ID from cua.listApps(),
  then refresh inventory and select its exact window. Launch revalidates the ID
  against native inventory; arbitrary executable paths are not accepted.
  Select an exact window when names are ambiguous. Linux requires the app to be open already.
- `await cua.listBrowsers({emit?})`, `await cua.listTabs({browser?, emit?})`.
- `const browser = await cua.getBrowser({id? , url?})`: select without opening a tab.
- `const tab = await cua.getTab("tab ID", {browser?})` or `getTab({url}, {browser?})`.
- `await cua.createBrowserTab(browserId, url?)`: open in the configured profile.
  Unavailable providers, tab mentions and unsupported creation options throw.

App and Tab observations:
- `getAXState({emit?, disableDiffing?})` returns text. Tabs and macOS apps use a diff by default;
  Windows and Linux apps return the complete state.
- `getScreenshot({emit?})` returns Uint8Array and emits the image.
- `getAXStateAndScreenshot(options?)` returns `{state, screenshot}` and emits both.
Discovery, selection and observations emit automatically. Call them directly;
wrapping `getScreenshot()` in `nodeRepl.emitImage()` or `getAXState()` in
`nodeRepl.write()` is redundant. Use `{emit:false}` when processing the result
yourself; inventory errors still appear. Identical images emitted within one call
are delivered once. A later call may emit the same image again.
Observations include a bounded settling window for brief UI updates (200 ms for
tabs, 400 ms for apps). This does not wait for arbitrary asynchronous work;
continuous animation does not extend the window. Refresh to observe later updates.
Screenshot-only observation clears accessibility indices.
If a native AX observation fails while an app is busy, refresh the same bound object
when the app responds again. Failed observations invalidate old indices and coordinates.

App and Tab actions:
- `moveCursor(index | [x,y])` indicates an observed location using a synthetic cursor.
  Coordinates use the same current screenshot as `click`; this does not consume it.
  The returned visibility is display feedback, not evidence of an input effect.
- `click(index | [x,y], {mouseButton?, clickCount?})`, `drag([x,y], [x,y])`.
- `scroll(index | [x,y], "up" | "down" | "left" | "right", pages?)`.
- `setValue(index, string)`.
- `selectText(index, text, {prefix?, suffix?, selectionType?})` where selectionType is
  `text`, `cursor_before` or `cursor_after`. Native selection is macOS-only.
  `text_not_found` means the text or supplied context is absent; read the current
  state again. `ambiguous_text` requires a more specific prefix/suffix.
- `performSecondaryAction(index, action)`: use an exact action listed in the native
  AX observation. CDP does not expose secondary actions and rejects this method.

App input: `typeText(text)`, `paste(text, {format?})`, `pressKey(key)`.
Tab input: `typeText(index|null, text)`, `paste(index|null, text, {format?})`,
`pressKey(index|null, key)`. A supplied index focuses the observed field first.
Use `null` for current focus. Key examples: `Return`, `Tab`, `super+a`, `shift+Left`.
Paste formats: `text` (default), `md` (Markdown source as plain text), and `html`.
Native HTML paste is macOS-only and needs a readable editable value and selection. It temporarily
activates the exact window, preserves its selection, and restores the prior clipboard
unless the user copied something newer. An unchanged value is reported as uncertain.
Browser HTML paste requires an observed contenteditable element.

Tab navigation: `goto(url)`, `back()`, `forward()`, `reload()`, `close()`.
Navigation supports HTTP(S) and about:blank and waits for an observable document.
The main CDP target is covered; cross-process iframe accessibility is not complete.
Native scrolling accepts page counts. macOS and CDP scrolling also accept
`{pixels:500}` as input deltas; applications may clamp, animate or transform them.
Windows/Linux native adapters currently refuse pixel-unit input. macOS/Windows
indexed scrolling preserves the selected accessibility target. Native indexed clicks support one semantic
click; use screenshot coordinates for multiple clicks when needed.

A successful input dispatch does not establish the resulting application state.
Coordinates belong to the latest screenshot. Moving/resizing, navigation, scrolling
or any action consumes/invalidates the mapping; capture again before another point.
Native semantic actions use retained accessibility elements. Application menus
are scoped to their owning process and the exact bound window; closed menu
contents are omitted until the menu is opened. Menu interaction may activate the
bound window and keeps it active while the menu is open.
macOS/Windows coordinate and keyboard input use the exact window's foreground
route; macOS restores the prior application after delivery where supported.
Linux keeps background delivery. Coordinate input can move the system pointer.
Unverified input effects are reported in the call output. There is no public
`delivery_mode` option or automatic replay.

`nodeRepl.write(value)` emits text/JSON. `await nodeRepl.emitImage(bytes | dataUrl |
{bytes, mimeType})` emits an image. File/HTTP image URLs, Node, arbitrary filesystem
and network APIs are unavailable. `cua.rewriteDocumentation()` reprints this reference.

Every operation uses current Host permissions; JS objects retain no grants.
In Ask mode, Computer Use approval happens before the REPL execution timeout starts.
Native macOS operations report `desktop_locked` while the screen is locked; connected
CDP providers and pure REPL computations remain independently available.
Each Session has its own Maka cursor. Input actions show it automatically; call
`moveCursor` only to point without acting. `cua.cursor.configure({label?, color?,
enabled?, reducedMotion?})` changes this Session's display. Colors are `blue`, `mint`,
`violet`, `amber`, `rose`, `cyan`; labels allow up to 48 characters. `cua.cursor.getState()`
reports settings and native/browser visibility. A native renderer in `idle` state starts
on the first native indication; `unavailable` reports a missing/failed display host.
Configure again to retry a failed renderer. Idle cursors remain until disabled or cleaned up.
Cursors share no input authority and do not move the system pointer. Multiple cursors
do not isolate the physical keyboard, application focus or input method.
Cancelled, timed-out or heap-exhausted REPLs require `cua_reset`, then target rebinding. Admitted
native work settles before returning; reset does not undo dispatched input.
Reset clears only this Session's REPL and bindings, leaving user apps and tabs open.