main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-eval description: >- Inject JavaScript into any surface of the Hydrogen window (app shell, VS Code workbench, wiki panel, Claude chat) through POST /eval-in, which runs over Hydrogen's frame bus on Linux. Use when asked to inject a UI add-on, add a demo arrow or overlay, highlight an element, or read the DOM of the Hydrogen window.

hydrogen-eval: inject JS into any Hydrogen surface (POST /eval-in)

The Hydrogen window is a tree of frames, not one page:

friendly target what it is typical use
shell the Hydrogen app shell (Svelte): top nav, logo menu, dialogs, the floating layer inject add-ons/overlays that float over everything
workbench the VS Code editor (code-server) activity bar, tabs, the "Claude Code: Open" button
wiki the wiki panel iframe wiki DOM
claude the Claude Code chat webview (only exists while the panel is open) the chat input + send button

How it runs on Linux: the frame bus

WebKitGTK has no Chrome DevTools Protocol. Hydrogen injects an agent script into every frame, in an isolated script world, and /eval-in sends your JS to the frame you name over that bus (hydrogen-app/src/linux_frame_bus.rs). What that means for you:

  • The DOM is shared, page JS globals are not. document.querySelector, events, click(), execCommand, styles and IndexedDB all work. A page's own globals (Svelte stores, a window.__something the page defined) are invisible: drive the DOM, not the page's functions.
  • Context ids are the agent's random ids, stable for the frame's life. Don't keep them across reloads.
  • No surface list: GET /targets and a /eval-in call without js return nothing on Linux. A miss returns an error that names every candidate frame, which is the discovery.
  • Same-origin child frames without their own agent (VS Code webview content) are reached through their parent's agent, so the Claude chat is still target:"claude".

Reaching the control API

The workspace shares the host's network, so the API is on 127.0.0.1. Read the live URL from the discovery file:

BASE="$(cat ~/.adom/hydrogen-control-url)"   # http://127.0.0.1:<dynamic>

(Never hardcode the port — read the live URL from ~/.adom/hydrogen-control-url.)

The call

POST /eval-in
{
  "target": "shell" | "workbench" | "wiki" | "claude" | "<url-substring>" | "<id>",
  "js":     "<javascript; value of last expression is returned>",
  "find":   "<OPTIONAL JS expression>",   // disambiguate among same-origin contexts
  "frame":  "<url-substring | index>",     // OPTIONAL nested-context selector
}
→ { "ok": true, "value": <result>, "target": "<matched url>", "contextId": N, "frames": [...] }

A returned promise is always awaited on Linux.

find — the important one

The workbench has several same-origin frames. Origin alone is ambiguous, so pass find: a JS expression (e.g. document.querySelector('...'), NOT a bare CSS selector). /eval-in evals it in each candidate context and runs your js in the first one where find is truthy.

Recipes

Add-on: a widget in the top nav (e.g. a usage meter) — target shell

Inject once; it persists until reload. Append your element to nav in the shell.

Demo overlay: a red arrow over everything that you reposition — target shell

Inject a position:fixed; z-index:2147483647; pointer-events:none element with a CSS transition into the shell body, then move it with cheap follow-up evals (it glides). The shell floats over all iframes, so window coords work everywhere.

Highlight an element (even deep in the workbench / Claude webview)

Eval inside the element's own surface and set outline — no coordinate math. Use find to land in the right context, e.g. find: document.querySelector("a[aria-label='Claude Code: Open']").

Type into & submit the Claude chat (panel must be open)

Stable selectors (NOT the CSS-module hash classes like .messageInput_xxxx, which change per build):

  • input = [aria-label='Message input'] (a contenteditable div) — focus it, then document.execCommand('insertText', false, text).
  • submit = button[type='submit'][data-permission-mode] (disabled until text) — .click() it; fallback = dispatch an Enter keydown on the input. Prefer the /claude/inject endpoints for this (see hydrogen-claude-management).

/eval-in returns the JS value, so always verify: after an action, eval a probe and check it; if it fails, try a second technique.

Don'ts

  • Don't hardcode the control port — read /ports.
  • Don't pass find as a bare CSS selector — it's a JS expression.
  • Don't select by CSS-module hash classes — use stable attributes (aria-label, data-*, role).
  • Don't expect the claude webview to exist unless the Claude panel is open.
  • Don't use /eval for workbench/Claude — it only reaches the shell page.
  • /iframe-eval is CDP-only and does nothing useful on Linux.
  • Don't call page globals: the isolated world cannot see them.

Cross-references

  • hydrogen-api — the full control API surface
  • hydrogen-ui / hydrogen-adom-menu — where UI elements live
  • hydrogen-self-screenshot — capture the result of your injection

Recipe: hide/show activity-bar icons (the RIGHT way — persisted, overflow-proof)

Do NOT hide activity-bar icons with display:none on .action-item — that misses icons collapsed into the "…" (Additional Views) overflow and doesn't persist. Instead write VS Code's own source-of-truth state, then reload the workbench:

  • DB: vscode-web-state-db-global → store ItemTable → key workbench.activity.pinnedViewlets2
  • It's an array of {id, pinned, visible, order}. Set pinned:false to hide an icon from the activity bar (works even if it's in the overflow), pinned:true to restore.
  • IDs: Explorer workbench.view.explorer · Search workbench.view.search · Source Control workbench.view.scm · Run&Debug workbench.view.debug · Extensions workbench.view.extensions (extension views: workbench.view.extension.<id>).
  • IndexedDB is per-origin, so read/write from any localhost:7380 context (target workbench, find: "(typeof indexedDB!=='undefined')") — don't require the workbench main doc (it's absent during a reload).
  • After writing, reload the workbench (iframe.src=iframe.src on the shell, or POST /reload-vscode) so VS Code re-reads pinnedViewlets2.
// hide Search / Source Control / Run&Debug (then reload)
{ "target":"workbench", "find":"(typeof indexedDB!=='undefined')", "awaitPromise":true,
  "js":"(async function(){function g(d,k){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var q=b.transaction('ItemTable','readonly').objectStore('ItemTable').get(k);q.onsuccess=function(){b.close();r(q.result)}}})}function p(d,k,v){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var t=b.transaction('ItemTable','readwrite');t.objectStore('ItemTable').put(v,k);t.oncomplete=function(){b.close();r(true)}}})}var DB='vscode-web-state-db-global',K='workbench.activity.pinnedViewlets2';var a=JSON.parse(await g(DB,K));var ids=['workbench.view.search','workbench.view.scm','workbench.view.debug'];a.forEach(function(e){if(ids.indexOf(e.id)>-1)e.pinned=false});await p(DB,K,JSON.stringify(a));return 'hidden';})()" }

POST /vscode/hide-activity-items does the same job server-side.