@hansenexus/hud 0.2.0 → 0.3.0

package/dist/next.d.ts

@@ -0,0 +1,48 @@
+import { n as HudMountProps } from "./define-hud-BHQR8Lbv.js";
+import { ComponentType } from "react";
+//#region src/next/env.d.ts
+/**
+ * Where the HUD believes it runs. An explicit `NEXT_PUBLIC_HUD_ENV` wins over
+ * heuristics because k3s deploys have no `VERCEL_ENV`.
+ */
+type HudEnv = "development" | "preview" | "staging" | "production" | "disabled";
+/**
+ * Env ladder: kill switch → `NODE_ENV` (inlined by Next, so production
+ * bundles fold the development branch) → `NEXT_PUBLIC_HUD_ENV` (k8s overlays)
+ * → `VERCEL_ENV` → production.
+ *
+ * Each read is a literal `process.env.X` so Next can inline it in client code.
+ */
+export declare function resolveHudEnv(): HudEnv;
+export declare function hudEnvLabel(env?: HudEnv): string;
+//#endregion
+//#region src/next/loader.d.ts
+type HudModuleLoader = () => Promise<{
+  default: ComponentType<HudMountProps>;
+}>;
+/**
+ * Mounts the app's `defineHud` module, lazily and client side only.
+ *
+ * The build gate belongs in the consumer's file, as a literal expression
+ * around the `import()`:
+ *
+ * ```tsx
+ * "use client";
+ * import { createHudLoader } from "@hansenexus/hud/next";
+ *
+ * export const HudLoader = createHudLoader(
+ *   process.env.NODE_ENV === "development" || process.env.NEXT_PUBLIC_HUD_ENABLED === "true"
+ *     ? () => import("./hud")
+ *     : null
+ * );
+ * ```
+ *
+ * Next inlines both env reads, so a production build folds the ternary to
+ * `null` and emits no HUD chunk at all. A check inside this function could not
+ * do that: the `import()` would still sit in the consumer's module and the
+ * chunk would ship unreachable but readable (hn-monorepo#1283). Pass `null`
+ * and the loader renders nothing.
+ */
+export declare function createHudLoader(load: HudModuleLoader | null): ComponentType<HudMountProps>;
+//#endregion
+export type { HudEnv, HudModuleLoader, HudMountProps };

package/dist/next.js

