Adom Bridge (macOS)

@@ -1,193 +0,0 @@-----name: adom-desktop-window-capture-description: >--  The complete reference for Adom Bridge screenshots on macOS: every capture verb, the exact JSON response shape, and how the CLI automatically stores each shot on disk (the window/ and screen/ buckets, the ISO-stamped filenames, the single-vs-full/safe pair, and the <stem>.json sidecar). Read this to capture an app window without stealing focus, to grab the screen, to understand the Screen Recording permission requirement, or to build a tool (like shotlog) that renders every screenshot shape Adom Bridge can return. Covers desktop_screenshot_window, desktop_screenshot_screen, kicad_screenshot_all, desktop_find_window, desktop_list_windows, desktop_list_monitors, and the exact on-disk sidecar schema.------# Adom Bridge screenshots (macOS): full capability, response shape, and on-disk contract--This is the deep reference for everything Adom Bridge can capture on a Mac and everything it writes to disk. Two audiences:--- **An AI driving a GUI app**: jump to "The verb map". The one thing to internalize: `desktop_screenshot_window {hwnd}` captures ONE window by its window id, even when it is behind other windows, without stealing focus.-- **A tool that renders Adom Bridge screenshots (e.g. shotlog)**: jump to "On-disk storage" and "The sidecar schema". Every shot lands in a predictable bucket with a self-describing `<stem>.json` next to it; you never have to parse the response envelope, just watch the folder.-------## 1. The verb map: what each capture verb returns--| Verb | Captures | Foreground? | Shape |-|---|---|---|---|-| **`desktop_screenshot_window {hwnd}`** | ONE window by its CGWindowID (`screencapture -l`) | No focus steal; works when occluded | one image (full/safe pair when large) |-| **`desktop_screenshot_screen {}`** | the MAIN display | n/a (whatever is on screen) | one image |-| **`kicad_screenshot_all {}`** | every open KiCad window (main + dialogs) as separate images | No | an ARRAY of sibling-window images |-| **`browser_screenshot`** | a browser PAGE / viewport (pup bridge, CDP; not a window grab) | No | one image (page pixels, not window chrome) |--**Rule of thumb:** for one app window, ALWAYS prefer `desktop_screenshot_window {hwnd}` (resolve the id with `desktop_find_window {titleContains}`). It captures the window's own content even when other windows cover it, and it never steals focus. Use `desktop_screenshot_screen` only when you genuinely want "what is on the user's screen right now."--**macOS mechanics and limits (all verified in `src-tauri/src/screenshot.rs`):**--- The `hwnd` field is the **CGWindowID** from `CGWindowListCopyWindowInfo`. Window enumeration (`desktop_list_windows`, `desktop_find_window`) lists **on-screen** windows only: a MINIMIZED window, or one on another Space, does not enumerate and cannot be captured. Occluded-but-on-screen windows are fine.-- Capture runs through the system `screencapture` tool (`-l <id>` per window; `-x` no shutter sound, `-o` no drop shadow, PNG output). Both window and screen captures are downscaled at capture time to at most **1568 px** on the longest side, so a Retina grab is never shipped raw.-- **App modal dialogs:** a sheet attached to a window renders INSIDE that window's capture. A separate dialog window is its own on-screen top-level window: find it with `desktop_list_windows` / `desktop_find_window` and capture it by its own id. There is no owned-popup `screenshots[]` array on macOS (that was a Windows mechanism); `kicad_screenshot_all` is the one verb that returns a multi-window array.-- **Multi-monitor:** `desktop_screenshot_screen` captures the MAIN display only. There are no `{monitor:N}` or `{perMonitor:true}` options on macOS. Enumerate displays with `desktop_list_monitors` (below).-- **No video recording on macOS.** The native recording verbs return a clean `recording_unsupported` error. Recording a browser TAB is the pup bridge's own CDP feature (`browser_record_start`), unrelated to this skill.-------## 2. Permission: Screen Recording (required)--macOS gates all window and screen capture behind the **Screen Recording** TCC permission. Grant it once:--**System Settings > Privacy & Security > Screen Recording > enable "Adom Bridge"**, then relaunch the app.--Symptoms of a missing grant:--- Captures come back black or empty, or `screencapture` errors ("Check Screen Recording permission" appears in the error message).-- Window TITLES are missing: without the permission, `kCGWindowName` is not populated, so `desktop_list_windows` falls back to showing the owning APP's name as the title. If every window's title is just the app name, the permission is not granted.--Driving controls in the background (`desktop_find_control`, `desktop_ui_click`, `desktop_ui_set`) additionally needs the **Accessibility** permission (System Settings > Privacy & Security > Accessibility); a missing grant returns `errorCode: ax_not_trusted`.-------## 3. The response shape--Every screenshot verb returns the same core envelope. Field by field, as produced by the app plus the CLI's auto-pull enrichment:--```jsonc-{-  "success": true,-  "output": "{...}",          // JSON string: { message, data: { image: <base64 PNG>, format, encoding, sizeBytes } }-  "error": "",--  // The image, on the DESKTOP (host) side: $TMPDIR/adom-desktop-shots/-  "fullPath":  ".../adom-desktop-shots/window-<hwnd>-<ts>.png",   // or a .full.png/.safe.png pair-  "safePath":  ".../adom-desktop-shots/window-<hwnd>-<ts>.png",-  "fullWidth": 1568, "fullHeight": 980,     // capture size (already capped at <=1568)-  "safeWidth": 1400, "safeHeight": 875,     // downscaled to <=resizeMax when the capture exceeded it-  "fullBytesHost": 402931, "safeBytesHost": 88104,-  "resizeMax": 1400,--  // The image, PULLED to the CALLER (container) side by the CLI:-  "fullPathHost": "...", "safePathHost": "...",   // host-path aliases-  "localFullPath": "/home/adom/project/screenshots/adom-desktop/window/2026-08-10T01-14-16.937-986710.png",-  "localSafePath": "/home/adom/project/screenshots/adom-desktop/window/2026-08-10T01-14-16.937-986710.png",-  "localFullExists": true, "localSafeExists": true,-  "savedTo": ".../window/2026-08-10T01-14-16.937-986710.png",   // = the safe copy (fallback full)-  "fullBytes": 402931, "safeBytes": 88104,   // bytes on the CALLER side-  "source": "desktop_screenshot_window",-  "narrative": "Captured and auto-pulled ONE PNG to .../window/ ...",-  "_cacheHint": "...",                        // where shots live + janitor recipe--  "drive": "background",                      // this capture never foregrounded the window-  "_related": "..."                           // sibling verbs-}-```--Args for `desktop_screenshot_window`: `hwnd` (required, from `desktop_find_window` / `desktop_list_windows`) and optional `resizeMax` (default 1400, clamped 64..4096): the longest side of the safe-resized copy.--**Clicking what you see:** pass SCREEN coordinates to `desktop_click` / `desktop_double_click` / `desktop_right_click` / `desktop_hover` (`{x, y}` in points, the same space as `desktop_list_windows` rects and `desktop_list_monitors` bounds). The Windows-only image-space contract (`{space:"image", shotId}` and the `coordMap` block) is NOT available on macOS: responses carry no `coordMap`/`shotId`. To click a control without doing coordinate math at all, prefer the Accessibility path: `desktop_find_control {hwnd, name|contains, role?}` returns the control's on-screen rect (`centerX`/`centerY`), and `desktop_ui_click` presses it in the background via AXPress.-------## 4. Monitors: `desktop_list_monitors`--`desktop_list_monitors` (alias `display`) is the authoritative display map, via CGDisplay:--```jsonc-{-  "monitors": [-    {-      "index": 0, "primary": true, "device": "CGDisplay-1",-      "bounds":        { "x": 0, "y": 0, "width": 1512, "height": 982 },  // POINTS, same space as clicks + window rects-      "workArea":      { ... },            // == bounds on macOS (menu bar / Dock not excluded)-      "logicalBounds": { ... },            // == bounds-      "pixelSize":     { "width": 3024, "height": 1964 },  // native pixels-      "scale": 2.0,                        // Retina backing scale-      "dpi": 144                           // 72 * scale-    }-  ]-}-```--Ordering is stable: primary first, then left to right. On macOS everything the input and window verbs speak is POINTS: `bounds` here, `desktop_list_windows` rects, and `desktop_click {x,y}` all share one coordinate space, so no scale math is ever needed. `pixelSize`/`scale` exist only to tell you the display is Retina.-------## 5. On-disk storage: where the CLI auto-pulls every shot (the shotlog contract)--The CLI auto-pulls every screenshot to the CALLER's machine and self-janitors the cache. This is the part a visualizer watches.--**Directory (resolved once, per machine):**-```-$ADOM_SHOTS_DIR                                  # explicit override, else:-~/project/screenshots/adom-desktop/              # when ~/project exists (the container convention)-~/.adom/screenshots/                             # fallback (no ~/project)-```-Never `/tmp`. The CLI deliberately does NOT touch `~/project/screenshots/*.png` (timestamp-named) or `~/project/screenshots/shotlog/`: those belong to other tools.--**Buckets (subfolders by kind):**-```-<shots_dir>/window/     # a specific window / app capture  (desktop_screenshot_window, kicad_*, browser_*)-<shots_dir>/screen/     # a full-screen grab               (desktop_screenshot_screen)-```--**Filenames: human-readable, sortable:**-```-window/2026-08-10T01-14-16.937-986710.png   # <ISO-stamp>-<windowId>.png (the folder says "window", so no prefix)-screen/2026-08-10T01-05-08.625.png          # a screen grab (no window id)-```-The ISO stamp is `YYYY-MM-DDThh-mm-ss.mmm` with no colons, so it is filename-safe AND lexicographic order == chronological order. Entries of a multi-window array (`kicad_screenshot_all`) keep each window's own name and gain `localPath`/`savedTo` per entry.--**Single file vs full/safe pair:**-- If the capture was already within the safe size cap (`resizeMax`, the common case on macOS since captures are pre-capped at 1568) it is written **ONCE** as `<stem>.png`, and `localFullPath == localSafePath` point at that one file.-- Only a shot LARGE enough to be downscaled gets the pair: `<stem>.full.png` + `<stem>.safe.png`. A renderer should prefer `.safe` for display and `.full` for pixel-exact work; when only `<stem>.png` exists, that IS both.--**Janitor (automatic):** the pull cache self-prunes (defaults: 7-day age cap, 2 GB size cap, 4000-file cap, oldest deleted first, newest always kept; a shot's sidecar follows its PNG on delete, plus an orphan-sidecar sweep). No cleanup is needed caller-side. Inspect with `adom-desktop janitor status`; force a sweep with `adom-desktop janitor '{"sub":"run"}'`. Tune with `ADOM_SHOTS_DIR`, `ADOM_SHOTS_MAX_AGE_DAYS`, `ADOM_SHOTS_MAX_GB`, `ADOM_SHOTS_MAX_FILES`, `ADOM_JANITOR=0`.-------## 6. The sidecar schema: `<stem>.json` next to every shot--Every pulled shot gets a `<stem>.json` sidecar (a full+safe pair shares ONE sidecar). **This is the self-describing record a visualizer should read instead of parsing the response envelope.**--```jsonc-{-  "source": "desktop_screenshot_window",     // the verb that produced it-  "timestamp": "2026-08-10T01:14:16.937Z",   // RFC3339 UTC-  "kind": "window",                          // "window" | "screen"-  "hwnd": 986710,                            // CGWindowID; null for a "screen" grab-  "title": "KiCad 9.0 - myboard.kicad_pcb",  // window title (null for screen)-  "full": { "path": ".../window/<stem>.png", "w": 1568, "h": 980, "bytes": 402931 },-  "safe": { "path": ".../window/<stem>.png", "w": 1568, "h": 980, "bytes": 402931 },-  //  (when the shot was under the cap, full.path == safe.path == the single <stem>.png)-  "coordMap": null,                          // always null on macOS (Windows-only field)-  "windowRect": null                         // always null on macOS-}-```--Array-entry shots (each window of a `kicad_screenshot_all`) get the same sidecar plus `parent`/`popupIndex` slots (null when the response has no top-level parent, which is the `kicad_screenshot_all` case) and their own `rect` when the entry carried one.--**How a renderer groups a capture from disk alone:**-1. List `<shots_dir>/window/` and `<shots_dir>/screen/`, newest-first (filenames sort chronologically).-2. Read each `<stem>.json` for source, kind, window id, title, and dims.-3. Prefer `safe.path` for thumbnails/inline display, `full.path` for a zoom view; if `full.path == safe.path`, there is a single file.-------## 7. Driving without disturbing the user--Capture is background by default (no focus steal, no cursor move). To also ACT without foregrounding:--- `desktop_find_control {hwnd, name|contains, role?}` then `desktop_ui_click` / `desktop_ui_set`: background press / set-value by accessible name via the macOS Accessibility API (AXPress / AXValue). Requires the Accessibility permission; action verbs are gated by shell approval. When an element exposes no usable AX action, the fallback is a CGEvent click, which foregrounds and is reported as `pathTaken:"cgevent-fallback"`. Every response carries a `foreground` block whose `observed`/`raised` are MEASURED (frontmost app before/after), never asserted.-- Coordinate clicks (`desktop_click {x, y}` in points) as the fallback when a control is not in the AX tree.-- `desktop_ui_watch` / `desktop_ui_events` / `desktop_ui_selftest` are not yet implemented on macOS and return a clean `not_implemented_macos` error.-------## Related--- `desktop_find_window {titleContains|className}`: resolve a window id; both are case-insensitive substrings, and `className` matches the owning APP's name on macOS. Topmost match wins.-- `desktop_list_windows`: enumerate all on-screen, titled windows with ids + rects (front-to-back Z-order).-- `desktop_list_monitors`: the display map (points bounds, pixel size, Retina scale, primary).-- `desktop_screenshot_screen`: main-display grab.-- `adom-desktop janitor status`: verify the auto-pull cache is being managed (so a tool never builds its own cleaner).