@hansenexus/hud 0.1.1 → 0.3.0

package/README.md

@@ -1,47 +1,128 @@
 # @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.
+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 element grabber is tracked in
+> [the PRD](https://github.com/hansenexus/hud/issues/1).
+
+## Develop
+
+```sh
+bun install
+bun run dev      # playground on http://localhost:5173, HUD imported from source (HMR)
+bun run check    # lint, typecheck, test, build
+```
+
+The playground (`playground/`) is a fake client site with every element that has fought a dev
+tool for a corner: sticky nav, a fixed booking CTA, a chat launcher and a cookie banner, plus a
+deliberately hostile stylesheet. If the HUD changes when you edit `playground/src/site.css`, the
+isolation leaks.
 
 ## Install
 
 ```sh
-npm install @hansenexus/hud
+bun add -d @hansenexus/hud   # or npm i -D @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.
+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)
 
-```tsx
-import { Hud, type HudPanel, NetworkConsolePanel, VitalsPanel } from "@hansenexus/hud";
-import { Activity, Terminal } from "lucide-react";
+Three files. The HUD definition, client only:
 
-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 },
-];
+```tsx
+// src/components/dev/hud.tsx
+import { defineHud } from "@hansenexus/hud";
+import { vitals } from "@hansenexus/hud/plugins/vitals";
 
-export function DevHud() {
-  return <Hud config={{ appSlug: "my-app" }} panels={panels} />;
-}
+export default defineHud({ app: "my-app", plugins: [vitals()] });
 ```
 
-Mount it only in development builds, for example behind `import.meta.env.DEV` and a lazy import.
+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
+);
+```
 
-## Tailwind v4
+Render `<HudLoader />` in the root layout. Plugin routes mount through one catch-all route, fed
+the plugins' server halves:
 
-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:
+```ts
+// src/app/api/hud/[...hud]/route.ts
+import { createHudHandler } from "@hansenexus/hud/server";
 
-```css
-@source "../node_modules/@hansenexus/hud";
+export const { GET, POST, PUT, PATCH, DELETE } = createHudHandler([/* plugins/<id>/server */]);
 ```
 
-The path is relative to that stylesheet. If a panel renders unstyled, this line is missing
-or points at the wrong place.
+`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.
+
+## 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                                                       |
+
+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. `⌘⇧G` is reserved for the
+  element grabber.
+
+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`.
+
+## Release
+
+Versions are driven by [Changesets](https://github.com/changesets/changesets). A PR that changes
+what the package ships adds one with `bun run changeset` (pre-1.0: `minor` for breaking changes,
+`patch` for the rest). On `main`, `.github/workflows/release.yml` gathers pending changesets into
+a "chore: version packages" PR. Merging that PR publishes the new version to npm over Trusted
+Publishing (GitHub OIDC, no `NPM_TOKEN`), tags `v<version>` and cuts a GitHub release from the
+CHANGELOG section. `Actions > Release > Run workflow` with `dry_run` runs the gate and
+`npm publish --dry-run` without publishing.
+
+Versions up to 0.1.1 were published from hn-monorepo; 0.2.0 is the first release from this repo.
+
+Provenance is off while the repo is private (npm refuses `--provenance` from a private source).
+When the repo goes public, set `NPM_PROVENANCE: "true"` in `release.yml`.
+
+**Owner step, once, needs npm 2FA:** npmjs.com → `@hansenexus/hud` → Settings → Trusted
+Publisher → GitHub Actions: organization `hansenexus`, repository `hud`, workflow `release.yml`.
+Do this before merging the first Version Packages PR. Keep the hn-monorepo publisher until
+hn-monorepo#2740 retires its old release workflow.
 
 ## License
 

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

@@ -0,0 +1,31 @@
+import { a as HudPlugin, n as HudCapability } from "./plugins-1QmTmZyL.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;
+}
+/**
+ * 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/index.d.ts

@@ -0,0 +1,36 @@
+import { a as HudPlugin, d as PinEdge, f as definePlugin, n as HudCapability, o as HudPluginContext, r as HudCommand, s as HudPluginProps, t as HudApiError } from "./plugins-1QmTmZyL.js";
+import { n as HudMountProps, r as defineHud, t as DefineHudOptions } from "./define-hud-BHQR8Lbv.js";
+//#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: 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`).
+ */
+export declare function Hud({ appSlug, envLabel, plugins, apiBase, can }: HudProps): import("react").JSX.Element;
+//#endregion
+export { type DefineHudOptions, HudApiError, type HudCapability, type HudCommand, type HudMountProps, type HudPlugin, type HudPluginContext, type HudPluginProps, type HudProps, type PinEdge, defineHud, definePlugin };