main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-self-screenshot description: >- Screenshot Hydrogen from inside the workspace: a panel or the whole window with adom-cli hydrogen screenshot, or one element with POST /screenshot and a CSS selector. Use when asked to screenshot the welcome page, a webview, a menu, my screen, or to verify a UI change.

Hydrogen: Screenshot a panel, webview or the window (Linux)

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.

On Linux every Hydrogen screenshot is WebKit's own snapshot of the main window (its visible region, iframes included), taken once and released. A CSS selector crops that snapshot to one element. There is no CDP capture on WebKitGTK.

Which tool

  1. Hydrogen content (the default): adom-cli hydrogen screenshot panel|workspace. Same command as web Hydrogen. It saves a PNG under ~/project/screenshots/ and prints the path; Read it.
  2. A precise element, inline base64, or no flash: POST /screenshot on the control API (below).
  3. Another app or the whole desktop: Hydrogen cannot capture outside its own window on Linux. adom-cli hydrogen screenshot screen returns the Hydrogen window, not the desktop. Its desktop_screenshot_* verbs work while Adom Bridge runs on this desktop (Hydrogen installs and starts it when a Linux build is published for the user's account; GET /ab/health tells you).
  4. Your app in a pup window: adom-bridge pup_screenshot (the pup skill), which needs Adom Bridge on the machine running pup.

Do this — it saves a PNG and prints the path; then Read it

# Whole workspace (simplest — no tab name needed):
adom-cli hydrogen screenshot workspace
# → prints  screenshots/<ts>.png  (relative to ~/project) → Read ~/project/screenshots/<ts>.png

# 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.

A panel shot activates the tab and crops to that panel.

adom-cli hydrogen screenshot status reports sharing; Hydrogen captures natively, so sharing always reads active and nothing holds the display.

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.)

POST /screenshot: any element, inline, or silent

For a precise element, an inline PNG or no flash, use Hydrogen's capture endpoint POST /screenshot (aliases: /shot, /capture/viewport). Read the control URL from the file:

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 on Linux
target Every target gets the whole main window (full, window, shell, hd, vscode, a tab name or a url piece). Per-surface crops are not implemented yet; use selector.
selector CSS selector in Hydrogen's own page: crops the snapshot to that element (for example .resource-bars, .setup-panel, .dialog, .dropdown-content.open, [data-pane-id="<id>"] .panel-body). Not found means the whole window is kept.
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

Content inside an iframe is in the snapshot, but a selector only matches elements of Hydrogen's own page (crop to the panel holding the iframe instead).

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.

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).

  • hydrogen-capture-share — the sharing/approval UX behind screenshot
  • hydrogen-recording · hydrogen-captions — sibling adom-cli hydrogen AV verbs
  • shotlog — the screenshot log viewer/injector
  • hydrogen-ui (the command bus), hydrogen-desktop-sse (how adom-cli reaches Hydrogen), hydrogen-annotate (the human marks up the screen)

Recording and capture_busy

Hydrogen's native screen recorder does not run on Linux, so a recording never blocks a screenshot. If the adom-cli path ever answers capture_busy, read its alternatives and use POST /screenshot; do not retry blindly. GET /capture/availability lists the methods.

Do not

  • Do not curl host.docker.internal; Hydrogen is at 127.0.0.1 (the workspace shares the host network) and the control URL is in ~/.adom/hydrogen-control-url.