Repository navigation
Description
Held RFC. This is a design proposal for discussion. It carries hold so no hive agent picks it up until maintainers settle Decisions for maintainers. It is the first of three related Activity Monitor RFCs: this one (display mode), {{RFC2}} (hub-wide activity monitor) and {{RFC3}} ("Matrix" code-stream mode). Part A works without the other two.
| Field | Value |
|---|---|
| Status | Proposal, open for maintainer discussion, not accepted |
| Target | v5 (dashboard SPA). Part C adds a server-side credential and may be better placed on v6 (Decision 2) |
| Scope | src/pkg/dashboard/static-src/js/boot.js, css/kiosk.css, the pop-out code from #15830 (js/tracker-popout.js, css/popout.css), dashboard auth for a read-only display credential, src/deploy/stream/authproxy |
| Initially out of scope | New dashboard panels other than the Activity Monitor; a Grafana data-source plugin; changing what ?kiosk=1 does for the headless streamer |
| Related | #15594 / #15596 (?kiosk=1, shipped), #15829 / #15830 (⧉ Pop out + ⛶ Full screen, open), #15846 (authproxy GET/HEAD only), src/docs/streaming-the-activity-monitor.md, {{RFC2}}, {{RFC3}} |
Executive summary
The problem. People want the Activity Monitor on a wall screen: a TV in the office, a second monitor, a lobby display, the way teams put Grafana up. The parts are partly in place. ?kiosk=1 exists, but you have to type it into the URL by hand and it was built for the headless Twitch streamer. #15830 adds a pop-out window and a full-screen toggle. A display that runs unattended for weeks still needs more: you can't get into kiosk mode from the UI, a URL can't carry filter state, nothing rotates between views, a frozen screen gives no stale-data signal, and there is no credential that suits a TV.
The proposal. Treat a Grafana-style display mode as a feature in its own right, built on ?kiosk=1 and #15830:
- an in-UI view-mode control: Normal → Pop out → Kiosk
- view state the URL can carry, plus a "Copy display link" button
- a TV density
- a live/stale health header
- best-effort wake lock and burn-in protection
- playlists that rotate views
- a scoped, revocable, read-only display token, paired to the screen without a token in the URL. It replaces the shared owner bearer the stream authproxy uses today.
What changes for operators. Nothing unless someone uses the new control or URL parameters. ?kiosk=1 keeps working byte-for-byte for the streamer.
Motivation
What exists today (v5 be04a9cb4):
| Capability | Today | Gap for a wall display |
|---|---|---|
| Chrome-less view | ?kiosk=1 (boot.js:19, css/kiosk.css) hides the sidebar, topbar, notices, Welcome, NPS and chat; forces dark unless &theme=light; &sound=off |
Only reachable by editing the URL; there is no way out except editing the URL back |
| Separate window / full screen | #15830 (open): ⧉ Pop out → ?popout=1, ⛶ Full screen via the Fullscreen API |
Nothing persists; the window is the full SPA with the other sections hidden |
| Filter state | localStorage key hive-activity-monitor-filter |
A screen can't be told "PRs only, repo X, grouped by repo" by its URL; two screens on one browser profile share one filter |
| Liveness | SSE stage-tracker frame on /api/events plus a ~30 s poll of /api/stage-tracker |
If SSE drops or the spoke is down, the last frame stays up looking live |
| Credential | Stream guide: shared owner bearer behind a loopback proxy limited to GET/HEAD (#15846), or a person's GitHub token on the public route | No revocable, viewer-only credential bound to one display |
Grafana's kiosk mode gives a useful checklist: one key to enter or leave kiosk, URL-encoded variables, playlists, TV mode, an auto-refresh interval, and controls that hide when the mouse is idle.
Design
A. View-mode control (client only)
- A View control in the Activity Monitor header next to ⧉/⛶ cycles Normal → Pop out → Kiosk. The
kkey does the same while focus is in the tracker.Escleaves kiosk for pop-out (Grafana'sd k/Esc). - Kiosk entered from the UI sets
body.kiosk-mode(the same CSS as?kiosk=1), requests full screen, and requestsnavigator.wakeLock.request('screen'). All three are best-effort; a refused request stays silent. - Auto-hide controls. After 3 s without mouse movement the cursor and a small overlay with Exit kiosk, Copy display link and Settings fade out. Moving the mouse brings them back. Under
?kiosk=1from the streamer the overlay never renders (no pointer, so no behaviour change). - URL-encoded view state. Every tracker filter round-trips through namespaced query parameters:
am.kind,am.repo,am.q,am.age,am.author,am.sort,am.dir,am.group. If anyam.*parameter is present, the URL wins overlocalStorage, and kiosk mode never writes it back tolocalStorage. Copy display link puts the current view into a URL. - TV density (
density=tv): larger type, columns pruned to stage, title and actor, rows capped to fit the viewport with a "+N more" footer instead of pagination. Pagination makes no sense on a screen nobody touches. - Health header: hive name, a clock, and a live dot driven by SSE state. If SSE has been disconnected for longer than 2× the poll interval, or
generated_atis older than 2×cache_ttl_s, the board dims and shows Stale: last update 4 m ago. After N failed reconnects, or when the dashboard version changes, the page reloads. A wall display must never show frozen data as live. - Burn-in protection (
shift=1, off by default): a 1–2 px content shift every few minutes for OLED panels.
B. Playlists
?kiosk=1&playlist=<view>,<view>&interval=60s rotates views in kiosk. A view is the tracker with a filter preset (am.*), the hub-wide monitor ({{RFC2}}), or Matrix mode ({{RFC3}}). Until those land, a playlist rotates tracker presets, e.g. "needs a human" → "in CI" → "merged today". Decision 1 is where presets live.
C. Display tokens (server)
- The owner mints a display credential in Settings or with
hivectl display token create --name lobby-tv. It is stored hashed, listed with last-seen time and IP, and revocable. Mint, revoke and first-use go to the audit log. - Scope: accepted on
GET/HEADonly. Allow-list:/, static assets,/api/theme.css,/api/stage-tracker, and/api/eventsrestricted to display frames. Never pane output (paneTailViewerstays false), never settings, never row actions. The SPA renders the tracker without the ⋯ / right-click action menus for this role. - Pairing, no token in the URL. Device-code style: the TV opens
/display, which shows a short code; the owner approves it in Settings, and the TV receives an HttpOnly cookie bound to that display token. The fallback for headless capture is the existing header injection, sosrc/deploy/stream/authproxyswaps the shared owner bearer for a display token.
Security and privacy
- Parts A and B change rendering only; auth is unchanged.
- Part C narrows exposure. Today the shared, unscoped owner token sits on a streaming box, and the proxy is the only thing that keeps it read-only ([sec-check] stream authproxy forwards every method with the shared owner bearer — bound the kiosk proxy to GET/HEAD #15846). A display token is read-only on the server side, revocable on its own, and visible in the audit log.
- The private-repository warning in
streaming-the-activity-monitor.mdstill applies: a display shows what the tracker shows.
Cost and footprint
Parts A and B are client-only. Part C adds one small token store under the dashboard's existing data directory, plus one middleware check.
Rollout
- Part A: view-mode control,
am.*URL state, Copy display link, TV density, health header and stale dimming, wake lock, burn-in shift. v5, after ✨ dashboard: pop out the Hive activity monitor into its own window and a full-screen toggle #15830 merges. - Part B: playlists, starting with tracker presets and gaining hub/Matrix views as {{RFC2}} and {{RFC3}} land.
- Part C: display tokens, pairing, and the authproxy cutover.
Alternatives considered
- Grafana itself, with
/api/stage-trackeras a JSON data source or Prometheus gauges per stage. This complements the proposal rather than replacing it. The tracker's value is its motion: rows moving through stages, merge toasts, sounds. A Grafana table loses all of that. Cheap per-stage gauges are Decision 5. - Keep the shared owner bearer behind the proxy. It works in-cluster, but one leaked box is an owner credential, and it doesn't help a TV on the office Wi-Fi.
- Browser extension or OS kiosk only. This handles full screen but not URL state, liveness, or credentials.
Decisions for maintainers
- Playlist presets: URL-only, or named presets under
dashboard.display.presetsinhive.yaml? - Display tokens: a new spoke credential on v5, or v6 alongside the dashboard-optional auth work? Or instead lean on hub viewer accounts (a GitHub read-only user on the public route)?
- Pairing: device-code approval (proposed), or a one-time pairing URL?
- Kiosk from the UI: should it auto-request full screen and wake lock, or leave them as separate toggles?
- Prometheus gauges per stage and modifier (
hive_tracker_items{stage,modifier}): in or out of scope?
Activity
hanthor commentedon Oct 30, 2026
Duplicate of #15860: created by a failed publish script run. Discussion lives on #15860.