---
name: hd-webview
description: >
  WEBVIEW — what the word "webview" means in Hydrogen Desktop and exactly how to
  open one. When the user says "show me in webview", "open it in webview", "in a
  webview", "webview panel", "wv", or asks to show ANY app/page/tool "in webview",
  it ALWAYS means a native Hydrogen workspace webview tab opened via
  `adom-cli hydrogen webview open-or-refresh` — NEVER VS Code's built-in Simple
  Browser, never an editor-internal browser, never an iframe hack. ALSO covers the
  External Webview (extwv): the opt-in real-browser panel for sites that refuse to
  be embedded (Google, Amazon), and the "This site can't be embedded" handoff card.
  Read this the moment the word webview (or wv, or extwv) appears. Trigger words —
  webview, wv, extwv, external webview, show me in webview, open in webview, in a
  webview, webview tab, webview panel, native webview, show in webview, launch in
  webview, webview app, site can't be embedded, refuses to embed, x-frame-options.
---

# hd-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 Desktop webview tab** — a first-class panel in the HD
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 HD 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 `hd-open-url` for the decision
  guide). "webview" is not ambiguous; it names exactly one thing.

## ✅ 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 HD window (never real OS fullscreen — the content stays
sandboxed inside HD). 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 **hd-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. HD 0.1.257+ handles this
with a second panel type: **External Webview (extwv)** — the same tab/pane
ergonomics, but backed by a REAL native browser surface (WebView2) 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 HD Browser Window**
(hdbw). Users can also add one directly from the **+ panel menu → "External
Webview"**.

**Check embeddability up front** (before choosing a surface for a known URL):

```bash
# HD 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 hdbw)
```

**Open an extwv tab programmatically** (HD 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: **HD'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.

## hdbw — HD's standalone browser window (the fourth surface)

Under Hydrogen Desktop there is one more surface: **hdbw**, HD's standalone built-in
Tauri browser window (picker label "HD Browser Window", destination id
`webview-window`, window label `hd-browse-*`). It is a separate OS window HD manages
directly — bigger than a pane tab, still not a real browser. Open one first-class via
`POST /hdbw/open {"url": ...}` on HD's control API (0.1.113+), or pick "HD Browser
Window" in the Browser Picker. The surface shortlist: **wv** (this skill's webview
panel; HD's pane tab inside HD), **extwv** (the real-browser pane tab for embed-blocked
sites, above), **pup**, **nb** (the user's native browser via abe), **hdbw**. VS
Code's Simple Browser is NEVER one of them.