---
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. Read this the
  moment the word webview (or wv) appears. Trigger words — webview, wv, show me
  in webview, open in webview, in a webview, webview tab, webview panel, native
  webview, show in webview, launch in webview, webview app.
---

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

## 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**.

## 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), **pup**, the user's **native browser**, **hdbw**. VS
Code's Simple Browser is NEVER one of them.