@hansenexus/hud 0.1.0

package/core/force-state.js

@@ -0,0 +1,21 @@
+import {
+  FORCED_STATES,
+  FORCE_STATE_MARKER,
+  FORCE_STATE_PARAM,
+  ForceStateStore,
+  forceStateParamFromSearch,
+  getForceStateStore,
+  parseForceStateParam,
+  resolveForcedState
+} from "../chunk-c5y856ad.js";
+import"../chunk-5gtx3pza.js";
+export {
+  resolveForcedState,
+  parseForceStateParam,
+  getForceStateStore,
+  forceStateParamFromSearch,
+  ForceStateStore,
+  FORCE_STATE_PARAM,
+  FORCE_STATE_MARKER,
+  FORCED_STATES
+};

package/core/mock-cookie.d.mts

@@ -0,0 +1,30 @@
+/**
+ * hud-mock cookie — the runtime mock-Convex toggle.
+ *
+ * SSR-consistency contract: the SERVER layout reads the cookie (next/headers)
+ * and passes the decision down as a `forceMock` prop to the app's
+ * ConvexClientProvider. The client never re-derives it during hydration, so
+ * server HTML and client render always agree. `isHudMockEnabled` is the single
+ * decision function both the layout (server) and any tooling use.
+ */
+declare const HUD_MOCK_COOKIE = "hud-mock";
+interface HudMockEnv {
+    /** process.env.NODE_ENV of the reading side. */
+    nodeEnv?: string;
+    /** NEXT_PUBLIC_HUD_ENABLED — the deployed-env opt-in flag. */
+    hudEnabled?: string;
+}
+/**
+ * Whether the mock override is active. The cookie only counts where the hud
+ * itself can exist (dev, or a deployment that explicitly opted in) — a stray
+ * cookie on production without the flag must be inert.
+ */
+declare function isHudMockEnabled(cookieValue: string | undefined, env: HudMockEnv): boolean;
+/** Serialized Set-Cookie/document.cookie string for the toggle. */
+declare function hudMockCookieString(enabled: boolean): string;
+/** Client-side read of the raw cookie value (panel display only, never render-gating). */
+declare function readHudMockCookie(): string | undefined;
+/** Client-side toggle. Takes effect on the next full load (the server re-reads it). */
+declare function setHudMockCookie(enabled: boolean): void;
+
+export { HUD_MOCK_COOKIE, type HudMockEnv, hudMockCookieString, isHudMockEnabled, readHudMockCookie, setHudMockCookie };

package/core/mock-cookie.js

@@ -0,0 +1,15 @@
+import {
+  HUD_MOCK_COOKIE,
+  hudMockCookieString,
+  isHudMockEnabled,
+  readHudMockCookie,
+  setHudMockCookie
+} from "../chunk-hc2g0n35.js";
+import"../chunk-5gtx3pza.js";
+export {
+  setHudMockCookie,
+  readHudMockCookie,
+  isHudMockEnabled,
+  hudMockCookieString,
+  HUD_MOCK_COOKIE
+};

package/core/types.d.mts

@@ -0,0 +1,59 @@
+import { LucideIcon } from 'lucide-react';
+import { ReactNode } from 'react';
+
+/**
+ * Where the hud believes it is running. Resolved by `resolveHudEnv()` —
+ * explicit `NEXT_PUBLIC_HUD_ENV` wins over heuristics because k3s deploys
+ * have no `VERCEL_ENV` (staging is only detectable if the overlay says so).
+ */
+type HudEnv = "development" | "preview" | "staging" | "production" | "disabled";
+/**
+ * Literal the CI bundle gate greps for in every app's client chunks
+ * (`scripts/ci/assert-no-hud-in-bundle.sh`). It is rendered as an attribute
+ * on the hud's chrome so a bundler cannot drop it while keeping the hud, and
+ * so the check has a marker that is unmistakably deliberate rather than an
+ * incidental string that a refactor could rename away.
+ */
+declare const HUD_BUNDLE_MARKER = "__HN_HUD_BUNDLE_MARKER__";
+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"];
+type HudCapability = (typeof HUD_CAPABILITIES)[number];
+interface HudPanel {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+    /** Required capability — the panel is dropped when the env's matrix denies it. */
+    capability: HudCapability;
+    content: ReactNode;
+    /** Lower sorts first in the tab bar. Default 0. */
+    order?: number;
+}
+interface HudConfig {
+    /** App slug as used in k8s/app-config.json (e.g. "console"). */
+    appSlug: string;
+    /** Toolbar display name. Working title until the naming vote lands. */
+    name?: string;
+    /** localStorage key for drawer height/tab persistence. Default `${appSlug}-hud`. */
+    storageKey?: string;
+    /** Drawer hotkey (Cmd/Ctrl+Shift+<key>). Default "h"; null disables. */
+    shortcutKey?: string | null;
+    /** Base path of the hud hub routes. Default "/api/hud" (same-origin proxy). */
+    apiBase?: string;
+    /**
+     * Source guesses for the element grabber (e.g. from the app's dev-routes
+     * or variant-preview manifest). Hints only — the dispatched session does
+     * the real lookup.
+     */
+    componentHints?: Array<{
+        name: string;
+        path: string;
+    }>;
+    /** FAB/drawer visual theme, passed through to @hn-monorepo/dev-tools. */
+    appearance?: "default" | "bauhaus";
+    /**
+     * Render the hud's own FAB (default true). Apps that already run a
+     * FloatingDockProvider set this false and register a dock item instead.
+     */
+    showFab?: boolean;
+}
+
+export { HUD_BUNDLE_MARKER, HUD_CAPABILITIES, type HudCapability, type HudConfig, type HudEnv, type HudPanel };

