adom-cli

@@ -0,0 +1,476 @@+---+name: workspace+description: "Hydrogen Workspace & Panels: Get layout, add/remove tabs, split/resize/close panes, move/swap tabs, activate tabs, Web View control, Sandbox eval/reset, screenshots (panel/workspace/screen). Auto-detects current repo."+---++# Workspace Management++Control the Hydrogen editor workspace layout — panes, tabs, splits, and screenshots.++All commands auto-detect auth, owner, and repo from `VSCODE_PROXY_URI`. No setup needed.++## Quick Recipes++```bash+# Check sharing status, request if needed+adom-cli hydrogen screenshot status+adom-cli hydrogen sharing request --share screen --audio --reason "Need to capture demo"++# Screenshot (saved automatically to ~/project/screenshots/)+adom-cli hydrogen screenshot workspace+adom-cli hydrogen screenshot panel --panel-id <leaf-id>+adom-cli hydrogen screenshot panel --tab-id <tab-id>++# Record screen with countdown (saved to ~/project/recordings/)+adom-cli hydrogen recording start --share tab --mic true --countdown 3 --reason "..."+adom-cli hydrogen recording stop++# Get workspace layout (to find panel/tab IDs)+adom-cli hydrogen workspace get++# Add a sandbox panel to the left of the current pane+adom-cli hydrogen workspace split --panel-id <leaf-id> --direction horizontal \+  --panel-type "adom/a1b2c3d4-5555-4000-a000-000000000050" --position before++# Navigate a web view+adom-cli hydrogen webview navigate --panel-id <leaf-id> "https://example.com"++# Run JS in a sandbox+adom-cli hydrogen sandbox eval --panel-id <leaf-id> 'document.body.innerHTML = "<h1>Hello</h1>"'+```++## Commands++### List all tabs (flat array — no tree parsing needed)+```bash+adom-cli hydrogen workspace tabs+```++### Find a tab by name+```bash+adom-cli hydrogen workspace find-tab "Schematic Editor"+```++### Get full workspace layout (tree)+```bash+adom-cli hydrogen workspace get+```++### Add a tab to a pane+```bash+adom-cli hydrogen workspace add-tab \+  --panel-id <leaf-id> \+  --panel-type "adom/a1b2c3d4-0031-4000-a000-000000000031" \+  --display-name "Bug Review" \+  --display-icon "mdi:bug" \+  --initial-state '{"url":"https://..."}' \+  --alert+```+- `--panel-id` (required): leaf pane ID+- `--panel-type` (required): panel type UUID+- `--display-name` (required): must be unique+- `--alert`: blink + scroll into view on creation+- `--alert-duration`: seconds to blink (0 = indefinite)++### Remove a tab (5 modes)+```bash+# Close just this tab (default mode)+adom-cli hydrogen workspace remove-tab --name "Bug Review"++# Close all other tabs in the pane, keep this one (becomes the active tab)+adom-cli hydrogen workspace remove-tab --name "Bug Review" --mode others++# Close the entire pane (fails if it's the last pane in the workspace)+adom-cli hydrogen workspace remove-tab --name "Bug Review" --mode all++# Close every tab to the right of the referenced tab+adom-cli hydrogen workspace remove-tab --name "Bug Review" --mode right++# Close every tab to the left of the referenced tab+adom-cli hydrogen workspace remove-tab --name "Bug Review" --mode left++# By UUID (same --mode options apply)+adom-cli hydrogen workspace remove-tab --panel-id <leaf-id> --tab-index 0+```++For `others`/`right`/`left`, the referenced tab becomes active automatically. For `all`, the pane is removed entirely and its sibling is promoted.++### Split a pane+```bash+adom-cli hydrogen workspace split \+  --panel-id <leaf-id> \+  --direction horizontal \+  --panel-type "adom/a1b2c3d4-0031-4000-a000-000000000031" \+  --display-name "New Pane" \+  --position before \+  --ratio 0.4+```+- `--display-name` (required): must be unique+- `--direction`: `horizontal` or `vertical`+- `--position`: `before` (left/top) or `after` (right/bottom). Default: `after`+- `--ratio`: 0.0–1.0. Default: `0.5`++### Resize a split+```bash+adom-cli hydrogen workspace resize --split-id <split-id> --ratio 0.6+```++### Move a tab between panes++The moved tab is **auto-activated and scrolled into view** in the target pane (Hydrogen takes care of this; no separate `active-tab` call needed).++```bash+# By name+adom-cli hydrogen workspace move-tab --source-name "Bug Review" --target-name "Schematic Editor"++# By UUID+adom-cli hydrogen workspace move-tab --from-panel-id <id> --tab-id <id> --to-panel-id <id>++# Insert at a specific position (default: append)+adom-cli hydrogen workspace move-tab --source-name "Bug Review" --target-name "Schematic Editor" --target-index 0++# Blink the moved tab in its new pane until user clicks (or duration elapses)+adom-cli hydrogen workspace move-tab --source-name "Bug Review" --target-name "Schematic Editor" \+  --alert                    # blink indefinitely+adom-cli hydrogen workspace move-tab --source-name "Bug Review" --target-name "Schematic Editor" \+  --alert --alert-duration 5 # blink for 5 seconds+```++Use `--alert` when the user might not be looking at the destination pane and you want to draw attention to where the tab landed.++### Swap all tabs between two panes+```bash+# By name+adom-cli hydrogen workspace swap --source-name "Bug Review" --target-name "Schematic Editor"++# By UUID+adom-cli hydrogen workspace swap --panel-id-a <id> --panel-id-b <id>+```++### Bring a tab to foreground+```bash+# By name (preferred)+adom-cli hydrogen workspace active-tab --name "Schematic Editor"++# By UUID+adom-cli hydrogen workspace active-tab --panel-id <leaf-id> --tab-id <tab-id>+```++### Close a pane+```bash+# By name or UUID+adom-cli hydrogen workspace close-panel "Bug Review"+adom-cli hydrogen workspace close-panel <leaf-id>+```++## Typical workflow++1. `workspace tabs` to see all tabs (flat list with names)+2. Use `--name` to target tabs — no UUIDs needed+3. `add-tab` or `split` to add content (with `--alert` to blink)+4. `close-panel` by name to remove panes++## Web View panel control++All webview commands accept `--name`, `--panel-id`, or `--tab-id` for targeting. **The tab name is the stable handle** — it survives user drags between panes. Always re-resolve by `--name` on each call; do **not** cache `tabId`/`panelId` across turns.++### Idempotent "open or refresh" — use this for long-lived viewers++When you have a viewer/dashboard tab that you create once and re-render many times (tscircuit viewer, log panel, etc.), use the one-shot idempotent command:++```bash+# First call: tab doesn't exist → creates it+adom-cli hydrogen webview open-or-refresh \+  --name "tscircuit viewer" \+  --url "https://kcknox-gallia-....adom.cloud/proxy/3000/" \+  --panel-id <target-pane-id>++# Every subsequent call with the same --name: navigates the existing tab,+# even if the user dragged it to a different pane. No duplicates. No --panel-id needed.+adom-cli hydrogen webview open-or-refresh \+  --name "tscircuit viewer" \+  --url "https://kcknox-gallia-....adom.cloud/proxy/3000/?cache-bust=$(date +%s)"+```++Response includes `"action": "created"` or `"action": "refreshed"` so you know which path ran. If the tab was closed, the next call recreates it (requires `--panel-id` again).++### Navigate response classes — Hydrogen probes URLs before applying++`webview navigate` and `open-or-refresh` now return structured responses based on URL reachability:++| Status | Meaning | `_hint` | Action |+|---|---|---|---|+| **204** | Clean success | "Navigated successfully." | Proceed |+| **200 + `warning`** | Navigated, but page is broken (ECONNREFUSED, HTTP 5xx, DNS fail) | Tells you which port's server isn't running | Start the server and re-run — tab stays, no recreate needed |+| **400** | Malformed URL or non-http/https scheme | "Check for typos, missing protocol" | Fix the URL, don't retry |+| **403** | SSRF blocked (localhost, 127.0.0.1, 10.x, 172.x, 192.168.x) | "Use the proxied URL: https://container.adom.cloud/proxy/PORT/" | Rewrite URL to use the proxy path |+| **404** | Wrong tab name | Lists all available tab names | Re-fetch tabs or fix the name |++The **soft-fail** case (200 + warning) is the most important for the AI: the response includes `warning.upstreamBody` with the actual error text (e.g., `"connect ECONNREFUSED 0.0.0.0:8830"`), so you can diagnose "dev server not started" without asking the user to look at the iframe.++### Lower-level operations (only when open-or-refresh isn't enough)++```bash+# Navigate a Web View by name+adom-cli hydrogen webview navigate --name "Bug Review" "https://example.com"++# Or by panel/tab ID (rarely needed — name is preferred)+adom-cli hydrogen webview navigate --panel-id <leaf-id> "https://example.com"+adom-cli hydrogen webview navigate --tab-id <tab-id> "https://example.com"++# Refresh the current page+adom-cli hydrogen webview refresh --name "Bug Review"++# Hide/show the address bar+adom-cli hydrogen webview set-header --name "Bug Review" true++# Enable/disable proxy mode (tracks in-page navigation)+adom-cli hydrogen webview set-proxy --name "Bug Review" true+```++## Sandbox panel control++All sandbox commands accept `--name`, `--panel-id`, or `--tab-id` for targeting.++```bash+# Execute JavaScript by tab name (preferred)+adom-cli hydrogen sandbox eval --name "My Script" 'document.body.innerHTML = "<h1>Hello</h1>"'++# Or by panel ID (finds sandbox tab in that leaf — 409 if multiple)+adom-cli hydrogen sandbox eval --panel-id <leaf-id> 'console.log("hi")'++# Reset the sandbox — wipe iframe and clear all state+adom-cli hydrogen sandbox reset --name "My Script"++# Hide/show the toolbar+adom-cli hydrogen sandbox set-header --name "My Script" true+adom-cli hydrogen sandbox set-header --name "My Script" false+```++**Eval response statuses:**+- `executed` — code ran, result printed+- `error` — code threw, error printed, exit 1+- `queued` — auto-approve is off, user must approve in the panel+- `rejected` — user rejected the queued code, exit 1++Sandbox panel type UUID: `adom/a1b2c3d4-5555-4000-a000-000000000050`++## Sharing & permissions++Before screenshots or recordings, check and request sharing:++```bash+# Check what's currently available+adom-cli hydrogen screenshot status++# Request sharing (opens approval dialog for the user)+adom-cli hydrogen sharing request --share tab                      # tab sharing (panel + workspace)+adom-cli hydrogen sharing request --share screen --audio           # screen + mic+adom-cli hydrogen sharing request --share screen --audio --reason "Recording demo walkthrough"+```++Returns `approved`, `already_active`, or `dismissed` (exit 1). After approval, screenshots and recordings work.++## Screenshots (any panel, workspace, or screen)++Screenshots are **workspace-level** and work on ANY panel type. Files are saved automatically to `~/project/screenshots/`.++```bash+# Capture a panel by name (preferred)+adom-cli hydrogen screenshot panel --name "Schematic Editor"++# Capture by panel ID or tab ID+adom-cli hydrogen screenshot panel --panel-id <leaf-id>+adom-cli hydrogen screenshot panel --tab-id <tab-id>++# Sandbox fallback (no sharing needed)+adom-cli hydrogen screenshot panel --panel-id <leaf-id> --method html2canvas++# Capture the entire workspace (all panels side by side)+adom-cli hydrogen screenshot workspace++# Capture the entire screen (desktop, taskbar, other apps)+adom-cli hydrogen screenshot screen++# Check sharing status and available scopes+adom-cli hydrogen screenshot status+```++Prints the file path on success (e.g. `screenshots/2026-04-08T22-51-15.png`).++| Scope | What it captures | Method |+|-------|-----------------|--------|+| `panel` | A single panel's content | `element-capture` (default) or `html2canvas` (sandbox only) |+| `workspace` | All panels side by side | `element-capture` only |+| `screen` | Entire display including desktop | `element-capture` only |++**Unified flow:** Just call `screenshot` with an optional `--reason`. If sharing isn't active, the approval dialog opens automatically with that reason and the call blocks until the user approves (up to 90s) — then the screenshot is captured and returned.++```bash+adom-cli hydrogen screenshot workspace --reason "Need to see the layout"+adom-cli hydrogen screenshot panel --name "Schematic Editor" --reason "Debugging schematic"+```++**AI decision flow:**+1. Just call `screenshot` with `--reason` — one call handles everything+2. If already sharing, it captures immediately; if not, the dialog opens and the call waits+3. `html2canvas` works without sharing for sandbox panels only+4. Use `screenshot status` if you need to check current sharing state without capturing++## Screen Recording — capture video with audio++Files are saved automatically to `~/project/recordings/`.++**`recording start` requires FOUR flags. All four are mandatory** — this forces you to think through scope, audio, pacing, and intent every time:++| Flag | Values | Why required |+|------|--------|--------------|+| `--share` | `tab` \| `screen` | What to capture (see below) |+| `--mic` | `true` \| `false` | Whether voiceover is part of this take |+| `--countdown` | `0`+ seconds | `0` for immediate, `3`+ for "get ready" pacing |+| `--reason` | string ≥20 chars | Shown in approval dialog **and** countdown toast so the user can tell **which** Claude session is asking — critical when multiple sessions are running |++```bash+# Hydrogen content with voiceover, 3-2-1 countdown+adom-cli hydrogen recording start --share tab --mic true --countdown 3 --reason "Schematic editor walkthrough — explaining the new molecule"++# Desktop apps demo (KiCad, Fusion, Chrome) with voiceover, no countdown+adom-cli hydrogen recording start --share screen --mic true --countdown 0 --reason "KiCad PCB layout — routing the power traces"++# Silent screen capture for a screenshot loop, no countdown+adom-cli hydrogen recording start --share tab --mic false --countdown 0 --reason "Capturing animation behavior in the new viewer"++# Stop recording (file saved automatically)+adom-cli hydrogen recording stop+```++Output is WebM (VP9 + Opus).++**Smart delta — the approval dialog only appears when something needs to change.** Hydrogen compares the requested `--share`/`--mic` to what's currently active:++| Current state | Requested state | What happens |+|---|---|---|+| Nothing shared | `tab` + mic | Dialog shown (first take) |+| Tab + mic active | `tab` + mic | **No dialog**, straight to countdown |+| Tab + mic active | `screen` + mic | Stops tab, dialog for screen |+| Screen + mic active | `tab` + mic | Stops screen, dialog for tab |+| Tab active, no mic | `tab` + mic | Dialog for mic only (share preserved) |+| Tab + mic active | `tab`, `mic false` | No dialog (mic just unused) |++This means **15-take demo loops never re-prompt** as long as you keep the same scope. Switching scope only prompts for what changed.++**If a recording is already active when you call `start` again, it auto-stops, saves, and uploads first** — the response includes a `previousRecording: { filePath, size }` field pointing to the saved file before the new recording begins.++**Choose `--share` based on what the user wants to record:**+- **`tab`** → captures the Hydrogen browser tab. Use for: panels, web views, sandbox demos, anything inside the editor.+- **`screen`** → captures the entire display including desktop apps. Use for: KiCad/Fusion 360 walkthroughs, demos that switch between Hydrogen and native apps, anything outside the browser.++**Reason is critical.** The user may have 6 Claude sessions running. When the approval dialog (or countdown toast) pops up, the reason is their **only** signal of which session is asking. "Recording" or "demo" is useless. Be specific: "Re-take 3 of KiCad PCB layout demo".++Same scope logic applies to screenshots: `screenshot workspace`/`panel` for editor content, `screenshot screen` for the whole desktop.++## Audio — microphone control and recording++Audio files are saved automatically to `~/project/audio/`.++```bash+# Enable mic (silent if permission already cached)+adom-cli hydrogen audio enable+adom-cli hydrogen audio enable --reason "Need mic for demo voiceover"++# Disable mic+adom-cli hydrogen audio disable++# Check mic status+adom-cli hydrogen audio status++# Start recording audio+adom-cli hydrogen audio start++# Stop recording (file saved automatically)+adom-cli hydrogen audio stop++# Get current mic level (rms, peak, clipping, gain)+adom-cli hydrogen audio level++# Set mic gain (0.0 - 4.0, persisted)+adom-cli hydrogen audio gain 1.5    # 1.5x boost+adom-cli hydrogen audio gain 0.5    # 0.5x reduction+adom-cli hydrogen audio gain 1.0    # unity (reset)+```++**Mic level / gain:**+- `level` returns `{ rms, peak, clipping, gain }` — use to verify input is healthy before recording+- `gain` is clamped to 0.0–4.0, persisted across sessions, applied smoothly (no clicks)+- `status` also includes the level/gain fields+- If `clipping: true` → reduce gain (audio is too loud)+- If `peak < 0.05` → increase gain or move closer to the mic++## Captions — overlay text on the workspace++```bash+# Default (center, medium, 3 seconds)+adom-cli hydrogen caption show "Hello World"++# Large at top for 5 seconds+adom-cli hydrogen caption show "Step 1: Calibrating" -d 5 -p top -s large++# Small at bottom, indefinite (stays until hidden)+adom-cli hydrogen caption show "Waiting for input..." -d 0 -p bottom -s small++# Hide the current caption+adom-cli hydrogen caption hide+```++| Option | Flag | Default | Values |+|--------|------|---------|--------|+| Duration (seconds) | `-d` | 3 | Any number, 0 = indefinite |+| Position | `-p` | center | `top`, `center`, `bottom` |+| Size | `-s` | medium | `small` (32px), `medium` (56px), `large` (96px) |++## Tab alerts — blink a tab to get attention++```bash+# Alert a tab (blinks until dismissed)+adom-cli hydrogen alert set <tab-id>++# Alert with auto-clear after 5 seconds+adom-cli hydrogen alert set <tab-id> -d 5++# Clear a specific tab's alert+adom-cli hydrogen alert clear <tab-id>++# Clear all alerts+adom-cli hydrogen alert clear+```++## Navigation bar — minimize/expand/toggle++```bash+adom-cli hydrogen nav minimize   # collapse the nav bar+adom-cli hydrogen nav expand     # expand the nav bar+adom-cli hydrogen nav toggle     # toggle between states+```++## Common panel type UUIDs (updated)++| Panel | UUID |+|-------|------|+| VS Code editor | `adom/a1b2c3d4-eeee-4000-a000-00000000000e` |+| Web View | `adom/a1b2c3d4-0031-4000-a000-000000000031` |+| Sandbox | `adom/a1b2c3d4-5555-4000-a000-000000000050` |+| 3D Viewer | `adom/a1b2c3d4-1111-4000-a000-000000000001` |+| Schematic Editor | `adom/a1b2c3d4-0012-4000-a000-000000000012` |+| System Log | `adom/a1b2c3d4-0011-4000-a000-000000000011` |++## Important++- **Never `PUT` or `DELETE` the `/current` workspace root.** `PUT /current` replaces the entire layout and breaks node IDs; `DELETE /current` tears down the editor session. Both are prohibited for AI use — past incidents have wiped user workspaces (VS Code + all panes) in a single call. Use the granular sub-paths only (`/current/tabs`, `/current/splits`, `/current/moves`, `/current/swaps`, `/current/panels/{id}`). If an operation isn't supported by those, it isn't supported for AI use — do not probe for additional methods.+- The Hydrogen editor must be open for these commands to work (not available via SSH)+- **Check browser connectivity + window mode before opening windows:** `adom-cli hydrogen probe` returns `{browser_connected, sse_connections, last_sse_event_at, window_mode}` in <300ms with no side effects. `window_mode` is `"webview"` (open as Hydrogen tab) or `"pup"` (open via Adom Desktop). Read it before opening any window — don't cache, so user toggles take effect immediately. If `"pup"` but Adom Desktop isn't reachable, fall back to webview and warn.+- **Get/set window mode:** `adom-cli hydrogen window-mode get` reads the preference; `adom-cli hydrogen window-mode set webview|pup` changes it (broadcasts live to any open browser tabs). Mostly used by the editor UI — CLIs just read from probe.+- **All mutation endpoints now honestly 409 when the browser is gone.** Hydrogen's E2 guard refuses writes against zombie SSE sessions — `add-tab`, `remove-tab`, `move-tab`, `split`, `swap`, `active-tab`, `close-panel`, `alert set/clear`, `caption show/hide`, `nav minimize/expand/toggle`, `sharing request/stop`, `recording start/stop`, `audio *`, `screenshot panel/workspace/screen` all return `409 Conflict` with `"No browser session is connected"` instead of silently writing ghosts. The CLI catches this and emits a structured `_hint`: ask the user to surface/click the Hydrogen tab — E3 auto-reconnect fires on `visibilitychange`/`focus` and re-registers within seconds. Hard-refresh is only needed as a fallback. Re-run `hydrogen probe` to confirm, then retry.+- **504 handling** is unchanged: still means "browser is connected but didn't respond within 120s" (commonly a dismissed approval dialog). Retry with a clearer `--reason`. The CLI now uses the new probe endpoint for diagnosis, not `screenshot status`.+- **Force-reload all browser tabs:** `adom-cli hydrogen reload` broadcasts an SSE reload event to every connected browser tab. Fire-and-forget (204). Use for: hot-reload after deploys, recovery from corrupted client state, forcing pickup of new feature flags. 409s if no browser is connected (with auto-retry via E3).+- **VS Code pane guard (v0.5.4+):** `workspace add-tab` and `webview open-or-refresh` automatically redirect away from the VS Code pane. If you pass a `--panel-id` that hosts VS Code, the CLI finds an alternative pane (or auto-splits to create one) and adds the `_vscode_guard` field to the response explaining the redirect. This means **you no longer need to manually avoid the VS Code pane** — the CLI enforces it. If every pane has VS Code (single-pane layout), it auto-splits horizontally to create a new pane.+- **Migration note:** Panel APIs (workspace + webview + sandbox) currently live in Hydrogen but will eventually move to Carbon. Keep implementations thin — don't build heavy abstractions on top of these endpoints.