@zenalexa/unicli 0.221.1 → 0.222.0

package/docs/operate/focus-behavior.md

@@ -2,24 +2,33 @@
 
 `unicli compute` defaults structured transports to `focus: false` for actuating
 verbs. Use `--focus` or `focus: true` only when the target app must be brought
-forward before the action can succeed. CUA is the visual fallback and is treated
-as focus-taking when the cascade reaches it.
+forward before the action can succeed. The visual fallback is treated as
+focus-taking when the cascade reaches it.
 
 ## Defaults
 
-| Verb                 | desktop-ax (macOS)                                                                                                                                                                 | desktop-uia (Windows)                                                                                                                                                                                                               | desktop-atspi (Linux)                                                                                                                                                                                                                                                             | cdp-browser                                                                                                                                     | cua                                                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `compute click`      | Uses `AXUIElementPerformAction(..., AXPress)` without app activation. Proof: [desktop-ax-swift.ts](../../src/transport/adapters/desktop-ax-swift.ts).                              | Descendant refs prefer native UIA `InvokePattern.Invoke`, `TogglePattern.Toggle`, or `SelectionItemPattern.Select`, then fall back to bounded HWND `PostMessageW` click. Proof: [invoke.rs](../../crates/unicli-uia/src/invoke.rs). | Descendant refs prefer native AT-SPI `ActionProxy.do_action(0)`, then fall back to bounded X11/Wayland click helpers. Top-level X11 refs use `wmctrl`; AT-SPI-only synthetic refs use `ComponentProxy.grab_focus()`. Proof: [invoke.rs](../../crates/unicli-atspi/src/invoke.rs). | Uses the attached renderer page and does not activate the browser window. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts). | Cascade passes `focus: true`; visual backend may move cursor or focus. Proof: [cua.ts](../../src/transport/adapters/cua.ts).                |
-| `compute type`       | Uses `AXUIElementSetAttributeValue` when possible, without activation. Proof: [desktop-ax-swift.ts](../../src/transport/adapters/desktop-ax-swift.ts).                             | Descendant refs prefer native UIA `ValuePattern.SetValue`; numeric values can fall through to `RangeValuePattern.SetValue` before bounded click plus `SendInput`. Proof: [invoke.rs](../../crates/unicli-uia/src/invoke.rs).        | Descendant refs prefer native AT-SPI `ValueProxy.set_current_value(...)` or `EditableTextProxy.set_text_contents(...)`, then fall back to display-server text helpers. Proof: [invoke.rs](../../crates/unicli-atspi/src/invoke.rs).                                               | Types through the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                                 | Cascade passes `focus: true`; visual typing may move cursor or focus. Proof: [cua.ts](../../src/transport/adapters/cua.ts).                 |
-| `compute press`      | Uses AX action dispatch when a ref/app scope is available; global key combos may require foreground app focus. Proof: [desktop-ax.ts](../../src/transport/adapters/desktop-ax.ts). | Planned per-window key dispatch keeps foreground changes behind `focus: true`. Proof: [unicli-uia main.rs](../../crates/unicli-uia/src/main.rs).                                                                                    | Uses display-server helpers for fallback key dispatch: `xdotool` on X11, `wtype` for printable Wayland keys, and `ydotool` for supported Wayland modifier combos. Proof: [input.rs](../../crates/unicli-atspi/src/input.rs).                                                      | Sends key events to the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                           | Cascade passes `focus: true`; visual key events may focus the active surface. Proof: [cua.ts](../../src/transport/adapters/cua.ts).         |
-| `compute scroll`     | Uses `AXScrollToVisible` through the AX element action path without activation. Proof: [desktop-ax-swift.ts](../../src/transport/adapters/desktop-ax-swift.ts).                    | Descendant refs prefer native UIA `ScrollPattern.Scroll(...)`, then fall back to `SendInput` wheel dispatch. Top-level window refs are foregrounded before `SendInput`. Proof: [input.rs](../../crates/unicli-uia/src/input.rs).    | Descendant refs prefer native AT-SPI `Component.scroll_to(...)`, then fall back to display-server wheel helpers. Top-level refs are activated before helper wheel dispatch. Proof: [input.rs](../../crates/unicli-atspi/src/input.rs).                                            | Sends wheel events to the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                         | Cascade passes `focus: true`; visual scrolling may move the cursor or active surface. Proof: [cua.ts](../../src/transport/adapters/cua.ts). |
-| `compute screenshot` | Reads window/screen state without activation; may require Screen Recording permission. Proof: [desktop-ax.ts](../../src/transport/adapters/desktop-ax.ts).                         | Descendant refs crop the owning HWND/GDI bitmap when bounds are known; top-level refs capture the window bitmap. Proof: [screenshot.rs](../../crates/unicli-uia/src/screenshot.rs).                                                 | Top-level X11 window refs capture with `import -window <id>`; Wayland refs with known bounds capture with `grim -g`. Other helper paths activate the target before screenshot. Proof: [screenshot.rs](../../crates/unicli-atspi/src/screenshot.rs).                               | Captures the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                                      | Backend-specific screenshot behavior. Proof: [cua.ts](../../src/transport/adapters/cua.ts).                                                 |
+| Verb                 | desktop-ax (macOS)                                                                                                                                                                                                                                                                                                                                                              | desktop-uia (Windows)                                                                                                                                                                                                               | desktop-atspi (Linux)                                                                                                                                                                                                                                                             | cdp-browser                                                                                                                                     | visual fallback                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `compute click`      | Uses `AXUIElementPerformAction(..., AXPress)` first; if AX fails and ref/window coordinates are present, falls back to pid/window-addressed `ax_background_click` without foregrounding the app. Proof: [desktop-ax.ts](../../src/transport/adapters/desktop-ax.ts), [desktop-ax-background-input-swift.ts](../../src/transport/adapters/desktop-ax-background-input-swift.ts). | Descendant refs prefer native UIA `InvokePattern.Invoke`, `TogglePattern.Toggle`, or `SelectionItemPattern.Select`, then fall back to bounded HWND `PostMessageW` click. Proof: [invoke.rs](../../crates/unicli-uia/src/invoke.rs). | Descendant refs prefer native AT-SPI `ActionProxy.do_action(0)`, then fall back to bounded X11/Wayland click helpers. Top-level X11 refs use `wmctrl`; AT-SPI-only synthetic refs use `ComponentProxy.grab_focus()`. Proof: [invoke.rs](../../crates/unicli-atspi/src/invoke.rs). | Uses the attached renderer page and does not activate the browser window. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts). | Cascade passes `focus: true`; visual backend may move cursor or focus.                |
+| `compute type`       | Uses `AXUIElementSetAttributeValue` first; if AX fails and an app/ref target is scoped, falls back to `ax_background_type` with Unicode key events posted to the target pid/window. Proof: [desktop-ax.ts](../../src/transport/adapters/desktop-ax.ts), [desktop-ax-background-input.ts](../../src/transport/adapters/desktop-ax-background-input.ts).                          | Descendant refs prefer native UIA `ValuePattern.SetValue`; numeric values can fall through to `RangeValuePattern.SetValue` before bounded click plus `SendInput`. Proof: [invoke.rs](../../crates/unicli-uia/src/invoke.rs).        | Descendant refs prefer native AT-SPI `ValueProxy.set_current_value(...)` or `EditableTextProxy.set_text_contents(...)`, then fall back to display-server text helpers. Proof: [invoke.rs](../../crates/unicli-atspi/src/invoke.rs).                                               | Types through the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                                 | Cascade passes `focus: true`; visual typing may move cursor or focus.                 |
+| `compute press`      | Uses `ax_background_press` for app/ref-scoped key combos before visual fallback, posting key events to the target pid/window. Unscoped global key combos still require a focus-taking fallback. Proof: [cascade.ts](../../src/transport/cascade.ts), [desktop-ax-background-input.ts](../../src/transport/adapters/desktop-ax-background-input.ts).                             | Planned per-window key dispatch keeps foreground changes behind `focus: true`. Proof: [unicli-uia main.rs](../../crates/unicli-uia/src/main.rs).                                                                                    | Uses display-server helpers for fallback key dispatch: `xdotool` on X11, `wtype` for printable Wayland keys, and `ydotool` for supported Wayland modifier combos. Proof: [input.rs](../../crates/unicli-atspi/src/input.rs).                                                      | Sends key events to the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                           | Cascade passes `focus: true`; visual key events may focus the active surface.         |
+| `compute scroll`     | Uses `AXScrollToVisible` through the AX element action path without activation. Proof: [desktop-ax-swift.ts](../../src/transport/adapters/desktop-ax-swift.ts).                                                                                                                                                                                                                 | Descendant refs prefer native UIA `ScrollPattern.Scroll(...)`, then fall back to `SendInput` wheel dispatch. Top-level window refs are foregrounded before `SendInput`. Proof: [input.rs](../../crates/unicli-uia/src/input.rs).    | Descendant refs prefer native AT-SPI `Component.scroll_to(...)`, then fall back to display-server wheel helpers. Top-level refs are activated before helper wheel dispatch. Proof: [input.rs](../../crates/unicli-atspi/src/input.rs).                                            | Sends wheel events to the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                         | Cascade passes `focus: true`; visual scrolling may move the cursor or active surface. |
+| `compute screenshot` | Reads window/screen state without activation; may require Screen Recording permission. Proof: [desktop-ax.ts](../../src/transport/adapters/desktop-ax.ts).                                                                                                                                                                                                                      | Descendant refs crop the owning HWND/GDI bitmap when bounds are known; top-level refs capture the window bitmap. Proof: [screenshot.rs](../../crates/unicli-uia/src/screenshot.rs).                                                 | Top-level X11 window refs capture with `import -window <id>`; Wayland refs with known bounds capture with `grim -g`. Other helper paths activate the target before screenshot. Proof: [screenshot.rs](../../crates/unicli-atspi/src/screenshot.rs).                               | Captures the attached renderer page. Proof: [cdp-browser.ts](../../src/transport/adapters/cdp-browser.ts).                                      | Backend-specific screenshot behavior.                                                 |
 
 ## Operational Notes
 
 - `compute click`, `compute type`, `compute press`, and `compute scroll` pass
   `focus: false` to AX, UIA, AT-SPI, and CDP unless the caller sets `--focus`
   or `focus: true`.