package/core/types.js

@@ -0,0 +1,9 @@
+import {
+  HUD_BUNDLE_MARKER,
+  HUD_CAPABILITIES
+} from "../chunk-v086j53b.js";
+import"../chunk-5gtx3pza.js";
+export {
+  HUD_CAPABILITIES,
+  HUD_BUNDLE_MARKER
+};

package/hud-provider.d.mts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { HudConfig, HudEnv, HudPanel, HudCapability } from './core/types.mjs';
+import 'lucide-react';
+
+interface HudPanelSource {
+    panels: HudPanel[];
+    /** Lower sorts first. Default 0. */
+    order?: number;
+}
+interface HudContextValue {
+    config: HudConfig;
+    env: HudEnv;
+    name: string;
+    can: (capability: HudCapability) => boolean;
+    /** Capability-filtered, order-sorted union of prop panels + registered sources. */
+    panels: HudPanel[];
+    registerSource: (id: string, source: HudPanelSource) => void;
+    unregisterSource: (id: string) => void;
+}
+interface HudProviderProps {
+    config: HudConfig;
+    env: HudEnv;
+    panels?: HudPanel[];
+    children: ReactNode;
+}
+declare function HudProvider({ config, env, panels: basePanels, children }: HudProviderProps): react.JSX.Element;
+declare function useHud(): HudContextValue;
+declare function useHudSafe(): HudContextValue | null;
+/**
+ * Contribute panels from any layout/page below the provider — mirrors
+ * dev-tools' `useRegisterDockItems`. Pass a memo-stable `panels` array; the
+ * source is replaced on change and removed on unmount, so calling with an
+ * empty array is safe (rules-of-hooks friendly).
+ */
+declare function useRegisterHudPanels(id: string, panels: HudPanel[], order?: number): void;
+
+export { HudProvider, type HudProviderProps, useHud, useHudSafe, useRegisterHudPanels };

package/hud-provider.js

@@ -0,0 +1,15 @@
+import {
+  HudProvider,
+  useHud,
+  useHudSafe,
+  useRegisterHudPanels
+} from "./chunk-wspz08q7.js";
+import"./chunk-babjpqkb.js";
+import"./chunk-v086j53b.js";
+import"./chunk-5gtx3pza.js";
+export {
+  useRegisterHudPanels,
+  useHudSafe,
+  useHud,
+  HudProvider
+};

package/hud.d.mts

@@ -0,0 +1,15 @@
+import * as react from 'react';
+import { HudConfig, HudPanel } from './core/types.mjs';
+import 'lucide-react';
+
+interface HudProps {
+    config: HudConfig;
+    panels?: HudPanel[];
+}
+/**
+ * The hud shell: env gate → drawer state → FAB + tabbed drawer. Mount once
+ * per app via a `ssr: false` dynamic import (see console's hud-loader).
+ */
+declare function Hud({ config, panels }: HudProps): react.JSX.Element | null;
+
+export { Hud, type HudProps };

package/hud.js

@@ -0,0 +1,18 @@
+import {
+  Hud
+} from "./chunk-xjn0896g.js";
+import"./chunk-msqkkqw7.js";
+import"./chunk-82nm9wcg.js";
+import"./chunk-ghxh8926.js";
+import"./chunk-xezxydm3.js";
+import"./chunk-24vrg16w.js";
+import"./chunk-r06bpmy6.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 {
+  Hud
+};

