Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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
- 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;Readit. - A precise element, inline base64, or no flash:
POST /screenshoton the control API (below). - Another app or the whole desktop: Hydrogen cannot capture outside its own window on
Linux.
adom-cli hydrogen screenshot screenreturns the Hydrogen window, not the desktop. Itsdesktop_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/healthtells you). - Your app in a pup window:
adom-bridge pup_screenshot(thepupskill), 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 screenshotproduces a normal PNG and theReadtool reads PNGs directly. (Don't reach for ImageMagickconvertor 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).
Related skills
- hydrogen-capture-share — the sharing/approval UX behind
screenshot - hydrogen-recording · hydrogen-captions — sibling
adom-cli hydrogenAV verbs shotlog— the screenshot log viewer/injectorhydrogen-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 at127.0.0.1(the workspace shares the host network) and the control URL is in~/.adom/hydrogen-control-url.
---
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
```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
# 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:
```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 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.
```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
- `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`.