@hansenexus/hud 0.1.0

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "@hansenexus/hud",
+  "version": "0.1.0",
+  "description": "Dev HUD for React apps: drawer, panels, capability-gated access.",
+  "license": "MIT",
+  "files": [
+    "**/*.js",
+    "**/*.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "import": "./index.js"
+    },
+    "./hud": {
+      "types": "./hud.d.mts",
+      "import": "./hud.js"
+    },
+    "./hud-provider": {
+      "types": "./hud-provider.d.mts",
+      "import": "./hud-provider.js"
+    },
+    "./lazy-panel": {
+      "types": "./lazy-panel.d.mts",
+      "import": "./lazy-panel.js"
+    },
+    "./state-boundary": {
+      "types": "./state-boundary.d.mts",
+      "import": "./state-boundary.js"
+    },
+    "./core/mock-cookie": {
+      "types": "./core/mock-cookie.d.mts",
+      "import": "./core/mock-cookie.js"
+    },
+    "./core/api-types": {
+      "types": "./core/api-types.d.mts",
+      "import": "./core/api-types.js"
+    },
+    "./core/capabilities": {
+      "types": "./core/capabilities.d.mts",
+      "import": "./core/capabilities.js"
+    },
+    "./core/capture-buffer": {
+      "types": "./core/capture-buffer.d.mts",
+      "import": "./core/capture-buffer.js"
+    },
+    "./core/types": {
+      "types": "./core/types.d.mts",
+      "import": "./core/types.js"
+    },
+    "./core/access": {
+      "types": "./core/access.d.mts",
+      "import": "./core/access.js"
+    },
+    "./core/force-state": {
+      "types": "./core/force-state.d.mts",
+      "import": "./core/force-state.js"
+    },
+    "./panels/tokens-panel": {
+      "types": "./panels/tokens-panel.d.mts",
+      "import": "./panels/tokens-panel.js"
+    },
+    "./panels/force-state-panel": {
+      "types": "./panels/force-state-panel.d.mts",
+      "import": "./panels/force-state-panel.js"
+    },
+    "./panels/role-switcher-panel": {
+      "types": "./panels/role-switcher-panel.d.mts",
+      "import": "./panels/role-switcher-panel.js"
+    },
+    "./panels/debug-info-panel": {
+      "types": "./panels/debug-info-panel.d.mts",
+      "import": "./panels/debug-info-panel.js"
+    },
+    "./panels/sessions-panel": {
+      "types": "./panels/sessions-panel.d.mts",
+      "import": "./panels/sessions-panel.js"
+    },
+    "./panels/network-console-panel": {
+      "types": "./panels/network-console-panel.d.mts",
+      "import": "./panels/network-console-panel.js"
+    },
+    "./panels/feature-flags-panel": {
+      "types": "./panels/feature-flags-panel.d.mts",
+      "import": "./panels/feature-flags-panel.js"
+    },
+    "./panels/mock-seed-panel": {
+      "types": "./panels/mock-seed-panel.d.mts",
+      "import": "./panels/mock-seed-panel.js"
+    },
+    "./panels/vitals-panel": {
+      "types": "./panels/vitals-panel.d.mts",
+      "import": "./panels/vitals-panel.js"
+    },
+    "./panels/info-row": {
+      "types": "./panels/info-row.d.mts",
+      "import": "./panels/info-row.js"
+    },
+    "./panels/cicd-panel": {
+      "types": "./panels/cicd-panel.d.mts",
+      "import": "./panels/cicd-panel.js"
+    },
+    "./panels/variants-panel": {
+      "types": "./panels/variants-panel.d.mts",
+      "import": "./panels/variants-panel.js"
+    },
+    "./panels/unlock-panel": {
+      "types": "./panels/unlock-panel.d.mts",
+      "import": "./panels/unlock-panel.js"
+    },
+    "./panels/env-info-panel": {
+      "types": "./panels/env-info-panel.d.mts",
+      "import": "./panels/env-info-panel.js"
+    },
+    "./panels/dispatch-panel": {
+      "types": "./panels/dispatch-panel.d.mts",
+      "import": "./panels/dispatch-panel.js"
+    },
+    "./server/guard": {
+      "types": "./server/guard.d.mts",
+      "import": "./server/guard.js"
+    },
+    "./server/unlock": {
+      "types": "./server/unlock.d.mts",
+      "import": "./server/unlock.js"
+    }
+  },
+  "dependencies": {
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.563.0",
+    "motion": "^12.29.2",
+    "tailwind-merge": "^3.4.0",
+    "web-vitals": "^5.2.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}

package/panels/cicd-panel.d.mts

@@ -0,0 +1,9 @@
+import * as react from 'react';
+
+/**
+ * CI/CD + deploy state via the hud hub: the deployed image plus recent
+ * GitHub Actions runs, each row labelled with its source.
+ */
+declare function CicdPanel(): react.JSX.Element | null;
+
+export { CicdPanel };

package/panels/cicd-panel.js

@@ -0,0 +1,13 @@
+import {
+  CicdPanel
+} from "../chunk-zzrpd92r.js";
+import"../chunk-xezxydm3.js";
+import"../chunk-wspz08q7.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-babjpqkb.js";
+import"../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  CicdPanel
+};

