feat(maestro): debug HUD overlay for inferred session metrics (#20)
ci / rust (push) Failing after 1m49s
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:
@@ -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
@@ -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
@@ -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
@@ -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(),
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user