+- macOS background input is not a global HID path. It resolves a running app
+  and on-screen window, installs per-process event taps for the previous and
+  target apps, sends an AppKit activation primer plus a center primer only when
+  the target is not already frontmost, then posts events with target pid and
+  window fields.
+- The macOS background path uses Accessibility and Input Monitoring
+  permissions. It may still fail for minimized, hidden, off-screen, disabled, or
+  security-hardened windows; those failures remain structured errors rather
+  than implicit foregrounding.
 - Linux AT-SPI refs from `compute snapshot` / `compute find --first` can target
   `compute click`, `compute type`, `compute scroll`, `compute screenshot`,
   `compute wait`, `compute observe`, and `compute assert`. Descendant click,
@@ -33,8 +42,8 @@ as focus-taking when the cascade reaches it.
   and scroll prefer native UIA patterns before bounded fallback paths.
 - Linux AT-SPI `compute press` remains a global display-server helper path, so
   it targets the active desktop surface.
-- CUA is a fallback for cases where structured transports cannot see or act on
-  the target. Because it is visual-provider based, the cascade dispatches CUA
-  actions with `focus: true`.
+- The visual backend is a fallback for cases where structured transports cannot
+  see or act on the target. Because it is pixel/provider based, the cascade
+  dispatches those actions with `focus: true`.
 - If a target is minimized, hidden, disabled, or off screen, prefer a fresh
   `compute snapshot` and a structured retry before enabling `--focus`.