@@ -0,0 +1,77 @@
+import { Suspense, lazy, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/next/env.ts
+/**
+* Env ladder: kill switch → `NODE_ENV` (inlined by Next, so production
+* bundles fold the development branch) → `NEXT_PUBLIC_HUD_ENV` (k8s overlays)
+* → `VERCEL_ENV` → production.
+*
+* Each read is a literal `process.env.X` so Next can inline it in client code.
+*/
+function resolveHudEnv() {
+	if (process.env.NEXT_PUBLIC_HUD_DISABLED === "true") return "disabled";
+	if (process.env.NODE_ENV === "development") return "development";
+	const explicit = process.env.NEXT_PUBLIC_HUD_ENV;
+	if (explicit === "staging" || explicit === "preview" || explicit === "production") return explicit;
+	if (process.env.VERCEL_ENV === "preview") return "preview";
+	return "production";
+}
+const LABELS = {
+	development: "DEV",
+	preview: "PREVIEW",
+	staging: "STAGING",
+	production: "PROD",
+	disabled: "OFF"
+};
+function hudEnvLabel(env = resolveHudEnv()) {
+	return LABELS[env];
+}
+//#endregion
+//#region src/next/loader.tsx
+/**
+* Mounts the app's `defineHud` module, lazily and client side only.
+*
+* The build gate belongs in the consumer's file, as a literal expression
+* around the `import()`:
+*
+* ```tsx
+* "use client";
+* import { createHudLoader } from "@hansenexus/hud/next";
+*
+* export const HudLoader = createHudLoader(
+*   process.env.NODE_ENV === "development" || process.env.NEXT_PUBLIC_HUD_ENABLED === "true"
+*     ? () => import("./hud")
+*     : null
+* );
+* ```
+*
+* Next inlines both env reads, so a production build folds the ternary to
+* `null` and emits no HUD chunk at all. A check inside this function could not
+* do that: the `import()` would still sit in the consumer's module and the
+* chunk would ship unreachable but readable (hn-monorepo#1283). Pass `null`
+* and the loader renders nothing.
+*/
+function createHudLoader(load) {
+	if (!load) return NoHud;
+	const LazyHud = lazy(load);
+	function HudLoader(props) {
+		const [mounted, setMounted] = useState(false);
+		useEffect(() => setMounted(true), []);
+		if (!mounted) return null;
+		const env = resolveHudEnv();
+		if (env === "disabled") return null;
+		return /* @__PURE__ */ jsx(Suspense, {
+			fallback: null,
+			children: /* @__PURE__ */ jsx(LazyHud, {
+				envLabel: hudEnvLabel(env),
+				...props
+			})
+		});
+	}
+	return HudLoader;
+}
+function NoHud(_props) {
+	return null;
+}
+//#endregion
+export { createHudLoader, hudEnvLabel, resolveHudEnv };

package/dist/plugins/vitals.d.ts

@@ -0,0 +1,25 @@
+import { Metric } from "web-vitals";
+//#region src/plugins/vitals/vitals-panel.d.ts
+declare function VitalsPanel(): import("react").JSX.Element;
+//#endregion
+//#region src/plugins/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
+//#region src/plugins/vitals/index.d.ts
+declare function VitalsPill(): import("react").JSX.Element;
+/** Core Web Vitals: LCP in the pill, all five metrics in the panel. Client only. */
+export declare function vitals(): {
+  readonly id: "vitals";
+  readonly title: "Vitals";
+  readonly pill: typeof VitalsPill;
+  readonly panel: typeof VitalsPanel;
+};
+//#endregion
+export type { Vital, VitalName, VitalRating, VitalsSnapshot };

package/dist/plugins/vitals.js

@@ -0,0 +1,109 @@
+import { i as definePlugin } from "../plugins-CzUiTn_r.js";
+import { useEffect, useSyncExternalStore } from "react";
+import { Fragment, 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
+//#region src/plugins/vitals/index.tsx
+function VitalsPill() {
+	useEffect(() => {
+		startVitals();
+	}, []);
+	const lcp = useVitals().LCP;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		className: "dot",
+		"data-rating": lcp?.rating
+	}), lcp ? `LCP ${formatVital("LCP", lcp.value)}` : "LCP –"] });
+}
+/** Core Web Vitals: LCP in the pill, all five metrics in the panel. Client only. */
+function vitals() {
+	return definePlugin({
+		id: "vitals",
+		title: "Vitals",
+		pill: VitalsPill,
+		panel: VitalsPanel
+	});
+}
+//#endregion
+export { vitals };

package/dist/plugins-1QmTmZyL.d.ts

@@ -0,0 +1,76 @@
+import { ComponentType } from "react";
+//#region src/core/plugins.d.ts
+/**
+ * A capability a plugin needs, such as `"cicd.read"`. Core assumes development
+ * and grants everything; the `access` plugin brings a matrix for deployed tiers.
+ */
+type HudCapability = string;
+type PinEdge = "left" | "right" | "bottom";
+/** What a plugin's panel and pill receive from the shell. */
+interface HudPluginContext {
+  /** App slug from `defineHud({ app })`. */
+  app: string;
+  /** Whether the current tier grants `capability`. */
+  can: (capability: HudCapability) => boolean;
+  /**
+   * Fetches JSON from this plugin's server routes: `api("/runs")` requests
+   * `<apiBase>/<plugin id>/runs`. Rejects with `HudApiError` on a non-2xx status.
+   */
+  api: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;
+  /** Pins this plugin's panel to an edge. Below 768 px the pin is kept but not applied. */
+  pin: (edge: PinEdge) => void;
+  /** Closes this plugin's panel. */
+  close: () => void;
+}
+interface HudPluginProps {
+  ctx: HudPluginContext;
+}
+interface HudCommand {
+  /** Unique within the plugin. */
+  id: string;
+  title: string;
+  /** Shortcut in `mod+shift+k` form; `mod` is ⌘ on macOS and Ctrl elsewhere. */
+  shortcut?: string;
+  run: (ctx: HudPluginContext) => void;
+}
+type HudHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface HudRouteContext {
+  /** Values of `:name` segments in the matched path. */
+  params: Record<string, string>;
+}
+type HudRouteHandler = (request: Request, ctx: HudRouteContext) => Response | Promise<Response>;
+/**
+ * Server routes keyed by path below the plugin's prefix, then by method:
+ * `{ "/runs/:id": { GET } }` serves `GET <apiBase>/<plugin id>/runs/42`.
+ */
+type HudRoutes = Record<string, Partial<Record<HudHttpMethod, HudRouteHandler>>>;
+/**
+ * The plugin contract. A plugin ships as two subpath exports that share this
+ * type: `@hansenexus/hud/plugins/<id>` carries the client half (`panel`,
+ * `pill`, `commands`) and `@hansenexus/hud/plugins/<id>/server` the server half
+ * (`routes`), so route code never reaches a client bundle and React never
+ * reaches the route handler. Both halves carry the same `id` and `capability`.
+ */
+interface HudPlugin {
+  /** Unique per HUD; also the URL segment of the plugin's routes. */
+  id: string;
+  /** Panel title and pill label when the plugin has no `pill`. Defaults to `id`. */
+  title?: string;
+  /** Without it the plugin is dropped, client and server side. */
+  capability?: HudCapability;
+  /** Floating panel content, opened from the plugin's pill item. */
+  panel?: ComponentType<HudPluginProps>;
+  /** Live content inside the plugin's pill item. Keep it inline and non-interactive. */
+  pill?: ComponentType<HudPluginProps>;
+  commands?: readonly HudCommand[];
+  routes?: HudRoutes;
+}
+/** Identity helper that types a plugin object without widening it. */
+declare function definePlugin<const P extends HudPlugin>(plugin: P): P;
+declare class HudApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(status: number, body: unknown, url: string);
+}
+//#endregion
+export { HudPlugin as a, HudRouteContext as c, PinEdge as d, definePlugin as f, HudHttpMethod as i, HudRouteHandler as l, HudCapability as n, HudPluginContext as o, HudCommand as r, HudPluginProps as s, HudApiError as t, HudRoutes as u };

package/dist/plugins-CzUiTn_r.js

