bootstrap

Adom Hydrogen (platform base)

Public Made by Adom

by adom

Layer Hydrogen's workspace onto a standard Adom workstation.

bootstraphydrogenworkspace
Overview Files Skills Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
hydrogen-bootstrap / skills / hydrogen-self-screenshot / SKILL.md
Download

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

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

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:

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.

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