feat(mac): host PeekabooBridge for ui

docs/clawdis-mac.md

@@ -1,10 +1,10 @@
 ---
-summary: "Spec for the Clawdis macOS companion menu bar app and XPC broker"
+summary: "Spec for the Clawdis macOS companion menu bar app and local broker (control socket + PeekabooBridge)"
 read_when:
   - Implementing macOS app features
-  - Touching XPC/CLI bridging
+  - Touching broker/CLI bridging
 ---
-# Clawdis macOS Companion (menu bar + XPC broker)
+# Clawdis macOS Companion (menu bar + local broker)
 
 Author: steipete · Status: draft spec · Date: 2025-12-05
 
@@ -12,21 +12,24 @@ Author: steipete · Status: draft spec · Date: 2025-12-05
 - Single macOS menu-bar app named **Clawdis** that:
   - Shows native notifications for Clawdis/clawdis events.
   - Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
-  - Brokers privileged actions (screen capture, shell with elevated UI context) via XPC.
+  - Brokers privileged actions via local IPC:
+    - Clawdis control socket (app-specific actions like notify/run)
+    - PeekabooBridge socket (`bridge.sock`) for UI automation (see `docs/mac/peekaboo.md`)
   - Provides a tiny CLI (`clawdis-mac`) that talks to the app; Node/TS shells out to it.
 - Replace the separate notifier helper pattern (Oracle) with a built-in notifier.
 - Offer a first-run experience similar to VibeTunnel’s onboarding (permissions + CLI install).
 
 ## High-level design
-- SwiftPM package in `apps/macos/` (macOS 15+, Swift 6):
-  - Dependency: `https://github.com/ChimeHQ/AsyncXPCConnection` (>=0.6.0).
-  - Targets:
-    - `ClawdisIPC` (shared Codable types + helpers).
-    - `Clawdis` (LSUIElement MenuBarExtra app; embeds XPC listener and notifier).
-    - `ClawdisCLI` (client that forms requests, talks XPC, prints JSON for scripts).
-- Bundle ID: `com.steipete.clawdis`; XPC service name: `com.steipete.clawdis.xpc`.
+- SwiftPM package in `apps/macos/` (macOS 15+, Swift 6).
+- Targets:
+  - `ClawdisIPC` (shared Codable types + helpers for app-specific commands).
+  - `Clawdis` (LSUIElement MenuBarExtra app; hosts control socket + optional PeekabooBridgeHost).
+  - `ClawdisCLI` (`clawdis-mac`; prints text by default, `--json` for scripts).
+- Bundle ID: `com.steipete.clawdis`.
 - The CLI lives in the app bundle `Contents/Helpers/clawdis-mac`; dev symlink `bin/clawdis-mac` points there.
-- Node/TS layer calls the CLI; no direct XPC from Node.
+- Node/TS layer calls the CLI; no direct privileged API calls from Node.
+
+Note: `docs/mac/xpc.md` describes an aspirational long-term Mach/XPC architecture. The current direction for UI automation is PeekabooBridge (socket-based).
 
 ## IPC contract (ClawdisIPC)
 - Codable enums; small payloads (<1 MB enforced in listener):
