@hansenexus/hud 0.2.0 → 0.4.0

package/dist/force-state-BaqWsmrf.js

@@ -0,0 +1,153 @@
+//#region src/plugins/design/force-state.ts
+/**
+* Force-state store: lets a reviewer (the States panel) or an agent
+* (`?__state=`) render any registered state boundary as loading, empty or
+* error without faking data.
+*
+* Development only. `StateBoundary` reaches this module behind a
+* `NODE_ENV === "development"` constant, so production builds drop it; a
+* consumer's bundle gate greps client chunks for FORCE_STATE_MARKER to prove it.
+*/
+const FORCED_STATES = [
+	"loading",
+	"empty",
+	"error"
+];
+/** `?__state=loading` forces top-level boundaries; `?__state=<id>:error` one boundary. */
+const FORCE_STATE_PARAM = "__state";
+/**
+* globalThis key of the store singleton, and the bundle-gate marker. Holding
+* the store on globalThis keeps one instance even if the module is evaluated
+* twice: HMR, or the app's `StateBoundary` chunk and the HUD's States panel
+* chunk each carrying a copy.
+*/
+const FORCE_STATE_MARKER = "__HANSENEXUS_HUD_FORCE_STATE__";
+function isForcedState(value) {
+	return FORCED_STATES.includes(value);
+}
+/** Parses the value of `?__state=`; anything unrecognised is ignored (null). */
+function parseForceStateParam(value) {
+	if (!value) return null;
+	const separator = value.lastIndexOf(":");
+	if (separator === -1) return isForcedState(value) ? {
+		state: value,
+		target: null
+	} : null;
+	const target = value.slice(0, separator);
+	const state = value.slice(separator + 1);
+	if (!target || !isForcedState(state)) return null;
+	return {
+		state,
+		target
+	};
+}
+/** Reads the param out of a `location.search` string. */
+function forceStateParamFromSearch(search) {
+	return parseForceStateParam(new URLSearchParams(search).get(FORCE_STATE_PARAM));
+}
+/** The param's value as it appears in the URL, `<id>:<state>` or `<state>`. */
+function formatForceStateParam(param) {
+	return param.target === null ? param.state : `${param.target}:${param.state}`;
+}
+/**
+* The state a boundary renders. A panel override for the boundary wins; else
+* the URL param applies to its target, or, untargeted, to the nearest
+* boundaries: the top-level ones. Forcing an outer boundary unmounts the
+* inner ones anyway, so the page-level state is what a screenshot wants.
+*/
+function resolveForcedState(snapshot, boundary) {
+	const override = snapshot.overrides[boundary.id];
+	if (override) return override;
+	const { param } = snapshot;
+	if (!param) return null;
+	if (param.target !== null) return param.target === boundary.id ? param.state : null;
+	return boundary.parentId === null ? param.state : null;
+}
+var ForceStateStore = class {
+	registrations = /* @__PURE__ */ new Map();
+	overrides = {};
+	search = "";
+	snapshot = {
+		boundaries: [],
+		overrides: {},
+		param: null
+	};
+	listeners = /* @__PURE__ */ new Set();
+	getSnapshot = () => this.snapshot;
+	subscribe = (listener) => {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	};
+	/** Registers a mounted boundary; the returned function unregisters it. Mounts are counted. */
+	register(id, parentId) {
+		const existing = this.registrations.get(id);
+		this.registrations.set(id, {
+			parentId,
+			count: (existing?.count ?? 0) + 1
+		});
+		this.emit();
+		return () => {
+			const current = this.registrations.get(id);
+			if (!current) return;
+			if (current.count > 1) this.registrations.set(id, {
+				...current,
+				count: current.count - 1
+			});
+			else this.registrations.delete(id);
+			this.emit();
+		};
+	}
+	/** Forces one boundary (panel toggle); null returns it to auto. */
+	force(id, state) {
+		const next = { ...this.overrides };
+		if (state) next[id] = state;
+		else delete next[id];
+		this.overrides = next;
+		this.emit();
+	}
+	clearOverrides() {
+		this.overrides = {};
+		this.emit();
+	}
+	/** Feeds the current `location.search`; a no-op when it did not change. */
+	syncSearch(search) {
+		if (search === this.search) return;
+		this.search = search;
+		this.emit();
+	}
+	emit() {
+		this.snapshot = {
+			boundaries: [...this.registrations].map(([id, { parentId }]) => ({
+				id,
+				parentId
+			})),
+			overrides: this.overrides,
+			param: forceStateParamFromSearch(this.search)
+		};
+		for (const listener of this.listeners) listener();
+	}
+};
+/** The page's store, created on first use. */
+function getForceStateStore() {
+	const holder = globalThis;
+	holder[FORCE_STATE_MARKER] ??= new ForceStateStore();
+	return holder[FORCE_STATE_MARKER];
+}
+/** Subscribes to the page's store and keeps it in step with back/forward navigation. */
+function subscribeForceState(listener) {
+	const store = getForceStateStore();
+	const onPopState = () => store.syncSearch(window.location.search);
+	window.addEventListener("popstate", onPopState);
+	const unsubscribe = store.subscribe(listener);
+	return () => {
+		window.removeEventListener("popstate", onPopState);
+		unsubscribe();
+	};
+}
+function getForceStateSnapshot() {
+	return getForceStateStore().getSnapshot();
+}
+//#endregion
+export { getForceStateSnapshot as a, subscribeForceState as c, formatForceStateParam as i, FORCE_STATE_MARKER as n, getForceStateStore as o, FORCE_STATE_PARAM as r, resolveForcedState as s, FORCED_STATES as t };