@@ -0,0 +1,68 @@
+//#region src/core/plugins.ts
+const HUD_HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+/** Identity helper that types a plugin object without widening it. */
+function definePlugin(plugin) {
+	return plugin;
+}
+const PLUGIN_ID = /^[a-z0-9][a-z0-9-]*$/;
+/**
+* Validates plugin ids and drops plugins whose capability `can` denies.
+* Ids must be unique and URL-safe because they become route segments.
+*/
+function resolvePlugins(plugins, can) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const plugin of plugins) {
+		if (!PLUGIN_ID.test(plugin.id)) throw new Error(`hud: plugin id "${plugin.id}" must match ${PLUGIN_ID}`);
+		if (seen.has(plugin.id)) throw new Error(`hud: duplicate plugin id "${plugin.id}"`);
+		seen.add(plugin.id);
+	}
+	return plugins.filter((plugin) => plugin.capability === void 0 || can(plugin.capability));
+}
+var HudApiError = class extends Error {
+	status;
+	body;
+	constructor(status, body, url) {
+		super(`hud: ${url} answered ${status}`);
+		this.status = status;
+		this.body = body;
+		this.name = "HudApiError";
+	}
+};
+function createPluginContext(plugin, { app, apiBase, can, pin, close }) {
+	const prefix = `${apiBase.replace(/\/+$/, "")}/${plugin.id}`;
+	return {
+		app,
+		can,
+		pin,
+		close,
+		api: async (path, init) => {
+			const url = `${prefix}/${path.replace(/^\/+/, "")}`;
+			const headers = new Headers(init?.headers);
+			if (!headers.has("accept")) headers.set("accept", "application/json");
+			const res = await fetch(url, {
+				...init,
+				headers
+			});
+			const body = parseBody(await res.text());
+			if (!res.ok) throw new HudApiError(res.status, body, url);
+			return body;
+		}
+	};
+}
+/** JSON when it parses, the raw text otherwise (an HTML error page, say). */
+function parseBody(text) {
+	if (!text) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+export { resolvePlugins as a, definePlugin as i, HudApiError as n, createPluginContext as r, HUD_HTTP_METHODS as t };

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+import { a as HudPlugin, c as HudRouteContext, f as definePlugin, i as HudHttpMethod, l as HudRouteHandler, n as HudCapability, u as HudRoutes } from "./plugins-1QmTmZyL.js";
+//#region src/server/handler.d.ts
+/**
+ * Decides whether a request may reach a plugin route. Return a `Response` to
+ * refuse it (404, 401, 403 ...) or `null` to let it through. The `access`
+ * plugin supplies one for deployed tiers.
+ */
+type HudGuard = (request: Request, capability: HudCapability | undefined) => Response | null | Promise<Response | null>;
+interface HudHandlerOptions {
+  /** Path the catch-all route is mounted at. Default `/api/hud`. */
+  basePath?: string;
+  /** Default: `developmentOnly`, which answers 404 unless `NODE_ENV` is `development`. */
+  guard?: HudGuard;
+  /** Drops plugins server side, like `defineHud({ can })` does client side. Default: grant all. */
+  can?: (capability: HudCapability) => boolean;
+}
+type HudRequestHandler = (request: Request) => Promise<Response>;
+/** One function per method, so a Next route can `export const { GET, POST } = createHudHandler(...)`. */
+type HudHandler = {
+  handle: HudRequestHandler;
+} & Record<HudHttpMethod, HudRequestHandler>;
+/**
+ * The default guard. Core assumes development, so a deployed build that
+ * mounts the route without an `access` guard serves nothing and reveals
+ * nothing about which plugins exist.
+ */
+export declare const developmentOnly: HudGuard;
+/**
+ * Serves every plugin's routes from one catch-all route
+ * (`app/api/hud/[...hud]/route.ts` in Next). A request to
+ * `<basePath>/<plugin id>/<path>` reaches that plugin's `routes[path][method]`;
+ * unknown plugin or path answers 404, a known path with another method 405.
+ *
+ * Pass the server halves (`@hansenexus/hud/plugins/<id>/server`): they carry
+ * `routes` and no React.
+ */
+export declare function createHudHandler(plugins: readonly HudPlugin[], options?: HudHandlerOptions): HudHandler;
+//#endregion
+export { type HudGuard, type HudHandler, type HudHandlerOptions, type HudHttpMethod, type HudPlugin, type HudRequestHandler, type HudRouteContext, type HudRouteHandler, type HudRoutes, definePlugin };

package/dist/server.js

@@ -0,0 +1,106 @@
+import { a as resolvePlugins, i as definePlugin, t as HUD_HTTP_METHODS } from "./plugins-CzUiTn_r.js";
+//#region src/server/handler.ts
+function json(status, body, headers) {
+	const res = Response.json(body, { status });
+	if (headers) for (const [key, value] of new Headers(headers)) res.headers.set(key, value);
+	return res;
+}
+function notFound() {
+	return json(404, {
+		ok: false,
+		error: "not found"
+	});
+}
+/**
+* The default guard. Core assumes development, so a deployed build that
+* mounts the route without an `access` guard serves nothing and reveals
+* nothing about which plugins exist.
+*/
+const developmentOnly = () => {
+	return (typeof process === "undefined" ? void 0 : process.env.NODE_ENV) === "development" ? null : notFound();
+};
+function splitPath(path) {
+	return path.split("/").filter(Boolean);
+}
+function compile(plugin) {
+	return Object.entries(plugin.routes ?? {}).map(([path, methods]) => ({
+		segments: splitPath(path),
+		methods
+	}));
+}
+function match(route, segments) {
+	if (route.segments.length !== segments.length) return null;
+	const params = {};
+	for (const [i, pattern] of route.segments.entries()) {
+		const segment = segments[i] ?? "";
+		if (!pattern.startsWith(":")) {
+			if (pattern !== segment) return null;
+			continue;
+		}
+		try {
+			params[pattern.slice(1)] = decodeURIComponent(segment);
+		} catch {
+			return null;
+		}
+	}
+	return params;
+}
+function isMethod(method) {
+	return HUD_HTTP_METHODS.includes(method);
+}
+/**
+* Serves every plugin's routes from one catch-all route
+* (`app/api/hud/[...hud]/route.ts` in Next). A request to
+* `<basePath>/<plugin id>/<path>` reaches that plugin's `routes[path][method]`;
+* unknown plugin or path answers 404, a known path with another method 405.
+*
+* Pass the server halves (`@hansenexus/hud/plugins/<id>/server`): they carry
+* `routes` and no React.
+*/
+function createHudHandler(plugins, options = {}) {
+	const basePath = splitPath(options.basePath ?? "/api/hud");
+	const guard = options.guard ?? developmentOnly;
+	const table = new Map(resolvePlugins(plugins, options.can ?? (() => true)).map((plugin) => [plugin.id, {
+		plugin,
+		routes: compile(plugin)
+	}]));
+	const handle = async (request) => {
+		const segments = splitPath(new URL(request.url).pathname);
+		if (!basePath.every((segment, i) => segments[i] === segment)) return notFound();
+		const [pluginId, ...rest] = segments.slice(basePath.length);
+		const entry = pluginId === void 0 ? void 0 : table.get(pluginId);
+		const refusal = await guard(request, entry?.plugin.capability);
+		if (refusal) return refusal;
+		if (!entry) return notFound();
+		for (const route of entry.routes) {
+			const params = match(route, rest);
+			if (!params) continue;
+			const method = request.method === "HEAD" ? "GET" : request.method;
+			const fn = isMethod(method) ? route.methods[method] : void 0;
+			if (!fn) return json(405, {
+				ok: false,
+				error: "method not allowed"
+			}, { allow: HUD_HTTP_METHODS.filter((m) => route.methods[m]).join(", ") });
+			try {
+				return await fn(request, { params });
+			} catch (error) {
+				console.error(`hud: ${entry.plugin.id} ${request.method} /${rest.join("/")} failed`, error);
+				return json(500, {
+					ok: false,
+					error: "plugin route failed"
+				});
+			}
+		}
+		return notFound();
+	};
+	return {
+		handle,
+		GET: handle,
+		POST: handle,
+		PUT: handle,
+		PATCH: handle,
+		DELETE: handle
+	};
+}
+//#endregion
+export { createHudHandler, definePlugin, developmentOnly };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hansenexus/hud",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Modular dev HUD for React apps: status pill, floating panels, element grabber, plugin API.",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./plugins/*": {
+      "types": "./dist/plugins/*.d.ts",
+      "import": "./dist/plugins/*.js"
     }
   },
   "sideEffects": false,
@@ -52,6 +64,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^30.1.2",
+    "rolldown": "^1.2.12",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"