@@ -36,13 +39,15 @@ enum Capability { notifications, accessibility, screenRecording, appleScript, mi
 enum Request {
   notify(title, body, sound?)
   ensurePermissions([Capability], interactive: Bool)
-  uiScreenshot(screenIndex?, windowID?)
   runShell(command:[String], cwd?, env?, timeoutSec?, needsScreenRecording: Bool)
   status
 }
 struct Response { ok: Bool; message?: String; payload?: Data }
 ```
-- Listener rejects oversize/unknown cases and validates the caller by code signature TeamID (with a `DEBUG`-only same-UID escape hatch controlled by `CLAWDIS_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`).
+- The control-socket server rejects oversize/unknown cases and validates the caller by code signature TeamID (with a `DEBUG`-only same-UID escape hatch controlled by `CLAWDIS_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`).
+
+UI automation is not part of `ClawdisIPC.Request`:
+- `clawdis-mac ui …` speaks **PeekabooBridge** (see `docs/mac/peekaboo.md`).
 
 ## App UX (Clawdis)
 - MenuBarExtra icon only (LSUIElement; no Dock).
@@ -52,28 +57,37 @@ struct Response { ok: Bool; message?: String; payload?: Data }
   - Permissions: live status + “Request” buttons for Notifications/Accessibility/Screen Recording; links to System Settings.
   - Debug (when enabled): PID/log links, restart/reveal app shortcuts, manual test notification.
   - About: version, links, license.
-- Pause behavior: matches Trimmy’s “Auto Trim” toggle. When paused, XPC listener returns `ok=false, message="clawdis paused"` for actions that would touch TCC (notify/run/screenshot). State is persisted (UserDefaults) and surfaced in menu and status view.
+- Pause behavior: matches Trimmy’s “Auto Trim” toggle. When paused, the broker returns `ok=false, message="clawdis paused"` for actions that would touch TCC. State is persisted (UserDefaults) and surfaced in menu and status view.
 - Onboarding (VibeTunnel-inspired): Welcome → What it does → Install CLI (shows `ln -s .../clawdis-mac /usr/local/bin`) → Permissions checklist with live status → Test notification → Done. Re-show when `welcomeVersion` bumps or CLI/app version mismatch.
 
 ## Built-in services
 - NotificationManager: UNUserNotificationCenter primary; AppleScript `display notification` fallback; respects the `--sound` value on each request.
 - PermissionManager: checks/requests Notifications, Accessibility (AX), Screen Recording (capture probe); publishes changes for UI.
-- ScreenCaptureManager: window/display PNG capture; gated on permission.
+- UI automation + capture: provided by **PeekabooBridgeHost** when enabled (see `docs/mac/peekaboo.md`).
 - ShellExecutor: executes `Process` with timeout; rejects when `needsScreenRecording` and permission missing; returns stdout/stderr in payload.
-- XPCListener actor: routes Request → managers; logs via OSLog.
+- ControlSocketServer actor: routes Request → managers; logs via OSLog.
 
 ## CLI (`clawdis-mac`)
 - Subcommands (text by default; `--json` for machine output; non-zero exit on failure):
   - `notify --title --body [--sound] [--priority passive|active|timeSensitive] [--delivery system|overlay|auto]`
   - `ensure-permissions --cap accessibility --cap screenRecording [--interactive]`
-  - `ui screens`
-  - `ui screenshot [--screen-index N] [--window-id N]`
+  - `ui permissions status`
+  - `ui frontmost`
+  - `ui apps`
+  - `ui windows [--bundle-id <id>]`
+  - `ui screenshot [--screen-index <n>] [--bundle-id <id>] [--window-index <n>] [--watch] [--scale native|1x]`
+  - `ui see [--bundle-id <id>] [--window-index <n>] [--snapshot-id <id>]`
+  - `ui click --on <elementId> [--bundle-id <id>] [--snapshot-id <id>] [--double|--right]`
+  - `ui type --text <value> [--into <elementId>] [--bundle-id <id>] [--snapshot-id <id>] [--clear] [--delay-ms <n>]`
+  - `ui wait --on <elementId> [--bundle-id <id>] [--snapshot-id <id>] [--timeout <sec>]`
   - `run -- cmd args... [--cwd] [--env KEY=VAL] [--timeout 30] [--needs-screen-recording]`
   - `status`
 - Sounds: supply any macOS alert name with `--sound` per notification; omit the flag to use the system default. There is no longer a persisted “default sound” in the app UI.
 - Priority: `timeSensitive` is best-effort and falls back to `active` unless the app is signed with the Time Sensitive Notifications entitlement.
 - Delivery: `overlay` and `auto` show an in-app toast panel (bypasses Notification Center/Focus).
-- Internals: builds a `ClawdisIPC.Request`, sends it to the running app over the local control socket, and prints text by default (or JSON with `--json`).
+- Internals:
+  - For app-specific commands (`notify`, `ensure-permissions`, `run`, `status`): build `ClawdisIPC.Request`, send over the control socket.
+  - For UI automation (`ui …`): connect to PeekabooBridge hosts (Peekaboo.app → Clawdis.app) and send one JSON request per command (see `docs/mac/peekaboo.md`).
 
 ## Integration with clawdis/Clawdis (Node/TS)
 - Add helper module that shells to `clawdis-mac`:
@@ -135,6 +149,6 @@ Notes:
 
 ## Open questions / decisions
 - Where to place the dev symlink `bin/clawdis-mac` (repo root vs. `apps/macos/bin`)?
-- Should `runShell` support streaming stdout/stderr (XPC with AsyncSequence) or just buffered? (Start buffered; streaming later.)
+- Should `runShell` support streaming stdout/stderr (IPC with AsyncSequence) or just buffered? (Start buffered; streaming later.)
 - Icon: reuse Clawdis lobster or new mac-specific glyph?
 - Sparkle updates: bundled via Sparkle; release builds point at `https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml` and enable auto-checks, while debug builds leave the feed blank and disable checks.