--- name: hd-self-screenshot description: > Screenshot HD 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 HD 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, NOT adom-desktop. Do NOT curl host.docker.internal, do NOT use adom-desktop's OS screenshot for anything inside HD (or for the screen), and 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 (`hd-ui`: `ui/invoke` to open a menu/dialog, then `/screenshot` its selector). Trigger words — screenshot HD, 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 HD 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, hd_shot, hd_screenshot, screenshot KiCad, screenshot another app, screenshot a non-HD window, desktop_screenshot_window, desktop_screenshot_screen, which screenshot tool, verify visually, ralph loop, shotlog, image resizer, resize screenshot. --- # HD — Screenshot a panel / webview / the workspace / the screen The built-in way to screenshot anything inside HD 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 `host.docker.internal`, no ImageMagick.** (`adom-desktop`'s host verbs DO have a place — other apps, no-flash grabs, the whole desktop — see the ladder; just not as the default for HD content.) ## Which screenshot tool? — the priority ladder You have HD-native capture AND AD's host verbs. **What** you're capturing (and whether you want the teal flash) picks the tool. Default to HD-native: 1. **HD 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 HD (HD 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 HD-only endpoint. - **HD-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. 2. **HD content, NO flash** (clean shot, or HD's CDP/SSE isn't mounted): `adom-desktop hd_shot '{"region":"full|titlebar|setup-panel|…"}'` (named HD-window regions) or `adom-desktop hd_screenshot` (the whole HD window). Host-side, deliberately **no teal flash**. 3. **A specific NON-HD app window** (KiCad, Fusion 360, a native dialog — **or an HD Tauri browser window, which is less-tested**): `adom-desktop desktop_list_windows` → `desktop_screenshot_window '{"hwnd":N}'`. OS PrintWindow of one window; coexists with a recording. See `hd-bridges`. 4. **Your app in a Pup browser window** (AI-driven Chrome — hero images, clean app shots): **`adom-desktop browser_screenshot '{"sessionId":"…"}'`** (the `pup` skill). Full-page, no HD chrome, no flash — separate Chrome, so it coexists with an HD recording. 5. **The whole physical desktop** (every app, taskbar): `adom-cli hydrogen screenshot screen` (HD scope) OR `adom-desktop desktop_screenshot_screen` (AD host GDI). Both **coexist with a recording** (independent of HD's WGC/DXGI recorder — corrected 2026-06-14; `ad_screen` can be intermittent under heavy load). ## During a recording (multi-thread) — pick a coexisting method, never blind-retry Adom users run **multiple AI threads on one HD**, so another thread may be recording the screen while you capture. **Only the `adom-cli` SSE path (`screenshot panel/workspace/screen`) is affected** — everything else coexists. HD makes this deterministic: - **Pre-flight `GET /capture/availability`** → `{recording:{active,source}, methods:{cdp, ad_window, ad_screen, pup, sse} each w/ reliability + coexists_with_recording, recommended, _sharing_note, _hint}`. Check it **only when a recording might be running.** - **`recommended` is STATE-DEPENDENT (HD v0.1.40+) and agrees with the default:** when `recording.active === false` it returns **`"sse"`** (≡ `adom-cli hydrogen screenshot`, the web-Hydrogen-consistent default, rung #1); 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. (Verified live 2026-06-14: idle → `recommended:"sse"`.) Your everyday default remains `adom-cli`; CDP is the during-a-recording fallback. - **`_sharing_note`:** HD-native capture uses CDP, so there is **no real screen-share to detect** (any "sharing" field would be a meaningless `false`) — the truthful signal is the note + the recording status, not a sharing flag. The display-hold / screensaver-block footgun is a **web-Hydrogen-only** problem (its `getDisplayMedia` holds `ES_DISPLAY_REQUIRED`); if you hit a pinned display, the fix is **`adom-cli hydrogen sharing stop`**, not anything HD-side. See [hd-screen-lock](../hd-screen-lock/SKILL.md). - **`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"},{ad_window},{ad_screen},{pup}], _hint}` — never an empty body. **On `capture_busy`: read `alternatives` and SWITCH — do NOT blindly retry the SSE path.** - **Coexistence matrix (verified live):** `POST /screenshot` (CDP) ✅ *best during a recording* · `desktop_screenshot_window` ✅ · `desktop_screenshot_screen` ✅ (medium) · `pup browser_screenshot` ✅ · `adom-cli screenshot panel/workspace/screen` ⚠️ → `capture_busy`. - Authoritative recording state: `GET /recording/native/status`. See `hd-recording`, `hd-screen-lock`. **Quick map:** in-HD → #1 (or #2 for no-flash) · other app → #3 · whole desktop → #4. ## 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 HD **workspace** (every panel side by side) | `adom-cli hydrogen screenshot workspace` | `workspace` | | The whole **screen** — desktop, taskbar, OTHER apps | `adom-cli hydrogen screenshot screen` | `screen` | **"My whole screen / my desktop / my monitor / everything"** → `adom-cli hydrogen screenshot screen`. Do **NOT** reach for `adom-desktop` here — that's only for one SPECIFIC non-HD window (KiCad, Fusion). The HD `screen` scope captures the real desktop and saves the PNG into your container, same as the others (verified live). ## 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/.png (relative to ~/project) → Read ~/project/screenshots/.png # Whole screen / desktop (other apps, taskbar): 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 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`** (HD v0.1.27+ matches the cloud contract); the `_hint` gives the full path: ``` screenshots/2026-06-13T20-04-43.png _hint: Screenshot saved to ~/project/screenshots/.png. Read the file to view it. ``` → `Read ~/project/screenshots/.png` (prepend `~/project/` to the line-1 path, or just use the full path from the `_hint`). (Legacy/edge case: an older HD build could return a doubled `~/project/~/project/` prefix, or inline JSON with `"dataUrl"` + `"uploadFailed": true` — both fixed in v0.1.27. If you ever see the `dataUrl` shape, base64-decode it to a .png and Read it; don't build the capture around it.) ### 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. Don't switch tools or reach for adom-desktop over this. ## 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 "" (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 `hd-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 HD as it does for web Hydrogen `adom-cli` is **one binary** used by both web Hydrogen and HD — you can test these commands anywhere. The difference is purely *where the work runs*: HD intercepts what adom-cli talks to. `adom-cli hydrogen ` hits `ADOM_HYDROGEN_URL`, which in HD points at **HD's local proxy** (`http://127.0.0.1:`). HD's proxy pulls out the **local hydrogen/SSE commands** (screenshot, webview, caption, notify, recording…) and runs them against the HD frontend over SSE, while **carbon/cloud calls pass straight through** to the cloud. For a screenshot: `PATCH /current/screenshot` → HD 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) - **Don't curl `host.docker.internal`.** That's a Docker-ism HD does not use. HD's host services are reached at `http://127.0.0.1:` (WSL2 mirrored networking); the live control URL is in `~/.adom/hd-control-url`. But for screenshots you don't need any of that — use the CLI above. - **Don't use `adom-desktop desktop_screenshot_*` for an HD panel/webview.** That grabs the whole Windows window/desktop, not the panel — it's the wrong tool for anything inside HD. Use it only for **non-HD** apps (KiCad, Fusion, a native window — see `hd-bridges`). - **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 HD'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/hd-control-url)" # http://127.0.0.1: curl -s -X POST "$CTRL/screenshot" -H 'Content-Type: application/json' \ -d '{"target":"full","b64":true}' ``` | Field | Meaning | |---|---| | `target` | the surface — `full`/`window` (whole HD 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 (fixed in HD v0.1.42).** `POST /screenshot {target:""}` 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. **Verified live 2026-06-14:** CDP *and* the `adom-cli` SSE path (`screenshot panel --name ScreenA`) both returned the background tab's content (example.com, not the active httpbin tab) and restored the prior tab — `target:""` was NO-PNG before v0.1.42. (The `adom-cli` SSE path has always activated; v0.1.42 brings the CDP `/screenshot` by-name path to parity.) This is the right call for "shot tab #2 while #4 is showing." **The teal zap:** every HD-driven capture flashes a teal (`#00b8b0`) highlight on the captured **region** (just the panel/menu/region; full-window flash only for `target:full`). Teal = HD-driven. (The `adom-desktop` host verbs `hd_shot`/`hd_screenshot` deliberately do NOT flash — different tool.) 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 **`hd-ui`**): **open a surface → screenshot just that surface → close it** — no screen-clicking, no guessing where it is. ```bash CTRL="$(cat ~/.adom/hd-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 `hd-ui`). ## Ralph loop + shotlog (optional) Verify a UI change: make the change → (rebuild if needed) → `adom-cli hydrogen screenshot panel --name ` → `Read` it → wrong? fix and repeat. Log shots for the user with `shotlog inject -c hd-ui -d "" ` (shotlog resizes internally — another reason you don't need `convert`). ## Host window control (for NON-HD windows only) `adom-desktop desktop_list_windows` → `desktop_set_window_state {hwnd,state}` → `desktop_bring_to_front {hwnd}` → then `desktop_screenshot_window`. Windows-only. ## Related skills - [hd-capture-share](../hd-capture-share/SKILL.md) — the sharing/approval UX behind `screenshot` - [hd-desktop-sse](../hd-desktop-sse/SKILL.md) — the adom-cli → HD-proxy → SSE interception model - [hd-recording](../hd-recording/SKILL.md) · [hd-captions](../hd-captions/SKILL.md) — sibling `adom-cli hydrogen` AV verbs - [hd-bridges](../hd-bridges/SKILL.md) — `desktop_screenshot_*` for NON-HD apps - `shotlog` — the screenshot log viewer/injector