Adom Hydrogen (platform base)

@@ -1,338 +0,0 @@-----name: hd-tab-icons-description: >-  How Hydrogen **webview** tab icons work in the Adom editor — panels with-  `panelType: adom/a1b2c3d4-0031-4000-a000-000000000031`. (Native panels-  like Schematic Editor, 3D Editor, Desktop Demo, KiCad panel have their-  own icon mechanism and are NOT covered here.) The critical gotcha:-  `displayIcon` (HTTP API) / `--display-icon` (CLI) is only the-  **pre-load placeholder** — the loaded page's own `<link rel="icon">`-  overrides it as soon as the page loads. The only stable way to control-  a webview tab's icon is to serve the favicon you want from your own app.-  Covers the override mechanism, shipping a custom favicon from a-  Rust/Node/Python app, using `mdi:<name>` and `data:image/svg+xml;base64,...`-  placeholders, common icons, and troubleshooting. Trigger words: hydrogen-  webview tab icon, webview tab icon, mdi icon webview tab, displayIcon-  webview, display-icon, webview tab icon not showing, custom webview tab-  icon, colored webview tab icon, tab chip icon, webview tab icon svg,-  webview tab icon base64, favicon override webview tab, webview tab icon-  keeps resetting, webview tab icon reverts after page load.------# Hydrogen Webview Tab Icons--How Hydrogen **webview** workspace tabs actually get their icons in-the Adom editor. **Read the "Real mechanism" section first** — the-placeholder vs. favicon distinction is the thing future Claude-sessions usually get wrong, including an earlier version of this-skill.--## Scope--This skill is **only** about tabs whose `panelType` is-`adom/a1b2c3d4-0031-4000-a000-000000000031` — the generic Hydrogen-webview that loads an HTML page from a URL. The favicon-override-mechanism described below is specific to webview panels because-only they load an HTML page that can ship its own-`<link rel="icon">`.--Other panel types — Schematic Editor, 3D Editor, KiCad panel,-Desktop Demo, Movie Maker, Adom Viewer native panel, etc. —-have their icons assigned by Hydrogen's internal panel registry-keyed off `panelType`, not by anything the tab adder passes in.-If your tab isn't a webview and its icon is wrong, **this skill-will not help you** — open a Hydrogen issue instead.--## Real mechanism (the thing everyone misses)--Hydrogen webview tabs have **two** sources for their displayed icon,-and the loaded page wins:--1. **`panelState.displayIcon`** — a placeholder you pass via-   `--display-icon` / HTTP `displayIcon`. Shown **only until the page-   loads**.-2. **The loaded page's `<link rel="icon">`** — Hydrogen's webview-   panel reads the favicon after `load` and writes it into-   `panelState.displayIcon`, overriding whatever the placeholder was.--**Practical consequence:** once any page with a favicon finishes-loading, your `--display-icon "mdi:chip"` is gone. If you want the-icon to be **stable and predictable**, you have to serve the favicon-you want **from the page you load**.--Empirical proof: create a tab with `--display-icon "mdi:rocket-launch"`,-navigate it to `https://example.com`, then inspect the tab's-`panelState.displayIcon` via `adom-cli hydrogen workspace tabs` — it-will be a `data:image/svg+xml;base64,...` value matching example.com's-favicon, not `mdi:rocket-launch`.--## Brand rule: icons must be monochrome `#e6edf3`--Per `gallia/skills/brand/SKILL.md`, **all Adom icons must be monochrome-white (`#e6edf3`)** — no colored icons, no multi-color, no brand-palette-colors in icons. This applies to tab icons too.--- **First choice:** use an `mdi:<name>` placeholder for the `--display-icon`-  flag. MDI icons are already monochrome and inherit the theme color-  automatically, so you get brand compliance for free. Search-  https://pictogrammers.com/library/mdi/ for a matching icon.-- **If you need a custom icon** (no MDI match, or you want to ship your-  own favicon for the page-load override): hand-roll an SVG with-  `fill="#e6edf3"` (or `fill="currentColor"` so it inherits), a-  `24x24` viewBox, and clean filled paths or 2px strokes. **No-  gradients, no shadows, no color.** Details that break at 16 px lose.--Concrete example of a brand-compliant custom icon (the adom-tsci-chip) — 318 bytes, single path, monochrome `#e6edf3`:--```svg-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#e6edf3">-  <path d="M6 2a2 2 0 0 0-2 2v2H2v2h2v3H2v2h2v3H2v2h2v2a2 2 0 0 0 2 2h2v2h2v-2h3v2h2v-2h3v2h2v-2a2 2 0 0 0 2-2v-2h2v-2h-2v-3h2v-2h-2V8h2V6h-2V4a2 2 0 0 0-2-2h-2V0h-2v2h-3V0h-2v2H9V0H7v2H6zm0 2h12v16H6V4zm2 3v10h8V7H8zm2 2h4v6h-4V9z"/>-</svg>-```--Rendered in a dark-background Hydrogen tab bar, that's a white chip-with pins sticking out — visually identical to `mdi:chip` but served-from your own app so it can't be overridden.--## The right way: serve your own favicon from your app--If you're writing a Rust/Node/Python/Go app that opens a Hydrogen-webview tab, **put a `<link rel="icon">` in the HTML you serve**.-Hydrogen will pick it up on load and that's what the user will see.-Use a **brand-compliant `#e6edf3` monochrome SVG** (see section above).--### Rust + tiny_http example (the `adom-tsci` pattern)--```html-<!-- src/assets/shell.html, embedded in the binary via include_str! -->-<!DOCTYPE html>-<html lang="en">-<head>-<meta charset="UTF-8">-<title>My App</title>-<!-- Hydrogen reads this and uses it as the tab icon. -->-<link rel="icon" type="image/svg+xml" href="favicon.svg">-...-```--```rust-// Serve favicon.svg from the tiny_http route handler.-if url == "/favicon.svg" || url == "/favicon.ico" {-    let body = include_str!("../assets/icon.svg");-    return Ok(request.respond(-        Response::from_string(body)-            .with_header(-                Header::from_bytes(&b"Content-Type"[..], &b"image/svg+xml"[..]).unwrap()-            ),-    )?);-}-```--```svg-<!-- src/assets/icon.svg — MONOCHROME per the brand rule. fill must be-     "#e6edf3" (or "currentColor"), NEVER a colored palette value. -->-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#e6edf3">-  <rect x="5" y="5" width="14" height="14" rx="1"/>-  <rect x="3"  y="7"  width="2" height="2"/>-  <rect x="3"  y="11" width="2" height="2"/>-  <rect x="3"  y="15" width="2" height="2"/>-  <rect x="19" y="7"  width="2" height="2"/>-  <rect x="19" y="11" width="2" height="2"/>-  <rect x="19" y="15" width="2" height="2"/>-  <rect x="7"  y="3"  width="2" height="2"/>-  <rect x="11" y="3"  width="2" height="2"/>-  <rect x="15" y="3"  width="2" height="2"/>-  <rect x="7"  y="19" width="2" height="2"/>-  <rect x="11" y="19" width="2" height="2"/>-  <rect x="15" y="19" width="2" height="2"/>-</svg>-```--(Perfectly symmetric chip: body + 12 pins, 3 per side, even 4-unit-spacing, rx=1 rounded corner, all in brand `#e6edf3`. This is the-exact `adom-tsci` icon — taken from the repo's `src/assets/icon.svg`.)--When the page loads from `https://<workspace>.adom.cloud/proxy/<port>/`,-the browser fetches `/proxy/<port>/favicon.svg`, your app returns the-SVG, Hydrogen syncs it onto the tab, and the icon stays put.--**Rules for the favicon file:**--- **Square `viewBox`** (e.g. `0 0 64 64` or `0 0 24 24`).-- **Self-contained SVG** — no external fonts, no `xlink:href` to-  other files, no embedded images.-- **Bold, filled shapes over thin strokes** — the tab bar is-  ~16–20 px so details get lost.-- **Transparent background** is fine, the tab bar shows through.-- **Brand color in the SVG itself** if you want a colored icon. MDI-  icons can't be tinted.--## Placeholder-only case: `mdi:<name>` / `data:...` via add-tab--If the page you're loading **doesn't set its own favicon**, or if-you're creating a tab that navigates to about:blank or similar, the-`--display-icon` placeholder is all you get — and it will stick.--Examples where this is actually useful:--- **A tab that loads an external site with no favicon.** Rare in-  practice; most real sites have a favicon.-- **A stopgap during the ~100ms the page takes to load** — the user-  sees the placeholder, then it swaps to the page's favicon.-- **When you don't own the page** — you can't inject a `<link>`, so-  the placeholder is your only control point, knowing it's about to-  get overridden.--### CLI--```bash-adom-cli hydrogen workspace add-tab \-  --panel-id <leaf-id> \-  --panel-type "adom/a1b2c3d4-0031-4000-a000-000000000031" \-  --display-name "My App" \-  --display-icon "mdi:chip" \-  --initial-state '{"url":"https://example.com/"}'-```--### HTTP API--```bash-curl -s -X POST \-  -H "X-Api-Key: $API_KEY" $TARGET_HEADER \-  -H "Content-Type: application/json" \-  -d '{-    "panelId": "<leaf-id>",-    "panelType": "adom/a1b2c3d4-0031-4000-a000-000000000031",-    "displayName": "My App",-    "displayIcon": "mdi:chip",-    "initialState": { "url": "https://example.com/" }-  }' \-  "https://hydrogen.adom.inc/api/workspaces/editor/$OWNER/$REPO/current/tabs"-```--### Two placeholder formats--| Format | When to use | Example |-|---|---|---|-| `mdi:<icon-name>` | Monochrome icon from [Material Design Icons](https://icon-sets.iconify.design/mdi/). Inherits the editor theme's foreground color. Can't be tinted. | `mdi:chip`, `mdi:bug`, `mdi:eye` |-| `data:image/svg+xml;base64,<b64>` | Custom SVG, full control. **Must still be monochrome `#e6edf3`** per the brand rule — don't color your own placeholder. | `data:image/svg+xml;base64,PHN2...` |--**Again: both are placeholders. The page's favicon overrides them-both as soon as it loads.**--### Common MDI icons used in existing Adom tabs--| Icon | Typical use |-|---|---|-| `mdi:chip` | chips, ICs, boards, PCB/tscircuit tools |-| `mdi:eye` | viewers (AV) |-| `mdi:bug` | bug-filing tools |-| `mdi:chart-line` | visualizers |-| `mdi:monitor-cellphone` | demo/desktop tools |-| `mdi:github` | repo browsers |-| `mdi:book-open-variant` | docs viewers |-| `mdi:cart` | commerce tools |-| `mdi:robot` | automation / AI |-| `mdi:folder` | file explorers |-| `mdi:code-tags` | code editors |-| `mdi:palette` | design tools |-| `mdi:camera` | screenshot tools |--Full catalog: https://icon-sets.iconify.design/mdi/.--## Building a custom SVG data URL by hand--When you need a one-off custom icon and don't want to ship a file,-you can build a `data:` URL inline:--```bash-SVG='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#00b8b0" d="M13.13 22.19L11.5 18.36..."/></svg>'-B64=$(echo -n "$SVG" | base64 -w0)-DATA_URL="data:image/svg+xml;base64,$B64"--adom-cli hydrogen workspace add-tab \-  --panel-id <leaf-id> \-  --panel-type "adom/a1b2c3d4-0031-4000-a000-000000000031" \-  --display-name "My App" \-  --display-icon "$DATA_URL" \-  --initial-state '{"url":"about:blank"}'-```--`base64 -w0` (no line wrapping) is important — newlines inside the-value break the JSON it gets embedded in.--This is still a **placeholder**. If the tab ever navigates to a page-with its own favicon, the placeholder is lost.--## Troubleshooting--### "I pass `mdi:chip` but the tab shows a different icon"--Your loaded page has a favicon that overrode the placeholder.-Options:--- **Best:** serve your own favicon from your app (see Real mechanism-  above). Pick an SVG that matches the brand/icon you want. Hydrogen-  will sync it onto the tab.-- **Acceptable:** if you don't control the page, you can re-set the-  `displayIcon` after load with another `add-tab`/PATCH call — but-  the next navigation will override it again.--### "My placeholder flickers for a moment then reverts"--That's the expected behavior — the placeholder shows until the page-finishes loading, then Hydrogen swaps in the page's favicon.--### "My tab has no icon at all"--The loaded page has no `<link rel="icon">` **and** no-`--display-icon` was passed. Hydrogen falls back to the default Web-View icon (a globe). Add a favicon to your served HTML.--### "I pass a `data:image/svg+xml;base64,...` and it's broken"--Usually a base64 encoding issue:--- Use `base64 -w0` (no wrap) so the output is a single line.-- Make sure the raw SVG has no unescaped newlines or tabs that break-  the JSON wrapper.-- The SVG must be self-contained: no `xlink:href` to other files, no-  `@import` in `<style>`, no embedded `<image>` pointing at URLs.--### "I set the tab to `mdi:chip` but `workspace tabs` shows a data URL"--Normal. Hydrogen rewrites `panelState.displayIcon` after page load-with whatever the page's favicon was (usually a data URL because-some sites inline their favicons). This is the override in action.--## How the `adom-tsci` app handles this--1. `src/cli/start.rs` passes `--display-icon "mdi:chip"` to-   `adom-cli hydrogen workspace add-tab` — this shows the MDI chip-   icon for ~100ms while the page loads.-2. `src/assets/shell.html` has-   `<link rel="icon" type="image/svg+xml" href="favicon.svg">`.-3. `src/server/mod.rs` serves the favicon at `/favicon.svg` with the-   content of `src/assets/icon.svg` — a teal-colored (`#00b8b0`)-   custom SVG chip.-4. When the shell loads, Hydrogen fetches `favicon.svg`, gets the-   teal chip SVG, and writes that into `panelState.displayIcon`.-5. The tab now **permanently** shows the teal chip — because every-   future reload re-serves the same favicon.--The MDI `mdi:chip` placeholder and the served `favicon.svg` are-visually similar by design — the transition is invisible. If they-were different, you'd see a brief flash.--## See also--- `~/.claude/skills/adom/guides/adom-workspace-control.md` — the full-  workspace API reference that documents `displayIcon` as a-  `panelState` field (but buries the favicon-override behavior).-- `~/.claude/skills/adom/webview/SKILL.md` — webview panel actions-  (navigate, refresh, setHeaderHidden, setProxyEnabled).-- `~/.claude/skills/adom/guides/app-creator.md` — app conventions-  including the `docs/icon.svg` brand-icon requirement.-- [iconify MDI catalog](https://icon-sets.iconify.design/mdi/) — the-  searchable list of every `mdi:<name>`.