Adom Hydrogen (platform base)

@@ -1,236 +0,0 @@-----name: hydrogen-self-screenshot-description: >-  Screenshot Hydrogen from inside the workspace — a panel/webview (the welcome page, a-  tab), the whole workspace, OR the whole screen/desktop — using the BUILT-IN-  `adom-cli hydrogen screenshot`. It saves a PNG into the container's-  `screenshots/` folder and prints the path to Read. THE answer for "take a-  screenshot of the welcome page", "screenshot the webview", "screenshot this-  panel", "screenshot the editor", "screenshot my whole screen / the desktop",-  "show me what Hydrogen looks like", or verifying a UI change (ralph loop). Use this-  even for "my whole screen / my desktop / my monitor" — that's the `screen`-  scope. You do NOT need any image resizer. For a SPECIFIC element/region (a CPU-  meter, a menu, a dialog, a toolbar) or an inline-b64 PNG, use the canonical-  `POST /screenshot` control endpoint with a CSS `selector` (it ALWAYS region-clips-  to that element) — and combine it with the UI command bus (`hydrogen-ui`: `ui/invoke`-  to open a menu/dialog, then `/screenshot` its selector). Identical across web-  Hydrogen and Hydrogen. Trigger words — screenshot Hydrogen, screenshot the welcome page,-  screenshot the webview, screenshot a panel, screenshot a tab, screenshot the-  workspace, screenshot the editor, screenshot my screen, screenshot the whole-  screen, screenshot the desktop, capture my monitor, full screen capture,-  screenshot everything on screen, what does Hydrogen look like, adom-cli hydrogen-  screenshot, capture panel, capture workspace, capture screen, screenshot a region,-  clip to selector, screenshot an element, screenshot a menu, screenshot a dialog,-  region screenshot, b64 screenshot, POST /screenshot, /shot, screenshot without flash,-  no-flash screenshot, which screenshot tool, verify visually, ralph loop, shotlog,-  image resizer, resize screenshot.------# Hydrogen — Screenshot a panel / webview / the workspace / the screen--The built-in way to screenshot anything inside Hydrogen is the **`adom-cli hydrogen-screenshot`** command — the *same* `adom-cli` you already use. It captures the-real rendered surface, drops a PNG into the container's `screenshots/` folder,-and prints the path. Just `Read` that path. **No image resizer needed.**--## Which screenshot tool? — the priority ladder--What you're capturing (and whether you want the teal flash) picks the tool. Default to-Hydrogen-native:--1. **Hydrogen content — a panel, the workspace, the editor, a webview, the screen-   (the 99% case): `adom-cli hydrogen screenshot panel|workspace|screen`. THIS IS THE-   DEFAULT — reach for it first.** It's the *same* command in web Hydrogen and Hydrogen (Hydrogen is-   meant to behave like web Hydrogen, and `adom-cli` is the one surface that's identical on-   both), saves a PNG to your container's `screenshots/`, and you just `Read` it. Don't lead-   with an Hydrogen-only endpoint.-   - **Hydrogen-only enhancement / power path — `POST /screenshot {target, selector, b64, silent}`-     (CDP).** Use ONLY when you need something `adom-cli` doesn't give you: a precise CSS-     `selector` region-clip, an inline-base64 PNG (`b64`), or a `silent` (no-flash) grab — see-     below. It does NOT exist in web Hydrogen, so it's a deliberate step OFF the consistent path.-   - **The one time you switch to CDP for an ordinary shot:** during another thread's-     recording the `adom-cli` SSE path returns `capture_busy` — then fall to `POST /screenshot`-     (CDP), which coexists (see "During a recording" below). That's a fallback, not the default.--## During a recording (multi-thread) — pick a coexisting method, never blind-retry--Adom users run **multiple AI threads on one Hydrogen**, so another thread may be recording the-screen while you capture. **Only the `adom-cli` SSE path (`screenshot panel/workspace/screen`)-is affected** — the CDP path coexists. Hydrogen makes this deterministic:--- **Pre-flight `GET /capture/availability`** → reports the recording state plus, per method,-  reliability + whether it coexists with a recording, a `recommended` method, and a `_hint`.-  Check it **only when a recording might be running.**-  - **`recommended` is STATE-DEPENDENT and agrees with the default:** when-    `recording.active === false` it returns **`"sse"`** (≡ `adom-cli hydrogen screenshot`, the-    web-Hydrogen-consistent default); when `recording.active === true` it returns **`"cdp"`**-    (the SSE path would `capture_busy`, so CDP is correct). So you can follow `recommended`-    directly — it will never push you off `adom-cli` while idle. Your everyday default remains-    `adom-cli`; CDP is the during-a-recording fallback.-- **`capture_busy`:** the SSE path (`PATCH /current/screenshot`, i.e. `adom-cli screenshot-  panel/workspace`) returns, the moment a recording is active, `{ok:false, error:"capture_busy",-  retry_after_ms, alternatives:[{method:"cdp"}], _hint}` — never an empty body. **On-  `capture_busy`: read `alternatives` and SWITCH — do NOT blindly retry the SSE path.**-- Authoritative recording state: `GET /recording/native/status`. See `hydrogen-recording`.--## Pick the scope — panel / workspace / screen--| You want… | Command | Sub-command |-|---|---|---|-| ONE panel or webview tab (the welcome page, a viewer, the editor) | `adom-cli hydrogen screenshot panel …` | `panel` |-| The whole Hydrogen **workspace** (every panel side by side) | `adom-cli hydrogen screenshot workspace` | `workspace` |-| The whole **screen** — desktop, OTHER apps | `adom-cli hydrogen screenshot screen` | `screen` |--**"My whole screen / my desktop / my monitor / everything"** → `adom-cli hydrogen-screenshot screen`. The Hydrogen `screen` scope captures the real desktop and saves the PNG into-your container, same as the others.--## Do this — it saves a PNG and prints the path; then Read it--```bash-# Whole workspace (simplest — no tab name needed):-adom-cli hydrogen screenshot workspace-# → prints  screenshots/<ts>.png  (relative to ~/project) → Read ~/project/screenshots/<ts>.png--# Whole screen / desktop (other apps too):-adom-cli hydrogen screenshot screen --reason "show the desktop"--# A specific panel / webview tab. Tab names are whatever the USER has open — DON'T-# guess (a guess like --name welcome 404s if the tab is actually named "Wiki").-# If you're not certain the tab exists by that name, LIST tabs first:-adom-cli hydrogen workspace get        # shows every panel/tab: its id AND name-# then capture by --tab-id (most reliable) or the EXACT name you saw:-adom-cli hydrogen screenshot panel --tab-id <tabId>-adom-cli hydrogen screenshot panel --name "3D Viewer"-```--The welcome page is *usually* a tab named "Welcome", but on an active workspace it-may be replaced (e.g. by a "Wiki" tab) — so if `--name welcome` 404s with-`No tab matching 'welcome'`, run `adom-cli hydrogen workspace get` and screenshot-the webview tab you find by its `--tab-id`.--### What it returns — a saved path; just Read it-The command saves the PNG into the container's `screenshots/` folder and prints the-path. **Read it — done.** No decoding, no resizer, no second tool. The printed path-is **relative to `~/project`** (matches the cloud contract); the `_hint` gives the full-path:--```-screenshots/2026-06-13T20-04-43.png-_hint: Screenshot saved to ~/project/screenshots/<ts>.png. Read the file to view it.-```-→ `Read ~/project/screenshots/<ts>.png` (prepend `~/project/` to the line-1 path, or-just use the full path from the `_hint`).--### If a capture errors, retry once-A COLD capture can occasionally fail with a proxy URL containing a literal `{{port}}`-(e.g. `…/proxy/{{port}}/: error sending request`) — a known **adom-cli** cold-start-race (the proxy port isn't substituted yet). Just **run the same command again**; the-warm retry succeeds.--## Sharing must be active (it usually is; here's the gate)--Capturing a panel/workspace needs an active tab/screen share. Check and, if-needed, the `--reason` you pass pops a one-time approval the user clicks:--```bash-adom-cli hydrogen screenshot status     # → {"sharing":{"active":true},"availableScopes":["panel","workspace"]}-# If a panel/workspace shot 409s or says sharing isn't active, just include-# --reason "<why>" (it triggers the approval dialog), or explicitly request it:-adom-cli hydrogen sharing request --share tab     # panel/workspace scopes-adom-cli hydrogen sharing request --share screen  # adds the 'screen' scope-```-The `screen` scope is for the whole desktop; `panel`/`workspace` come from tab-sharing. See `hydrogen-capture-share` for the sharing/approval UX.--**Release SCREEN sharing when you're done.** A `screen` share (getDisplayMedia) holds the-display **awake** — leaving it active blocks the user's screensaver. After a one-off-`screen` capture, run `adom-cli hydrogen sharing stop` (and close any Pup windows you-opened). Tab `panel`/`workspace` sharing doesn't hold the display, so this only matters-once you've requested the `screen` scope.--## Why this works the same in Hydrogen as it does for web Hydrogen--`adom-cli` is **one binary** used by both web Hydrogen and Hydrogen — you can test these-commands anywhere. The difference is purely *where the work runs*: Hydrogen intercepts-what adom-cli talks to. `adom-cli hydrogen <cmd>` hits `ADOM_HYDROGEN_URL`, which-in Hydrogen points at **Hydrogen's local proxy**. Hydrogen's proxy pulls out the **local hydrogen/SSE-commands** (screenshot, webview, caption, notify, recording…) and runs them against-the Hydrogen frontend over SSE, while **carbon/cloud calls pass straight through** to the-cloud. For a screenshot: `PATCH /current/screenshot` → Hydrogen broadcasts an SSE-`screenshot_request` → the frontend Element-Captures the panel → uploads it into-**this container's** `screenshots/` folder → the CLI returns the saved path. So the-command, and the returned path, behave the same — the bytes just land in your local-container.--## What NOT to do (these are the traps)--- **You do NOT need an image resizer.** `adom-cli hydrogen screenshot` produces a-  normal PNG and the `Read` tool reads PNGs directly. (Don't reach for ImageMagick-  `convert` or Pillow — neither is guaranteed in the golden image, and you don't-  need them.)--## Capture ANY region, element, or surface — `POST /screenshot`--`adom-cli hydrogen screenshot` above is the easy "save a panel/workspace/screen PNG"-path. For **precise control** — a specific VS Code or webview surface, **any CSS-region** (a meter, a menu, a dialog, a toolbar), or an inline PNG with no flash — use-Hydrogen's **canonical capture endpoint `POST /screenshot`** (aliases: `/shot`,-`/capture/viewport`). Read the control URL from the FILE — it's the dynamic port, and-your non-login Bash shell won't have the env var:--```bash-CTRL="$(cat ~/.adom/hydrogen-control-url)"   # http://127.0.0.1:<dynamic>-curl -s -X POST "$CTRL/screenshot" -H 'Content-Type: application/json' \-  -d '{"target":"full","b64":true}'-```--| Field | Meaning |-|---|---|-| `target` | the surface — `full`/`window` (whole Hydrogen window) · `vscode`/`editor`/`workbench`/`code` (the VS Code panel) · `shell`/`hd` (the Svelte shell: title bar, menus, panels) · a **webview url-substring** (e.g. `wiki`) · **or a TAB DISPLAY NAME** (e.g. `"ScreenA"`, `"VS Code"`) — see by-name note below |-| `selector` | **optional CSS selector — it ALWAYS WINS and region-clips to that element.** e.g. `.resource-bars` (CPU/RAM meter), `iframe[src*='wiki']`, `.setup-panel`, `.dialog`, `.dropdown-content.open` |-| `b64` | `true` → returns the PNG inline as a `dataUrl` (decode + Read); else saved to a file in `screenshots/` |-| `silent` | `true` → suppress the capture flash |-| `name` | optional label for the saved file |--A `selector` clips to the **first matching element** in that surface — grab JUST a-meter, a menu, a dialog, a toolbar instead of the whole window (verified live:-`{selector:".resource-bars"}` → 192×61, vs `{target:"full"}` → the whole window).--**Screenshot a tab by its display NAME — incl. a BACKGROUND tab.**-`POST /screenshot {target:"<tab name>"}` resolves the name → the workspace panel, **activates-that tab** (so a *background* tab actually paints — a webview is an OOPIF and can't be CDP-shot-while hidden), captures the shell cropped to that panel, then **restores the previously-active-tab**. So in a pane stacked `VS Code | ScreenA | ScreenB` (ScreenB showing), `{target:"ScreenA"}`-returns ScreenA's pixels and leaves ScreenB active. The `adom-cli` SSE path-(`screenshot panel --name ScreenA`) also activates + restores. This is the right call for-"shot tab #2 while #4 is showing."--**The teal zap:** every Hydrogen-driven capture flashes a teal (`#00b8b0`) highlight on the-captured **region** (just the panel/menu/region; full-window flash only for-`target:full`). Teal = Hydrogen-driven. Pass `silent:true` to suppress it.--### Screenshot a menu / dialog / panel — open it, then clip to it-The killer combo with the UI command bus (see **`hydrogen-ui`**): **open a surface →-screenshot just that surface → close it** — no screen-clicking, no guessing where it is.-```bash-CTRL="$(cat ~/.adom/hydrogen-control-url)"-curl -s -X POST "$CTRL/ui/invoke"  -H 'Content-Type: application/json' -d '{"id":"adom-menu.open"}'-curl -s -X POST "$CTRL/screenshot" -H 'Content-Type: application/json' -d '{"target":"shell","selector":".dropdown-content.open","b64":true}'-curl -s -X POST "$CTRL/ui/invoke"  -H 'Content-Type: application/json' -d '{"id":"adom-menu.close"}'-```-Resolved selectors (verified live): **Adom menu & profile menu** → `.dropdown-content.open`-(only one open at a time); **Setup panel** → `.setup-panel`; **API Explorer** → `.dialog`.-`GET $CTRL/ui/actions` for the live set of menus/dialogs you can open (see `hydrogen-ui`).--## Ralph loop + shotlog (optional)--Verify a UI change: make the change → (rebuild if needed) →-`adom-cli hydrogen screenshot panel --name <panel>` → `Read` it → wrong? fix and-repeat. Log shots for the user with `shotlog inject -c hydrogen-ui -d "<desc>" <path>`-(shotlog resizes internally — another reason you don't need `convert`).--## Related skills-- [hydrogen-capture-share](../hydrogen-capture-share/SKILL.md) — the sharing/approval UX behind `screenshot`-- [hydrogen-recording](../hydrogen-recording/SKILL.md) · [hydrogen-captions](../hydrogen-captions/SKILL.md) — sibling `adom-cli hydrogen` AV verbs-- `shotlog` — the screenshot log viewer/injector