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-webview description: >- What "webview" means in Hydrogen: a native workspace tab opened with adom-cli hydrogen webview open-or-refresh, never VS Code's Simple Browser; plus the External Webview for sites that refuse embedding and the Hydrogen Browser Window (hbw). Use when the user says show me in webview, open in webview, wv, extwv or hbw.
hydrogen-webview — "webview" means a native Hydrogen webview tab. Period.
When a user (or a setup prompt) says "show me X in webview", they mean a native Hydrogen webview tab — a first-class panel in the Hydrogen workspace, next to their editor. Nothing else qualifies.
⛔ NEVER (the 2026-07-16 incident — do not repeat)
- NEVER open VS Code's built-in "Simple Browser" (or any editor-internal browser page) to satisfy a webview request. A setup-thread AI did this once — the user called it "an awful outcome that can never happen again." The Simple Browser is not the Hydrogen webview: it's cramped, it isn't a workspace tab, and it breaks every downstream flow (screenshots, captions, panel routing).
- Don't fall back silently to pup or a native browser either — those are
different, deliberate destinations (see
hydrogen-open-urlfor the decision guide). "webview" is not ambiguous; it names exactly one thing.
⭐ URLs for YOUR OWN servers: direct port, NOT /proxy//
The workspace machine shares this Linux computer's network, so every port you bind inside it
is the same port on the host: http://localhost:<port>/. For a server on port 8850:
http://localhost:8850/ ✅ the Hydrogen (ah) way
http://localhost:7380/proxy/8850/ ❌ Hydrogen Cloud (hc) habit — do not default to this here
The /proxy/<port>/ route through code-server (what VSCODE_PROXY_URI points at) exists for
Hydrogen Cloud parity. Here it costs an extra hop, breaks absolute-path assets (/style.css),
and dies whenever the editor reloads. Opening a /proxy URL still works; the reply hints you back
to the direct form. If the direct port does not answer, check that your server listens (the
hydrogen-networking skill).
✅ The exact command (idempotent — safe to re-run)
# open (or refresh, if a tab with this name already exists) a webview tab:
adom-cli hydrogen webview open-or-refresh --name "<Tab Name>" --url "<url>" --panel-id <id>
# ⚠️ --panel-id is REQUIRED to CREATE a new tab (without it: "Tab 'X' not found
# and --panel-id not provided"). Get a panel id first:
adom-cli hydrogen workspace get # or: adom-cli hydrogen workspace tabs
# Re-running with the same --name once the tab exists just navigates/refreshes
# (no --panel-id needed). The --name is your stable handle.
Local Adom apps (parts search, chip-fetcher, adom-tsci previews, wiki pages)
are all shown this way: start/locate the app's local URL, then
open-or-refresh it into a named tab.
Fullscreen: the 90% dialog
Every webview toolbar has a fullscreen button: it grows the page to a 90% dialog over the Hydrogen window (never real OS fullscreen — the content stays sandboxed inside Hydrogen). Exit via the close button, clicking outside, or Esc. Pages that call the browser fullscreen API get the same 90% treatment.
Verify you actually did it
The tab must appear in adom-cli hydrogen workspace tabs with your --name.
If it isn't there, you did NOT open a webview — go again.
For the broader "which surface should this URL open in?" decision (webview vs pup vs native browser vs headless fetch), see hydrogen-open-url.
extwv — External Webview: the real-browser panel for sites that refuse embedding
The default webview tab is an iframe, so sites that send X-Frame-Options: deny/sameorigin
or a restrictive CSP frame-ancestors (Google, Amazon, most login walls) will not load in it.
The External Webview (extwv) panel is the same tab ergonomics backed by a native WebKitGTK
webview that loads anything.
How users hit it: navigating a webview to a blocked site shows a handoff card — "This site can't be embedded" — with two buttons: Open in External Webview (a new extwv tab in the same pane) and Open in Hydrogen Browser Window (hbw). Users can also add one directly from the + panel menu → "External Webview".
On Linux Hydrogen's page has the origin tauri://localhost, which a CSP wildcard does not
match, so frame-ancestors * also refuses it; only a list naming tauri: lets it in. The check
below accounts for that.
Check embeddability up front (before choosing a surface for a known URL):
# Hydrogen control API — returns {"embeddable": bool, "reason": "...", "title": "<page title>"}
GET http://127.0.0.1:{control}/webview-can-embed?url=https://google.com
# → embeddable=false, reason "x-frame-options: sameorigin" → use extwv (or hbw)
Open an extwv tab programmatically (Hydrogen control API; the adom-cli hydrogen webview verbs target the DEFAULT webview panel type, not extwv):
POST http://127.0.0.1:{control}/workspace/tabs
{"panelType": "adom/a1b2c3d4-0032-4000-a000-000000000032",
"displayName": "Google", "initialState": {"url": "https://google.com"}}
Know the trade-offs (why extwv is opt-in, not the default):
- It is a native OS surface: Hydrogen's own HTML can never draw on top of it (menus and overlays are designed around it, but don't try to float custom UI over an extwv pane).
- Heavier than an iframe tab; prefer the default webview whenever the site embeds fine.
- Reload lives in the tab's right-click menu (0.1.258+), and the tab's hover tooltip identifies the panel as "External Webview (extwv)" (0.1.261+), so you can always tell the two apart.
Vocabulary: "open it in extwv" == this panel. See the shared Adom glossary
(definitions skill / wiki.adom.inc/adom/definitions) for the full surface
vocabulary.
hbw: the Hydrogen Browser Window
hbw is Hydrogen's standalone browser window (picker label "Hydrogen Browser Window", window
label hbw-*): a separate desktop window Hydrogen manages, bigger than a pane tab, still not a
real browser. Open one with POST $C/hbw/open {"url": "..."} (the reply carries its label;
POST $C/hbw/close {"label": "hbw-..."} closes it), or pick it in the Browser Picker (C=$(cat ~/.adom/hydrogen-control-url)).
A browsing hbw window that is not in front is slowed to about 4 frames a second (its
requestAnimationFrame is capped), so a background 3D page cannot starve the editor. The window
in front runs at full speed. To keep a background one at full speed while you watch or film it:
curl -sX POST "$C/hbw/speed" -d '{"target":"Sprinkler Yard","minutes":20,"reason":"filming the 3D tour"}'
curl -s "$C/hbw/speed" # each window's mode and any lease left
target is the window's label or part of its title; minutes 1 to 120, renewable, 0 ends it.
On Linux "in front" means the window has keyboard focus, and Hydrogen has no native recorder or
GPU-process restart here, so a lease is the only way to keep a background window at full speed.
Surface shortlist: wv (this skill's pane tab), extwv (the native pane tab for embed-blocked sites), hbw, pup (a real browser through Adom Bridge), nb (the user's own browser). VS Code's Simple Browser is NEVER one of them.
---
name: hydrogen-webview
description: >-
What "webview" means in Hydrogen: a native workspace tab opened with adom-cli hydrogen
webview open-or-refresh, never VS Code's Simple Browser; plus the External Webview for
sites that refuse embedding and the Hydrogen Browser Window (hbw). Use when the user says
show me in webview, open in webview, wv, extwv or hbw.
---
# hydrogen-webview — "webview" means a native Hydrogen webview tab. Period.
When a user (or a setup prompt) says **"show me X in webview"**, they mean a
**native Hydrogen webview tab** — a first-class panel in the Hydrogen
workspace, next to their editor. Nothing else qualifies.
## ⛔ NEVER (the 2026-07-16 incident — do not repeat)
- **NEVER open VS Code's built-in "Simple Browser"** (or any editor-internal
browser page) to satisfy a webview request. A setup-thread AI did this once —
the user called it "an awful outcome that can never happen again." The Simple
Browser is not the Hydrogen webview: it's cramped, it isn't a workspace tab, and it
breaks every downstream flow (screenshots, captions, panel routing).
- Don't fall back silently to pup or a native browser either — those are
*different, deliberate* destinations (see `hydrogen-open-url` for the decision
guide). "webview" is not ambiguous; it names exactly one thing.
## ⭐ URLs for YOUR OWN servers: direct port, NOT /proxy/<port>/
The workspace machine shares this Linux computer's network, so every port you bind inside it
is the same port on the host: `http://localhost:<port>/`. For a server on port 8850:
```
http://localhost:8850/ ✅ the Hydrogen (ah) way
http://localhost:7380/proxy/8850/ ❌ Hydrogen Cloud (hc) habit — do not default to this here
```
The `/proxy/<port>/` route through code-server (what `VSCODE_PROXY_URI` points at) exists for
Hydrogen Cloud parity. Here it costs an extra hop, breaks absolute-path assets (`/style.css`),
and dies whenever the editor reloads. Opening a /proxy URL still works; the reply hints you back
to the direct form. If the direct port does not answer, check that your server listens (the
`hydrogen-networking` skill).
## ✅ The exact command (idempotent — safe to re-run)
```bash
# open (or refresh, if a tab with this name already exists) a webview tab:
adom-cli hydrogen webview open-or-refresh --name "<Tab Name>" --url "<url>" --panel-id <id>
# ⚠️ --panel-id is REQUIRED to CREATE a new tab (without it: "Tab 'X' not found
# and --panel-id not provided"). Get a panel id first:
adom-cli hydrogen workspace get # or: adom-cli hydrogen workspace tabs
# Re-running with the same --name once the tab exists just navigates/refreshes
# (no --panel-id needed). The --name is your stable handle.
```
Local Adom apps (parts search, chip-fetcher, adom-tsci previews, wiki pages)
are all shown this way: start/locate the app's local URL, then
`open-or-refresh` it into a named tab.
## Fullscreen: the 90% dialog
Every webview toolbar has a **fullscreen button**: it grows the page to a 90%
dialog over the Hydrogen window (never real OS fullscreen — the content stays
sandboxed inside Hydrogen). Exit via the close button, clicking outside, or Esc. Pages
that call the browser fullscreen API get the same 90% treatment.
## Verify you actually did it
The tab must appear in `adom-cli hydrogen workspace tabs` with your `--name`.
If it isn't there, you did NOT open a webview — go again.
For the broader "which surface should this URL open in?" decision (webview vs
pup vs native browser vs headless fetch), see **hydrogen-open-url**.
## extwv — External Webview: the real-browser panel for sites that refuse embedding
The default webview tab is an **iframe**, so sites that send `X-Frame-Options: deny/sameorigin`
or a restrictive CSP `frame-ancestors` (Google, Amazon, most login walls) will not load in it.
The **External Webview (extwv)** panel is the same tab ergonomics backed by a native WebKitGTK
webview that loads anything.
**How users hit it:** navigating a webview to a blocked site shows a handoff
card — "This site can't be embedded" — with two buttons: **Open in External
Webview** (a new extwv tab in the same pane) and **Open in Hydrogen Browser Window**
(hbw). Users can also add one directly from the **+ panel menu → "External
Webview"**.
On Linux Hydrogen's page has the origin `tauri://localhost`, which a CSP wildcard does not
match, so `frame-ancestors *` also refuses it; only a list naming `tauri:` lets it in. The check
below accounts for that.
**Check embeddability up front** (before choosing a surface for a known URL):
```bash
# Hydrogen control API — returns {"embeddable": bool, "reason": "...", "title": "<page title>"}
GET http://127.0.0.1:{control}/webview-can-embed?url=https://google.com
# → embeddable=false, reason "x-frame-options: sameorigin" → use extwv (or hbw)
```
**Open an extwv tab programmatically** (Hydrogen control API; the `adom-cli hydrogen
webview` verbs target the DEFAULT webview panel type, not extwv):
```bash
POST http://127.0.0.1:{control}/workspace/tabs
{"panelType": "adom/a1b2c3d4-0032-4000-a000-000000000032",
"displayName": "Google", "initialState": {"url": "https://google.com"}}
```
**Know the trade-offs** (why extwv is opt-in, not the default):
- It is a native OS surface: **Hydrogen's own HTML can never draw on top of it**
(menus and overlays are designed around it, but don't try to float custom UI
over an extwv pane).
- Heavier than an iframe tab; prefer the default webview whenever the site
embeds fine.
- Reload lives in the tab's right-click menu (0.1.258+), and the tab's hover
tooltip identifies the panel as "External Webview (extwv)" (0.1.261+), so you
can always tell the two apart.
**Vocabulary:** "open it in extwv" == this panel. See the shared Adom glossary
(`definitions` skill / wiki.adom.inc/adom/definitions) for the full surface
vocabulary.
## hbw: the Hydrogen Browser Window
**hbw** is Hydrogen's standalone browser window (picker label "Hydrogen Browser Window", window
label `hbw-*`): a separate desktop window Hydrogen manages, bigger than a pane tab, still not a
real browser. Open one with `POST $C/hbw/open {"url": "..."}` (the reply carries its label;
`POST $C/hbw/close {"label": "hbw-..."}` closes it), or pick it in the Browser Picker (`C=$(cat ~/.adom/hydrogen-control-url)`).
A browsing hbw window that is not in front is slowed to about 4 frames a second (its
`requestAnimationFrame` is capped), so a background 3D page cannot starve the editor. The window
in front runs at full speed. To keep a background one at full speed while you watch or film it:
```bash
curl -sX POST "$C/hbw/speed" -d '{"target":"Sprinkler Yard","minutes":20,"reason":"filming the 3D tour"}'
curl -s "$C/hbw/speed" # each window's mode and any lease left
```
`target` is the window's label or part of its title; `minutes` 1 to 120, renewable, `0` ends it.
On Linux "in front" means the window has keyboard focus, and Hydrogen has no native recorder or
GPU-process restart here, so a lease is the only way to keep a background window at full speed.
Surface shortlist: **wv** (this skill's pane tab), **extwv** (the native pane tab for
embed-blocked sites), **hbw**, **pup** (a real browser through Adom Bridge), **nb** (the user's
own browser). VS Code's Simple Browser is NEVER one of them.