@hansenexus/hud 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,102 +1,256 @@
-import { useCallback, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
-import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { a as resolvePlugins, i as definePlugin, n as HudApiError, r as createPluginContext } from "./plugins-CzUiTn_r.js";
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
-//#region src/core/marker.ts
-/**
-* Literal a consumer's CI bundle gate greps for in production client chunks.
-* It is rendered as an attribute on the HUD root, so a bundler cannot drop it
-* while keeping the HUD, and it is unmistakably deliberate rather than an
-* incidental string a refactor could rename away.
-*/
-const HUD_DEV_MARKER = "__HANSENEXUS_HUD_DEV__";
-/** Tag name of the element that hosts the HUD's shadow root. */
-const HUD_HOST_TAG = "hn-hud";
+//#region src/shell/commands/context.ts
+const RegistryContext = createContext(null);
+function useRegistry() {
+	const registry = useContext(RegistryContext);
+	if (!registry) throw new Error("HUD commands used outside <CommandProvider>");
+	return registry;
+}
+function useCommands() {
+	const registry = useRegistry();
+	return useSyncExternalStore(registry.subscribe, registry.list, registry.list);
+}
+/** Registers `commands` while the caller is mounted. Pass a stable (memoised) array. */
+function useRegisterCommands(commands) {
+	const registry = useRegistry();
+	useEffect(() => {
+		const unregister = commands.map((command) => registry.register(command));
+		return () => {
+			for (const off of unregister) off();
+		};
+	}, [registry, commands]);
+}
 //#endregion
-//#region src/vitals/store.ts
-/** Display order: the three Core Web Vitals first, then the diagnostics. */
-const VITAL_ORDER = [
-	"LCP",
-	"INP",
-	"CLS",
-	"FCP",
-	"TTFB"
-];
-let snapshot = {};
-const listeners = /* @__PURE__ */ new Set();
-let started = false;
-function record(metric) {
-	snapshot = {
-		...snapshot,
-		[metric.name]: {
-			name: metric.name,
-			value: metric.value,
-			rating: metric.rating
-		}
+//#region src/shell/commands/shortcut.ts
+function parseShortcut(spec) {
+	const parts = spec.toLowerCase().split("+");
+	return {
+		key: parts.at(-1) ?? "",
+		mod: parts.includes("mod"),
+		shift: parts.includes("shift"),
+		alt: parts.includes("alt")
 	};
-	for (const listener of listeners) listener();
 }
+function isApplePlatform() {
+	return typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent);
+}
+function matchesShortcut(event, shortcut, apple) {
+	if ((apple ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey) !== shortcut.mod) return false;
+	if (event.shiftKey !== shortcut.shift || event.altKey !== shortcut.alt) return false;
+	if (event.key.toLowerCase() === shortcut.key) return true;
+	if (/^[a-z]$/.test(shortcut.key)) return event.code === `Key${shortcut.key.toUpperCase()}`;
+	if (/^\d$/.test(shortcut.key)) return event.code === `Digit${shortcut.key}`;
+	return false;
+}
+function formatShortcut(shortcut, apple) {
+	const key = shortcut.key.toUpperCase();
+	if (apple) return `${shortcut.mod ? "⌘" : ""}${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${key}`;
+	return [
+		shortcut.mod && "Ctrl",
+		shortcut.alt && "Alt",
+		shortcut.shift && "Shift",
+		key
+	].filter(Boolean).join("+");
+}
+//#endregion
+//#region src/shell/commands/registry.ts
+/** Element grab arrives with the grabber slice (hud#7); the shortcut is reserved now. */
+const GRAB_COMMAND = {
+	id: "hud.grab",
+	title: "Grab element",
+	shortcut: "mod+shift+g",
+	run: () => {}
+};
 /**
-* Starts collection once per page. Called when the HUD mounts, not when the
-* panel opens: LCP and FCP are only reported for the initial load, so a lazy
-* start would miss them.
+* Commands the shell and plugins contribute. Registering an id again
+* replaces the earlier command; the first registered shortcut match wins.
 */
-function startVitals() {
-	if (started) return;
-	started = true;
-	const opts = { reportAllChanges: true };
-	try {
-		onLCP(record, opts);
-		onINP(record, opts);
-		onCLS(record, opts);
-		onFCP(record, opts);
-		onTTFB(record, opts);
-	} catch {}
+var CommandRegistry = class {
+	#commands = /* @__PURE__ */ new Map();
+	#snapshot = [];
+	#listeners = /* @__PURE__ */ new Set();
+	register(command) {
+		this.#commands.set(command.id, command);
+		this.#emit();
+		return () => {
+			if (this.#commands.get(command.id) !== command) return;
+			this.#commands.delete(command.id);
+			this.#emit();
+		};
+	}
+	list = () => this.#snapshot;
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	};
+	run(id) {
+		const command = this.#commands.get(id);
+		command?.run();
+		return command !== void 0;
+	}
+	/** Runs the command bound to this key press, if any, and reports whether one ran. */
+	handleKey(event, apple) {
+		for (const command of this.#commands.values()) if (command.shortcut && matchesShortcut(event, parseShortcut(command.shortcut), apple)) {
+			command.run();
+			return true;
+		}
+		return false;
+	}
+	#emit() {
+		this.#snapshot = [...this.#commands.values()];
+		for (const listener of this.#listeners) listener();
+	}
+};
+//#endregion
+//#region src/shell/commands/command-provider.tsx
+const BUILTIN = [GRAB_COMMAND];
+/** Owns one HUD's command registry and binds its shortcuts on `window`. */
+function CommandProvider({ commands, children }) {
+	const [registry] = useState(() => new CommandRegistry());
+	useEffect(() => {
+		const unregister = [...BUILTIN, ...commands].map((command) => registry.register(command));
+		return () => {
+			for (const off of unregister) off();
+		};
+	}, [registry, commands]);
+	useEffect(() => {
+		const apple = isApplePlatform();
+		const onKeyDown = (event) => {
+			if (event.repeat || event.defaultPrevented) return;
+			if (registry.handleKey(event, apple)) event.preventDefault();
+		};
+		window.addEventListener("keydown", onKeyDown, true);
+		return () => window.removeEventListener("keydown", onKeyDown, true);
+	}, [registry]);
+	return /* @__PURE__ */ jsx(RegistryContext.Provider, {
+		value: registry,
+		children
+	});
 }
-function getVitals() {
-	return snapshot;
+//#endregion
+//#region src/shell/panels/layout.ts
+const EMPTY_LAYOUT = {
+	open: [],
+	floats: {},
+	pins: {},
+	hidden: false
+};
+/** A pinned edge never takes more than this share of the viewport. */
+const MAX_SHARE = .4;
+function visiblePanels(layout) {
+	return layout.hidden ? [] : layout.open;
 }
-function subscribeVitals(listener) {
-	listeners.add(listener);
-	return () => listeners.delete(listener);
+function openPanel(layout, id, fallback) {
+	return {
+		...layout,
+		open: [...layout.open.filter((open) => open !== id), id],
+		floats: id in layout.floats ? layout.floats : {
+			...layout.floats,
+			[id]: fallback
+		},
+		hidden: false
+	};
 }
-function useVitals() {
-	return useSyncExternalStore(subscribeVitals, getVitals, getVitals);
+function closePanel(layout, id) {
+	if (!layout.open.includes(id)) return layout;
+	return {
+		...layout,
+		open: layout.open.filter((open) => open !== id)
+	};
 }
-function formatVital(name, value) {
-	if (name === "CLS") return value.toFixed(2);
-	if (value >= 1e3) return `${(value / 1e3).toFixed(1)} s`;
-	return `${Math.round(value)} ms`;
+function focusPanel(layout, id) {
+	if (layout.open.at(-1) === id || !layout.open.includes(id)) return layout;
+	return {
+		...layout,
+		open: [...layout.open.filter((open) => open !== id), id]
+	};
 }
-//#endregion
-//#region src/vitals/vitals-panel.tsx
-function VitalsPanel() {
-	const vitals = useVitals();
-	const rows = VITAL_ORDER.flatMap((name) => {
-		const vital = vitals[name];
-		return vital ? [vital] : [];
-	});
-	if (rows.length === 0) return /* @__PURE__ */ jsx("p", {
-		className: "empty",
-		children: "No metrics yet. LCP reports after the first interaction or tab switch."
-	});
-	return /* @__PURE__ */ jsx("table", {
-		className: "vitals",
-		children: /* @__PURE__ */ jsx("tbody", { children: rows.map((vital) => /* @__PURE__ */ jsxs("tr", { children: [/* @__PURE__ */ jsx("td", {
-			className: "label",
-			children: vital.name
-		}), /* @__PURE__ */ jsxs("td", { children: [/* @__PURE__ */ jsx("span", {
-			className: "dot",
-			"data-rating": vital.rating,
-			style: {
-				display: "inline-block",
-				marginRight: 6
-			}
-		}), formatVital(vital.name, vital.value)] })] }, vital.name)) })
-	});
+function movePanel(layout, id, pos) {
+	return {
+		...layout,
+		floats: {
+			...layout.floats,
+			[id]: pos
+		}
+	};
+}
+/** Pins `id` to `edge`, at the end of that edge's stack; `null` floats it again. */
+function pinPanel(layout, id, edge) {
+	const pins = Object.fromEntries(Object.entries(layout.pins).filter(([pinned]) => pinned !== id));
+	if (edge) pins[id] = edge;
+	return {
+		...layout,
+		pins
+	};
+}
+/**
+* ⌘⇧H: hide a shown layout, show a hidden one, and on an empty layout open
+* `firstId` so the shortcut always shows something.
+*/
+function toggleLayout(layout, firstId, fallback) {
+	if (layout.hidden) return {
+		...layout,
+		hidden: false
+	};
+	if (layout.open.length > 0) return {
+		...layout,
+		hidden: true
+	};
+	return firstId ? openPanel(layout, firstId, fallback) : layout;
+}
+/**
+* Where pinned panels sit. Side pins run the full height and split it; bottom
+* pins sit between the side pins and split the remaining width.
+*/
+function pinGeometry(layout, viewport) {
+	const visible = new Set(visiblePanels(layout));
+	const stacks = {
+		left: [],
+		right: [],
+		bottom: []
+	};
+	for (const [id, edge] of Object.entries(layout.pins)) if (visible.has(id)) stacks[edge].push(id);
+	const side = Math.min(360, Math.round(viewport.w * MAX_SHARE));
+	const bottom = Math.min(280, Math.round(viewport.h * MAX_SHARE));
+	const reserve = {
+		left: stacks.left.length > 0 ? side : 0,
+		right: stacks.right.length > 0 ? side : 0,
+		bottom: stacks.bottom.length > 0 ? bottom : 0
+	};
+	const rects = {};
+	const split = (ids, length, place) => {
+		ids.forEach((id, i) => {
+			const start = Math.round(i * length / ids.length);
+			const end = Math.round((i + 1) * length / ids.length);
+			rects[id] = place(start, end - start);
+		});
+	};
+	split(stacks.left, viewport.h, (top, height) => ({
+		left: 0,
+		top,
+		width: side,
+		height
+	}));
+	split(stacks.right, viewport.h, (top, height) => ({
+		left: viewport.w - side,
+		top,
+		width: side,
+		height
+	}));
+	split(stacks.bottom, viewport.w - reserve.left - reserve.right, (start, width) => ({
+		left: reserve.left + start,
+		top: viewport.h - bottom,
+		width,
+		height: bottom
+	}));
+	return {
+		reserve,
+		rects
+	};
 }
-//#endregion
-//#region src/shell/floating-panel.tsx
 /** Keeps at least this much of the title bar on screen so a panel can always be dragged back. */
 const GRIP = 40;
 function clampPosition(pos, width, viewport) {
@@ -105,46 +259,86 @@ function clampPosition(pos, width, viewport) {
 		y: Math.min(Math.max(pos.y, 0), viewport.h - GRIP)
 	};
 }
+function snapEdge(x, y, viewport) {
+	if (x <= 24) return "left";
+	if (x >= viewport.w - 24) return "right";
+	if (y >= viewport.h - 24) return "bottom";
+	return null;
+}
+//#endregion
+//#region src/shell/panels/panel-frame.tsx
+/** The narrowest a floating panel renders (`.panel { min-width }`). */
+const MIN_WIDTH = 240;
+const PIN_GLYPH = {
+	left: "◧",
+	right: "◨",
+	bottom: "⬓"
+};
+const PIN_ORDER = [
+	"left",
+	"bottom",
+	"right"
+];
 /**
-* A draggable panel. Pinning to an edge and persistence arrive with the panel
-* manager (hud#3); this is the single-window tracer.
+* One panel window: floating and draggable, or pinned to an edge. Dropping a
+* drag near the left, right or bottom edge pins it there.
 */
-function FloatingPanel({ title, initial, onClose, children }) {
-	const [pos, setPos] = useState(initial);
+function PanelFrame({ title, z, viewport, position, pinned, onFocus, onClose, onMove, onPin, onSnapPreview, children }) {
 	const panelRef = useRef(null);
 	const drag = useRef(null);
-	const onPointerDown = useCallback((e) => {
-		if (e.target.closest("button")) return;
+	const [dragPos, setDragPos] = useState(null);
+	const pos = dragPos ?? clampPosition(position, MIN_WIDTH, viewport);
+	const onPointerDown = (e) => {
+		if (pinned || e.target.closest("button")) return;
 		drag.current = {
 			dx: e.clientX - pos.x,
-			dy: e.clientY - pos.y
+			dy: e.clientY - pos.y,
+			pos,
+			edge: null
 		};
 		e.currentTarget.setPointerCapture(e.pointerId);
-	}, [pos]);
-	const onPointerMove = useCallback((e) => {
+	};
+	const onPointerMove = (e) => {
 		const d = drag.current;
 		if (!d) return;
-		const width = panelRef.current?.offsetWidth ?? 240;
-		setPos(clampPosition({
+		const width = panelRef.current?.offsetWidth ?? MIN_WIDTH;
+		d.pos = clampPosition({
 			x: e.clientX - d.dx,
 			y: e.clientY - d.dy
-		}, width, {
-			w: window.innerWidth,
-			h: window.innerHeight
-		}));
-	}, []);
-	const onPointerUp = useCallback((e) => {
+		}, width, viewport);
+		const edge = snapEdge(e.clientX, e.clientY, viewport);
+		if (edge !== d.edge) {
+			d.edge = edge;
+			onSnapPreview(edge);
+		}
+		setDragPos(d.pos);
+	};
+	const onPointerUp = (e) => {
+		const d = drag.current;
 		drag.current = null;
 		if (e.currentTarget.hasPointerCapture(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
-	}, []);
+		if (!d) return;
+		setDragPos(null);
+		if (d.edge) {
+			onSnapPreview(null);
+			onPin(d.edge);
+		} else if (d.pos.x !== position.x || d.pos.y !== position.y) onMove(d.pos);
+	};
+	const style = pinned ? {
+		...pinned.rect,
+		zIndex: z
+	} : {
+		left: pos.x,
+		top: pos.y,
+		zIndex: z
+	};
 	return /* @__PURE__ */ jsxs("section", {
 		ref: panelRef,
 		className: "panel",
 		"aria-label": title,
-		style: {
-			left: pos.x,
-			top: pos.y
-		},
+		"data-pin": pinned?.edge,
+		style,
+		onPointerDownCapture: onFocus,
 		children: [/* @__PURE__ */ jsxs("div", {
 			className: "panel-bar",
 			onPointerDown,
@@ -154,20 +348,615 @@ function FloatingPanel({ title, initial, onClose, children }) {
 			children: [/* @__PURE__ */ jsx("span", {
 				className: "panel-title",
 				children: title
+			}), /* @__PURE__ */ jsxs("span", {
+				className: "panel-actions",
+				children: [pinned ? /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "panel-action",
+					"aria-label": `Unpin ${title}`,
+					title: "Unpin",
+					onClick: () => onPin(null),
+					children: "▢"
+				}) : PIN_ORDER.map((edge) => /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "panel-action",
+					"aria-label": `Pin ${title} to the ${edge} edge`,
+					title: `Pin ${edge}`,
+					onClick: () => onPin(edge),
+					children: PIN_GLYPH[edge]
+				}, edge)), /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "panel-action",
+					"aria-label": `Close ${title}`,
+					onClick: onClose,
+					children: "×"
+				})]
+			})]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "panel-body",
+			children
+		})]
+	});
+}
+//#endregion
+//#region src/shell/panels/panel-sheet.tsx
+/** Below 768 px every open panel lives in one full-width bottom sheet, one tab each. */
+function PanelSheet({ panels, active, onSelect, onClose, children }) {
+	return /* @__PURE__ */ jsxs("section", {
+		className: "sheet",
+		"aria-label": active.title,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "sheet-bar",
+			children: [/* @__PURE__ */ jsx("div", {
+				className: "sheet-tabs",
+				role: "tablist",
+				"aria-label": "Open panels",
+				children: panels.map((panel) => /* @__PURE__ */ jsx("button", {
+					type: "button",
+					role: "tab",
+					className: "sheet-tab",
+					"aria-selected": panel === active,
+					onClick: () => onSelect(panel.id),
+					children: panel.title
+				}, panel.id))
 			}), /* @__PURE__ */ jsx("button", {
 				type: "button",
-				className: "panel-close",
-				"aria-label": `Close ${title}`,
-				onClick: onClose,
+				className: "panel-action",
+				"aria-label": `Close ${active.title}`,
+				onClick: () => onClose(active.id),
 				children: "×"
 			})]
 		}), /* @__PURE__ */ jsx("div", {
 			className: "panel-body",
+			role: "tabpanel",
 			children
 		})]
 	});
 }
 //#endregion
+//#region src/shell/panels/panels-context.ts
+const PanelsContext = createContext(null);
+function usePanels() {
+	const api = useContext(PanelsContext);
+	if (!api) throw new Error("usePanels() used outside <PanelManager>");
+	return api;
+}
+//#endregion
+//#region src/shell/panels/types.ts
+const EDGES = [
+	"left",
+	"right",
+	"bottom"
+];
+//#endregion
+//#region src/shell/panels/reserve.ts
+const PADDING = {
+	left: "padding-left",
+	right: "padding-right",
+	bottom: "padding-bottom"
+};
+/**
+* Pushes the page away from pinned panels by adding padding to <html>, so
+* normal-flow content reflows instead of being covered. Inline `!important`,
+* like the HUD host, so a client stylesheet cannot zero it. The host's own
+* padding is kept and added to.
+*
+* Limit: nothing short of an iframe narrows the viewport, so the host's
+* `position: fixed` elements and its media queries still see the full window.
+*
+* Returns a function that restores the previous inline values.
+*/
+function reservePageSpace(reserve, root = document.documentElement) {
+	const touched = EDGES.filter((edge) => reserve[edge] > 0).map((edge) => PADDING[edge]);
+	if (touched.length === 0) return () => {};
+	const computed = getComputedStyle(root);
+	const saved = touched.map((prop) => ({
+		prop,
+		value: root.style.getPropertyValue(prop),
+		priority: root.style.getPropertyPriority(prop)
+	}));
+	for (const edge of EDGES) {
+		if (reserve[edge] <= 0) continue;
+		const prop = PADDING[edge];
+		const base = Number.parseFloat(computed.getPropertyValue(prop)) || 0;
+		root.style.setProperty(prop, `${base + reserve[edge]}px`, "important");
+	}
+	return () => {
+		for (const { prop, value, priority } of saved) if (value) root.style.setProperty(prop, value, priority);
+		else root.style.removeProperty(prop);
+	};
+}
+//#endregion
+//#region src/shell/panels/storage.ts
+const VERSION = 1;
+function layoutKey(appSlug) {
+	return `hansenexus-hud:layout:${appSlug}`;
+}
+/**
+* Reads the stored layout for `appSlug`, dropping panels that are no longer
+* registered. Storage can be missing, blocked or full of someone else's JSON;
+* every failure yields an empty layout.
+*/
+function loadLayout(appSlug, known) {
+	try {
+		const raw = window.localStorage.getItem(layoutKey(appSlug));
+		return raw ? sanitizeLayout(JSON.parse(raw), known) : EMPTY_LAYOUT;
+	} catch {
+		return EMPTY_LAYOUT;
+	}
+}
+function saveLayout(appSlug, layout) {
+	try {
+		window.localStorage.setItem(layoutKey(appSlug), JSON.stringify({
+			v: VERSION,
+			...layout
+		}));
+	} catch {}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPosition(value) {
+	return isRecord(value) && Number.isFinite(value.x) && Number.isFinite(value.y);
+}
+function isEdge(value) {
+	return EDGES.some((edge) => edge === value);
+}
+function sanitizeLayout(value, known) {
+	if (!isRecord(value) || value.v !== VERSION) return EMPTY_LAYOUT;
+	const open = Array.isArray(value.open) ? [...new Set(value.open.filter((id) => typeof id === "string" && known.has(id)))] : [];
+	const floats = {};
+	if (isRecord(value.floats)) {
+		for (const [id, pos] of Object.entries(value.floats)) if (known.has(id) && isPosition(pos)) floats[id] = {
+			x: pos.x,
+			y: pos.y
+		};
+	}
+	const pins = {};
+	if (isRecord(value.pins)) {
+		for (const [id, edge] of Object.entries(value.pins)) if (known.has(id) && isEdge(edge)) pins[id] = edge;
+	}
+	return {
+		open,
+		floats,
+		pins,
+		hidden: value.hidden === true
+	};
+}
+function subscribeResize(listener) {
+	window.addEventListener("resize", listener);
+	return () => window.removeEventListener("resize", listener);
+}
+let cached = {
+	w: 0,
+	h: 0
+};
+/**
+* The layout viewport without scrollbars: the box `position: fixed` resolves
+* against. `clientWidth` of <html> is that box regardless of its padding.
+*/
+function readViewport() {
+	const root = document.documentElement;
+	const w = root.clientWidth || window.innerWidth;
+	const h = root.clientHeight || window.innerHeight;
+	if (w !== cached.w || h !== cached.h) cached = {
+		w,
+		h
+	};
+	return cached;
+}
+function useViewport() {
+	return useSyncExternalStore(subscribeResize, readViewport, readViewport);
+}
+/** Window width including the scrollbar, the same width a `max-width` media query tests. */
+const readNarrow = () => window.innerWidth < 768;
+function useNarrow() {
+	return useSyncExternalStore(subscribeResize, readNarrow, readNarrow);
+}
+//#endregion
+//#region src/shell/panels/panel-manager.tsx
+/** Where a panel opens the first time: stacked up and right from above the pill. */
+function defaultPosition(index) {
+	const step = 28 * index;
+	return {
+		x: 12 + step,
+		y: Math.max(12, window.innerHeight - 300 - step)
+	};
+}
+/**
+* Window management for the HUD: open panels, z-order, drag, pin-to-edge with
+* page push, per-app persistence, the mobile sheet, and the command registry
+* (⌘⇧H toggles the layout).
+*/
+function PanelManager({ commands, ...props }) {
+	return /* @__PURE__ */ jsx(CommandProvider, {
+		commands,
+		children: /* @__PURE__ */ jsx(Workspace, { ...props })
+	});
+}
+function Workspace({ appSlug, panels, apiRef, children }) {
+	const byId = useMemo(() => new Map(panels.map((panel) => [panel.id, panel])), [panels]);
+	const [layout, setLayout] = useState(() => loadLayout(appSlug, new Set(byId.keys())));
+	const viewport = useViewport();
+	const narrow = useNarrow();
+	const [snap, setSnap] = useState(null);
+	useEffect(() => saveLayout(appSlug, layout), [appSlug, layout]);
+	const { reserve, rects } = useMemo(() => pinGeometry(layout, viewport), [layout, viewport]);
+	const { left, right, bottom } = narrow ? {
+		left: 0,
+		right: 0,
+		bottom: 0
+	} : reserve;
+	useLayoutEffect(() => reservePageSpace({
+		left,
+		right,
+		bottom
+	}), [
+		left,
+		right,
+		bottom
+	]);
+	const api = useMemo(() => ({
+		panels,
+		isOpen: (id) => !layout.hidden && layout.open.includes(id),
+		open: (id) => setLayout((l) => openPanel(l, id, defaultPosition(l.open.length))),
+		close: (id) => setLayout((l) => closePanel(l, id)),
+		toggle: (id) => setLayout((l) => !l.hidden && l.open.includes(id) ? closePanel(l, id) : openPanel(l, id, defaultPosition(l.open.length))),
+		pin: (id, edge) => setLayout((l) => pinPanel(l, id, edge))
+	}), [panels, layout]);
+	useLayoutEffect(() => {
+		if (!apiRef) return;
+		apiRef.current = api;
+		return () => {
+			apiRef.current = null;
+		};
+	}, [apiRef, api]);
+	useRegisterCommands(useMemo(() => [{
+		id: "hud.toggle-layout",
+		title: "Toggle layout",
+		shortcut: "mod+shift+h",
+		run: () => setLayout((l) => toggleLayout(l, panels[0]?.id, defaultPosition(l.open.length)))
+	}, {
+		id: "hud.reset-layout",
+		title: "Reset layout",
+		run: () => setLayout(EMPTY_LAYOUT)
+	}], [panels]));
+	const zOrder = visiblePanels(layout);
+	const visible = panels.filter((panel) => zOrder.includes(panel.id));
+	const active = byId.get(zOrder.at(-1) ?? "");
+	const controls = (id) => ({
+		id,
+		pinned: narrow ? null : layout.pins[id] ?? null,
+		narrow,
+		pin: (edge) => api.pin(id, edge),
+		close: () => api.close(id)
+	});
+	const snapRect = snap ? pinGeometry(pinPanel(layout, snap.id, snap.edge), viewport).rects[snap.id] : void 0;
+	const offsets = {
+		"--hud-reserve-left": `${left}px`,
+		"--hud-reserve-bottom": `${bottom}px`
+	};
+	return /* @__PURE__ */ jsx(PanelsContext.Provider, {
+		value: api,
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "hud-layout",
+			style: offsets,
+			children: [
+				children,
+				narrow ? active && /* @__PURE__ */ jsx(PanelSheet, {
+					panels: visible,
+					active,
+					onSelect: (id) => setLayout((l) => focusPanel(l, id)),
+					onClose: api.close,
+					children: active.render(controls(active.id))
+				}) : visible.map((panel) => {
+					const edge = layout.pins[panel.id];
+					const rect = rects[panel.id];
+					return /* @__PURE__ */ jsx(PanelFrame, {
+						title: panel.title,
+						z: zOrder.indexOf(panel.id) + 1,
+						viewport,
+						position: layout.floats[panel.id] ?? defaultPosition(0),
+						pinned: edge && rect ? {
+							edge,
+							rect
+						} : null,
+						onFocus: () => setLayout((l) => focusPanel(l, panel.id)),
+						onClose: () => api.close(panel.id),
+						onMove: (pos) => setLayout((l) => movePanel(l, panel.id, pos)),
+						onPin: (next) => api.pin(panel.id, next),
+						onSnapPreview: (next) => setSnap(next ? {
+							id: panel.id,
+							edge: next
+						} : null),
+						children: panel.render(controls(panel.id))
+					}, panel.id);
+				}),
+				snapRect && /* @__PURE__ */ jsx("div", {
+					className: "snap-zone",
+					style: snapRect
+				})
+			]
+		})
+	});
+}
+//#endregion
+//#region src/shell/panels/pill-menu.tsx
+/** The pill's "⋯" menu: every panel, every command with its shortcut, and Reset layout. */
+function PillMenu() {
+	const panels = usePanels();
+	const commands = useCommands();
+	const apple = useMemo(isApplePlatform, []);
+	const [open, setOpen] = useState(false);
+	const ref = useRef(null);
+	useEffect(() => {
+		if (!open) return;
+		const onPointerDown = (e) => {
+			if (ref.current && !e.composedPath().includes(ref.current)) setOpen(false);
+		};
+		const onKeyDown = (e) => {
+			if (e.key === "Escape") setOpen(false);
+		};
+		window.addEventListener("pointerdown", onPointerDown, true);
+		window.addEventListener("keydown", onKeyDown, true);
+		return () => {
+			window.removeEventListener("pointerdown", onPointerDown, true);
+			window.removeEventListener("keydown", onKeyDown, true);
+		};
+	}, [open]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "menu-anchor",
+		ref,
+		children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: "pill-item",
+			"aria-label": "HUD menu",
+			"aria-haspopup": "menu",
+			"aria-expanded": open,
+			onClick: () => setOpen((o) => !o),
+			children: "⋯"
+		}), open && /* @__PURE__ */ jsxs("div", {
+			className: "menu",
+			role: "menu",
+			"aria-label": "HUD menu",
+			children: [
+				/* @__PURE__ */ jsx("div", {
+					className: "menu-label",
+					children: "Panels"
+				}),
+				panels.panels.map((panel) => /* @__PURE__ */ jsxs("button", {
+					type: "button",
+					role: "menuitemcheckbox",
+					className: "menu-item",
+					"aria-checked": panels.isOpen(panel.id),
+					onClick: () => panels.toggle(panel.id),
+					children: [/* @__PURE__ */ jsx("span", { children: panel.title }), /* @__PURE__ */ jsx("span", {
+						className: "menu-check",
+						children: panels.isOpen(panel.id) ? "✓" : ""
+					})]
+				}, panel.id)),
+				/* @__PURE__ */ jsx("div", {
+					className: "menu-label",
+					children: "Commands"
+				}),
+				commands.map((command) => /* @__PURE__ */ jsxs("button", {
+					type: "button",
+					role: "menuitem",
+					className: "menu-item",
+					onClick: () => {
+						setOpen(false);
+						command.run();
+					},
+					children: [/* @__PURE__ */ jsx("span", { children: command.title }), command.shortcut && /* @__PURE__ */ jsx("kbd", { children: formatShortcut(parseShortcut(command.shortcut), apple) })]
+				}, command.id))
+			]
+		})]
+	});
+}
+//#endregion
+//#region src/shell/panels/styles.ts
+/**
+* Panel manager styles, appended to `HUD_CSS` inside the same shadow root and
+* built on its `--hud-*` tokens.
+*/
+const PANEL_CSS = `
+.hud-layout { display: contents; }
+
+/* Pinned panels push the page; the pill moves with it so it stays visible. */
+.pill {
+  left: calc(12px + var(--hud-reserve-left, 0px));
+  bottom: calc(12px + var(--hud-reserve-bottom, 0px));
+}
+
+.menu-anchor { position: relative; display: flex; }
+
+.menu {
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 8px);
+  display: flex;
+  flex-direction: column;
+  min-width: 220px;
+  padding: 4px;
+  background: var(--hud-bg);
+  border: 1px solid var(--hud-border);
+  border-radius: var(--hud-radius);
+  box-shadow: var(--hud-shadow);
+  font-family: var(--hud-font);
+}
+
+.menu-label {
+  padding: 6px 8px 2px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--hud-fg-muted);
+}
+
+.hud .menu-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 4px 8px;
+  border-radius: 4px;
+  text-align: left;
+}
+
+.hud .menu-item:hover { background: var(--hud-bg-subtle); }
+.menu-check { color: var(--hud-accent); }
+.menu kbd { font-family: var(--hud-mono); font-size: 11px; color: var(--hud-fg-muted); }
+
+.panel {
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  min-width: 240px;
+  max-width: min(420px, calc(100vw - 24px));
+  max-height: calc(100vh - 24px);
+  background: var(--hud-bg);
+  border: 1px solid var(--hud-border);
+  border-radius: var(--hud-radius);
+  box-shadow: var(--hud-shadow);
+  pointer-events: auto;
+  overflow: hidden;
+}
+
+.panel[data-pin] {
+  min-width: 0;
+  max-width: none;
+  max-height: none;
+  border-radius: 0;
+  box-shadow: none;
+}
+
+.panel-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 6px 6px 6px 10px;
+  border-bottom: 1px solid var(--hud-border);
+  background: var(--hud-bg-subtle);
+  cursor: grab;
+  user-select: none;
+  touch-action: none;
+}
+
+.panel-bar:active { cursor: grabbing; }
+.panel[data-pin] .panel-bar { cursor: default; }
+.panel-title { font-weight: 600; }
+.panel-actions { display: flex; gap: 2px; }
+.hud .panel-action {
+  width: 20px;
+  height: 20px;
+  border-radius: 4px;
+  color: var(--hud-fg-muted);
+  line-height: 20px;
+  text-align: center;
+}
+.hud .panel-action:hover { background: var(--hud-border); color: var(--hud-fg); }
+.panel-body { flex: 1; padding: 8px 10px; overflow: auto; }
+
+.snap-zone {
+  position: fixed;
+  z-index: 1000;
+  background: color-mix(in srgb, var(--hud-accent) 18%, transparent);
+  border: 2px dashed var(--hud-accent);
+  pointer-events: none;
+}
+
+.sheet {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  max-height: 60vh;
+  background: var(--hud-bg);
+  border-top: 1px solid var(--hud-border);
+  border-radius: var(--hud-radius) var(--hud-radius) 0 0;
+  box-shadow: var(--hud-shadow);
+  pointer-events: auto;
+}
+
+.sheet-bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 6px;
+  border-bottom: 1px solid var(--hud-border);
+  background: var(--hud-bg-subtle);
+  border-radius: var(--hud-radius) var(--hud-radius) 0 0;
+}
+
+.sheet-tabs { display: flex; flex: 1; gap: 2px; overflow-x: auto; }
+.hud .sheet-tab { padding: 4px 10px; border-radius: 4px; white-space: nowrap; color: var(--hud-fg-muted); }
+.hud .sheet-tab[aria-selected="true"] { background: var(--hud-bg); color: var(--hud-fg); font-weight: 600; }
+`;
+//#endregion
+//#region src/shell/plugin-slots.tsx
+/** One stable context per plugin, so panels and pills can depend on `ctx` in effects. */
+function usePluginSlots(plugins, { app, apiBase, can, close, pin }) {
+	return useMemo(() => plugins.map((plugin) => ({
+		plugin,
+		title: plugin.title ?? plugin.id,
+		ctx: createPluginContext(plugin, {
+			app,
+			apiBase,
+			can,
+			close: () => close(plugin.id),
+			pin: (edge) => pin(plugin.id, edge)
+		})
+	})), [
+		plugins,
+		app,
+		apiBase,
+		can,
+		close,
+		pin
+	]);
+}
+/**
+* A plugin's pill item. With a panel it is a toggle button; without one it
+* only shows the plugin's `pill` content.
+*/
+function PluginPillItem({ slot, open, onToggle }) {
+	const { plugin, ctx, title } = slot;
+	const Pill = plugin.pill;
+	const content = Pill ? /* @__PURE__ */ jsx(Pill, { ctx }) : title;
+	if (!plugin.panel) return Pill ? /* @__PURE__ */ jsx("span", {
+		className: "pill-item",
+		children: content
+	}) : null;
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		className: "pill-item",
+		"aria-pressed": open,
+		title,
+		onClick: onToggle,
+		children: content
+	});
+}
+function PluginPanelBody({ slot }) {
+	const Panel = slot.plugin.panel;
+	return Panel ? /* @__PURE__ */ jsx(Panel, { ctx: slot.ctx }) : null;
+}
+//#endregion
+//#region src/core/marker.ts
+/**
+* Literal a consumer's CI bundle gate greps for in production client chunks.
+* It is rendered as an attribute on the HUD root, so a bundler cannot drop it
+* while keeping the HUD, and it is unmistakably deliberate rather than an
+* incidental string a refactor could rename away.
+*/
+const HUD_DEV_MARKER = "__HANSENEXUS_HUD_DEV__";
+/** Tag name of the element that hosts the HUD's shadow root. */
+const HUD_HOST_TAG = "hn-hud";
+//#endregion
 //#region src/shell/shadow-host.tsx
 /**
 * Inline `!important` on the host element: author `!important` in a host
@@ -211,14 +1000,8 @@ function ShadowHost({ css, children }) {
 	return mount ? createPortal(children, mount) : null;
 }
 //#endregion
-//#region src/shell/styles.ts
-/**
-* The HUD's whole stylesheet. It lives inside the shadow root, so host
-* selectors cannot reach in and these rules cannot leak out. Inherited
-* properties (font, color, line-height) still cross the shadow boundary, which
-* is what `all: initial` on the root resets.
-*/
-const HUD_CSS = `
+//#region src/shell/hud.tsx
+const CSS = `
 .hud {
   all: initial;
   --hud-bg: #ffffff;
@@ -286,7 +1069,7 @@ const HUD_CSS = `
   pointer-events: auto;
 }
 
-.pill-item {
+.hud .pill-item {
   display: flex;
   align-items: center;
   gap: 6px;
@@ -304,96 +1087,112 @@ const HUD_CSS = `
 .dot[data-rating="needs-improvement"] { background: var(--hud-warn); }
 .dot[data-rating="poor"] { background: var(--hud-poor); }
 
-.panel {
-  position: fixed;
-  display: flex;
-  flex-direction: column;
-  min-width: 240px;
-  max-width: min(420px, calc(100vw - 24px));
-  max-height: calc(100vh - 24px);
-  background: var(--hud-bg);
-  border: 1px solid var(--hud-border);
-  border-radius: var(--hud-radius);
-  box-shadow: var(--hud-shadow);
-  pointer-events: auto;
-  overflow: hidden;
-}
-
-.panel-bar {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 8px;
-  padding: 6px 8px 6px 10px;
-  border-bottom: 1px solid var(--hud-border);
-  background: var(--hud-bg-subtle);
-  cursor: grab;
-  user-select: none;
-  touch-action: none;
-}
-
-.panel-bar:active { cursor: grabbing; }
-.panel-title { font-weight: 600; }
-.panel-close { width: 20px; height: 20px; border-radius: 4px; color: var(--hud-fg-muted); }
-.panel-close:hover { background: var(--hud-border); color: var(--hud-fg); }
-.panel-body { padding: 8px 10px; overflow: auto; }
-
 .vitals { width: 100%; border-collapse: collapse; font-family: var(--hud-mono); }
 .vitals td { padding: 3px 0; }
 .vitals td:last-child { text-align: right; }
 .vitals .label { color: var(--hud-fg-muted); }
 .empty { color: var(--hud-fg-muted); }
-`;
-//#endregion
-//#region src/shell/hud.tsx
+` + PANEL_CSS;
+const NO_PLUGINS = [];
+const GRANT_ALL = () => true;
 /**
 * The HUD shell: a shadow-rooted status pill and floating panels.
 *
 * It renders unconditionally. Keeping it out of production builds is the
 * loader's job, at the import site, so a bundler can drop the whole module
-* (see the Next adapter, hud#4).
+* (see `@hansenexus/hud/next`).
 */
-function Hud({ appSlug, envLabel = "DEV" }) {
-	useEffect(() => {
-		startVitals();
-	}, []);
+function Hud({ appSlug, envLabel = "DEV", plugins = NO_PLUGINS, apiBase = "/api/hud", can = GRANT_ALL }) {
+	const resolved = useMemo(() => resolvePlugins(plugins, can), [plugins, can]);
 	return /* @__PURE__ */ jsx(ShadowHost, {
-		css: HUD_CSS,
+		css: CSS,
 		children: /* @__PURE__ */ jsx(Shell, {
 			appSlug,
-			envLabel
+			envLabel,
+			plugins: resolved,
+			apiBase,
+			can
+		})
+	});
+}
+function Shell({ appSlug, envLabel, plugins, apiBase, can }) {
+	const panelsRef = useRef(null);
+	const slots = usePluginSlots(plugins, {
+		app: appSlug,
+		apiBase,
+		can,
+		close: useCallback((id) => panelsRef.current?.close(id), []),
+		pin: useCallback((id, edge) => panelsRef.current?.pin(id, edge), [])
+	});
+	const panels = useMemo(() => slots.filter((slot) => slot.plugin.panel).map((slot) => ({
+		id: slot.plugin.id,
+		title: slot.title,
+		render: () => /* @__PURE__ */ jsx(PluginPanelBody, { slot })
+	})), [slots]);
+	const commands = useMemo(() => slots.flatMap(({ plugin, ctx }) => (plugin.commands ?? []).map((command) => ({
+		id: `${plugin.id}.${command.id}`,
+		title: command.title,
+		shortcut: command.shortcut,
+		run: () => command.run(ctx)
+	}))), [slots]);
+	return /* @__PURE__ */ jsx(PanelManager, {
+		appSlug,
+		panels,
+		commands,
+		apiRef: panelsRef,
+		children: /* @__PURE__ */ jsx(Pill, {
+			appSlug,
+			envLabel,
+			slots
 		})
 	});
 }
-function Shell({ appSlug, envLabel }) {
-	const [vitalsOpen, setVitalsOpen] = useState(false);
-	const lcp = useVitals().LCP;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("div", {
+function Pill({ appSlug, envLabel, slots }) {
+	const panels = usePanels();
+	return /* @__PURE__ */ jsxs("div", {
 		className: "pill",
 		role: "toolbar",
 		"aria-label": `${appSlug} hud`,
-		children: [/* @__PURE__ */ jsx("span", {
-			className: "pill-item env",
-			children: envLabel
-		}), /* @__PURE__ */ jsxs("button", {
-			type: "button",
-			className: "pill-item",
-			"aria-pressed": vitalsOpen,
-			onClick: () => setVitalsOpen((open) => !open),
-			children: [/* @__PURE__ */ jsx("span", {
-				className: "dot",
-				"data-rating": lcp?.rating
-			}), lcp ? `LCP ${formatVital("LCP", lcp.value)}` : "LCP –"]
-		})]
-	}), vitalsOpen && /* @__PURE__ */ jsx(FloatingPanel, {
-		title: "Vitals",
-		initial: {
-			x: 12,
-			y: Math.max(12, window.innerHeight - 260)
-		},
-		onClose: () => setVitalsOpen(false),
-		children: /* @__PURE__ */ jsx(VitalsPanel, {})
-	})] });
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "pill-item env",
+				children: envLabel
+			}),
+			slots.map((slot) => /* @__PURE__ */ jsx(PluginPillItem, {
+				slot,
+				open: panels.isOpen(slot.plugin.id),
+				onToggle: () => panels.toggle(slot.plugin.id)
+			}, slot.plugin.id)),
+			/* @__PURE__ */ jsx(PillMenu, {})
+		]
+	});
+}
+//#endregion
+//#region src/core/define-hud.tsx
+/**
+* The app's one HUD file:
+*
+* ```tsx
+* export default defineHud({ app: "hansenexus", plugins: [vitals()] });
+* ```
+*
+* Returns a component. The plugin list is frozen here, so the shell sees a
+* stable array across renders.
+*/
+function defineHud({ app, plugins, apiBase, can }) {
+	resolvePlugins(plugins, () => true);
+	const list = Object.freeze([...plugins]);
+	function DefinedHud({ envLabel }) {
+		return /* @__PURE__ */ jsx(Hud, {
+			appSlug: app,
+			plugins: list,
+			...envLabel === void 0 ? {} : { envLabel },
+			...apiBase === void 0 ? {} : { apiBase },
+			...can === void 0 ? {} : { can }
+		});
+	}
+	DefinedHud.displayName = `Hud(${app})`;
+	return DefinedHud;
 }
 //#endregion
-export { HUD_DEV_MARKER, HUD_HOST_TAG, Hud };
+export { HUD_DEV_MARKER, HUD_HOST_TAG, Hud, HudApiError, defineHud, definePlugin };