@hansenexus/hud 0.1.1 → 0.2.0

package/README.md

@@ -1,47 +1,66 @@
 # @hansenexus/hud
 
-A dev HUD for React apps. It gives you a drawer with panels (vitals, network and console
-capture, env info, feature flags, forced UI states and more), and capability-gated access
-that stays observe-only in production.
+A dev HUD for React apps: a status pill and floating panels, rendered in a shadow root so a
+client site's CSS cannot touch it and it cannot touch the site.
+
+> Early. The plugin API, pinning, the element grabber and the Next adapter are tracked in
+> [the PRD](https://github.com/hansenexus/hud/issues/1).
+
+## Develop
+
+```sh
+bun install
+bun run dev      # playground on http://localhost:5173, HUD imported from source (HMR)
+bun run check    # lint, typecheck, test, build
+```
+
+The playground (`playground/`) is a fake client site with every element that has fought a dev
+tool for a corner: sticky nav, a fixed booking CTA, a chat launcher and a cookie banner, plus a
+deliberately hostile stylesheet. If the HUD changes when you edit `playground/src/site.css`, the
+isolation leaks.
 
 ## Install
 
 ```sh
-npm install @hansenexus/hud
+bun add -d @hansenexus/hud   # or npm i -D @hansenexus/hud
 ```
 
-The host provides the peers `react` and `react-dom` 19. `next` is optional: without Next,
-alias `next/link` to a plain anchor component in your bundler.
+Peer dependencies: `react` and `react-dom` 19. Nothing else: no Tailwind, no stylesheet to import,
+no host CSS assumptions. The HUD ships its own styles inside its shadow root.
 
 ## Use
 
 ```tsx
-import { Hud, type HudPanel, NetworkConsolePanel, VitalsPanel } from "@hansenexus/hud";
-import { Activity, Terminal } from "lucide-react";
-
-const panels: HudPanel[] = [
-  { id: "vitals", label: "Vitals", icon: Activity, capability: "observe.app", content: <VitalsPanel />, order: 1 },
-  { id: "net", label: "Net / Console", icon: Terminal, capability: "observe.app", content: <NetworkConsolePanel />, order: 2 },
-];
+import { Hud } from "@hansenexus/hud";
 
 export function DevHud() {
-  return <Hud config={{ appSlug: "my-app" }} panels={panels} />;
+  return <Hud appSlug="my-app" />;
 }
 ```
 
-Mount it only in development builds, for example behind `import.meta.env.DEV` and a lazy import.
+Mount it only in development builds, behind a check the bundler can fold (for example
+`process.env.NODE_ENV === "development"` around a lazy import), so production bundles carry no
+HUD code. `HUD_DEV_MARKER` is rendered on the HUD root for a CI grep.
 
-## Tailwind v4
+## Release
 
-The panels use Tailwind utilities, and Tailwind does not scan `node_modules` on its own. Add
-the package as a source in the stylesheet that imports Tailwind:
+Versions are driven by [Changesets](https://github.com/changesets/changesets). A PR that changes
+what the package ships adds one with `bun run changeset` (pre-1.0: `minor` for breaking changes,
+`patch` for the rest). On `main`, `.github/workflows/release.yml` gathers pending changesets into
+a "chore: version packages" PR. Merging that PR publishes the new version to npm over Trusted
+Publishing (GitHub OIDC, no `NPM_TOKEN`), tags `v<version>` and cuts a GitHub release from the
+CHANGELOG section. `Actions > Release > Run workflow` with `dry_run` runs the gate and
+`npm publish --dry-run` without publishing.
 
-```css
-@source "../node_modules/@hansenexus/hud";
-```
+Versions up to 0.1.1 were published from hn-monorepo; 0.2.0 is the first release from this repo.
+
+Provenance is off while the repo is private (npm refuses `--provenance` from a private source).
+When the repo goes public, set `NPM_PROVENANCE: "true"` in `release.yml`.
 
-The path is relative to that stylesheet. If a panel renders unstyled, this line is missing
-or points at the wrong place.
+**Owner step, once, needs npm 2FA:** npmjs.com → `@hansenexus/hud` → Settings → Trusted
+Publisher → GitHub Actions: organization `hansenexus`, repository `hud`, workflow `release.yml`.
+Do this before merging the first Version Packages PR. Keep the hn-monorepo publisher until
+hn-monorepo#2740 retires its old release workflow.
 
 ## License
 

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { Metric } from "web-vitals";
+//#region src/core/marker.d.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.
+ */
+export declare const HUD_DEV_MARKER = "__HANSENEXUS_HUD_DEV__";
+/** Tag name of the element that hosts the HUD's shadow root. */
+export declare const HUD_HOST_TAG = "hn-hud";
+//#endregion
+//#region src/shell/hud.d.ts
+interface HudProps {
+  /** App slug, used for labels now and for the layout storage key later. */
+  appSlug: string;
+  /** Badge shown at the start of the pill. Default "DEV". */
+  envLabel?: string;
+}
+/**
+ * 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).
+ */
+export declare function Hud({ appSlug, envLabel }: HudProps): import("react").JSX.Element;
+//#endregion
+//#region src/vitals/store.d.ts
+type VitalName = Metric["name"];
+type VitalRating = Metric["rating"];
+interface Vital {
+  name: VitalName;
+  value: number;
+  rating: VitalRating;
+}
+type VitalsSnapshot = Partial<Record<VitalName, Vital>>;
+//#endregion
+export type { HudProps, Vital, VitalName, VitalRating, VitalsSnapshot };

package/dist/index.js

@@ -0,0 +1,399 @@
+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 { 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";
+//#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
+		}
+	};
+	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/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
+//#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) {
+	return {
+		x: Math.min(Math.max(pos.x, GRIP - width), viewport.w - GRIP),
+		y: Math.min(Math.max(pos.y, 0), viewport.h - GRIP)
+	};
+}
+/**
+* A draggable panel. Pinning to an edge and persistence arrive with the panel
+* manager (hud#3); this is the single-window tracer.
+*/
+function FloatingPanel({ title, initial, onClose, children }) {
+	const [pos, setPos] = useState(initial);
+	const panelRef = useRef(null);
+	const drag = useRef(null);
+	const onPointerDown = useCallback((e) => {
+		if (e.target.closest("button")) return;
+		drag.current = {
+			dx: e.clientX - pos.x,
+			dy: e.clientY - pos.y
+		};
+		e.currentTarget.setPointerCapture(e.pointerId);
+	}, [pos]);
+	const onPointerMove = useCallback((e) => {
+		const d = drag.current;
+		if (!d) return;
+		const width = panelRef.current?.offsetWidth ?? 240;
+		setPos(clampPosition({
+			x: e.clientX - d.dx,
+			y: e.clientY - d.dy
+		}, width, {
+			w: window.innerWidth,
+			h: window.innerHeight
+		}));
+	}, []);
+	const onPointerUp = useCallback((e) => {
+		drag.current = null;
+		if (e.currentTarget.hasPointerCapture(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
+	}, []);
+	return /* @__PURE__ */ jsxs("section", {
+		ref: panelRef,
+		className: "panel",
+		"aria-label": title,
+		style: {
+			left: pos.x,
+			top: pos.y
+		},
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "panel-bar",
+			onPointerDown,
+			onPointerMove,
+			onPointerUp,
+			onPointerCancel: onPointerUp,
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "panel-title",
+				children: title
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "panel-close",
+				"aria-label": `Close ${title}`,
+				onClick: onClose,
+				children: "×"
+			})]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "panel-body",
+			children
+		})]
+	});
+}
+//#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, 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", HUD_DEV_MARKER);
+		shadow.append(style, root);
+		document.body.appendChild(host);
+		setMount(root);
+		return () => {
+			host.remove();
+			setMount(null);
+		};
+	}, [css]);
+	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-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-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;
+}
+
+.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); }
+
+.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
+/**
+* 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).
+*/
+function Hud({ appSlug, envLabel = "DEV" }) {
+	useEffect(() => {
+		startVitals();
+	}, []);
+	return /* @__PURE__ */ jsx(ShadowHost, {
+		css: HUD_CSS,
+		children: /* @__PURE__ */ jsx(Shell, {
+			appSlug,
+			envLabel
+		})
+	});
+}
+function Shell({ appSlug, envLabel }) {
+	const [vitalsOpen, setVitalsOpen] = useState(false);
+	const lcp = useVitals().LCP;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__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, {})
+	})] });
+}
+//#endregion
+export { HUD_DEV_MARKER, HUD_HOST_TAG, Hud };