package/panels/debug-info-panel.d.mts

@@ -0,0 +1,21 @@
+import * as react from 'react';
+
+interface HudUserInfo {
+    name?: string;
+    email?: string;
+    id?: string;
+    role?: string;
+    /** App-specific extras (organization, tier, locale, …). */
+    extra?: Record<string, string>;
+}
+interface DebugInfoPanelProps {
+    user?: HudUserInfo;
+    isLoading?: boolean;
+}
+/**
+ * Session + environment snapshot. Harvested from nexus-lms' dev toolbar and
+ * genericized: the app feeds its user via props instead of app hooks.
+ */
+declare function DebugInfoPanel({ user, isLoading }: DebugInfoPanelProps): react.JSX.Element;
+
+export { DebugInfoPanel, type DebugInfoPanelProps, type HudUserInfo };

package/panels/debug-info-panel.js

@@ -0,0 +1,9 @@
+import {
+  DebugInfoPanel
+} from "../chunk-8tam7r3h.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  DebugInfoPanel
+};

package/panels/dispatch-panel.d.mts

@@ -0,0 +1,10 @@
+import * as react from 'react';
+
+/**
+ * Element grabber → agent dispatch. Local Claude runs go through docket via
+ * the bridge (no second dispatcher); queue markers are the human-in-loop
+ * fallback; Hermes goes through the console hub.
+ */
+declare function DispatchPanel(): react.JSX.Element;
+
+export { DispatchPanel };

package/panels/dispatch-panel.js

@@ -0,0 +1,14 @@
+import {
+  DispatchPanel
+} from "../chunk-6gw4x08j.js";
+import"../chunk-50pq4sg6.js";
+import"../chunk-82nm9wcg.js";
+import"../chunk-wspz08q7.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-babjpqkb.js";
+import"../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  DispatchPanel
+};

package/panels/env-info-panel.d.mts

@@ -0,0 +1,9 @@
+import * as react from 'react';
+
+/**
+ * What runs here right now: app, resolved hud env, build context, and the
+ * live capability matrix column — the canonical first tab of every hud.
+ */
+declare function EnvInfoPanel(): react.JSX.Element;
+
+export { EnvInfoPanel };

package/panels/env-info-panel.js

@@ -0,0 +1,12 @@
+import {
+  EnvInfoPanel
+} from "../chunk-0cj8dkk7.js";
+import"../chunk-wspz08q7.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-babjpqkb.js";
+import"../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  EnvInfoPanel
+};

package/panels/feature-flags-panel.d.mts

@@ -0,0 +1,26 @@
+import * as react from 'react';
+
+interface HudFlagDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+    category?: string;
+    defaultValue: boolean;
+    enabled: boolean;
+}
+interface HudFlagsAdapter {
+    flags: HudFlagDescriptor[];
+    isLoading?: boolean;
+    onToggle: (flagId: string) => Promise<void> | void;
+}
+/**
+ * Feature-flag switches over an app-provided adapter. Harvested from
+ * nexus-lms' dev toolbar; the per-app FLAG_REGISTRY + admin hook moved
+ * behind `HudFlagsAdapter` (flag registries are still per-app — see the
+ * hud plan's deferred consolidation item).
+ */
+declare function FeatureFlagsPanel({ adapter }: {
+    adapter: HudFlagsAdapter;
+}): react.JSX.Element;
+
+export { FeatureFlagsPanel, type HudFlagDescriptor, type HudFlagsAdapter };

