From f3c4784acc5a5b94e9ac401a2d0aeca5105364b5 Mon Sep 17 00:00:00 2001 From: naps62-yolo Date: Sun, 21 Jun 2026 14:55:41 +0000 Subject: [PATCH] feat(maestro): debug HUD overlay for inferred session metrics (#20) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A game-HUD-style debug overlay (FPS-counter for sessions) that surfaces the daemon-inferred fields from #18 — activity, foreground, idle time, status — on the active session, live off the existing events WS. Lets us validate the inferred data before designing any "real" UI, and stays useful as a permanent debugging tool. - Off by default; toggled via Ctrl+Shift+D (persisted in localStorage) or `?hud` in dev (debug.ts). - Fixed bottom-right overlay, pointer-events:none so it never blocks the terminal; activity value is color-coded (active/awaiting/idle). - Generic: renders every non-client-owned Session field, so a new daemon-derived field (#19 `detail`, later metrics) surfaces with no overlay change. Idle time re-renders on a 1s ticker; values update on SessionUpdated. - Pure consumer-side: no daemon/protocol/registry changes. The `?mock` fixture seeds varied activity so the HUD can be reviewed without a daemon. Closes #20 Co-Authored-By: Claude Opus 4.8 (1M context) --- web/src/debug.ts | 42 ++++++++++++++ web/src/hud.ts | 135 +++++++++++++++++++++++++++++++++++++++++++++ web/src/main.ts | 13 ++++- web/src/mock.ts | 11 +++- web/src/styles.css | 62 +++++++++++++++++++++ 5 files changed, 261 insertions(+), 2 deletions(-) create mode 100644 web/src/debug.ts create mode 100644 web/src/hud.ts diff --git a/web/src/debug.ts b/web/src/debug.ts new file mode 100644 index 0000000..5dfcc0b --- /dev/null +++ b/web/src/debug.ts @@ -0,0 +1,42 @@ +// Debug-HUD toggle (#20). Off by default; persisted in localStorage so it +// survives reloads, flipped by a keybind (Ctrl+Shift+D), and force-enabled by +// `?hud` in dev. A `maestro-hud-toggle` event lets the HUD re-render on change. + +const STORAGE_KEY = "maestro:hud"; +export const HUD_TOGGLE_EVENT = "maestro-hud-toggle"; + +/** Whether the debug HUD should be shown. */ +export function isHudEnabled(): boolean { + if (import.meta.env.DEV && location.search.includes("hud")) return true; + try { + return localStorage.getItem(STORAGE_KEY) === "1"; + } catch { + // Private-mode / storage-disabled: HUD just stays off. + return false; + } +} + +/** Persist the HUD on/off state and notify listeners. */ +export function setHudEnabled(on: boolean): void { + try { + if (on) localStorage.setItem(STORAGE_KEY, "1"); + else localStorage.removeItem(STORAGE_KEY); + } catch { + // ignore storage failures — the event still drives the in-memory HUD + } + window.dispatchEvent(new CustomEvent(HUD_TOGGLE_EVENT)); +} + +export function toggleHud(): void { + setHudEnabled(!isHudEnabled()); +} + +/** Global keybind: Ctrl+Shift+D toggles the debug HUD. */ +export function installHudKeybind(): void { + window.addEventListener("keydown", (e) => { + if (e.ctrlKey && e.shiftKey && (e.key === "D" || e.key === "d")) { + e.preventDefault(); + toggleHud(); + } + }); +} diff --git a/web/src/hud.ts b/web/src/hud.ts new file mode 100644 index 0000000..bbab533 --- /dev/null +++ b/web/src/hud.ts @@ -0,0 +1,135 @@ +// Game-style debug HUD (#20): a fixed-corner overlay on the active session +// showing the daemon-inferred fields (activity, foreground, idle time, status, +// …) live off the events WS — an FPS-counter for sessions, to validate the +// inferred data before any "real" UI is designed. +// +// It renders **whatever non-client-owned fields are present** on the Session, so +// a new daemon-derived field (#19 `detail`, later metrics) surfaces with no +// change here. Off by default — see `debug.ts`. + +import { HUD_TOGGLE_EVENT, isHudEnabled } from "./debug.js"; +import type { CatalogStore } from "./events.js"; +import { sessionName, type Session, type Uuid } from "./types.js"; + +/** Fields the client itself owns/sets — not daemon-inferred, so the HUD skips + * them. Everything else on the Session is shown, including future fields. */ +const CLIENT_OWNED = new Set([ + "id", + "daemon_id", + "cwd", + "command", + "env", + "metadata", + "created_at", +]); + +/** Friendlier labels for known keys; unknown (future) keys show their raw name. */ +const LABELS: Record = { + last_activity_at: "idle", + foreground: "fg", +}; + +export interface Hud { + /** Re-evaluate visibility + content (e.g. after navigation). */ + refresh(): void; + dispose(): void; +} + +/** Mount the HUD into `root`. It reflects the session returned by + * `getActiveId()`, updating on store changes, a 1s ticker (for idle time), and + * the toggle event. */ +export function mountHud( + root: HTMLElement, + store: CatalogStore, + getActiveId: () => Uuid | null, +): Hud { + const el = document.createElement("aside"); + el.className = "debug-hud"; + el.hidden = true; + el.setAttribute("aria-hidden", "true"); + root.appendChild(el); + + const render = () => { + if (!isHudEnabled()) { + el.hidden = true; + return; + } + const id = getActiveId(); + const session = id ? store.snapshot().sessions.get(id) : undefined; + if (!session) { + el.hidden = true; + return; + } + el.hidden = false; + el.replaceChildren(...buildRows(session)); + }; + + const unsubscribe = store.subscribe(render); + const ticker = window.setInterval(render, 1000); + window.addEventListener(HUD_TOGGLE_EVENT, render); + render(); + + return { + refresh: render, + dispose() { + unsubscribe(); + window.clearInterval(ticker); + window.removeEventListener(HUD_TOGGLE_EVENT, render); + el.remove(); + }, + }; +} + +function buildRows(session: Session): HTMLElement[] { + const rows: HTMLElement[] = []; + + const head = document.createElement("div"); + head.className = "hud-head"; + head.textContent = sessionName(session); + rows.push(head); + + for (const [key, value] of Object.entries(session)) { + if (CLIENT_OWNED.has(key) || value === undefined) continue; + rows.push(buildRow(key, value)); + } + return rows; +} + +function buildRow(key: string, value: unknown): HTMLElement { + const row = document.createElement("div"); + row.className = "hud-row"; + + const k = document.createElement("span"); + k.className = "hud-k"; + k.textContent = LABELS[key] ?? key; + + const v = document.createElement("span"); + v.className = "hud-v"; + if (key === "last_activity_at") { + v.textContent = relativeAge(value); + } else if (value === null) { + v.textContent = "—"; + } else { + v.textContent = String(value); + } + // Lets the stylesheet color the activity value by state. + if (key === "activity" && typeof value === "string") { + v.dataset.activity = value; + } + + row.append(k, v); + return row; +} + +/** A timestamp rendered as "Ns" / "Nm Ns" / "Nh Nm" since now. */ +function relativeAge(value: unknown): string { + if (typeof value !== "string") return "—"; + const t = Date.parse(value); + if (!Number.isFinite(t)) return "—"; + const secs = Math.max(0, Math.round((Date.now() - t) / 1000)); + if (secs < 60) return `${secs}s`; + const mins = Math.floor(secs / 60); + if (mins < 60) return `${mins}m ${secs % 60}s`; + const hrs = Math.floor(mins / 60); + return `${hrs}h ${mins % 60}m`; +} diff --git a/web/src/main.ts b/web/src/main.ts index 9cd615d..bb491f9 100644 --- a/web/src/main.ts +++ b/web/src/main.ts @@ -1,6 +1,8 @@ import { renderSidebar, renderTopbar } from "./catalog.js"; import { ConnectionPool } from "./connections.js"; +import { installHudKeybind } from "./debug.js"; import { CatalogStore } from "./events.js"; +import { mountHud, type Hud } from "./hud.js"; import { openSpawnModal } from "./spawn.js"; import { initTheme } from "./theme.js"; import { sessionName } from "./types.js"; @@ -9,6 +11,7 @@ import "./styles.css"; initTheme(); installViewportSizing(); +installHudKeybind(); registerServiceWorker(); // Register the PWA service worker so the app is installable and the shell loads @@ -64,10 +67,18 @@ root.replaceChildren(renderTopbar(store), shellEl); // The pool owns attach connections independently of the route: navigating away // parks a session (keeps it streaming); navigating back re-mounts it instantly. +let hud: Hud | undefined; const pool = new ConnectionPool({ - onActiveChange: (id) => sidebar.setActive(id), + onActiveChange: (id) => { + sidebar.setActive(id); + hud?.refresh(); + }, }); +// Debug HUD (#20): a fixed-corner overlay on the active session's inferred +// fields, off by default (Ctrl+Shift+D, or `?hud` in dev). +hud = mountHud(root, store, () => pool.active()); + function renderWelcome(): HTMLElement { const el = document.createElement("div"); el.className = "empty content-welcome"; diff --git a/web/src/mock.ts b/web/src/mock.ts index a23eafd..ab76ffd 100644 --- a/web/src/mock.ts +++ b/web/src/mock.ts @@ -2,7 +2,11 @@ // main.ts (`?mock`), so it never ships in a production bundle. It pushes a // synthetic Snapshot through the store's normal event path. import type { CatalogStore } from "./events.js"; -import type { Session, DaemonInfo } from "./types.js"; +import type { ActivityState, Session, DaemonInfo } from "./types.js"; + +// Rotate inferred activity across the fixture so the debug HUD (#20) shows all +// three states. Keyed off the id's last hex digit for stable variety. +const ACTIVITIES: ActivityState[] = ["Active", "Idle", "AwaitingInput"]; function sess( id: string, @@ -11,6 +15,7 @@ function sess( status: "Running" | "Dead", meta: Record, ): Session { + const seed = parseInt(id.slice(-1), 16) || 0; return { id, daemon_id: daemon, @@ -20,6 +25,10 @@ function sess( metadata: meta, status, created_at: "2026-06-15T12:00:00Z", + // Inferred fields (#18) so the HUD has real data to render in review. + foreground: command.split(" ")[0], + activity: ACTIVITIES[seed % ACTIVITIES.length], + last_activity_at: new Date(Date.now() - seed * 11_000).toISOString(), }; } diff --git a/web/src/styles.css b/web/src/styles.css index 781e61a..7b389dd 100644 --- a/web/src/styles.css +++ b/web/src/styles.css @@ -1831,3 +1831,65 @@ textarea { animation: none; } } + +/* ---------- debug HUD (#20) ---------- */ + +.debug-hud { + position: fixed; + right: var(--sp-3); + bottom: var(--sp-3); + z-index: var(--z-toast); + min-width: 180px; + max-width: 280px; + padding: var(--sp-2) var(--sp-3); + background: color-mix(in oklab, var(--surface) 88%, transparent); + border: 1px solid var(--border-strong); + border-radius: var(--r-2); + box-shadow: var(--shadow-2); + font-family: var(--font-mono); + font-size: var(--fs-12); + line-height: 1.5; + /* Diagnostics only — never intercept clicks on the terminal beneath it. */ + pointer-events: none; + user-select: none; +} + +.hud-head { + color: var(--ink); + font-weight: 600; + margin-bottom: 2px; + border-bottom: 1px solid var(--border); + padding-bottom: 2px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.hud-row { + display: flex; + justify-content: space-between; + gap: var(--sp-3); +} + +.hud-k { + color: var(--muted); +} + +.hud-v { + color: var(--ink); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.hud-v[data-activity="Active"] { + color: var(--accent); +} + +.hud-v[data-activity="AwaitingInput"] { + color: var(--warn); +} + +.hud-v[data-activity="Idle"] { + color: var(--muted); +}