package/docs/operate/troubleshooting.md

@@ -11,7 +11,7 @@ path.
 
 Remedy: run `unicli doctor compute --install`, then retry the compute command.
 
-Fallback: use CDP-backed Electron/browser control or CUA screenshot fallback if
+Fallback: use CDP-backed Electron/browser control or visual fallback if
 configured.
 
 ## desktop-uia.startup_failed
@@ -46,7 +46,7 @@ Cause: the target element does not expose the UIA Invoke pattern.
 Remedy: use `unicli compute type`, `unicli compute press`, or focus the control
 first and retry.
 
-Fallback: use CUA when no structured pattern is exposed.
+Fallback: use visual fallback when no structured pattern is exposed.
 
 ## desktop-uia.timeout
 
@@ -92,7 +92,7 @@ expected path.
 
 Remedy: run `unicli doctor compute --install`, then retry.
 
-Fallback: use CDP-backed Electron/browser control or CUA screenshot fallback if
+Fallback: use CDP-backed Electron/browser control or visual fallback if
 configured.
 
 ## desktop-atspi.dbus_blocked
@@ -110,7 +110,7 @@ Cause: the target app does not expose a usable AT-SPI tree.
 Remedy: enable accessibility support for the app. Electron apps may need an
 accessibility flag at launch.
 
