Skip to content

📝 RFC: Activity Monitor kiosk/display mode for wall-screen dashboards #15855

Closed as not planned

Description

@hanthor

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 k key does the same while focus is in the tracker. Esc leaves kiosk for pop-out (Grafana's d k / Esc).
  • Kiosk entered from the UI sets body.kiosk-mode (the same CSS as ?kiosk=1), requests full screen, and requests navigator.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=1 from 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 any am.* parameter is present, the URL wins over localStorage, and kiosk mode never writes it back to localStorage. 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_at is 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/HEAD only. Allow-list: /, static assets, /api/theme.css, /api/stage-tracker, and /api/events restricted to display frames. Never pane output (paneTailViewer stays 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, so src/deploy/stream/authproxy swaps the shared owner bearer for a display token.

Security and privacy

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

Alternatives considered

  • Grafana itself, with /api/stage-tracker as 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

  1. Playlist presets: URL-only, or named presets under dashboard.display.presets in hive.yaml?
  2. 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)?
  3. Pairing: device-code approval (proposed), or a one-time pairing URL?
  4. Kiosk from the UI: should it auto-request full screen and wake lock, or leave them as separate toggles?
  5. Prometheus gauges per stage and modifier (hive_tracker_items{stage,modifier}): in or out of scope?

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Oct 30, 2026
  2. hanthor commented on Oct 30, 2026

    @hanthor
    ContributorAuthor

    Duplicate of #15860: created by a failed publish script run. Discussion lives on #15860.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.holdkind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions