feat(maestro): debug HUD overlay for inferred session metrics (#20)
ci / rust (push) Failing after 1m49s

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) <noreply@anthropic.com>
This commit is contained in:
2026-06-21 14:55:41 +00:00
co-authored by Claude Opus 4.8
parent fd80ae152a
commit f3c4784acc
5 changed files with 261 additions and 2 deletions
+42
View File
@@ -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();
}
});
}
+135
View File
@@ -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<string, string> = {
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`;
}
+12 -1
View File
@@ -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";
+10 -1
View File
@@ -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<string, unknown>,
): 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(),
};
}
+62
View File
@@ -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);
}