@hansenexus/hud 0.2.0 → 0.4.0

package/README.md

@@ -3,8 +3,7 @@
 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).
+> Early. The roadmap is tracked in [the PRD](https://github.com/hansenexus/hud/issues/1).
 
 ## Develop
 
@@ -28,19 +27,264 @@ bun add -d @hansenexus/hud   # or npm i -D @hansenexus/hud
 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
+## Use (Next.js)
+
+Three files. The HUD definition, client only:
+
+```tsx
+// src/components/dev/hud.tsx
+import { defineHud } from "@hansenexus/hud";
+import { vitals } from "@hansenexus/hud/plugins/vitals";
+
+export default defineHud({ app: "my-app", plugins: [vitals()] });
+```
+
+The loader, with the build gate as a literal expression around the `import()`. Next inlines both
+env reads, so a production build folds the ternary to `null` and emits no HUD chunk:
+
+```tsx
+// src/components/dev/hud-loader.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
+);
+```
+
+Render `<HudLoader />` in the root layout. Plugin routes mount through one catch-all route, fed
+the plugins' server halves:
+
+```ts
+// src/app/api/hud/[...hud]/route.ts
+import { createHudHandler } from "@hansenexus/hud/server";
+
+export const { GET, POST, PUT, PATCH, DELETE } = createHudHandler([/* plugins/<id>/server */]);
+```
+
+`createHudHandler` answers 404 to everything unless `NODE_ENV` is `development`; pass `guard` to
+open deployed tiers deliberately. `HUD_DEV_MARKER` is rendered on the HUD root for a CI grep.
+
+## Deployed tiers (access plugin)
+
+Core assumes development: without the `access` plugin `defineHud` renders nothing on any other
+tier and `createHudHandler` answers 404. To open preview, staging or production deliberately, add
+both halves:
 
 ```tsx
-import { Hud } from "@hansenexus/hud";
+// hud.tsx
+import { access } from "@hansenexus/hud/plugins/access";
+export default defineHud({ app: "my-app", plugins: [access(), vitals()] });
+```
+
+```ts
+// app/api/hud/[...hud]/route.ts
+import { accessGuard, accessServer } from "@hansenexus/hud/plugins/access/server";
+
+export const { GET, POST, PUT, PATCH, DELETE } = createHudHandler([accessServer(), /* ... */], {
+  guard: accessGuard(),
+});
+```
+
+The tier comes from the env ladder (`NEXT_PUBLIC_HUD_DISABLED` → `NODE_ENV` → `NEXT_PUBLIC_HUD_ENV`
+→ `VERCEL_ENV` → production). A deployed tier also needs `NEXT_PUBLIC_HUD_ENABLED=true` (in the
+loader's build gate and on the server) and `HUD_ACCESS_PASSWORD`. Every plugin route then answers,
+in this order:
+
+| status | when                                                                         |
+| ------ | ---------------------------------------------------------------------------- |
+| 404    | the tier has not opted in, or is disabled                                    |
+| 403    | the tier's matrix denies the plugin's capability, or the route declares none |
+| 401    | permitted, but no valid unlock cookie (or no password configured)            |
+
+The denial comes before the lock, so a password never widens the matrix. Every 403 carries the
+same `{ "error": "forbidden" }` body, naming neither tier nor capability. The matrix is
+default-deny; production grants `observe.app`, `observe.estate` and `cicd.read`. Pass the same
+`{ matrix: { staging: [...] } }` to `access()` and `accessGuard()` to replace a tier's list.
+Until the operator unlocks (12 h on preview/staging, 2 h on production), the pill shows only the
+lock. Client-side hiding is display only; the guard is what enforces the tier.
+
+Server-only variables (never prefix them `NEXT_PUBLIC_`, never pass them to client code):
+
+| variable              | does                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `HUD_ACCESS_PASSWORD` | the unlock password. **Make it long and random** (a generated 32+ character string): it is the only barrier in front of the deployed HUD |
+| `HUD_ACCESS_SECRET`   | optional. Signs the unlock cookie instead of the password, so a leaked cookie gives nothing to guess the password against |
+| `HUD_DISABLED`        | `true` turns every HUD route into a 404 at request time                               |
+
+The cookie (`__Host-hud-unlock`, httpOnly, `SameSite=Strict`) is signed with a key derived per
+tier, so a staging cookie does not open production. Wrong passwords are budgeted per client
+(`x-real-ip`, else the last `x-forwarded-for` entry, which your proxy must append; the leftmost
+entries are client-controlled and ignored): ten per client per ten minutes, then 429 for every
+attempt, the right password included. Past a hundred failures overall, every client with recent
+failures of its own is throttled too, while a client without any still unlocks.
+
+`NEXT_PUBLIC_*` flags are inlined at build time: changing `NEXT_PUBLIC_HUD_ENABLED` or
+`NEXT_PUBLIC_HUD_DISABLED` needs a rebuild. To switch a running deployment off, set
+`HUD_DISABLED=true` and restart.
+
+In the playground, `?env=staging` runs this flow with the password `playground`.
+
+## Write a plugin
+
+A plugin is `{ id, title?, capability?, panel?, pill?, commands?, routes? }`, shipped as two
+halves with the same `id`: the client half (`panel`, `pill`, `commands`) and the server half
+(`routes`), so route code never reaches a client bundle. The panel is a plain React component
+receiving `ctx`:
+
+| `ctx`         | does                                                                  |
+| ------------- | --------------------------------------------------------------------- |
+| `can(cap)`    | capability check (core grants all; the `access` plugin narrows it)    |
+| `api(path)`   | JSON fetch from the plugin's routes at `/api/hud/<id>/<path>`         |
+| `pin(edge)`   | pin the panel to `left`, `right` or `bottom`                          |
+| `close()`     | close the panel                                                       |
+| `open()`      | open the panel                                                        |
+| `grab`        | the element grabber: `start()`, `cancel()`, `clear()`; read it with `useGrab(ctx.grab)` |
+
+Routes are keyed by path, then method: `routes: { "/runs/:id": { GET: (req, { params }) => ... } }`.
+An unknown path answers 404, a known path with another method 405.
+
+`playground/src/plugins/server-info` is a working example: the playground serves its routes
+through MSW with the same `createHudHandler` an app mounts.
+
+## Panels and shortcuts
+
+- Open panels from the pill (`⋯` lists every panel and command). Drag by the title bar; a click
+  raises a panel.
+- Pin a panel with ◧ ⬓ ◨ or by dropping it at the left, right or bottom edge. Pinning pushes the
+  page (padding on `<html>`) instead of covering it; pins on one edge stack. The host's
+  `position: fixed` elements and media queries still see the full window.
+- The layout (open panels, positions, pins) is kept per `appSlug` in `localStorage`.
+  `⋯ → Reset layout` clears it.
+- Below 768 px panels open as one full-width bottom sheet with a tab per panel; no pinning.
+- `⌘⇧H` (Ctrl+Shift+H elsewhere) hides and restores the layout.
 
-export function DevHud() {
-  return <Hud appSlug="my-app" />;
+A plugin's panel can pin itself with `ctx.pin("right")`. Plugin `commands` join the registry as
+`<plugin id>.<command id>`, appear in the `⋯` menu and bind their `shortcut`.
+
+## Element grabber
+
+`⌘⇧G` or the pill's ⌖ starts a grab: hover outlines an element and labels it with the React
+component and file that rendered it, a click picks it, `Esc` cancels. Open panels stay mounted
+and usable meanwhile. The pick becomes a `GrabPayload` (route, selector, label, component,
+viewport) handed to every plugin's `onGrab(payload, ctx)` and kept in `ctx.grab`. The source line
+comes from React's dev stack and points into the dev server's transformed module, so it can sit a
+few lines below the original.
+
+`ElementPicker` is exported on its own and carries no dev marker, for the review entrypoint.
+
+## Agent plugins
+
+Two plugins from one module: `agentDispatch()` (Dispatch panel: the last grab plus an
+instruction, sent to a provider; opens itself on a grab) and `agentSessions()` (Sessions panel:
+runs and sessions of every provider).
+
+```tsx
+import { agentDispatch, agentSessions } from "@hansenexus/hud/plugins/agent";
+defineHud({ app: "my-app", plugins: [agentDispatch({ componentHints }), agentSessions()] });
+```
+
+```ts
+import { agentDispatch, agentSessions, claudeCode, hermes } from "@hansenexus/hud/plugins/agent/server";
+
+const providers = [
+  claudeCode(), // `claude -p <prompt> --permission-mode acceptEdits` in the dev server's cwd
+  hermes({ baseUrl: "http://hn-hub.ts.hansenexus.dev:8642", token: process.env.HERMES_API_TOKEN }),
+];
+export const { GET, POST } = createHudHandler([agentDispatch({ providers }), agentSessions({ providers })]);
+```
+
+A provider is `{ id, label, status?, dispatch(order), sessions? }`; `order.prompt` is the built
+task text. `POST /dispatch` refuses cross-site requests (`Sec-Fetch-Site`) and anything not
+`application/json`, so another origin cannot start an agent through the developer's browser.
+`claudeCode()` loads Node built-ins on first use, so the server entry also imports where `node:`
+modules are missing.
+
+## Design plugin
+
+`@hansenexus/hud/plugins/design` exports three client-only plugins:
+
+```tsx
+import { forceState, tokens, variants } from "@hansenexus/hud/plugins/design";
+
+tokens({
+  groups: [
+    { label: "Theme", tokens: ["--background", "--primary", { cssVar: "--ring", label: "ring" }] },
+    { label: "Brand", tokens: ["--brand"], scope: { attribute: "data-theme", value: "brand" } },
+  ],
+  sourceHint: "src/app/globals.css",
+});
+variants({ categories: async () => loadCategories(), reviewHref: "/dev/review" });
+forceState();
+```
+
+- **Tokens** reads each value from the host document (a hidden probe in `<body>` carrying the
+  group's `scope` attribute), so themed and scoped tokens show what the page renders. It re-reads
+  when `<html>`/`<body>` attributes, stylesheets or the OS color scheme change.
+- **Variants** lists the app's variant categories through an adapter (a list or an async loader)
+  and queues generate briefs when the tier grants `variants.generate`.
+- **States** toggles every mounted `StateBoundary` between real, loading, empty and error. It
+  needs `state.force`.
+
+`StateBoundary` is app code and production-safe to import. Outside development it renders
+`children(null)` and the bundler drops the store; `?__state=loading|empty|error` forces the
+top-level boundaries and `?__state=<id>:error` one boundary:
+
+```tsx
+import { StateBoundary } from "@hansenexus/hud/state-boundary";
+
+<StateBoundary id="blog-post">
+  {(forced) => (forced === "loading" || post === undefined ? <Skeleton /> : <Post post={post} />)}
+</StateBoundary>;
+```
+
+`FORCE_STATE_MARKER` (`__HANSENEXUS_HUD_FORCE_STATE__`) is the store's global key; grep production
+chunks for it to prove the fold.
+
+## Review entrypoint (production)
+
+`@hansenexus/hud/review` is the client review widget: a pill on the right edge, the element
+picker and a docked review sheet with the page's pins. It is safe to ship in production and
+carries none of the dev shell or its plugins. It needs `convex` (an optional peer dependency).
+
+The gate is a prop, not a build flag, so one image can serve a client production with the widget
+off and a staging production with it on. Read the URL on the server per deployment and pass it
+down; empty renders nothing:
+
+```tsx
+"use client";
+import { Review } from "@hansenexus/hud/review";
+
+export function ReviewMount({ convexUrl, locale }: { convexUrl?: string; locale: string }) {
+  return <Review convexUrl={convexUrl} projectSlug="elbe-akustik" locale={locale} />;
 }
 ```
 
-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.
+Even with a URL the widget stays invisible until the visitor opens a review link (`?rv=<grant>`,
+redeemed once and stripped from the address bar) or has a stored session. Pins are stored per
+locale-stripped route (`/en/standorte` and `/standorte` are one route) and per viewport bucket;
+a pin that cannot be placed is listed under "Ohne Position", never moved onto a neighbour. The
+widget talks to the review app's Convex functions `access:redeemGrant`, `access:whoami`,
+`pins:listForRoute` and `pins:plant`; pass `backend` (a `ReviewBackend`) instead of `convexUrl`
+to run it against anything else. In the playground, `?review` mounts it with an in-memory
+backend.
+
+### Bundle gate
+
+`@hansenexus/hud/markers` exports the literals to grep production client chunks for, with no
+dependencies so a Node gate script can import it:
+
+| marker              | value                       | expected in production chunks             |
+| ------------------- | --------------------------- | ----------------------------------------- |
+| `HUD_DEV_MARKER`    | `__HANSENEXUS_HUD_DEV__`    | never                                     |
+| `HUD_REVIEW_MARKER` | `__HANSENEXUS_HUD_REVIEW__` | only where `/review` is meant to ship     |
+
+CI proves both on every PR: `fixtures/next-app` mounts the dev HUD behind the loader's build gate
+and `<Review>` beside it, installs the packed tarball, runs `next build` and fails on any dev
+marker or dev-only string in `.next/static` (`bun run build && bun run --cwd fixtures/next-app
+gate`). `fixtures/next-app/scripts/check-bundle.js` is a starting point for an app's own gate.
 
 ## Release
 

package/dist/access-CNvJOwKM.d.ts

@@ -0,0 +1,54 @@
+import { r as HudCapability } from "./plugins-CQ_0w1ot.js";
+import { t as HudEnv } from "./env-vEjyJfPW.js";
+//#region src/plugins/access/capabilities.d.ts
+/** The capability vocabulary of the default matrix. Development grants these and any other. */
+declare const HUD_CAPABILITIES: readonly ["observe.app", "observe.estate", "cicd.read", "cicd.trigger", "inject.seed", "mock.toggle", "auth.impersonate", "dispatch.local", "dispatch.hermes", "variants.switch", "variants.vote", "variants.generate", "state.force"];
+/**
+ * The access plugin's own capability. The guard lets the unlock route through
+ * on every enabled tier, so it never needs a matrix entry; nothing else may use it.
+ */
+declare const ACCESS_UNLOCK_CAPABILITY = "access.unlock";
+/** Tiers whose grants an app may replace. Development grants all, disabled nothing. */
+type DeployedTier = "preview" | "staging" | "production";
+/** Per-tier replacement lists, for apps whose plugins bring capabilities of their own. */
+type CapabilityMatrixOverride = Partial<Record<DeployedTier, readonly HudCapability[]>>;
+type CapabilityMatrix = Record<HudEnv, readonly HudCapability[]>;
+/**
+ * Default-deny capability matrix. Client filtering is convenience only: the
+ * guard re-checks every route against the same matrix server side.
+ * Staging's `auth.impersonate` is further flag-gated by the plugin that uses it.
+ */
+declare const CAPABILITY_MATRIX: CapabilityMatrix;
+/** Core assumes development, so development grants every capability, listed or not. */
+declare function hasCapability(env: HudEnv, capability: HudCapability, matrix?: CapabilityMatrix): boolean;
+/**
+ * Whether the HUD exists at all. Outside development a deployed tier also
+ * needs its overlay to set `NEXT_PUBLIC_HUD_ENABLED=true`.
+ */
+declare function isHudVisible(env: HudEnv, enabled?: boolean): boolean;
+//#endregion
+//#region src/plugins/access/access.d.ts
+type HudAccess = "open" | "password" | "flag" | "denied";
+/**
+ * httpOnly cookie holding the signed unlock token. `__Host-` makes browsers
+ * refuse it unless it is Secure, host-only and on `/`, so a sibling subdomain
+ * cannot set or shadow it.
+ */
+declare const HUD_UNLOCK_COOKIE = "__Host-hud-unlock";
+declare function resolveHudAccess(env: HudEnv): HudAccess;
+/** Whether this tier needs a valid unlock cookie before any HUD data flows. */
+declare function hudRequiresUnlock(access: HudAccess): boolean;
+/**
+ * Mints an unlock token for `env`, `<issuedAt>.<hmac>`. The issue time is in
+ * the clear so expiry is verifiable without server state, and covered by the
+ * signature so it cannot be back-dated. `secret` is `HUD_ACCESS_SECRET` when
+ * set, the password otherwise.
+ */
+declare function signHudUnlockToken(secret: string, env: HudEnv, issuedAt?: number): Promise<string>;
+interface HudUnlockVerifyOptions {
+  now?: number;
+  ttlMs?: number;
+}
+declare function verifyHudUnlockToken(token: string | undefined, secret: string | undefined, env: HudEnv, options?: HudUnlockVerifyOptions): Promise<boolean>;
+//#endregion
+export { signHudUnlockToken as a, CAPABILITY_MATRIX as c, hasCapability as d, isHudVisible as f, resolveHudAccess as i, CapabilityMatrixOverride as l, HudAccess as n, verifyHudUnlockToken as o, hudRequiresUnlock as r, ACCESS_UNLOCK_CAPABILITY as s, HUD_UNLOCK_COOKIE as t, HUD_CAPABILITIES as u };

package/dist/capabilities-CjulXFQX.js

@@ -0,0 +1,189 @@
+//#region src/plugins/access/access.ts
+/**
+* httpOnly cookie holding the signed unlock token. `__Host-` makes browsers
+* refuse it unless it is Secure, host-only and on `/`, so a sibling subdomain
+* cannot set or shadow it.
+*/
+const HUD_UNLOCK_COOKIE = "__Host-hud-unlock";
+/** Unlock lifetime per tier. Production is deliberately the shortest window. */
+const HUD_UNLOCK_TTL_MS = {
+	open: 0,
+	password: 432e5,
+	flag: 72e5,
+	denied: 0
+};
+function resolveHudAccess(env) {
+	if (env === "disabled") return "denied";
+	if (env === "development") return "open";
+	if (env === "production") return "flag";
+	return "password";
+}
+/** Whether this tier needs a valid unlock cookie before any HUD data flows. */
+function hudRequiresUnlock(access) {
+	return access === "password" || access === "flag";
+}
+function hudUnlockTtlMs(access) {
+	return HUD_UNLOCK_TTL_MS[access];
+}
+const encoder = new TextEncoder();
+/**
+* The HMAC key is never the secret itself: HKDF derives one per tier, so a
+* cookie minted on staging does not verify on production even when both
+* share a password.
+*/
+async function signingKey(secret, env) {
+	const material = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveKey"]);
+	return crypto.subtle.deriveKey({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: encoder.encode("@hansenexus/hud"),
+		info: encoder.encode(`hud-unlock:${env}`)
+	}, material, {
+		name: "HMAC",
+		hash: "SHA-256",
+		length: 256
+	}, false, ["sign"]);
+}
+async function hmacHex(secret, env, issuedAt) {
+	const key = await signingKey(secret, env);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${env}.${issuedAt}`));
+	return Array.from(new Uint8Array(signature)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Length-independent, constant-time comparison of two strings. */
+function timingSafeEqual(a, b) {
+	const length = Math.max(a.length, b.length);
+	let diff = a.length ^ b.length;
+	for (let i = 0; i < length; i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+	return diff === 0;
+}
+/**
+* Mints an unlock token for `env`, `<issuedAt>.<hmac>`. The issue time is in
+* the clear so expiry is verifiable without server state, and covered by the
+* signature so it cannot be back-dated. `secret` is `HUD_ACCESS_SECRET` when
+* set, the password otherwise.
+*/
+async function signHudUnlockToken(secret, env, issuedAt = Date.now()) {
+	return `${issuedAt}.${await hmacHex(secret, env, String(issuedAt))}`;
+}
+async function verifyHudUnlockToken(token, secret, env, options = {}) {
+	if (!token || !secret) return false;
+	const separator = token.indexOf(".");
+	if (separator <= 0) return false;
+	const issuedAtRaw = token.slice(0, separator);
+	const signature = token.slice(separator + 1);
+	const issuedAt = Number(issuedAtRaw);
+	if (!Number.isSafeInteger(issuedAt) || issuedAt <= 0) return false;
+	const now = options.now ?? Date.now();
+	const ttlMs = options.ttlMs ?? HUD_UNLOCK_TTL_MS.flag;
+	const age = now - issuedAt;
+	if (age < 0 || age > ttlMs) return false;
+	return timingSafeEqual(signature, await hmacHex(secret, env, issuedAtRaw));
+}
+/** Parses one cookie out of a raw `Cookie:` header. */
+function readCookie(header, name) {
+	if (!header) return void 0;
+	for (const part of header.split(";")) {
+		const trimmed = part.trim();
+		if (trimmed.startsWith(`${name}=`)) try {
+			return decodeURIComponent(trimmed.slice(name.length + 1));
+		} catch {
+			return;
+		}
+	}
+}
+/** Serialized `Set-Cookie` value for the unlock token, or its removal. */
+function hudUnlockCookieString(token, ttlMs) {
+	const base = `${HUD_UNLOCK_COOKIE}=${token ?? ""}; Path=/; HttpOnly; SameSite=Strict; Secure`;
+	return token ? `${base}; Max-Age=${Math.floor(ttlMs / 1e3)}` : `${base}; Max-Age=0`;
+}
+//#endregion
+//#region src/plugins/access/capabilities.ts
+/** The capability vocabulary of the default matrix. Development grants these and any other. */
+const HUD_CAPABILITIES = [
+	"observe.app",
+	"observe.estate",
+	"cicd.read",
+	"cicd.trigger",
+	"inject.seed",
+	"mock.toggle",
+	"auth.impersonate",
+	"dispatch.local",
+	"dispatch.hermes",
+	"variants.switch",
+	"variants.vote",
+	"variants.generate",
+	"state.force"
+];
+/**
+* The access plugin's own capability. The guard lets the unlock route through
+* on every enabled tier, so it never needs a matrix entry; nothing else may use it.
+*/
+const ACCESS_UNLOCK_CAPABILITY = "access.unlock";
+/**
+* Default-deny capability matrix. Client filtering is convenience only: the
+* guard re-checks every route against the same matrix server side.
+* Staging's `auth.impersonate` is further flag-gated by the plugin that uses it.
+*/
+const CAPABILITY_MATRIX = {
+	development: HUD_CAPABILITIES,
+	staging: [
+		"observe.app",
+		"observe.estate",
+		"cicd.read",
+		"mock.toggle",
+		"auth.impersonate",
+		"variants.switch",
+		"variants.vote"
+	],
+	preview: [
+		"observe.app",
+		"observe.estate",
+		"cicd.read",
+		"mock.toggle",
+		"variants.switch",
+		"variants.vote"
+	],
+	production: [
+		"observe.app",
+		"observe.estate",
+		"cicd.read"
+	],
+	disabled: []
+};
+/**
+* The default matrix with an app's tier lists swapped in. `access.unlock` is
+* stripped from them: it is the guard's exemption, never a grant.
+*/
+function resolveMatrix(override = {}) {
+	const matrix = { ...CAPABILITY_MATRIX };
+	for (const [tier, list] of Object.entries(override)) if (list) matrix[tier] = list.filter((capability) => capability !== ACCESS_UNLOCK_CAPABILITY);
+	return matrix;
+}
+/** Core assumes development, so development grants every capability, listed or not. */
+function hasCapability(env, capability, matrix = CAPABILITY_MATRIX) {
+	if (env === "disabled") return false;
+	if (env === "development") return true;
+	return matrix[env].includes(capability);
+}
+/**
+* Whether the HUD exists at all. Outside development a deployed tier also
+* needs its overlay to set `NEXT_PUBLIC_HUD_ENABLED=true`.
+*/
+function isHudVisible(env, enabled = process.env.NEXT_PUBLIC_HUD_ENABLED === "true") {
+	if (env === "disabled") return false;
+	if (env === "development") return true;
+	return enabled;
+}
+const ENVS = [
+	"development",
+	"preview",
+	"staging",
+	"production",
+	"disabled"
+];
+/** Narrows the loader's env string; anything unrecognised is treated as disabled. */
+function toHudEnv(env) {
+	return ENVS.includes(env) ? env : "disabled";
+}
+//#endregion
+export { isHudVisible as a, HUD_UNLOCK_COOKIE as c, hudUnlockTtlMs as d, readCookie as f, verifyHudUnlockToken as g, timingSafeEqual as h, hasCapability as i, hudRequiresUnlock as l, signHudUnlockToken as m, CAPABILITY_MATRIX as n, resolveMatrix as o, resolveHudAccess as p, HUD_CAPABILITIES as r, toHudEnv as s, ACCESS_UNLOCK_CAPABILITY as t, hudUnlockCookieString as u };

package/dist/define-hud-BBzsSl8b.d.ts

@@ -0,0 +1,36 @@
+import { o as HudPlugin, r as HudCapability } from "./plugins-CQ_0w1ot.js";
+import { ComponentType } from "react";
+//#region src/core/define-hud.d.ts
+interface DefineHudOptions {
+  /** App slug: labels the pill and keys the persisted layout. */
+  app: string;
+  /** Client halves (`@hansenexus/hud/plugins/<id>`), in pill order. */
+  plugins: readonly HudPlugin[];
+  /** Base path of the catch-all route serving `createHudHandler`. Default "/api/hud". */
+  apiBase?: string;
+  /** Capability check. Default: grant all (core assumes development). */
+  can?: (capability: HudCapability) => boolean;
+}
+/** Props the loader passes in at mount time. */
+interface HudMountProps {
+  /** Badge at the start of the pill. Default "DEV". */
+  envLabel?: string;
+  /**
+   * Tier the loader resolved. Default "development". Any other tier renders
+   * nothing unless a plugin brings `access`.
+   */
+  env?: string;
+}
+/**
+ * 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.
+ */
+declare function defineHud({ app, plugins, apiBase, can }: DefineHudOptions): ComponentType<HudMountProps>;
+//#endregion
+export { HudMountProps as n, defineHud as r, DefineHudOptions as t };

package/dist/env-DfxpPfs9.js

@@ -0,0 +1,28 @@
+//#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
+export { resolveHudEnv as n, hudEnvLabel as t };

package/dist/env-vEjyJfPW.d.ts

@@ -0,0 +1,17 @@
+//#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.
+ */
+declare function resolveHudEnv(): HudEnv;
+declare function hudEnvLabel(env?: HudEnv): string;
+//#endregion
+export { hudEnvLabel as n, resolveHudEnv as r, HudEnv as t };