-Fallback: use CDP for Electron/browser targets or CUA screenshot fallback.
+Fallback: use CDP for Electron/browser targets or visual fallback.
 
 ## desktop-atspi.atspi_apps
 
@@ -120,7 +120,7 @@ Remedy: ensure the AT-SPI bus is running. Uni-CLI prefers `wmctrl -lG -p` for
 real X11 window ids and geometry, but can fall back to AT-SPI-only registry
 roots when `wmctrl` is missing or empty.
 
-Fallback: target an Electron/browser app through CDP, or use CUA fallback.
+Fallback: target an Electron/browser app through CDP, or use visual fallback.
 
 ## desktop-atspi.atspi_windows
 
@@ -130,7 +130,7 @@ Remedy: install `wmctrl` when real X11 window ids are needed. On Wayland or
 minimal environments, verify the AT-SPI bus is running so Uni-CLI can use
 synthetic `atspi-root-N` windows from the accessibility registry.
 
-Fallback: use `compute snapshot` on another transport or CUA fallback.
+Fallback: use `compute snapshot` on another transport or visual fallback.
 
 ## desktop-atspi.wayland-input
 
@@ -157,7 +157,7 @@ Remedy: install ImageMagick `import` for X11 top-level window capture, or
 install `grim` for Wayland top-level bounds capture. Install
 `gnome-screenshot` / `grim` for display-server fallback capture.
 
-Fallback: use CDP for Electron/browser targets or CUA screenshot fallback.
+Fallback: use CDP for Electron/browser targets or visual fallback.
 
 ## desktop-atspi.invalid_input
 
@@ -275,13 +275,18 @@ for example `sudo apt-get install libgtk-3-bin`.
 Fallback: start the app manually, then use `compute attach`, `compute snapshot`,
 or the native desktop transport for follow-up actions.
 
-## cua.no_backend
+## visual.no_backend
 
-Cause: screenshot/VLM fallback is enabled in the cascade, but no backend API key
-is configured.
+Cause: visual fallback is enabled in the cascade, but no backend endpoint or
+credential is configured.
 
-Remedy: set a supported backend environment variable such as
-`ANTHROPIC_API_KEY`, `TRYCUA_API_KEY`, or `OPENAI_API_KEY`.
+Remedy: set the generic visual backend environment:
+
+```bash
+export VISUAL_BACKEND=remote
+export VISUAL_BACKEND_ENDPOINT=http://localhost:8800
+export VISUAL_BACKEND_API_KEY=...
+```
 
 Fallback: use structured AX/UIA/AT-SPI/CDP control where possible.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenalexa/unicli",
-  "version": "0.221.1",
+  "version": "0.222.0",
   "description": "Agent execution substrate for web, apps, local tools, and system capabilities. Self-repairing CLI catalog with stdio + Streamable HTTP MCP server.",
   "packageManager": "npm@11.14.0",
   "type": "module",
@@ -96,9 +96,9 @@
       "types": "./dist/transport/adapters/desktop-ax.d.ts",
       "import": "./dist/transport/adapters/desktop-ax.js"
     },
