main
John Lauer Publish 0.1.0 d8a45ab

Hydrogen Browser Picker (Linux)

The Problem

Hydrogen wraps a WebKitGTK webview that contains:

  • The Hydrogen SvelteKit frontend (localhost:1420 in DEV mode only; prod Hydrogen serves it via the tauri protocol)
  • The code-server iframe (VS Code + Claude Code) on port 7380
  • Webview panel iframes (any external URL like wiki, google, etc.)

When a link is clicked anywhere in this stack, Hydrogen needs to:

  1. Catch it before it opens uncontrolled
  2. Route it through the Browser Picker dialog
  3. Let the user choose: native browser (Chrome/Edge), Hydrogen Tab (wv), Hydrogen Browser Window (short name: hbw), or Pup

With Settings > Hydrogen > Behavior > "When a link opens" on Remember per website (the default, setting hydrogen.link_open_mode):

  • A link opens where that website's links went last time, or at the picker's usual default (saved domain pref, then the bias file, then the work profile).
  • A toast says where ("Opened example.org in Firefox ([email protected])") with a Change button that reopens the full picker for the same link; a pick there is remembered.
  • Sign-in links and "move this page" (-move triggers) still show the picker every time.
  • Always ask brings back the picker plus countdown on every link.
  • Shift-click does not force the picker on Linux (Shift is not detected). Use Change on the toast, or POST /open-url {"url":..., "force":true}.
Event Caught by Result
window.open() / target="_blank" from the app or the editor (VS Code openExternal, extension links) Tauri on_new_window Browser Picker
VS Code's window.open('') then location = url frame-bus script turns '' into about:blank; Hydrogen grants a managed popup (hd-popup-*) whose outside navigation goes to the picker, then the empty popup closes Browser Picker
The main page itself starting to load an outside http(s) URL GTK load-changed guard on the main frame: the load is stopped Browser Picker
Link inside a webview tab iframe not intercepted navigates the iframe
mailto: / tel: / sms: in any frame frame bus app-link handler the desktop's default app, or the address copied to the clipboard if none

Hydrogen turns on WebKitGTK's javascript-can-open-windows-automatically for the main webview so scripted popups reach on_new_window at all (otherwise code-server shows "The browser blocked opening a new window"). There is no "Open Link with Browser Picker" item in the right-click menu on Linux.

Browser Picker Dialog

src/lib/components/BrowserProfileDialog.svelte

3 Branded Variants

  1. Claude auth — Claude logo, "Connect to Claude Code" (domains: *.claude.ai, *.claude.com)
  2. Adom auth — Adom logo, "Sign in to Hydrogen" (domains: *.adom.inc + /auth/intent)
  3. General link — "Browser Picker" title, no logo

On Linux, other AI sign-ins count as sign-ins too: auth.openai.com, accounts.google.com, Kimi / Moonshot, x.ai, login.microsoftonline.com, GitHub device login, any /oauth/authorize, /oauth2/auth or /device URL. For sign-ins the Hydrogen section starts collapsed, so native browsers come first (those pages refuse to load inside Hydrogen), and the fresh-window toggle starts on.

Consistent Elements (all variants)

  • "Browser Picker" title at top
  • Native Browsers section with real Google profile avatars
  • Hydrogen section (collapsible, collapsed for auth)
  • Details section (collapsible, collapsed) — URL, remember checkbox, trigger info, build version
  • Auto-timer with progress bar (cancelled by mouse movement): 5 s for links, 10 s for sign-ins
  • Keyboard navigation (arrow keys + Enter)
  • 800ms delayed tooltips

Auto-Timer Behavior

  • Picks best default: the saved domain pref, then the bias file, then the work browser profile (non-gmail email)
  • 5-second countdown for links, 10 seconds for sign-ins, with a progress bar
  • ANY mouse movement cancels the timer
  • force:true on /open-url shows the dialog without the timer (Shift is not detected on Linux)
  • Selected destination highlighted with teal border

Fresh-window option

