Skip to content

feat(dashboard): install the dashboard as an app, with a help page when BrowserHive isn't running - #62

Draft
arg1998 wants to merge 24 commits into
mainfrom
feat/dashboard-pwa
Draft

arg1998 wants to merge 24 commits into
mainfrom
feat/dashboard-pwa

Conversation

@arg1998

@arg1998 arg1998 commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

What / why

The dashboard can now be installed as an app. When BrowserHive isn't running, it shows a help page instead of the browser's "can't connect" error.

  • Install app sits in the account menu and the command palette.

    • Chrome, Edge and other Chromium browsers open their own install dialog.
    • Other browsers get a dialog with that browser's steps, or a plain statement that the browser can't install apps (for example Firefox on Linux and macOS) and what to use instead.
    • There is no CLI command, by design: a command can't install anything.
  • Offline help page. A small service worker holds only the help page's own public files, never API or operator data. When the daemon doesn't answer, the page tells these cases apart:

    • not running
    • not responding
    • starting
    • a proxy whose upstream is down
    • BrowserHive refusing the address
    • the device is offline
    • another program on the port

    It shows copyable commands for the visitor's OS and opens the dashboard by itself once BrowserHive is ready.

  • Banner in the running dashboard. If the daemon stops while a page is open, a banner says so after about 15–20 s. What to do opens the same help. The banner clears without a reload.

  • Daemon changes.

    • Every response carries X-BrowserHive-Version. The worker uses it to tell BrowserHive apart from another program on a reused port, and removes itself when another program answers.
    • Without --admin, a browser navigation to any dashboard path gets the status page instead of a JSON error.

The spec went through three adversarial review rounds before implementation (browser behaviour, codebase fit, failure modes); every blocker found was fixed in the spec.

Decisions

  • D-59 (new, Accepted; D-59 to D-58 are reserved for the session-templates spec): the dashboard is an installable web app with an offline "daemon not running" page, and there is no CLI command.
  • Specs: 04 §18 (new) and §4.2 (socket connect timeout); 03 §2 (marker header) and §8 (static files, admin=false navigations); 06 §3, §4 and §6; 09 §3.4–§3.6; 12.

Contract changes