package/index.d.mts

@@ -0,0 +1,94 @@
+import { HudBridgeInfo, HudDispatchPayload, HudAnchor, HudComponentHint } from './core/api-types.mjs';
+export { HudCicdDeployed, HudCicdResponse, HudCicdRun, HudDispatchRequest, HudDispatchResponse, HudDispatchTarget, HudSeedDescriptor, HudSeedRequest, HudSeedResponse, HudSessionInfo, HudSignozResponse } from './core/api-types.mjs';
+export { HUD_UNLOCK_COOKIE, HudAccess, hudRequiresUnlock, hudUnlockTtlMs, resolveHudAccess } from './core/access.mjs';
+export { CAPABILITY_MATRIX, hasCapability, isHudVisible, resolveHudEnv } from './core/capabilities.mjs';
+export { CaptureBuffer, CaptureEntry, CaptureKind, captureBuffer } from './core/capture-buffer.mjs';
+export { HUD_MOCK_COOKIE, hudMockCookieString, isHudMockEnabled, readHudMockCookie, setHudMockCookie } from './core/mock-cookie.mjs';
+import { HudConfig, HudEnv } from './core/types.mjs';
+export { HUD_BUNDLE_MARKER, HUD_CAPABILITIES, HudCapability, HudPanel } from './core/types.mjs';
+export { Hud, HudProps } from './hud.mjs';
+export { HudProvider, HudProviderProps, useHud, useHudSafe, useRegisterHudPanels } from './hud-provider.mjs';
+export { HudPanelMeta, hudLazyPanel } from './lazy-panel.mjs';
+export { CicdPanel } from './panels/cicd-panel.mjs';
+export { DebugInfoPanel, DebugInfoPanelProps, HudUserInfo } from './panels/debug-info-panel.mjs';
+export { DispatchPanel } from './panels/dispatch-panel.mjs';
+export { EnvInfoPanel } from './panels/env-info-panel.mjs';
+export { FeatureFlagsPanel, HudFlagDescriptor, HudFlagsAdapter } from './panels/feature-flags-panel.mjs';
+export { InfoRow, LoadingSpinner, PanelSection, ShortcutRow } from './panels/info-row.mjs';
+export { MockSeedPanel } from './panels/mock-seed-panel.mjs';
+export { NetworkConsolePanel } from './panels/network-console-panel.mjs';
+export { HudRoleAdapter, HudRoleDescriptor, RoleSwitcherPanel } from './panels/role-switcher-panel.mjs';
+export { SessionsPanel } from './panels/sessions-panel.mjs';
+export { HudTokenDescriptor, HudTokenGroup, HudTokensAdapter, TokensPanel } from './panels/tokens-panel.mjs';
+export { HudUnlockPanel, HudUnlockPanelProps, HudUnlockState, useHudUnlock } from './panels/unlock-panel.mjs';
+export { HudGenerateRequest, HudGenerateResult, HudVariantCategory, HudVariantsAdapter, VariantsPanel } from './panels/variants-panel.mjs';
+export { VitalsPanel, getVitalsSnapshot } from './panels/vitals-panel.mjs';
+import 'lucide-react';
+import 'react';
+
+declare function getBridgeInfo(apiBase: string): Promise<HudBridgeInfo | null>;
+declare function resetBridgeInfo(): void;
+declare function bridgeFetch(info: HudBridgeInfo, path: string, init?: RequestInit): Promise<Response>;
+
+declare function installCapture(): void;
+declare function uninstallCapture(): void;
+
+/**
+ * Module-level grabber state. Lives outside React because the drawer (and
+ * with it every panel) unmounts while grabbing — the dispatch panel closes
+ * the drawer, the controller in the always-mounted shell does the DOM work,
+ * and the payload must survive the round trip.
+ */
+interface GrabberState {
+    mode: "idle" | "grabbing";
+    payload: HudDispatchPayload | null;
+}
+declare function getGrabberState(): GrabberState;
+declare function subscribeGrabber(listener: () => void): () => void;
+declare function startGrab(): void;
+declare function cancelGrab(): void;
+declare function completeGrab(payload: HudDispatchPayload): void;
+declare function clearGrabbedPayload(): void;
+
+/**
+ * CSS-ish path from `root` down to `el` — originally console's design-comments,
+ * by way of the HUD grabber. Canonical home; `@hn-monorepo/hud` re-exports it.
+ */
+declare function buildAnchorSelector(el: Element, root: Element): string;
+
+/**
+ * Viewport-relative anchor for a grab that is dispatched immediately.
+ *
+ * Correct here and only here: the payload is sent within the second, so the
+ * scroll offset it was measured at is still the one on screen. Anything that
+ * PERSISTS a position needs `capturePinAnchor` from
+ * `@hn-monorepo/review-kit/anchor`, which stores document-relative fractions —
+ * reload at a different scroll offset and these percentages point elsewhere.
+ */
+declare function buildAnchor(el: Element): HudAnchor;
+/**
+ * Score manifest entries against the current route + anchor label. Pure
+ * token overlap — a hint, not a resolution; the dispatched session does the
+ * real source lookup (console's design-review dispatch proves that works).
+ */
+declare function matchComponentHints(hints: HudComponentHint[] | undefined, route: string, label: string, max?: number): HudComponentHint[];
+declare function buildDispatchPayload(input: {
+    config: HudConfig;
+    env: HudEnv;
+    anchor: HudAnchor;
+    vitals: Record<string, number>;
+}): HudDispatchPayload;
+
+interface PollState<T> {
+    data?: T;
+    error?: string;
+    loading: boolean;
+}
+/**
+ * Minimal JSON polling for hud panels — deliberately not SWR to keep the
+ * package dependency-light. Pauses while the tab is hidden; a redirect
+ * (auth wall) or non-JSON response surfaces as a readable error.
+ */
+declare function usePoll<T>(url: string | null, intervalMs?: number): PollState<T>;
+
+export { HudAnchor, HudBridgeInfo, HudComponentHint, HudConfig, HudDispatchPayload, HudEnv, bridgeFetch, buildAnchor, buildAnchorSelector, buildDispatchPayload, cancelGrab, clearGrabbedPayload, completeGrab, getBridgeInfo, getGrabberState, installCapture, matchComponentHints, resetBridgeInfo, startGrab, subscribeGrabber, uninstallCapture, usePoll };

package/index.js

@@ -0,0 +1,170 @@
+import {
+  EnvInfoPanel
+} from "./chunk-0cj8dkk7.js";
+import {
+  DispatchPanel
+} from "./chunk-6gw4x08j.js";
+import {
+  SessionsPanel
+} from "./chunk-t9eh4t0b.js";
+import {
+  NetworkConsolePanel
+} from "./chunk-tf774c4w.js";
+import {
+  FeatureFlagsPanel
+} from "./chunk-71se605m.js";
+import {
+  MockSeedPanel
+} from "./chunk-k0vr8dsy.js";
+import {
+  bridgeFetch,
+  getBridgeInfo,
+  resetBridgeInfo
+} from "./chunk-50pq4sg6.js";
+import {
+  CicdPanel
+} from "./chunk-zzrpd92r.js";
+import {
+  VariantsPanel
+} from "./chunk-k50yfp5d.js";
+import {
+  TokensPanel
+} from "./chunk-nm82wr8r.js";
+import {
+  RoleSwitcherPanel
+} from "./chunk-6jt8yg4m.js";
+import {
+  DebugInfoPanel
+} from "./chunk-8tam7r3h.js";
+import {
+  Hud,
+  buildAnchor,
+  buildAnchorSelector,
+  buildDispatchPayload,
+  installCapture,
+  matchComponentHints,
+  uninstallCapture
+} from "./chunk-xjn0896g.js";
+import {
+  HudUnlockPanel,
+  useHudUnlock
+} from "./chunk-msqkkqw7.js";
+import {
+  cancelGrab,
+  clearGrabbedPayload,
+  completeGrab,
+  getGrabberState,
+  startGrab,
+  subscribeGrabber
+} from "./chunk-82nm9wcg.js";
+import {
+  VitalsPanel,
+  getVitalsSnapshot
+} from "./chunk-ghxh8926.js";
+import {
+  usePoll
+} from "./chunk-xezxydm3.js";
+import {
+  CaptureBuffer,
+  captureBuffer
+} from "./chunk-24vrg16w.js";
+import {
+  HUD_UNLOCK_COOKIE,
+  hudRequiresUnlock,
+  hudUnlockTtlMs,
+  resolveHudAccess
+} from "./chunk-r06bpmy6.js";
+import {
+  HudProvider,
+  useHud,
+  useHudSafe,
+  useRegisterHudPanels
+} from "./chunk-wspz08q7.js";
+import {
+  hudLazyPanel
+} from "./chunk-3j9sm249.js";
+import {
+  InfoRow,
+  LoadingSpinner,
+  PanelSection,
+  ShortcutRow
+} from "./chunk-kyeb6qeq.js";
+import"./chunk-xztw0xyt.js";
+import {
+  HUD_MOCK_COOKIE,
+  hudMockCookieString,
+  isHudMockEnabled,
+  readHudMockCookie,
+  setHudMockCookie
+} from "./chunk-hc2g0n35.js";
+import {
+  CAPABILITY_MATRIX,
+  hasCapability,
+  isHudVisible,
+  resolveHudEnv
+} from "./chunk-babjpqkb.js";
+import {
+  HUD_BUNDLE_MARKER,
+  HUD_CAPABILITIES
+} from "./chunk-v086j53b.js";
+import"./chunk-5gtx3pza.js";
+export {
+  useRegisterHudPanels,
+  usePoll,
+  useHudUnlock,
+  useHudSafe,
+  useHud,
+  uninstallCapture,
+  subscribeGrabber,
+  startGrab,
+  setHudMockCookie,
+  resolveHudEnv,
+  resolveHudAccess,
+  resetBridgeInfo,
+  readHudMockCookie,
+  matchComponentHints,
+  isHudVisible,
+  isHudMockEnabled,
+  installCapture,
+  hudUnlockTtlMs,
+  hudRequiresUnlock,
+  hudMockCookieString,
+  hudLazyPanel,
+  hasCapability,
+  getVitalsSnapshot,
+  getGrabberState,
+  getBridgeInfo,
+  completeGrab,
+  clearGrabbedPayload,
+  captureBuffer,
+  cancelGrab,
+  buildDispatchPayload,
+  buildAnchorSelector,
+  buildAnchor,
+  bridgeFetch,
+  VitalsPanel,
+  VariantsPanel,
+  TokensPanel,
+  ShortcutRow,
+  SessionsPanel,
+  RoleSwitcherPanel,
+  PanelSection,
+  NetworkConsolePanel,
+  MockSeedPanel,
+  LoadingSpinner,
+  InfoRow,
+  HudUnlockPanel,
+  HudProvider,
+  Hud,
+  HUD_UNLOCK_COOKIE,
+  HUD_MOCK_COOKIE,
+  HUD_CAPABILITIES,
+  HUD_BUNDLE_MARKER,
+  FeatureFlagsPanel,
+  EnvInfoPanel,
+  DispatchPanel,
+  DebugInfoPanel,
+  CicdPanel,
+  CaptureBuffer,
+  CAPABILITY_MATRIX
+};

package/lazy-panel.d.mts

@@ -0,0 +1,28 @@
+import { ComponentType } from 'react';
+import { HudPanel, HudEnv } from './core/types.mjs';
+import 'lucide-react';
+
+type HudPanelMeta = Omit<HudPanel, "content">;
+/**
+ * Declare a panel whose code is only fetched where its capability is granted.
+ *
+ * The provider already drops panels the tier denies, but that happens at
+ * render, and the panel's module is still in the graph, so an observe-only
+ * production hud downloads the dispatch, seed and impersonation panels it can
+ * never open. Returning `null` here instead keeps `lazy()`'s `import()`
+ * unreached, so the bundler emits those panels as separate chunks and the
+ * browser never asks for them.
+ *
+ * Callers spread the result and filter: the array shape stays declarative.
+ *
+ * ```tsx
+ * const PANELS = [
+ *   { id: "env", ..., content: <EnvInfoPanel /> },
+ *   hudLazyPanel(HUD_ENV, { id: "dispatch", ..., capability: "dispatch.hermes" },
+ *     () => import("@hn-monorepo/hud/panels/dispatch-panel").then((m) => m.DispatchPanel)),
+ * ].filter((panel): panel is HudPanel => panel !== null);
+ * ```
+ */
+declare function hudLazyPanel(meta: HudPanelMeta, load: () => Promise<ComponentType>, env?: HudEnv): HudPanel | null;
+
+export { type HudPanelMeta, hudLazyPanel };

package/lazy-panel.js

@@ -0,0 +1,11 @@
+import {
+  hudLazyPanel
+} from "./chunk-3j9sm249.js";
+import"./chunk-kyeb6qeq.js";
+import"./chunk-xztw0xyt.js";
+import"./chunk-babjpqkb.js";
+import"./chunk-v086j53b.js";
+import"./chunk-5gtx3pza.js";
+export {
+  hudLazyPanel
+};