Adom Hydrogen (platform base)

@@ -1,7 +1,7 @@ --- name: hydrogen-widget description: "Build, list, open and drive Hydrogen Widgets: small live panels in Hydrogen Desktop's Title Bar (Claude usage, Codex usage, a clock, or your own), each served by a binary inside the workspace and mounted in a sandboxed slot. Covers the hydrogen-widget.json facet a wiki repo carries (alone, or next to its dock manifest and project workspace), the per-widget page the pulldown links to, the launch contract (HYDROGEN_WIDGET_ID / _PORT / _SLOT / HYDROGEN_PROXY_PORT, the health URL, the explicit takeover, stop-first relaunch), the tall and compact layouts, vendor marks, private repos (read with the user's session), the curated list on adom/hydrogen-bootstrap, the Hydrogen Widgets pulldown, and the control API (GET /widgets, POST /widgets/open|close|navigate|refresh|menu, GET /widgets/status) so an AI can do all of it with no mouse. Trigger words: hydrogen widget, hydrogen-widget, title bar widget, widgets pulldown, widget slot, claude usage widget, codex usage widget, tokens left widget, usage meter in the title bar, hydrogen-widget.json, /widgets/open, make a widget, add a widget to hydrogen, private widget, widget SDK."-version: 1.5.6+version: 1.5.7 ---  # hydrogen-widget: small live panels in Hydrogen Desktop's Title Bar@@ -109,7 +109,7 @@ an AI sign-in that lives next to the editor extension; a repo with one thing to | field | meaning | |---|---| | `id` | unique, lowercase, stable; the curated list and the control API address it |-| `name`, `brief` | the pulldown row and its hover text |+| `name`, `brief` | the pulldown row and its hover text; `brief` is also the body of the hover card when the widget shows no live view there, so write it for a person | | `icon` | an iconify name for the row (`mdi:clock-outline`), or `vendor:claude` / `vendor:codex` for the vendor marks the AI launch bar paints, so a person can tell whose numbers a widget shows | | `launch.port` | the port your page serves on inside the workspace. Pick one far from where apps land: not the 8000s (dashboards, dev servers, the KiCad dashboard's 8931), not the ephemeral range (32768 and up). The shipped widgets sit at 27011 to 27013; take 27020 and up for yours. A widget is a side panel and must never cost an app its port (John 2026-09-15). | | `width` | slot width in px in the compact Title Bar (one horizontal row); clamped to 48..320 |@@ -118,8 +118,8 @@ an AI sign-in that lives next to the editor extension; a repo with one thing to | `launch.command` | run in the workspace as the workspace user, backgrounded; `launch.stop` optional | | `launch.port` | the port the page listens on, 127.0.0.1 inside the workspace | | `health.url` | path Hydrogen polls until it answers (default `/`); `timeout_seconds` default 60 |-| `about` | one or two sentences on how it works, shown on the hover card ("Reads the Claude Code sign-in ... asks the usage endpoint ... no quota is spent") |-| `refresh` | how often it asks anything, shown on the hover card ("the provider at most once every 3 minutes; pauses while hidden; backs off on errors") |+| `about` | one or two sentences on how it works, shown under Details on the hover card ("Reads the Claude Code sign-in ... asks the usage endpoint ... no quota is spent") |+| `refresh` | how often it asks anything, shown under Details on the hover card ("the provider at most once every 3 minutes; pauses while hidden; backs off on errors") | | `docs` | the widget's own page: a repo file path (`widgets/README.md`) or a full URL. The pulldown row links to it. Defaults to `<repo>/files/widgets/README.md` |  ### The widget's own page (what the pulldown row opens)@@ -143,13 +143,20 @@ copy it.  A tooltip inside your page cannot reach past the slot's edge, so Hydrogen draws the card: hover the slot and, after a moment, a card appears under it in the host, in the style of the-tab cards. It shows the widget's name and mark, its repo, its live URL or its current status,-`brief`, `about`, `refresh`, the port and the log path, and four links: the widget's page-(`docs`), the wiki repo, this SDK, and Close widget. Moving onto the card keeps it; a click on-the card (or its pin) pins it so the links are live; Escape or a click outside closes a pinned-card. Your page needs nothing for this beyond the manifest fields. An AI shows the same card-with `POST /widgets/card {"id": "...", "pinned": true}` and hides it with `{"id": "...",-"open": false}`.+tab cards. It is for the person looking at the widget, so it leads with what the widget shows:+the name and mark, then the widget's own live view when it asks for one (see "A bigger view on+hover" below), otherwise its `brief`. A status line under the name appears only while the+widget is not live (Installing, Starting, Waiting for the workspace, Could not start: reason).++Everything about how it runs sits under **Details** at the foot of the card, folded by default:+`brief` (when a live view took its place), `about`, `refresh`, the port and the log path, the+page URL, the repo, and four links: the widget's page (`docs`), the wiki repo, this SDK, and+Close widget. Opening Details pins the card, so those links are live as soon as they show.+Moving onto the card keeps it; a click on the card (or its pin) pins it; Escape or a click+outside closes a pinned card. Your page needs nothing for this beyond the manifest fields, so+write `brief` for a person ("how much of your limits you have used; hover for when they+reset"), and put the mechanics in `about` and `refresh`. An AI shows the same card with+`POST /widgets/card {"id": "...", "pinned": true}` and hides it with `{"id": "...", "open": false}`.  ### Resizing: who tells the page @@ -182,22 +189,36 @@ the reference: adom/adom-vscode `widgets/bin/hydrogen-widget-lib.py` is the page `hydrogen-widget-claude-usage` and `hydrogen-widget-codex-usage` the data feeds, and adom/hydrogen-bootstrap `bin/hydrogen-widget-clock` the smallest one. -### A bigger view on hover (optional, Hydrogen 1.0.429+)+### Who draws what: your two canvases -A widget can ask for a larger live surface inside its hover card by adding `expand` to the-same message: `window.parent.postMessage({hdWidget: {width: 265, expand: {width: 560, height:-400}}}, '*')`. When the card opens, Hydrogen moves the SAME frame over a reserved area of the-card (width clamped 280..720, height 120..600, at most 45% of the window height); the title-bar-slot keeps its place and shows "Expanded below". Nothing reloads, so your page keeps its state.-Moving off the card shrinks it back. Rules:+Your widget has two canvases and draws everything inside them: the **slot** in the Title Bar and,+if you ask for one, the **card** view on hover. Hydrogen draws only what surrounds them: the slot's+edge, its height (38 or 20 px) and its close button, and the card's frame, header (your `name` and+`icon`), pin and Details (your `about`, `refresh`, `docs`, plus the port and log). Anything inside a+canvas changes when you publish your package, with no Hydrogen release. The table and the diagram:+the Hydrogen Widgets page, `widgets/README.md` on adom/hydrogen, section "Who draws what". -- keep `width` the compact title-bar width; never send the expanded width as `width`;-- switch layouts on height (`@media (min-height: 100px)` shows the big view), not on a message;-- send `expand: null` to withdraw, and omit it to keep the plain card;-- the request is dropped whenever the frame loads, so post it again on your `load` event;-- keys do not leave an iframe: forward Escape with `postMessage({hdWidget: {collapse: true}}, '*')`.+### A bigger view on hover (optional; Hydrogen 1.0.609+ gives the card its own frame)++Ask for a live view in the hover card by adding `expand` to the same message:+`window.parent.postMessage({hdWidget: {width: 265, expand: {width: 560, height: 400}}}, '*')`.+When the card opens, Hydrogen loads a **second copy of your page** in the card at that size (width+clamped 280..720, height 120..600, at most 45% of the window height), or the page at `expand.path`+(`{width, height, path: "/card"}`, a path on your own origin) if you want a separate one. Your slot+keeps showing your page the whole time. Rules: -Only the widget's own frame, from its own origin, is listened to. Adom AI Flow is the reference.+- keep `width` the compact title-bar width; never send the expanded width as `width`;+- switch layouts on height (`@media (min-height: 100px)` shows the big view), not on a message:+  the card copy is simply a taller frame of the same page;+- the card copy is a fresh page each time the card opens: keep state you need on your server;+- send `expand: null` to withdraw, and omit it to keep the plain card (your `brief` as text);+- the request is dropped whenever the slot frame loads, so post it again on your `load` event;+- only the slot frame's `width` and `expand` count; the card frame may only send+  `{hdWidget: {collapse: true}}` (forward Escape with it, since keys do not leave an iframe).++Before 1.0.609 Hydrogen moved the slot's own frame into the card, leaving the slot empty with a+"Expanded below" stand-in; pages written for that work unchanged, because they already pick the big+layout by height. Adom AI Flow and the usage widgets are the references. Details: `docs/hydrogen-widget-expansion.md` in the Hydrogen source.  ### Listing it@@ -240,3 +261,5 @@ curl -s http://27013.localhost:$(python3 -c "import json;print(json.load(open('/  Then look: a screenshot of the Hydrogen window shows the slot left of the meter, the chevron makes the Title Bar compact and the slot follows, and `/widgets/close` makes it go away.++