Contract change: additive only. Nothing existing changes or breaks.

  • New subpath @browserhive/contracts/paths: NON_SPA_PREFIXES and isNonSpaPath, zod-free. The export-snapshot golden diff is exactly these two names.
  • New response header on every HTTP response: X-BrowserHive-Version: <version>.
  • admin=false browser navigations (Sec-Fetch-Mode: navigate, Sec-Fetch-Dest: document, or Accept: text/html when no Sec-Fetch-* header is present) to non-/ paths get the status page as HTML with status 404. Other requests keep the JSON 404.
  • New public bundle files: /manifest.webmanifest, /icons/*, /sw.js, /sw-precache.json, /offline.html, /assets/offline-*.
  • No tool, route, WS message, config key or DB migration changes.

Test evidence

All of these were run locally on the branch head:

Suite Result
bun run check (lint, typecheck, depcruise, tests, generated-file checks) exit 0; 3612 server + 753 dashboard tests, 0 fail
bun run build exit 0
bun run package:check ok (tarball contents and the new installable-app assertions)
dashboard-offline.test.ts (in-process daemon + Playwright Chromium) 9 pass, run repeatedly
e2e on a built, seeded daemon 20 passed, 1 skipped (includes the new pwa project)

The integration test drives:

  • a stopped daemon;
  • one held in starting;
  • a hung TCP server;
  • a proxy answering 502;
  • admin=false;
  • the banner;
  • the worker retiring itself when another server answers on the port.

The pwa e2e project checks installability in a persistent channel: 'chromium' context (with a no-manifest negative control) and exercises the native beforeinstallprompt path.

CI on all three OSes runs on this PR.

Manual browser gate (04 §18.12) — passed

Verified by hand by the owner on 2026-11-08, running this branch's build against their own data directory. Every item passed.

  • Chrome on Linux:
    • install from the account menu;
    • check the launcher icon;
    • the app opens standalone;
    • the title bar follows the theme;
    • shortcuts work.
  • Chrome with the daemon stopped:
    • the offline page shows, and Copy works;
    • after a restart the app returns to the dashboard;
    • with a foreign server on the port, its own page shows and the worker is gone.
  • Daemon dies while the dashboard is open: the banner appears and clears. Close the lid for a minute with the daemon running: no banner on wake.
  • Edge: install from the address bar, and through the menu path.
  • Firefox on Linux: Install app explains it can't install; the offline page works after one visit.
  • Safari on macOS (if available): Add to Dock, launch once with the daemon up, then stop it: the offline page.
  • Without --admin: the installed app and /sessions show the status page.

Screenshots

These are taken from the built dashboard on a real daemon, at 390 px and 1280 px, in light and dark:

  • every offline-page state;
  • the account menu;
  • the install dialogs;
  • the banner and its dialog.

They are local and not committed: scratchpad/dashboard-pwa-shots/ and scratchpad/dashboard-pwa-shots/phase3/ in the worktree.

Changeset

.changeset/dashboard-install-app.md: browserhive minor. The four workspace packages share one version group, so changeset status shows minor for all of them.

Checklist

  • bun run check passes locally
  • behavior tested at the outermost observable surface (real daemon + real Chromium)
  • contracts/goldens/docs/changeset updated for wire changes
  • no new any, payload casts, !, String(err), silent catch, floating promise, process.env, module-level mutable state
  • TSDoc on exports, @module headers, "why" comments on constants
  • new dependencies justified, license allowed, pinned per policy (no new dependencies)
  • dashboard: keyboard-operable, tokens only, both themes, screenshots taken
  • D-xx references added where code implements a decision

Related: #54 (a dependency-cruiser blind spot found while building this; the new daemon-help boundary rule is backed by a test until #54 is fixed).

…ON_SPA_PREFIXES

The reserved path prefixes (/api, /mcp, /health, /trace-viewer) and
isNonSpaPath() move to an import-free leaf that the daemon, the dev
proxy and the dashboard's service worker share (D-49, spec 04 §18.10).
Added to the package exports, the tsdown entries and the root entry;
the export snapshot gains NON_SPA_PREFIXES and isNonSpaPath.
…admin=false navigations

- secureHeaders sets X-BrowserHive-Version on every HTTP response,
  errors, 404s and the host guard included; the pre-app 503 "starting"
  fallback in listeners-http sets it too (spec 03 §2, D-49).
- Without --admin, a browser navigation (Sec-Fetch-Mode: navigate,
  Sec-Fetch-Dest: document, or Accept listing text/html when neither
  header is present) to a non-reserved path other than / gets the
  status page with 404; other requests keep the JSON 404 (spec 03 §8).
- The status page gains light/dark styles and the sentence "The
  dashboard is turned off. Restart BrowserHive with --admin to use it."
- spa.ts reads NON_SPA_PREFIXES from @browserhive/contracts/paths.
…ne page

- lib/daemon-help/probe.ts: probeHealth (injectable fetch and timers,
  5 s timeout), isDaemonAnswer and classifyProbe per spec 04 §18.6.1.
- lib/daemon-help/commands.ts: daemonHelp, detectPlatform and
  helpCommandsFor per §18.6.3 (loopback-only --port and port-holder
  lines, bunx with the last-seen version, detected OS first).
- lib/storage.ts gains sessionStorage helpers; lib/clipboard.ts takes
  copyText from CopyButton; theme/resolve.ts holds the React-free
  resolveTheme and parsePreference; src/dev-proxy.ts exports
  PROXIED_PATHS for vite.config.ts.
- Root test test/dashboard/daemon-help.test.ts (now in test:server)
  checks every help command against the CLI registry and config keys.
- dependency-cruiser rules for daemon-help, src/offline and src/sw.
The manifest of 04 §18.2, the any and maskable icons rasterised from two
SVG sources with the Playwright Chromium (gen:icons; --check reads source
hashes and PNG headers only and joins bun run check), and the manifest,
apple-touch-icon and beforeinstallprompt capture in index.html. THEME_COLORS
moves to the React-free theme/resolve.ts so the offline page can use it.
- src/sw: pure routing, navigation fallback and cache rules (sw-core), the
  worker wiring (marker-checked precache, stale-cache cleanup, navigation
  fetch(event.request) raced against a 10 s timer, cache-first assets,
  retire() under waitUntil) and the kill switch; typed by tsconfig.sw.json
- offline.html + src/offline: the help page per probe state with copyable
  commands, polling with a hidden pause and Retry now, reload loop guard,
  Forget this address, theme following the OS, no framework, no innerHTML
- scripts/offline-sw-plugin.ts: isolated nested build of the offline page,
  precache budget and collision checks, IIFE sw.js and sw-precache.json
- app/register-sw.ts: registration after the first render, lastSeen and
  reload-counter bookkeeping on every boot
- lib/daemon-help/keys.ts holds the two shared storage keys (allow-list
  extended); DOCS_PAGES gains dashboardInstall and troubleshootingNotRunning
  with their docs sections
package:check asserts the D-49 bundle contents (manifest, worker, precache
completeness and budget, no imports or zod in sw.js, no icon stamp);
run-from-source rebuilds on offline.html and the dashboard scripts; CI runs
gen:icons --check in goldens and builds the dashboard before the
integration suites on every OS.
…ker and offline page

In-process daemon on a free port, Playwright Chromium with service workers:
install and precache, navigation headers, not running on the same URL,
starting then reload into /login (ready phase held 4 s), a hung port after
the 10 s navigation timeout, an unmarked 502 proxy, the admin=false status
page through the worker, and retirement on another program's HTML page.
Step 8 (the banner) is a todo for phase 3.
…t, Sec-Fetch-Dest)

keys.ts joins the offline allow-list; THEME_COLORS moves with resolveTheme;
the worker entries start only under the plugin's defines and share
scope.ts; install fetches everything before storing; the kill switch
build flag; the offline page's latin-only fonts and data: tab icon; and
step 2 of dashboard-offline.test.ts no longer expects Sec-Fetch-Dest:
document, which Chromium does not send for a worker's fetch.
…10 s fails

A daemon that accepts the connection but never answers kept the socket store in connecting forever. Each attempt now closes after CONNECT_TIMEOUT_MS (10 s) without the server's hello and counts toward offline (04 §4.2, D-49).
DaemonReachabilityProvider owns every /health probe the shell makes: the REST rechecks HealthPill used to run, now through probeHealth, plus a 5 s outage cadence from the socket's first offline. Three consecutive failed outage probes, with a gap over 15 s resetting the count, show DaemonUnreachableBanner under the topbar in place of AuthRetryBanner; What to do opens the offline page's explanation and copyable commands, and a permanent status region announces it. Any daemon answer hides it.

Install app in the account menu and the command palette calls the browser's own prompt when it offered one (adopting the event the inline bootstrap captured) and otherwise opens InstallAppDialog with this browser's steps or a plain explanation; hidden inside the installed app. appinstalled raises a toast. CodeBlock moves to components/shared and the state copy to lib/daemon-help (04 §18.7, §18.8, D-49).
…at to do dialog

Wrapped commands keep their copy button beside the first line and wrap only between words; the dialog gets the same icon header as Install BrowserHive and keeps Learn more and Close on one row at 390 px.
…ath and the offline worker

A dedicated pwa Playwright project (service workers allowed) runs pwa.e2e.ts; desktop and phone block workers and ignore it. In a persistent channel:'chromium' context, CDP reports the manifest without errors and no installability errors, a page without a manifest reports no-manifest, and after a click the browser's offer arrives and Install app calls prompt(). In an ordinary context the worker activates and controls the page, and Install app opens the instructions dialog, which passes axe (09 §3.5, D-49).
Sign in through REST (first-run password, forced change, new password), open /overview, stop the daemon: the banner appears within 30 s and What to do lists browserhive doctor; restart: it clears within 15 s in the same document (09 §3.4 step 8, D-49).
… security guide, and the changeset

The dashboard guide names the palette action, the banner and Firefox on Android; the security guide says what the service worker stores (public static files only) and that whoever holds a stopped daemon's port can serve that address. Changeset: browserhive minor.
…all handler, e2e negative control)

04: DaemonReachability in watcher.ts with the socket state passed in, the outage cadence only for offline: network, the banner following the latest probe and the dialog's back state, copy.ts and CodeBlock overflow, InstallAppProvider, the prompt store's global hand-off, Firefox for Android to the generic row, the copyable address field, the connect-timeout close code, where the step versions came from. 09: the negative control under a reserved prefix, the watcher unit tests. 12: the dashboard tour line.
- register-sw and clipboard tests import the DOM setup themselves, like the other DOM tests,
  instead of relying on the preload's path check.
- The preload's path check accepts Windows backslash paths.
- Integration step 3 navigates to /sessions explicitly; reloading raced the signed-out
  dashboard's redirect to /login on slower runners.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant