@hansenexus/hud 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hansenexus GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @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.
+
+## Install
+
+```sh
+npm install @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.
+
+## 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 },
+];
+
+export function DevHud() {
+  return <Hud config={{ appSlug: "my-app" }} panels={panels} />;
+}
+```
+
+Mount it only in development builds, for example behind `import.meta.env.DEV` and a lazy import.
+
+## Tailwind v4
+
+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:
+
+```css
+@source "../node_modules/@hansenexus/hud";
+```
+
+The path is relative to that stylesheet. If a panel renders unstyled, this line is missing
+or points at the wrong place.
+
+## License
+
+MIT

package/chunk-0cj8dkk7.js

@@ -0,0 +1,127 @@
+import {
+  useHud
+} from "./chunk-wspz08q7.js";
+import {
+  InfoRow,
+  PanelSection,
+  ShortcutRow
+} from "./chunk-kyeb6qeq.js";
+import {
+  Badge
+} from "./chunk-xztw0xyt.js";
+import {
+  CAPABILITY_MATRIX
+} from "./chunk-babjpqkb.js";
+import {
+  HUD_CAPABILITIES
+} from "./chunk-v086j53b.js";
+
+// panels/env-info-panel.tsx
+import { Boxes, Info, Monitor, ShieldCheck } from "lucide-react";
+import { version as reactVersion } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+"use client";
+function EnvInfoPanel() {
+  const { config, env, can } = useHud();
+  return /* @__PURE__ */ jsxs("div", {
+    className: "space-y-4",
+    children: [
+      /* @__PURE__ */ jsxs(PanelSection, {
+        icon: Boxes,
+        title: "App",
+        children: [
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "App",
+            value: config.appSlug
+          }),
+          /* @__PURE__ */ jsxs("div", {
+            className: "flex items-center justify-between px-2 py-1",
+            children: [
+              /* @__PURE__ */ jsx("span", {
+                className: "text-[10px] text-muted-foreground",
+                children: "hud env"
+              }),
+              /* @__PURE__ */ jsx(Badge, {
+                variant: "outline",
+                className: "h-4 px-1.5 font-mono text-[10px] uppercase",
+                children: env
+              })
+            ]
+          }),
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "Origin",
+            value: typeof window !== "undefined" ? window.location.origin : "—",
+            copyable: true
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs(PanelSection, {
+        icon: Monitor,
+        title: "Build",
+        children: [
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "NODE_ENV",
+            value: "production"
+          }),
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "React",
+            value: reactVersion
+          }),
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "Convex URL",
+            value: process.env.NEXT_PUBLIC_CONVEX_URL ?? "not set",
+            copyable: true
+          }),
+          /* @__PURE__ */ jsx(InfoRow, {
+            label: "App URL",
+            value: process.env.NEXT_PUBLIC_APP_URL ?? "not set"
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsxs(PanelSection, {
+        icon: ShieldCheck,
+        title: `Capabilities · ${env}`,
+        children: [
+          /* @__PURE__ */ jsx("div", {
+            className: "grid grid-cols-2 gap-x-4",
+            children: HUD_CAPABILITIES.map((capability) => {
+              const granted = can(capability);
+              return /* @__PURE__ */ jsxs("div", {
+                className: "flex items-center justify-between px-2 py-0.5",
+                title: granted ? undefined : `denied in ${env} (see CAPABILITY_MATRIX in core/capabilities.ts)`,
+                children: [
+                  /* @__PURE__ */ jsx("span", {
+                    className: `font-mono text-[10px] ${granted ? "" : "text-muted-foreground/50 line-through"}`,
+                    children: capability
+                  }),
+                  /* @__PURE__ */ jsx("span", {
+                    className: `h-1.5 w-1.5 rounded-full ${granted ? "bg-emerald-500" : "bg-muted-foreground/20"}`
+                  })
+                ]
+              }, capability);
+            })
+          }),
+          /* @__PURE__ */ jsxs("p", {
+            className: "px-2 text-[10px] text-muted-foreground/60",
+            children: [
+              CAPABILITY_MATRIX[env].length,
+              "/",
+              HUD_CAPABILITIES.length,
+              " granted — default deny, server routes re-check independently."
+            ]
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsx(PanelSection, {
+        icon: Info,
+        title: "Shortcuts",
+        children: /* @__PURE__ */ jsx(ShortcutRow, {
+          keys: ["⌘", "⇧", "H"],
+          label: "Toggle hud"
+        })
+      })
+    ]
+  });
+}
+
+export { EnvInfoPanel };

package/chunk-1atxwdhw.js

@@ -0,0 +1,48 @@
+import {
+  HUD_UNLOCK_COOKIE,
+  hudRequiresUnlock,
+  hudUnlockTtlMs,
+  readCookie,
+  resolveHudAccess,
+  verifyHudUnlockToken
+} from "./chunk-r06bpmy6.js";
+import {
+  hasCapability,
+  isHudVisible,
+  resolveHudEnv
+} from "./chunk-babjpqkb.js";
+
+// server/guard.ts
+async function checkHudRequest(request, capability) {
+  const env = resolveHudEnv();
+  if (!isHudVisible(env)) {
+    return { ok: false, status: 404, error: "not found" };
+  }
+  if (!hasCapability(env, capability)) {
+    return { ok: false, status: 403, error: `capability ${capability} is denied in ${env}` };
+  }
+  const access = resolveHudAccess(env);
+  if (!hudRequiresUnlock(access)) {
+    return { ok: true, env };
+  }
+  const password = process.env.HUD_ACCESS_PASSWORD;
+  if (!password) {
+    return { ok: false, status: 401, error: "hud unlock is not configured" };
+  }
+  const token = readCookie(request.headers.get("cookie"), HUD_UNLOCK_COOKIE);
+  const unlocked = await verifyHudUnlockToken(token, password, { ttlMs: hudUnlockTtlMs(access) });
+  if (!unlocked) {
+    return { ok: false, status: 401, error: "hud is locked" };
+  }
+  return { ok: true, env };
+}
+async function isHudRequestUnlocked(request) {
+  const access = resolveHudAccess();
+  if (!hudRequiresUnlock(access))
+    return true;
+  const password = process.env.HUD_ACCESS_PASSWORD;
+  const token = readCookie(request.headers.get("cookie"), HUD_UNLOCK_COOKIE);
+  return verifyHudUnlockToken(token, password, { ttlMs: hudUnlockTtlMs(access) });
+}
+
+export { checkHudRequest, isHudRequestUnlocked };

package/chunk-24vrg16w.js

@@ -0,0 +1,39 @@
+// core/capture-buffer.ts
+class CaptureBuffer {
+  entries = [];
+  snapshot = [];
+  listeners = new Set;
+  nextId = 1;
+  maxEntries;
+  constructor(maxEntries = 500) {
+    this.maxEntries = maxEntries;
+  }
+  push(input) {
+    const entry = { id: this.nextId++, ts: Date.now(), ...input };
+    this.entries.push(entry);
+    if (this.entries.length > this.maxEntries) {
+      this.entries.splice(0, this.entries.length - this.maxEntries);
+    }
+    this.emit();
+    return entry;
+  }
+  clear() {
+    if (this.entries.length === 0)
+      return;
+    this.entries = [];
+    this.emit();
+  }
+  getSnapshot = () => this.snapshot;
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  emit() {
+    this.snapshot = [...this.entries];
+    for (const listener of this.listeners)
+      listener();
+  }
+}
+var captureBuffer = new CaptureBuffer(500);
+
+export { CaptureBuffer, captureBuffer };

package/chunk-3j9sm249.js

@@ -0,0 +1,26 @@
+import {
+  LoadingSpinner
+} from "./chunk-kyeb6qeq.js";
+import {
+  hasCapability,
+  resolveHudEnv
+} from "./chunk-babjpqkb.js";
+
+// lazy-panel.tsx
+import { lazy, Suspense } from "react";
+import { jsx } from "react/jsx-runtime";
+"use client";
+function hudLazyPanel(meta, load, env = resolveHudEnv()) {
+  if (!hasCapability(env, meta.capability))
+    return null;
+  const Panel = lazy(async () => ({ default: await load() }));
+  return {
+    ...meta,
+    content: /* @__PURE__ */ jsx(Suspense, {
+      fallback: /* @__PURE__ */ jsx(LoadingSpinner, {}),
+      children: /* @__PURE__ */ jsx(Panel, {})
+    })
+  };
+}
+
+export { hudLazyPanel };

package/chunk-50pq4sg6.js

@@ -0,0 +1,41 @@
+// bridge-client.ts
+var cached;
+async function getBridgeInfo(apiBase) {
+  if (cached !== undefined)
+    return cached;
+  try {
+    const res = await fetch(`${apiBase}/bridge-info`, {
+      headers: { "x-hud-internal": "1" }
+    });
+    if (!res.ok) {
+      cached = null;
+      return null;
+    }
+    const info = await res.json();
+    const health = await fetch(`http://127.0.0.1:${info.port}/health`, {
+      headers: { "x-hud-internal": "1" },
+      signal: AbortSignal.timeout(1500)
+    }).catch(() => null);
+    cached = health?.ok ? info : null;
+    return cached;
+  } catch {
+    cached = null;
+    return null;
+  }
+}
+function resetBridgeInfo() {
+  cached = undefined;
+}
+async function bridgeFetch(info, path, init) {
+  return fetch(`http://127.0.0.1:${info.port}${path}`, {
+    ...init,
+    headers: {
+      ...init?.headers,
+      Authorization: `Bearer ${info.token}`,
+      "x-hud-internal": "1",
+      ...init?.body ? { "Content-Type": "application/json" } : {}
+    }
+  });
+}
+
+export { getBridgeInfo, resetBridgeInfo, bridgeFetch };

package/chunk-5gtx3pza.js

@@ -0,0 +1,9 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };

package/chunk-6gw4x08j.js

@@ -0,0 +1,264 @@
+import {
+  bridgeFetch,
+  getBridgeInfo
+} from "./chunk-50pq4sg6.js";
+import {
+  clearGrabbedPayload,
+  getGrabberState,
+  startGrab,
+  subscribeGrabber,
+  useDevDrawer
+} from "./chunk-82nm9wcg.js";
+import {
+  useHud
+} from "./chunk-wspz08q7.js";
+import {
+  LoadingSpinner,
+  PanelSection
+} from "./chunk-kyeb6qeq.js";
+import {
+  Badge,
+  Button
+} from "./chunk-xztw0xyt.js";
+
+// panels/dispatch-panel.tsx
+import { Crosshair, Send, X } from "lucide-react";
+import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+"use client";
+function DispatchPanel() {
+  const { config } = useHud();
+  const { closeDrawer } = useDevDrawer();
+  const grabber = useSyncExternalStore(subscribeGrabber, getGrabberState, getGrabberState);
+  const [bridge, setBridge] = useState(undefined);
+  const [target, setTarget] = useState("docket");
+  const [note, setNote] = useState("");
+  const [runs, setRuns] = useState([]);
+  const apiBase = config.apiBase ?? "/api/hud";
+  useEffect(() => {
+    let cancelled = false;
+    getBridgeInfo(apiBase).then((info) => {
+      if (cancelled)
+        return;
+      setBridge(info);
+      if (!info)
+        setTarget("hermes");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [apiBase]);
+  const payload = grabber.payload;
+  const targets = useMemo(() => [
+    {
+      id: "docket",
+      label: "Local Claude session (docket)",
+      detail: "worktree + claude -p via the bridge — events land on the docket board",
+      enabled: bridge != null,
+      disabledReason: "bridge not reachable (run `bun hud:bridge` in the repo)"
+    },
+    {
+      id: "queue",
+      label: "Queue marker (.claude/queue)",
+      detail: "human in the loop — the next Claude session picks it up",
+      enabled: bridge != null,
+      disabledReason: "bridge not reachable"
+    },
+    {
+      id: "hermes",
+      label: "Hermes (remote)",
+      detail: "via the console hub → hermes-dispatch workflow, tier balanced",
+      enabled: true,
+      disabledReason: ""
+    }
+  ], [bridge]);
+  async function send() {
+    if (!payload)
+      return;
+    const title = `${payload.anchor.label} — ${note.slice(0, 60) || "hud dispatch"}`;
+    const localId = `local-${Date.now()}`;
+    setRuns((prev) => [{ id: localId, title, target, status: "sending" }, ...prev]);
+    clearGrabbedPayload();
+    setNote("");
+    try {
+      let res;
+      if (target === "hermes") {
+        res = await fetch(`${apiBase}/dispatch`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "x-hud-internal": "1" },
+          body: JSON.stringify({ target, note, payload })
+        });
+      } else {
+        if (!bridge)
+          throw new Error("bridge not reachable");
+        res = await bridgeFetch(bridge, "/dispatch", {
+          method: "POST",
+          body: JSON.stringify({ target, note, payload })
+        });
+      }
+      const body = await res.json();
+      setRuns((prev) => prev.map((run) => run.id === localId ? {
+        ...run,
+        status: body.ok ? "dispatched" : "failed",
+        detail: body.runId ?? body.markerPath ?? body.error
+      } : run));
+    } catch (error) {
+      setRuns((prev) => prev.map((run) => run.id === localId ? {
+        ...run,
+        status: "failed",
+        detail: error instanceof Error ? error.message : "dispatch failed"
+      } : run));
+    }
+  }
+  return /* @__PURE__ */ jsxs("div", {
+    className: "space-y-4",
+    children: [
+      !payload && /* @__PURE__ */ jsx(PanelSection, {
+        icon: Crosshair,
+        title: "Grab an element",
+        children: /* @__PURE__ */ jsxs("div", {
+          className: "px-2",
+          children: [
+            /* @__PURE__ */ jsxs(Button, {
+              size: "sm",
+              className: "h-7 text-xs",
+              onClick: () => {
+                closeDrawer();
+                startGrab();
+              },
+              children: [
+                /* @__PURE__ */ jsx(Crosshair, {
+                  className: "mr-1.5 h-3.5 w-3.5"
+                }),
+                "Grab element"
+              ]
+            }),
+            /* @__PURE__ */ jsx("p", {
+              className: "mt-2 text-[10px] text-muted-foreground/60",
+              children: "Click any element on the page — selector, source hints, recent errors, and vitals become the dispatch payload."
+            })
+          ]
+        })
+      }),
+      payload && /* @__PURE__ */ jsx(PanelSection, {
+        icon: Send,
+        title: "Dispatch",
+        children: /* @__PURE__ */ jsxs("div", {
+          className: "space-y-2 px-2",
+          children: [
+            /* @__PURE__ */ jsx(PayloadPreview, {
+              payload,
+              onDiscard: clearGrabbedPayload
+            }),
+            /* @__PURE__ */ jsx("textarea", {
+              value: note,
+              onChange: (e) => setNote(e.target.value),
+              placeholder: "Instruction, e.g.: button feels heavy — try a ghost variant",
+              className: "min-h-[52px] w-full rounded-md border bg-muted/20 p-2 font-mono text-[11px] outline-none focus:ring-1 focus:ring-ring"
+            }),
+            /* @__PURE__ */ jsx("div", {
+              className: "space-y-1",
+              children: targets.map((t) => /* @__PURE__ */ jsxs("label", {
+                className: `flex cursor-pointer items-start gap-2 rounded-md border p-2 ${target === t.id ? "border-primary/60 bg-muted/30" : "border-border/50"} ${t.enabled ? "" : "cursor-not-allowed opacity-50"}`,
+                children: [
+                  /* @__PURE__ */ jsx("input", {
+                    type: "radio",
+                    name: "hud-dispatch-target",
+                    checked: target === t.id,
+                    disabled: !t.enabled,
+                    onChange: () => setTarget(t.id),
+                    className: "mt-0.5"
+                  }),
+                  /* @__PURE__ */ jsxs("span", {
+                    children: [
+                      /* @__PURE__ */ jsx("span", {
+                        className: "block text-xs font-medium",
+                        children: t.label
+                      }),
+                      /* @__PURE__ */ jsx("span", {
+                        className: "block text-[10px] text-muted-foreground",
+                        children: t.enabled ? t.detail : t.disabledReason
+                      })
+                    ]
+                  })
+                ]
+              }, t.id))
+            }),
+            /* @__PURE__ */ jsxs(Button, {
+              size: "sm",
+              className: "h-7 text-xs",
+              onClick: send,
+              children: [
+                /* @__PURE__ */ jsx(Send, {
+                  className: "mr-1.5 h-3 w-3"
+                }),
+                "Dispatch"
+              ]
+            })
+          ]
+        })
+      }),
+      bridge === undefined && /* @__PURE__ */ jsx(LoadingSpinner, {}),
+      runs.length > 0 && /* @__PURE__ */ jsx(PanelSection, {
+        title: "Dispatched from this session",
+        children: runs.map((run) => /* @__PURE__ */ jsxs("div", {
+          className: "flex items-center gap-2 px-2 py-1 font-mono text-[10.5px]",
+          children: [
+            /* @__PURE__ */ jsx(Badge, {
+              variant: "outline",
+              className: `h-4 px-1.5 text-[9px] ${run.status === "dispatched" ? "text-emerald-500" : run.status === "failed" ? "text-red-500" : "text-amber-500"}`,
+              children: run.status
+            }),
+            /* @__PURE__ */ jsx("span", {
+              className: "min-w-0 flex-1 truncate",
+              children: run.title
+            }),
+            /* @__PURE__ */ jsx("span", {
+              className: "text-muted-foreground/60",
+              children: run.target
+            }),
+            run.detail && /* @__PURE__ */ jsx("span", {
+              className: "max-w-[180px] truncate text-muted-foreground/60",
+              title: run.detail,
+              children: run.detail
+            })
+          ]
+        }, run.id))
+      })
+    ]
+  });
+}
+function PayloadPreview({
+  payload,
+  onDiscard
+}) {
+  return /* @__PURE__ */ jsxs("div", {
+    className: "rounded-md border bg-muted/20 p-2",
+    children: [
+      /* @__PURE__ */ jsxs("div", {
+        className: "flex items-center gap-2",
+        children: [
+          /* @__PURE__ */ jsx("span", {
+            className: "min-w-0 flex-1 truncate font-mono text-[11px]",
+            children: payload.anchor.label
+          }),
+          /* @__PURE__ */ jsx(Button, {
+            variant: "ghost",
+            size: "icon",
+            className: "h-5 w-5",
+            onClick: onDiscard,
+            children: /* @__PURE__ */ jsx(X, {
+              className: "h-3 w-3"
+            })
+          })
+        ]
+      }),
+      /* @__PURE__ */ jsx("pre", {
+        className: "mt-1 max-h-40 overflow-auto text-[9.5px] leading-relaxed text-muted-foreground",
+        children: JSON.stringify(payload, null, 2)
+      })
+    ]
+  });
+}
+
+export { DispatchPanel };