package/dist/force-state-CCqoTfVB.d.ts

@@ -0,0 +1,23 @@
+//#region src/plugins/design/force-state.d.ts
+/**
+ * Force-state store: lets a reviewer (the States panel) or an agent
+ * (`?__state=`) render any registered state boundary as loading, empty or
+ * error without faking data.
+ *
+ * Development only. `StateBoundary` reaches this module behind a
+ * `NODE_ENV === "development"` constant, so production builds drop it; a
+ * consumer's bundle gate greps client chunks for FORCE_STATE_MARKER to prove it.
+ */
+declare const FORCED_STATES: readonly ["loading", "empty", "error"];
+type ForcedState = (typeof FORCED_STATES)[number];
+/** `?__state=loading` forces top-level boundaries; `?__state=<id>:error` one boundary. */
+declare const FORCE_STATE_PARAM = "__state";
+/**
+ * globalThis key of the store singleton, and the bundle-gate marker. Holding
+ * the store on globalThis keeps one instance even if the module is evaluated
+ * twice: HMR, or the app's `StateBoundary` chunk and the HUD's States panel
+ * chunk each carrying a copy.
+ */
+declare const FORCE_STATE_MARKER = "__HANSENEXUS_HUD_FORCE_STATE__";
+//#endregion
+export { ForcedState as i, FORCE_STATE_MARKER as n, FORCE_STATE_PARAM as r, FORCED_STATES as t };

package/dist/handler-WmE4Lu7l.d.ts

@@ -0,0 +1,39 @@
+import { a as HudHttpMethod, o as HudPlugin, r as HudCapability } from "./plugins-CQ_0w1ot.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.
+ */
+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.
+ */
+declare function createHudHandler(plugins: readonly HudPlugin[], options?: HudHandlerOptions): HudHandler;
+//#endregion
+export { createHudHandler as a, HudRequestHandler as i, HudHandler as n, developmentOnly as o, HudHandlerOptions as r, HudGuard as t };

package/dist/index-BYsdS-7d.d.ts