fresh:true opens a brand-new browser window rather than a tab. It does not force the foreground: on Linux the window manager decides focus.

  • Mechanism: Chromium-family browsers get --new-window and Firefox -new-window before the URL. With no concrete browser program, xdg-open is the fallback, which loses profile and fresh.
  • UI: an "Open in a fresh window" checkbox above the Native Browsers list. Defaulted ON for auth URLs (Claude/Adom), OFF otherwise. Only native-browser destinations honor it; internal Hydrogen destinations ignore it. The dialog dispatches select with fresh: dest.category==='native' ? freshWindow : false; onProfileSelect threads it to open_in_browser_profile / /open-in-profile.
  • fresh is honored by: Tauri open_in_browser_profile (direct), POST /open-in-profile (direct), and POST /open-url (where it pre-seeds the picker's toggle; add direct:true to open immediately instead). Direct paths echo {"fresh":…, "method":"<exe … fresh-window>"}.

URL Event Deduplication

The frontend drops a repeat of the same URL within 1 second, so several handlers firing for one click open it once.

Prefs Sync

Preferences re-read from localStorage on every dialog open. If user deletes a domain in Browser Picker Manager, the next dialog open reflects it immediately.

Browser detection (hydrogen-control-ui/src/linux_browsers.rs)

  • Programs: each browser's commands on PATH plus /snap/bin, and Flatpak exports (system and per-user): Firefox (firefox, firefox-esr), Chrome (google-chrome-stable), Chromium, Edge, Brave, Vivaldi, Opera.
  • Profiles: Chromium-family Default / Profile N dirs under ~/.config (and the snap and Flatpak homes); Firefox profiles from profiles.ini (~/.mozilla, ~/.config/mozilla, snap, Flatpak), only ones that have been used, with the Firefox Account email when signed in.
  • Default browser: xdg-settings get default-web-browser, then mimeapps.list.
  • Launch: Chromium-family with --profile-directory=<dir>; Firefox Default without -P (reuses the running Firefox), any other profile with -P <name>. fresh adds --new-window / -new-window. With no concrete program, xdg-open (via open::that) is the fallback, which loses profile and fresh.

"The picker lists no browsers": check the browser runs from a terminal by one of the names above, and that a profile has been used at least once.

Files

File What
src-tauri/crates/hydrogen-app/src/lib.rs on_new_window, granted popups, the Linux main-frame guard, dispatch_url_event, linux_open_app_link
src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs window.open('') fix and the app-link handler in every frame
src-tauri/crates/hydrogen-control-ui/src/linux_browsers.rs browser, profile and default detection
src/lib/components/BrowserProfileDialog.svelte Browser Picker dialog (3 variants, auto-timer, keyboard nav)
src/lib/components/editor/EditorNav.svelte Browser Picker Manager modal
src/routes/+layout.svelte CustomEvent listeners, URL event parsing, deduplication
src/lib/assets/claude-logo.svg Real Claude logo from claude.ai/favicon.svg
src/lib/assets/adom-logo-teal.svg Adom brand logo
src/lib/buildVersion.ts Build version tracking for verification

The auto-countdown (why AI loves it)

The picker opens with a countdown on its best-default destination. If nothing interrupts, the URL auto-routes there. This is the key feature for AI automation: triggers like OAuth redirects, "open in browser" links, or wiki references work hands-free.

  • AI scripts can fire a URL open and the right thing happens within seconds: no clicking, no blocking on a dialog.
  • Mouse movement cancels the timer — if a human is at the keyboard, just wiggle the mouse and the picker waits.

AI automation recipe

BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com","force":true}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","browser":"firefox","profileDir":"Default","fresh":true}' "$BASE/open-in-profile"

/open-url ROUTES THROUGH THE PICKER by default (emits browser-open-request): fresh pre-seeds the "Open in a fresh window" toggle, force:true skips the 5s auto-timer, direct:true (or naming a concrete browser) bypasses the picker and opens immediately. The response routed field is "browser-picker" or "direct". /open-in-profile always opens directly (no picker). signin:true on Linux always opens directly in the system browser. Read method in the reply before claiming success.

Prefs are now an API — the picker is a FALLBACK, not a gate

The per-domain routing memory is CRUD over the control API, so the AI governs routing and the picker only pops for a domain with no policy + no direct call: GET /browser-picker/prefs (read {domains:{<host>:{destination,label}}}), PUT /browser-picker/prefs {domain,destination,label?} (set/override), DELETE /browser-picker/prefs/<host> (forget one), DELETE /browser-picker/prefs (clear all). destination is an ID: hydrogen-tab (wv) | webview-window (hbw — Hydrogen's standalone Tauri browser window; also POST /hbw/open; close one with POST /hbw/close {"label":"hbw-<ts>"}, hbw labels only, from 1.0.142) | pup-window (pup), or a native id (nb): users address these as nb <browser> [profile] — "nb chrome work", "nb edge" — resolve via GET /browser-profiles; the id form is browser:<browser>:<dir> (profile dir encoded in the ID). fresh is per-open, not stored. Writes hit the Manager's live state (localStorage + hydrogen-url-routing-prefs-changed). Full routing-policy guidance lives in hydrogen-open-url.