Repository navigation
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
Draft
feat(dashboard): install the dashboard as an app, with a help page when BrowserHive isn't running#62arg1998 wants to merge 24 commits into
arg1998 wants to merge 24 commits into
Conversation
…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.
…cannot see npm imports (D-49)
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.
…-58 are reserved for session templates)
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
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:
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.
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.--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
admin=falsenavigations); 06 §3, §4 and §6; 09 §3.4–§3.6; 12.Contract changes
Contract change: additive only. Nothing existing changes or breaks.
@browserhive/contracts/paths:NON_SPA_PREFIXESandisNonSpaPath, zod-free. The export-snapshot golden diff is exactly these two names.X-BrowserHive-Version: <version>.admin=falsebrowser navigations (Sec-Fetch-Mode: navigate,Sec-Fetch-Dest: document, orAccept: text/htmlwhen noSec-Fetch-*header is present) to non-/paths get the status page as HTML with status 404. Other requests keep the JSON 404./manifest.webmanifest,/icons/*,/sw.js,/sw-precache.json,/offline.html,/assets/offline-*.Test evidence
All of these were run locally on the branch head:
bun run check(lint, typecheck, depcruise, tests, generated-file checks)bun run buildbun run package:checkdashboard-offline.test.ts(in-process daemon + Playwright Chromium)pwaproject)The integration test drives:
starting;admin=false;The
pwae2e project checks installability in a persistentchannel: 'chromium'context (with a no-manifest negative control) and exercises the nativebeforeinstallpromptpath.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.
--admin: the installed app and/sessionsshow 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:
They are local and not committed:
scratchpad/dashboard-pwa-shots/andscratchpad/dashboard-pwa-shots/phase3/in the worktree.Changeset
.changeset/dashboard-install-app.md:browserhiveminor. The four workspace packages share one version group, sochangeset statusshows minor for all of them.Checklist
bun run checkpasses locallyany, payload casts,!,String(err), silent catch, floating promise,process.env, module-level mutable state@moduleheaders, "why" comments on constantsD-xxreferences added where code implements a decisionRelated: #54 (a dependency-cruiser blind spot found while building this; the new
daemon-helpboundary rule is backed by a test until #54 is fixed).