@hansenexus/hud 0.3.0 → 0.4.0

package/dist/styles--slk86ZQ.js

@@ -0,0 +1,332 @@
+import { n as HUD_HOST_TAG } from "./marker-uZYPOJ4M.js";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+//#region src/core/grabber/picker.tsx
+/**
+* Styles for the picker overlay. The picker renders where it is mounted, so
+* the caller puts these into the same (shadow) root. Colours fall back when
+* the `--hud-*` tokens are absent.
+*/
+const PICKER_CSS = `
+.grab-layer { position: fixed; inset: 0; pointer-events: none; }
+.grab-hint {
+  position: fixed;
+  top: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  padding: 3px 12px;
+  border-radius: 0 0 6px 6px;
+  white-space: nowrap;
+  background: var(--hud-accent, #0369a1);
+  color: var(--hud-accent-fg, #ffffff);
+  font: 600 11px/1.5 var(--hud-mono, ui-monospace, monospace);
+}
+.grab-outline {
+  position: fixed;
+  border: 1.5px solid var(--hud-accent, #0369a1);
+  background: color-mix(in srgb, var(--hud-accent, #0369a1) 8%, transparent);
+  border-radius: 3px;
+}
+.grab-label {
+  position: fixed;
+  max-width: min(480px, calc(100vw - 8px));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 1px 6px;
+  border-radius: 3px;
+  background: var(--hud-accent, #0369a1);
+  color: var(--hud-accent-fg, #ffffff);
+  font: 600 10px/1.6 var(--hud-mono, ui-monospace, monospace);
+}
+`;
+/**
+* Host pages set `cursor` on buttons and links, which beats an inherited
+* crosshair, so grab mode briefly adds one global rule to the document.
+*/
+const CURSOR_RULE = "*, *::before, *::after { cursor: crosshair !important; }";
+/** Pointer events the page must not see while picking: they would focus, submit or navigate. */
+const SWALLOWED = [
+	"pointerdown",
+	"mousedown",
+	"pointerup",
+	"mouseup",
+	"dblclick"
+];
+function describeTag(element) {
+	return element.tagName.toLowerCase();
+}
+/**
+* Click-to-pick controller: crosshair, hover outline with a label, the next
+* click picks, Escape cancels. Events inside the picker's own shadow host
+* (the HUD's pill and panels) pass through untouched, so panels stay usable
+* and mounted during a grab.
+*/
+function ElementPicker({ active, onPick, onCancel, hint = "Click an element · Esc cancels", describe = describeTag, ignore }) {
+	const layer = useRef(null);
+	const [highlight, setHighlight] = useState(null);
+	const props = useRef({
+		onPick,
+		onCancel,
+		describe,
+		ignore
+	});
+	props.current = {
+		onPick,
+		onCancel,
+		describe,
+		ignore
+	};
+	useEffect(() => {
+		if (!active) {
+			setHighlight(null);
+			return;
+		}
+		const root = layer.current?.getRootNode();
+		const ownHost = root instanceof ShadowRoot ? root.host : null;
+		const doc = layer.current?.ownerDocument ?? document;
+		let hovered = null;
+		function target(event) {
+			const path = event.composedPath();
+			if (ownHost && path.includes(ownHost)) return null;
+			const el = path[0];
+			if (!(el instanceof Element)) return null;
+			if (el === doc.documentElement || el === doc.body) return null;
+			return props.current.ignore?.(el) ? null : el;
+		}
+		function measure() {
+			if (!hovered?.isConnected) {
+				setHighlight(null);
+				return;
+			}
+			const r = hovered.getBoundingClientRect();
+			setHighlight({
+				left: r.left,
+				top: r.top,
+				width: r.width,
+				height: r.height,
+				label: props.current.describe(hovered)
+			});
+		}
+		function onMove(event) {
+			const el = target(event);
+			if (el === hovered) return;
+			hovered = el;
+			measure();
+		}
+		function swallow(event) {
+			if (!target(event)) return;
+			event.preventDefault();
+			event.stopPropagation();
+		}
+		function onClick(event) {
+			const el = target(event);
+			if (!el) return;
+			event.preventDefault();
+			event.stopPropagation();
+			props.current.onPick(el, {
+				clientX: event.clientX,
+				clientY: event.clientY
+			});
+		}
+		function onKey(event) {
+			if (event.key !== "Escape") return;
+			event.preventDefault();
+			event.stopPropagation();
+			props.current.onCancel();
+		}
+		const cursor = doc.createElement("style");
+		cursor.textContent = CURSOR_RULE;
+		doc.head.appendChild(cursor);
+		const win = doc.defaultView ?? window;
+		doc.addEventListener("pointermove", onMove, true);
+		doc.addEventListener("click", onClick, true);
+		for (const type of SWALLOWED) doc.addEventListener(type, swallow, true);
+		win.addEventListener("keydown", onKey, true);
+		win.addEventListener("scroll", measure, true);
+		win.addEventListener("resize", measure);
+		return () => {
+			cursor.remove();
+			doc.removeEventListener("pointermove", onMove, true);
+			doc.removeEventListener("click", onClick, true);
+			for (const type of SWALLOWED) doc.removeEventListener(type, swallow, true);
+			win.removeEventListener("keydown", onKey, true);
+			win.removeEventListener("scroll", measure, true);
+			win.removeEventListener("resize", measure);
+			setHighlight(null);
+		};
+	}, [active]);
+	return /* @__PURE__ */ jsxs("div", {
+		ref: layer,
+		className: "grab-layer",
+		hidden: !active,
+		children: [active && /* @__PURE__ */ jsx("div", {
+			className: "grab-hint",
+			role: "status",
+			children: hint
+		}), active && highlight && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
+			className: "grab-outline",
+			style: {
+				left: highlight.left - 2,
+				top: highlight.top - 2,
+				width: highlight.width + 4,
+				height: highlight.height + 4
+			}
+		}), /* @__PURE__ */ jsx("div", {
+			className: "grab-label",
+			style: {
+				left: Math.max(highlight.left - 2, 4),
+				top: highlight.top >= 22 ? highlight.top - 20 : highlight.top + highlight.height + 4
+			},
+			children: highlight.label
+		})] })]
+	});
+}
+//#endregion
+//#region src/shell/shadow-host.tsx
+/**
+* Inline `!important` on the host element: author `!important` in a host
+* stylesheet (`* { position: static !important }`) loses to inline
+* `!important`, so this is the one set of rules a client site cannot override.
+* The host covers the viewport but lets every click through; HUD surfaces opt
+* back in with `pointer-events: auto`.
+*/
+const HOST_STYLE = {
+	all: "initial",
+	position: "fixed",
+	inset: "0",
+	"z-index": "2147483000",
+	"pointer-events": "none",
+	display: "block"
+};
+/**
+* Renders children into a shadow root on a host element appended to <body>.
+* Mounted in an effect, so server rendering emits nothing and hydration never
+* differs.
+*/
+function ShadowHost({ css, marker, children }) {
+	const [mount, setMount] = useState(null);
+	useLayoutEffect(() => {
+		const host = document.createElement(HUD_HOST_TAG);
+		for (const [prop, value] of Object.entries(HOST_STYLE)) host.style.setProperty(prop, value, "important");
+		const shadow = host.attachShadow({ mode: "open" });
+		const style = document.createElement("style");
+		style.textContent = css;
+		const root = document.createElement("div");
+		root.className = "hud";
+		root.setAttribute("data-hud-marker", marker);
+		shadow.append(style, root);
+		document.body.appendChild(host);
+		setMount(root);
+		return () => {
+			host.remove();
+			setMount(null);
+		};
+	}, [css, marker]);
+	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 = `
+.hud {
+  all: initial;
+  --hud-bg: #ffffff;
+  --hud-bg-subtle: #f4f4f5;
+  --hud-fg: #18181b;
+  --hud-fg-muted: #71717a;
+  --hud-border: rgba(24, 24, 27, 0.14);
+  --hud-accent: #0369a1;
+  --hud-accent-fg: #ffffff;
+  --hud-good: #15803d;
+  --hud-warn: #b45309;
+  --hud-poor: #b91c1c;
+  --hud-shadow: 0 8px 24px rgba(0, 0, 0, 0.12), 0 2px 6px rgba(0, 0, 0, 0.08);
+  --hud-radius: 8px;
+  --hud-font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --hud-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+  font-family: var(--hud-font);
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--hud-fg);
+}
+
+@media (prefers-color-scheme: dark) {
+  .hud {
+    --hud-bg: #18181b;
+    --hud-bg-subtle: #27272a;
+    --hud-fg: #f4f4f5;
+    --hud-fg-muted: #a1a1aa;
+    --hud-border: rgba(244, 244, 245, 0.16);
+    --hud-accent: #38bdf8;
+    --hud-accent-fg: #082f49;
+    --hud-good: #4ade80;
+    --hud-warn: #fbbf24;
+    --hud-poor: #f87171;
+    --hud-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
+  }
+}
+
+.hud *, .hud *::before, .hud *::after { box-sizing: border-box; }
+
+.hud button {
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: 0;
+  margin: 0;
+  padding: 0;
+  cursor: pointer;
+}
+
+.hud :focus-visible { outline: 2px solid var(--hud-accent); outline-offset: 1px; }
+
+.pill {
+  position: fixed;
+  left: 12px;
+  bottom: 12px;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background: var(--hud-bg);
+  border: 1px solid var(--hud-border);
+  border-radius: 999px;
+  box-shadow: var(--hud-shadow);
+  font-family: var(--hud-mono);
+  pointer-events: auto;
+}
+
+.hud .pill-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  white-space: nowrap;
+}
+
+.pill-item:hover, .pill-item[aria-pressed="true"] { background: var(--hud-bg-subtle); }
+
+.env { font-weight: 600; color: var(--hud-accent); }
+
+.dot { width: 6px; height: 6px; border-radius: 50%; background: var(--hud-fg-muted); }
+.dot[data-rating="good"] { background: var(--hud-good); }
+.dot[data-rating="needs-improvement"] { background: var(--hud-warn); }
+.dot[data-rating="poor"] { background: var(--hud-poor); }
+
+.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
+export { PICKER_CSS as i, ShadowHost as n, ElementPicker as r, HUD_CSS as t };

package/dist/types-DADBRiGk.d.ts

@@ -0,0 +1,50 @@
+import { r as GrabPayload, t as ComponentHint } from "./payload-CLKDVZWl.js";
+//#region src/plugins/agent/types.d.ts
+/** Wire types shared by the agent plugins' client and server halves. */
+/** One dispatch target as `GET <apiBase>/agent-dispatch/targets` lists it. */
+interface DispatchTargetInfo {
+  id: string;
+  label: string;
+  description?: string;
+  available: boolean;
+  /** Why the target is unavailable, e.g. "no Hermes token configured". */
+  reason?: string;
+}
+/** `POST <apiBase>/agent-dispatch/dispatch`. Needs a `note`, a `payload`, or both. */
+interface DispatchBody {
+  target: string;
+  note: string;
+  payload: GrabPayload | null;
+  /** Component-manifest matches for the payload, see `matchComponentHints`. */
+  hints?: ComponentHint[];
+}
+interface DispatchReceipt {
+  ok: boolean;
+  target: string;
+  runId?: string;
+  /** Provider detail, e.g. the log file of a local run. */
+  detail?: string;
+  error?: string;
+}
+type AgentSessionStatus = "queued" | "running" | "idle" | "done" | "failed";
+interface AgentSession {
+  /** Provider id, e.g. `claude-code` or `hermes`. */
+  provider: string;
+  id: string;
+  title: string;
+  status: AgentSessionStatus;
+  startedAt?: string;
+  updatedAt?: string;
+  detail?: string;
+}
+/** `GET <apiBase>/agent-sessions/sessions`: every provider's sessions, newest first. */
+interface SessionsResponse {
+  sessions: AgentSession[];
+  /** Providers that failed to answer; the others still list. */
+  errors: {
+    provider: string;
+    error: string;
+  }[];
+}
+//#endregion
+export { DispatchTargetInfo as a, DispatchReceipt as i, AgentSessionStatus as n, SessionsResponse as o, DispatchBody as r, AgentSession as t };

package/dist/types-QJUajwWq.js

@@ -0,0 +1,35 @@
+//#region src/plugins/ops/meta.ts
+const OPS_CAPABILITY = "cicd.read";
+//#endregion
+//#region src/plugins/ops/state.ts
+/**
+* Combines the states of one commit's runs: any failure fails it, anything
+* still going keeps it running, and it only passes when something passed.
+*/
+function combineStates(states) {
+	if (states.length === 0) return null;
+	if (states.includes("failure")) return "failure";
+	if (states.includes("running")) return "running";
+	if (states.includes("queued")) return "queued";
+	if (states.includes("cancelled")) return "cancelled";
+	return states.includes("success") ? "success" : "neutral";
+}
+/** Maps a state onto the shell's `.dot[data-rating]` colours. */
+function stateRating(state) {
+	switch (state) {
+		case "success": return "good";
+		case "running":
+		case "queued": return "needs-improvement";
+		case "failure": return "poor";
+		default: return;
+	}
+}
+//#endregion
+//#region src/plugins/ops/types.ts
+const TELEMETRY_RANGES = [
+	"1h",
+	"24h",
+	"7d"
+];
+//#endregion
+export { OPS_CAPABILITY as i, combineStates as n, stateRating as r, TELEMETRY_RANGES as t };

package/dist/types-f3jlNxzw.d.ts

@@ -0,0 +1,92 @@
+//#region src/plugins/ops/types.d.ts
+/**
+ * Provider seams of the `ops` plugin and the JSON its routes answer with.
+ * Type-only, so the client half can share them without pulling in a provider.
+ */
+/** Normalised run outcome, whatever the CI provider calls it. */
+type CiState = "success" | "failure" | "cancelled" | "running" | "queued" | "neutral";
+interface CiRun {
+  id: string;
+  /** Workflow or pipeline name. */
+  name: string;
+  /** First line of the commit message, or the run name. */
+  title: string;
+  state: CiState;
+  branch?: string;
+  /** Short commit sha. */
+  sha?: string;
+  url?: string;
+  /** ISO timestamp. */
+  startedAt?: string;
+}
+/** What is deployed right now, for providers that know. */
+interface CiDeployment {
+  /** Environment name, such as `production`. */
+  environment?: string;
+  /** Deployed image reference, if the deploy is an image. */
+  image?: string;
+  sha?: string;
+  /** Ready replicas as `ready/desired`, or a provider's own status text. */
+  ready?: string;
+  url?: string;
+  /** ISO timestamp. */
+  at?: string;
+}
+interface CiSnapshot {
+  /** Provider name, such as `github-actions`. */
+  provider: string;
+  /** False when the provider's env is incomplete; `missing` names what to set. */
+  configured: boolean;
+  missing?: string;
+  /** Repository or project the runs belong to. */
+  repo: string;
+  /** Branch the runs were filtered by; null when it could not be resolved. */
+  branch: string | null;
+  /** Combined state of the latest commit's runs on `branch`; null without runs. */
+  state: CiState | null;
+  /** Short sha of the commit `state` describes. */
+  sha: string | null;
+  /** Newest first. */
+  runs: CiRun[];
+}
+/** A CI provider. Runs server side only; it may read tokens from env. */
+interface CiProvider {
+  readonly name: string;
+  snapshot(): Promise<CiSnapshot>;
+  /** Optional: current deployment. Null when nothing is deployed. */
+  deployment?(): Promise<CiDeployment | null>;
+}
+/** `GET <apiBase>/ops/ci` */
+interface CiResponse extends CiSnapshot {
+  ok: true;
+  /** Present when the provider implements `deployment`. */
+  deployment?: CiDeployment | null;
+}
+declare const TELEMETRY_RANGES: readonly ["1h", "24h", "7d"];
+type TelemetryRange = (typeof TELEMETRY_RANGES)[number];
+interface TelemetrySnapshot {
+  /** Provider name, such as `signoz`. */
+  provider: string;
+  /** False when the provider's env is incomplete; `missing` names what to set. */
+  configured: boolean;
+  missing?: string;
+  service: string;
+  range: TelemetryRange;
+  /** Errored calls per second, latest sample. */
+  errorRate: number | null;
+  /** 95th percentile latency in ms, latest sample. */
+  p95Ms: number | null;
+  /** Calls per second, latest sample. */
+  requestRate: number | null;
+}
+/** A telemetry provider. Runs server side only; it may read keys from env. */
+interface TelemetryProvider {
+  readonly name: string;
+  snapshot(range: TelemetryRange): Promise<TelemetrySnapshot>;
+}
+/** `GET <apiBase>/ops/telemetry?range=1h` */
+interface TelemetryResponse extends TelemetrySnapshot {
+  ok: true;
+}
+//#endregion
+export { CiSnapshot as a, TelemetryRange as c, CiRun as i, TelemetryResponse as l, CiProvider as n, CiState as o, CiResponse as r, TelemetryProvider as s, CiDeployment as t, TelemetrySnapshot as u };

package/dist/vitals-panel-Dvc5dnR-.js

@@ -0,0 +1,87 @@
+import { useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
+//#region src/plugins/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
+		}
+	};
+	for (const listener of listeners) listener();
+}
+/**
+* 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.
+*/
+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 {}
+}
+function getVitals() {
+	return snapshot;
+}
+function subscribeVitals(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+function useVitals() {
+	return useSyncExternalStore(subscribeVitals, getVitals, getVitals);
+}
+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`;
+}
+//#endregion
+//#region src/plugins/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)) })
+	});
+}
+//#endregion
+export { useVitals as i, formatVital as n, startVitals as r, VitalsPanel as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hansenexus/hud",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Modular dev HUD for React apps: status pill, floating panels, element grabber, plugin API.",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,8 @@
   },
   "workspaces": [
     ".",
-    "playground"
+    "playground",
+    "fixtures/next-app"
   ],
   "files": [
     "dist",
@@ -33,6 +34,18 @@
     "./plugins/*": {
       "types": "./dist/plugins/*.d.ts",
       "import": "./dist/plugins/*.js"
+    },
+    "./state-boundary": {
+      "types": "./dist/state-boundary.d.ts",
+      "import": "./dist/state-boundary.js"
+    },
+    "./review": {
+      "types": "./dist/review.d.ts",
+      "import": "./dist/review.js"
+    },
+    "./markers": {
+      "types": "./dist/markers.d.ts",
+      "import": "./dist/markers.js"
     }
   },
   "sideEffects": false,
@@ -54,7 +67,13 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "convex": "^1.43.0"
+  },
+  "peerDependenciesMeta": {
+    "convex": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
@@ -63,6 +82,7 @@
     "@testing-library/react": "^16.3.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
+    "convex": "^1.46.0",
     "jsdom": "^30.1.2",
     "rolldown": "^1.2.12",
     "tsdown": "^0.23.0",