package/panels/feature-flags-panel.js

@@ -0,0 +1,9 @@
+import {
+  FeatureFlagsPanel
+} from "../chunk-71se605m.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  FeatureFlagsPanel
+};

package/panels/force-state-panel.d.mts

@@ -0,0 +1,11 @@
+import * as react from 'react';
+
+/**
+ * Toggles every mounted state boundary (`StateBoundary` from
+ * `@hn-monorepo/hud/state-boundary`) between its real state and a forced
+ * loading, empty or error. Toggles live in memory: a reload returns every
+ * boundary to auto, so a forgotten toggle cannot outlive the tab's page.
+ */
+declare function ForceStatePanel(): react.JSX.Element;
+
+export { ForceStatePanel };

package/panels/force-state-panel.js

@@ -0,0 +1,113 @@
+import {
+  InfoRow,
+  PanelSection
+} from "../chunk-kyeb6qeq.js";
+import {
+  Badge,
+  Button
+} from "../chunk-xztw0xyt.js";
+import {
+  FORCED_STATES,
+  FORCE_STATE_PARAM,
+  getForceStateStore,
+  resolveForcedState
+} from "../chunk-c5y856ad.js";
+import"../chunk-5gtx3pza.js";
+
+// panels/force-state-panel.tsx
+import { Layers } from "lucide-react";
+import { useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+"use client";
+var CHOICES = [null, ...FORCED_STATES];
+function subscribe(listener) {
+  return getForceStateStore().subscribe(listener);
+}
+function getSnapshot() {
+  return getForceStateStore().getSnapshot();
+}
+function ForceStatePanel() {
+  const store = getForceStateStore();
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const hasOverrides = Object.keys(snapshot.overrides).length > 0;
+  return /* @__PURE__ */ jsxs("div", {
+    className: "space-y-4 p-3",
+    "data-hud-force-state": "",
+    children: [
+      /* @__PURE__ */ jsxs(PanelSection, {
+        icon: Layers,
+        title: "State boundaries",
+        children: [
+          snapshot.boundaries.length === 0 ? /* @__PURE__ */ jsx("p", {
+            className: "px-2 text-[10px] text-muted-foreground",
+            children: "No state boundary on this page. Wrap a query branch in StateBoundary to list it here."
+          }) : snapshot.boundaries.map((boundary) => {
+            const override = snapshot.overrides[boundary.id] ?? null;
+            const effective = resolveForcedState(snapshot, boundary);
+            return /* @__PURE__ */ jsxs("div", {
+              className: "space-y-1 px-2 py-1",
+              children: [
+                /* @__PURE__ */ jsxs("div", {
+                  className: "flex items-center justify-between gap-2",
+                  children: [
+                    /* @__PURE__ */ jsxs("span", {
+                      className: "truncate font-mono text-[10px]",
+                      children: [
+                        boundary.parentId ? "↳ " : "",
+                        boundary.id
+                      ]
+                    }),
+                    /* @__PURE__ */ jsx(Badge, {
+                      variant: effective ? "default" : "outline",
+                      className: "text-[9px]",
+                      children: effective ?? "real"
+                    })
+                  ]
+                }),
+                /* @__PURE__ */ jsx("div", {
+                  className: "flex gap-1",
+                  children: CHOICES.map((choice) => /* @__PURE__ */ jsx(Button, {
+                    size: "xs",
+                    variant: override === choice ? "default" : "outline",
+                    className: "h-6 flex-1 px-1 text-[10px]",
+                    onClick: () => store.force(boundary.id, choice),
+                    children: choice ?? "auto"
+                  }, choice ?? "auto"))
+                })
+              ]
+            }, boundary.id);
+          }),
+          hasOverrides && /* @__PURE__ */ jsx(Button, {
+            size: "xs",
+            variant: "ghost",
+            className: "h-6 w-full text-[10px]",
+            onClick: () => store.clearOverrides(),
+            children: "Reset all to auto"
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs(PanelSection, {
+        title: "URL param",
+        children: [
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: `?${FORCE_STATE_PARAM}=`,
+            value: snapshot.param ? `${snapshot.param.target ? `${snapshot.param.target}:` : ""}${snapshot.param.state}` : "not set"
+          }),
+          /* @__PURE__ */ jsxs("p", {
+            className: "px-2 text-[10px] text-muted-foreground",
+            children: [
+              "?",
+              FORCE_STATE_PARAM,
+              "=loading|empty|error forces the top-level boundaries; ?",
+              FORCE_STATE_PARAM,
+              "=<id>:error targets one. A panel toggle wins over the param."
+            ]
+          })
+        ]
+      })
+    ]
+  });
+}
+export {
+  ForceStatePanel
+};

package/panels/info-row.d.mts

@@ -0,0 +1,21 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { LucideIcon } from 'lucide-react';
+
+declare function PanelSection({ icon: Icon, title, children, }: {
+    icon?: LucideIcon;
+    title: string;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function InfoRow({ label, value, copyable, }: {
+    label: string;
+    value: string;
+    copyable?: boolean;
+}): react.JSX.Element;
+declare function ShortcutRow({ keys, label }: {
+    keys: string[];
+    label: string;
+}): react.JSX.Element;
+declare function LoadingSpinner(): react.JSX.Element;
+
+export { InfoRow, LoadingSpinner, PanelSection, ShortcutRow };

package/panels/info-row.js

@@ -0,0 +1,14 @@
+import {
+  InfoRow,
+  LoadingSpinner,
+  PanelSection,
+  ShortcutRow
+} from "../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  ShortcutRow,
+  PanelSection,
+  LoadingSpinner,
+  InfoRow
+};

package/panels/mock-seed-panel.d.mts

@@ -0,0 +1,15 @@
+import * as react from 'react';
+import { HudSeedDescriptor } from '../core/api-types.mjs';
+
+/**
+ * Runtime mock toggle + data seeding. The mock switch writes the `hud-mock`
+ * cookie and reloads — the server layout re-reads it and passes `forceMock`
+ * into the app's ConvexClientProvider, so SSR and client always agree. Seeds
+ * run on the dev machine through the bridge (`bunx convex run`), which keeps
+ * remote-refusal guardrails in seed functions intact.
+ */
+declare function MockSeedPanel({ seeds }: {
+    seeds?: HudSeedDescriptor[];
+}): react.JSX.Element;
+
+export { MockSeedPanel };

package/panels/mock-seed-panel.js

@@ -0,0 +1,14 @@
+import {
+  MockSeedPanel
+} from "../chunk-k0vr8dsy.js";
+import"../chunk-50pq4sg6.js";
+import"../chunk-wspz08q7.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-hc2g0n35.js";
+import"../chunk-babjpqkb.js";
+import"../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  MockSeedPanel
+};

package/panels/network-console-panel.d.mts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+
+/** Console + fetch + long-task capture (ring buffer, newest last). */
+declare function NetworkConsolePanel(): react.JSX.Element;
+
+export { NetworkConsolePanel };

package/panels/network-console-panel.js

@@ -0,0 +1,9 @@
+import {
+  NetworkConsolePanel
+} from "../chunk-tf774c4w.js";
+import"../chunk-24vrg16w.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  NetworkConsolePanel
+};

package/panels/role-switcher-panel.d.mts

@@ -0,0 +1,28 @@
+import * as react from 'react';
+
+interface HudRoleDescriptor {
+    id: string;
+    label: string;
+    /** Hierarchy level shown as "Lvl n"; omit to hide. */
+    level?: number;
+    /** Badge classes for the current-role chip (tone is app-specific). */
+    badgeClassName?: string;
+}
+interface HudRoleAdapter {
+    roles: HudRoleDescriptor[];
+    currentRoleId?: string;
+    currentUserLabel?: string;
+    isLoading?: boolean;
+    /** Perform the switch (Convex mutation, dev-login POST, …). May throw. */
+    onSwitch: (roleId: string) => Promise<void> | void;
+}
+/**
+ * Role switcher over an app-provided adapter. Harvested from nexus-lms'
+ * dev toolbar; the Convex mutation moved behind `onSwitch` so any auth
+ * backend (or dev-routes' `useDevRoleLogin`) can drive it.
+ */
+declare function RoleSwitcherPanel({ adapter }: {
+    adapter: HudRoleAdapter;
+}): react.JSX.Element;
+
+export { type HudRoleAdapter, type HudRoleDescriptor, RoleSwitcherPanel };

package/panels/role-switcher-panel.js

@@ -0,0 +1,9 @@
+import {
+  RoleSwitcherPanel
+} from "../chunk-6jt8yg4m.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  RoleSwitcherPanel
+};

package/panels/sessions-panel.d.mts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+
+/** Active Claude Code sessions on this machine, via the local bridge. */
+declare function SessionsPanel(): react.JSX.Element;
+
+export { SessionsPanel };

package/panels/sessions-panel.js

@@ -0,0 +1,13 @@
+import {
+  SessionsPanel
+} from "../chunk-t9eh4t0b.js";
+import"../chunk-50pq4sg6.js";
+import"../chunk-wspz08q7.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-babjpqkb.js";
+import"../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  SessionsPanel
+};

package/panels/tokens-panel.d.mts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+
+interface HudTokenDescriptor {
+    /** CSS custom property, including the leading dashes (e.g. --bauhaus-primary-ink). */
+    cssVar: string;
+    /** Short display label; defaults to the var name without its prefix. */
+    label?: string;
+}
+interface HudTokenGroup {
+    label: string;
+    tokens: HudTokenDescriptor[];
+    /**
+     * Scope attribute the design system hangs its tokens on, with optional
+     * value — e.g. { attribute: "data-bauhaus" } or
+     * { attribute: "data-direction", value: "glass-vercel" }. Rendered onto the
+     * group's swatch container so scoped var() lookups resolve. Omit for
+     * :root-scoped systems.
+     */
+    scope?: {
+        attribute: string;
+        value?: string;
+    };
+}
+interface HudTokensAdapter {
+    groups: HudTokenGroup[];
+    /** Where the tokens live, shown as a hint (e.g. packages/ui/styles/bauhaus-tokens.css). */
+    sourceHint?: string;
+}
+/**
+ * Live design-token swatches: each tile paints `var(<token>)` inside the
+ * group's scope attribute, so what renders IS the resolved value in the
+ * current theme — no hardcoded copies to drift. Click copies the var name.
+ */
+declare function TokensPanel({ adapter }: {
+    adapter: HudTokensAdapter;
+}): react.JSX.Element;
+
+export { type HudTokenDescriptor, type HudTokenGroup, type HudTokensAdapter, TokensPanel };

package/panels/tokens-panel.js

@@ -0,0 +1,9 @@
+import {
+  TokensPanel
+} from "../chunk-nm82wr8r.js";
+import"../chunk-kyeb6qeq.js";
+import"../chunk-xztw0xyt.js";
+import"../chunk-5gtx3pza.js";
+export {
+  TokensPanel
+};

package/panels/unlock-panel.d.mts

@@ -0,0 +1,33 @@
+import * as react from 'react';
+import { HudAccess } from '../core/access.mjs';
+import { HudEnv } from '../core/types.mjs';
+import 'lucide-react';
+
+type HudUnlockState = "checking" | "locked" | "unlocked" | "unconfigured";
+/**
+ * Unlock state for a deployed hud.
+ *
+ * The browser never sees the password or the token: the cookie is httpOnly
+ * and only the server can judge it, so this hook asks `${apiBase}/unlock`
+ * rather than reading anything locally. On a tier that needs no unlock it
+ * settles on `unlocked` without a request.
+ */
+declare function useHudUnlock(apiBase: string, access: HudAccess): {
+    state: HudUnlockState;
+    error: string | null;
+    unlock: (password: string) => Promise<boolean>;
+};
+interface HudUnlockPanelProps {
+    env: HudEnv;
+    state: HudUnlockState;
+    error: string | null;
+    onUnlock: (password: string) => Promise<boolean>;
+}
+/**
+ * The only panel a locked deployed hud shows. Everything else, including
+ * the read-only production panels, stays behind it, because the panels
+ * themselves fetch from `/api/hud/*` routes that would refuse anyway.
+ */
+declare function HudUnlockPanel({ env, state, error, onUnlock }: HudUnlockPanelProps): react.JSX.Element;
+
+export { HudUnlockPanel, type HudUnlockPanelProps, type HudUnlockState, useHudUnlock };