main
John Lauer Publish 0.1.0 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-url for 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.