@@ -0,0 +1,55 @@
+import { o as HudPlugin, r as HudCapability } from "./plugins-CQ_0w1ot.js";
+import "./define-hud-BBzsSl8b.js";
+//#region src/core/grabber/picker.d.ts
+interface PickPoint {
+  clientX: number;
+  clientY: number;
+}
+interface ElementPickerProps {
+  active: boolean;
+  onPick: (element: Element, point: PickPoint) => void;
+  onCancel: () => void;
+  /** Banner text while active. */
+  hint?: string;
+  /** Label next to the hover outline. Default: the tag name. */
+  describe?: (element: Element) => string;
+  /** Extra elements to leave alone, on top of the picker's own shadow host. */
+  ignore?: (element: Element) => boolean;
+}
+/**
+ * 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.
+ */
+declare const PICKER_CSS = "\n.grab-layer { position: fixed; inset: 0; pointer-events: none; }\n.grab-hint {\n  position: fixed;\n  top: 0;\n  left: 50%;\n  transform: translateX(-50%);\n  padding: 3px 12px;\n  border-radius: 0 0 6px 6px;\n  white-space: nowrap;\n  background: var(--hud-accent, #0369a1);\n  color: var(--hud-accent-fg, #ffffff);\n  font: 600 11px/1.5 var(--hud-mono, ui-monospace, monospace);\n}\n.grab-outline {\n  position: fixed;\n  border: 1.5px solid var(--hud-accent, #0369a1);\n  background: color-mix(in srgb, var(--hud-accent, #0369a1) 8%, transparent);\n  border-radius: 3px;\n}\n.grab-label {\n  position: fixed;\n  max-width: min(480px, calc(100vw - 8px));\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  padding: 1px 6px;\n  border-radius: 3px;\n  background: var(--hud-accent, #0369a1);\n  color: var(--hud-accent-fg, #ffffff);\n  font: 600 10px/1.6 var(--hud-mono, ui-monospace, monospace);\n}\n";
+/**
+ * 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.
+ */
+declare function ElementPicker({ active, onPick, onCancel, hint, describe, ignore }: ElementPickerProps): import("react").JSX.Element;
+//#endregion
+//#region src/shell/hud.d.ts
+interface HudProps {
+  /** App slug: labels the pill and keys the persisted layout. */
+  appSlug: string;
+  /** Badge shown at the start of the pill. Default "DEV". */
+  envLabel?: string;
+  /** Client halves of the plugins, in pill order. Keep the array stable across renders. */
+  plugins?: readonly HudPlugin[];
+  /** Base path of the plugin routes. Default "/api/hud". */
+  apiBase?: string;
+  /** Capability check. Default: grant all (core assumes development). Keep it stable. */
+  can?: (capability: HudCapability) => boolean;
+}
+/**
+ * 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 `@hansenexus/hud/next`).
+ */
+declare function Hud({ appSlug, envLabel, plugins, apiBase, can }: HudProps): import("react").JSX.Element;
+//#endregion
+export { PICKER_CSS as a, ElementPickerProps as i, HudProps as n, PickPoint as o, ElementPicker as r, Hud as t };

package/dist/index.d.ts

@@ -1,39 +1,6 @@
-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 };
+import { a as GrabComponent, i as matchComponentHints, n as GrabAnchor, r as GrabPayload, t as ComponentHint } from "./payload-CLKDVZWl.js";
+import { c as HudPluginProps, f as PinEdge, g as useGrab, h as HudGrabState, i as HudCommand, m as HudGrab, n as HudApiError, o as HudPlugin, p as definePlugin, r as HudCapability, s as HudPluginContext, t as HudAccessControl } from "./plugins-CQ_0w1ot.js";
+import { n as HudMountProps, r as defineHud, t as DefineHudOptions } from "./define-hud-BBzsSl8b.js";
+import { a as PICKER_CSS, i as ElementPickerProps, n as HudProps, o as PickPoint, r as ElementPicker, t as Hud } from "./index-BYsdS-7d.js";
+import { n as HUD_HOST_TAG, t as HUD_DEV_MARKER } from "./marker-CMrvxPmS.js";
+export { type ComponentHint, type DefineHudOptions, ElementPicker, type ElementPickerProps, type GrabAnchor, type GrabComponent, type GrabPayload, HUD_DEV_MARKER, HUD_HOST_TAG, Hud, type HudAccessControl, HudApiError, type HudCapability, type HudCommand, type HudGrab, type HudGrabState, type HudMountProps, type HudPlugin, type HudPluginContext, type HudPluginProps, type HudProps, PICKER_CSS, type PickPoint, type PinEdge, defineHud, definePlugin, matchComponentHints, useGrab };