-    "./transport/cua": {
-      "types": "./dist/transport/adapters/cua.d.ts",
-      "import": "./dist/transport/adapters/cua.js"
+    "./transport/visual": {
+      "types": "./dist/transport/adapters/visual.d.ts",
+      "import": "./dist/transport/adapters/visual.js"
     },
     "./browser/cdp": {
       "types": "./dist/browser/cdp-client.d.ts",
@@ -148,7 +148,7 @@
     "stats": "tsx scripts/build-manifest.js && tsx scripts/count-stats.ts && tsx scripts/build-readme.ts && tsx scripts/build-agents.ts",
     "stats:check": "tsx scripts/count-consistency.ts",
     "build:agents": "tsx scripts/build-agents.ts",
-    "test": "vitest run --project unit",
+    "test": "vitest run --project unit --maxWorkers=1 --reporter=dot",
     "test:adapter": "vitest run --project adapter",
     "test:perf": "vitest run --project perf",
     "compute:smoke": "tsx scripts/compute-live-smoke.ts",
@@ -239,12 +239,6 @@
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
-  "optionalDependencies": {
-    "@zenalexa/unicli-atspi-linux-arm64": "0.218.1",
-    "@zenalexa/unicli-atspi-linux-x64": "0.218.1",
-    "@zenalexa/unicli-uia-win32-arm64": "0.218.1",
-    "@zenalexa/unicli-uia-win32-x64": "0.218.1"
-  },
   "devDependencies": {
     "@ai-sdk/openai-compatible": "^2.0.41",
     "@base-ui/react": "^1.4.1",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.olo-dot-io/Uni-CLI",
   "description": "Self-repairing CLI catalog that exposes 282 websites, desktop apps, and external CLIs as one MCP server. 949 declarative YAML adapters and 1686 commands; structured error envelopes let agents fix failing adapters at runtime and retry.",
-  "version": "0.221.1",
+  "version": "0.222.0",
   "repository": {
     "url": "https://github.com/olo-dot-io/Uni-CLI",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@zenalexa/unicli",
-      "version": "0.221.1",
+      "version": "0.222.0",
       "transport": {
         "type": "stdio"
       },

package/skills/unicli/SKILL.md

@@ -11,7 +11,7 @@ description: >
   major platform; run desktop workflows or system tasks; or when the user says
   "unicli", "scrape", "fetch from", "get trending", "check [site]", "find on
   [platform]", "获取", "查询", "抓取".
-version: 0.221.1
+version: 0.222.0
 category: core
 depends-on:
   - talk-normal

package/skills/unicli-claude-code/SKILL.md

@@ -6,7 +6,7 @@ description: >
   newlines, or inline JSON — shell-quoted invocations hit TC0 circuit
   limits and drop to <50% success above ICS=4. Also covers --describe
   introspection and next_actions-driven navigation.
-version: 0.221.1
+version: 0.222.0
 depends-on:
   - talk-normal
 triggers:

package/skills/unicli-hermes/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Use Uni-CLI to interact with 237 websites, desktop apps, and system tools.
   Trigger when: user asks to check a website, fetch data, control a desktop app,
   or interact with social media, news, finance, or AI platforms.
-version: 0.221.1
+version: 0.222.0
 depends-on:
   - talk-normal
 triggers:

package/skills/unicli-repair/references/error-codes.md

@@ -12,7 +12,7 @@ type Envelope<T> =
   | { ok: false; error: EnvelopeError; elapsedMs?: number };
 
 interface EnvelopeError {
-  transport: TransportKind; // "fetch" | "cdp-browser" | "subprocess" | "cua" | "http" | "desktop-*" | ...
+  transport: TransportKind; // "fetch" | "cdp-browser" | "subprocess" | "visual" | "http" | "desktop-*" | ...
   adapter_path?: string; // relative to repo or ~/.unicli/adapters
   step: number; // 0-indexed pipeline step
   action: string; // step kind: "fetch", "select", "map", "click", ...
@@ -110,13 +110,13 @@ automatically; surfaces here as a quick map. Full doc anchors live under
 | `cdp-browser.attach_failed`                       | Check the CDP port; relaunch with remote debugging |
 | `cdp-browser.electron_running_without_debug_port` | `unicli compute launch <app> --debug-port 9229`    |
 
-### CUA / Compute
+### Visual / Compute
 
-| Capability                              | Fix                                          |
-| --------------------------------------- | -------------------------------------------- |
-| `cua.no_backend`                        | Configure a CUA backend key for VLM fallback |
-| `compute.<step>.no-transport-available` | `unicli doctor compute`                      |
-| `compute.compute_find.ref-store`        | `unicli compute snapshot`, then retry find   |
+| Capability                              | Fix                                                              |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `visual.no_backend`                     | Configure `VISUAL_BACKEND_ENDPOINT` and `VISUAL_BACKEND_API_KEY` |
+| `compute.<step>.no-transport-available` | `unicli doctor compute`                                          |
+| `compute.compute_find.ref-store`        | `unicli compute snapshot`, then retry find                       |
 
 ### Compute edge cases (suffix on `minimum_capability`)
 

package/src/adapters/_archived/README.md

@@ -4,9 +4,9 @@ These adapters are preserved for provenance but are outside active discovery.
 The loader, manifest builder, conformance report, and quarantine repair list
 skip underscore-prefixed adapter directories.
 
-| Site        | Commands    | Archived on | Replacement                                                             |
-| ----------- | ----------- | ----------- | ----------------------------------------------------------------------- |
-| apple-music | rate-album  | 2026-05-06  | `unicli macos music-now`; `unicli macos music-control <action>`         |
-| az          | account     | 2026-05-06  | `az account list --output json` through external CLI passthrough        |
-| ctrip       | hot, search | 2026-05-06  | `unicli web read` or browser/CUA against an authenticated Ctrip session |
-| gcloud      | projects    | 2026-05-06  | `gcloud projects list --format=json` through external CLI passthrough   |
+| Site        | Commands    | Archived on | Replacement                                                                |
+| ----------- | ----------- | ----------- | -------------------------------------------------------------------------- |
+| apple-music | rate-album  | 2026-05-06  | `unicli macos music-now`; `unicli macos music-control <action>`            |
+| az          | account     | 2026-05-06  | `az account list --output json` through external CLI passthrough           |
+| ctrip       | hot, search | 2026-05-06  | `unicli web read` or browser/Visual against an authenticated Ctrip session |
+| gcloud      | projects    | 2026-05-06  | `gcloud projects list --format=json` through external CLI passthrough      |

package/src/adapters/_archived/apple-music/rate-album.yaml

@@ -1,17 +1,17 @@
 # @owner   src/adapters/_archived/apple-music/rate-album.yaml
-# @does    Preserve the archived Apple Music CUA rating demo outside active discovery.
-# @needs   macOS Music app, desktop AX transport, CUA backend, caller-provided star coordinates
+# @does    Preserve the archived Apple Music Visual rating demo outside active discovery.
+# @needs   macOS Music app, desktop AX transport, Visual backend, caller-provided star coordinates
 # @feeds   src/adapters/_archived/archive.json provenance, historical adapter review
 # @breaks  Moving back under an active site would reintroduce an archive-only discovered site.
 site: apple-music
 name: rate-album
-description: Rate the currently-playing Apple Music album via AX menu + CUA click
+description: Rate the currently-playing Apple Music album via AX menu + Visual click
 type: browser
 strategy: ui
 domain: music.apple.com
 browser: false
 quarantine: true
-quarantineReason: Requires macOS + Apple Music desktop app + a CUA backend (quarantined 2026-04-15)
+quarantineReason: Requires macOS + Apple Music desktop app + a Visual backend (quarantined 2026-04-15)
 args:
   stars:
     type: int
@@ -33,34 +33,34 @@ pipeline:
   - ax_focus:
       app: Music
 
-  - cua_wait:
+  - visual_wait:
       ms: 300
 
-  - cua_snapshot: {}
+  - visual_snapshot: {}
 
-  - cua_ask:
+  - visual_ask:
       question: Is an album currently displayed with a star-rating row visible?
 
-  - cua_click:
+  - visual_click:
       x: ${{ args.x }}
       y: ${{ args.y }}
 
-  - cua_assert:
+  - visual_assert:
       predicate: The album now shows ${{ args.stars }} filled stars
 
 columns: [backend, stars]
 
 capabilities:
   [
-    "cua.ask",
-    "cua.assert",
-    "cua.click",
-    "cua.snapshot",
-    "cua.wait",
+    "visual.ask",
+    "visual.assert",
+    "visual.click",
+    "visual.snapshot",
+    "visual.wait",
     "desktop-ax.focus",
     "desktop-ax.launch_app",
   ]
-minimum_capability: cua.click
+minimum_capability: visual.click
 trust: user
 confidentiality: public
 schema_version: v2

package/src/adapters/_archived/archive.json

@@ -7,7 +7,7 @@
       "commands": ["rate-album"],
       "original_paths": ["src/adapters/apple-music/rate-album.yaml"],
       "archived_paths": ["src/adapters/_archived/apple-music/rate-album.yaml"],
-      "reason": "Host-app CUA demo requires the macOS Music app and a CUA backend; active Apple Music controls remain under the macos adapter.",
+      "reason": "Host-app Visual demo requires the macOS Music app and a Visual backend; active Apple Music controls remain under the macos adapter.",
       "replacement": "unicli macos music-now; unicli macos music-control <action>"
     },
     {
@@ -30,7 +30,7 @@
         "src/adapters/_archived/ctrip/search.yaml"
       ],
       "reason": "Public Ctrip endpoints were verified broken or CAPTCHA-gated on 2026-05-05, with no stable public replacement captured.",
-      "replacement": "Use the web adapter or browser/CUA flow against an authenticated Ctrip session."
+      "replacement": "Use the web adapter or browser/Visual flow against an authenticated Ctrip session."
     },
     {
       "site": "gcloud",

package/src/adapters/figma/export-selected.yaml

@@ -1,21 +1,21 @@
-# CUA+AX demo — export the currently-selected Figma frame.
+# Visual+AX demo — export the currently-selected Figma frame.
 #
 # Composes three transports:
 #   1. desktop-ax    → launch & focus the desktop Figma app
-#   2. cua           → VLM confirms the export dialog is visible
+#   2. visual           → VLM confirms the export dialog is visible
 #   3. desktop-ax    → click through the File > Export menu path
 #
-# Quarantined because the Figma desktop app and a VLM backend
-# (ANTHROPIC_API_KEY | TRYCUA_API_KEY | …) are both required.
+# Quarantined because the Figma desktop app and a visual backend are both
+# required.
 site: figma
 name: export-selected
-description: Export the currently-selected Figma frame via CUA + macOS AX
+description: Export the currently-selected Figma frame via Visual + macOS AX
 type: browser
 strategy: ui
 domain: figma.com
 browser: false
 quarantine: true
-quarantineReason: Requires macOS + Figma desktop app + a CUA backend (ANTHROPIC_API_KEY etc.) (quarantined 2026-04-15)
+quarantineReason: Requires macOS + Figma desktop app + a visual backend (quarantined 2026-04-15)
 args:
   format:
     type: str
@@ -30,12 +30,12 @@ pipeline:
   - ax_focus:
       app: Figma
 
-  - cua_wait:
+  - visual_wait:
       ms: 500
 
-  - cua_snapshot: {}
+  - visual_snapshot: {}
 
-  - cua_ask:
+  - visual_ask:
       question: Is a frame currently selected on the Figma canvas?
 
   - ax_menu_select:
@@ -44,10 +44,10 @@ pipeline:
         - File
         - Export ${{ args.format }}
 
-  - cua_wait:
+  - visual_wait:
       ms: 800
 
-  - cua_assert:
+  - visual_assert:
       predicate: The Figma export dialog is visible with a Save button
 
 columns: [backend, ok]
@@ -55,15 +55,15 @@ columns: [backend, ok]
 # schema-v2 metadata — injected by `unicli migrate schema-v2`
 capabilities:
   [
-    "cua.ask",
-    "cua.assert",
-    "cua.snapshot",
-    "cua.wait",
+    "visual.ask",
+    "visual.assert",
+    "visual.snapshot",
+    "visual.wait",
     "desktop-ax.focus",
     "desktop-ax.launch_app",
     "desktop-ax.menu_select",
   ]
-minimum_capability: cua.snapshot
+minimum_capability: visual.snapshot
 trust: user
 confidentiality: public
 schema_version: v2

package/src/adapters/openalex/works.test.ts

@@ -31,38 +31,46 @@ describe("openalex agent-facing commands", () => {
   });
 
   it("maps search rows", () => {
-    expect(
-      mapOpenAlexSearchRows(
-        [
-          {
-            id: "https://openalex.org/W1234",
-            doi: "https://doi.org/10.1/example",
-            title: "A paper",
-            publication_year: 2026,
-            cited_by_count: 5,
-            authorships: [{ author: { display_name: "Ada" } }],
-            primary_location: { source: { display_name: "Journal" } },
-            open_access: { is_oa: true },
-            type: "article",
-          },
-        ],
-        20,
-      ),
-    ).toEqual([
-      {
-        rank: 1,
-        id: "W1234",
-        title: "A paper",
-        year: 2026,
-        citations: 5,
-        firstAuthor: "Ada",
-        venue: "Journal",
-        openAccess: true,
-        type: "article",
-        doi: "10.1/example",
-        url: "https://openalex.org/W1234",
-      },
-    ]);
+    const rows = mapOpenAlexSearchRows(
+      [
+        {
+          id: "https://openalex.org/W1234",
+          doi: "https://doi.org/10.1/example",
+          title: "A paper",
+          publication_year: 2026,
+          cited_by_count: 5,
+          authorships: [{ author: { display_name: "Ada" } }],
+          primary_location: { source: { display_name: "Journal" } },
+          open_access: { is_oa: true },
+          type: "article",
+        },
+      ],
+      20,
+    );
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      rank: 1,
+      id: "W1234",
+      title: "A paper",
+      year: 2026,
+      citations: 5,
+      firstAuthor: "Ada",
+      authors: ["Ada"],
+      venue: "Journal",
+      openAccess: true,
+      is_open_access: true,
+      type: "article",
+      doi: "10.1/example",
+      pdf_url: "",
+      openalex_id: "W1234",
+      source_adapter: "openalex",
+      source_url: "https://openalex.org/W1234",
+      url: "https://openalex.org/W1234",
+    });
+    expect(rows[0]?.retrieved_at).toEqual(
+      expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+    );
   });
 
   it("maps work detail rows", () => {

package/src/adapters/zoom/toggle-mute.yaml

@@ -1,6 +1,6 @@
 # Pure AX demo — toggle microphone mute in an in-progress Zoom meeting.
 #
-# No CUA involved. Zoom's "Meeting > Mute/Unmute Audio" menu item is
+# No Visual involved. Zoom's "Meeting > Mute/Unmute Audio" menu item is
 # deterministic and driven entirely through the Accessibility API.
 site: zoom
 name: toggle-mute

package/dist/engine/steps/cua.d.ts

@@ -1,41 +0,0 @@
-/**
- * CUA pipeline step handlers — every cua_* action delegates to the
- * transport bus (`bus.require`/`adapter.open`/`adapter.action`). The bus
- * routes to whichever transport declares the step; `action()` never
- * throws — callers always receive an envelope.
- */
-import type { Envelope } from "../../core/envelope.js";
-import type { TransportBus, TransportContext } from "../../transport/types.js";
-/** Shared shape used by every cua_* handler. */
-export interface CuaStepContext {
-    bus: TransportBus;
-    transportCtx: TransportContext;
-    platform?: NodeJS.Platform;
-}
-export declare function handleCuaSnapshot(ctx: CuaStepContext, params?: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaClick(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaType(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaKey(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaScroll(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaDrag(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaWait(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaAssert(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaAsk(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaBackend(ctx: CuaStepContext, params?: Record<string, unknown>): Promise<Envelope<unknown>>;
-export declare function handleCuaLaunch(ctx: CuaStepContext, params: Record<string, unknown>): Promise<Envelope<unknown>>;
-/** Kind → handler dispatch table (consumed by executor.dispatchBusStep in src/engine/executor.ts). */
-export declare const CUA_STEP_HANDLERS: {
-    readonly cua_snapshot: typeof handleCuaSnapshot;
-    readonly cua_click: typeof handleCuaClick;
-    readonly cua_type: typeof handleCuaType;
-    readonly cua_key: typeof handleCuaKey;
-    readonly cua_scroll: typeof handleCuaScroll;
-    readonly cua_drag: typeof handleCuaDrag;
-    readonly cua_wait: typeof handleCuaWait;
-    readonly cua_assert: typeof handleCuaAssert;
-    readonly cua_ask: typeof handleCuaAsk;
-    readonly cua_backend: typeof handleCuaBackend;
-    readonly cua_launch: typeof handleCuaLaunch;
-};
-export type CuaStepKind = keyof typeof CUA_STEP_HANDLERS;
-//# sourceMappingURL=cua.d.ts.map

package/dist/engine/steps/cua.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cua.d.ts","sourceRoot":"","sources":["../../../src/engine/steps/cua.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAGV,YAAY,EACZ,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAElC,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,YAAY,CAAC;IAClB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAYD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,cAAc,EACnB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAE5B;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;CAYpB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,iBAAiB,CAAC"}