@hansenexus/hud 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +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
+> Early. The element grabber is tracked in
 > [the PRD](https://github.com/hansenexus/hud/issues/1).
 
 ## Develop
@@ -28,19 +28,81 @@ 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
-import { Hud } from "@hansenexus/hud";
+// 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 function DevHud() {
-  return <Hud appSlug="my-app" />;
-}
+export const { GET, POST, PUT, PATCH, DELETE } = createHudHandler([/* plugins/<id>/server */]);
 ```
 
-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.
+`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
 

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

@@ -1,4 +1,5 @@
-import { Metric } from "web-vitals";
+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.
@@ -12,28 +13,24 @@ export declare const HUD_HOST_TAG = "hn-hud";
 //#endregion
 //#region src/shell/hud.d.ts
 interface HudProps {
-  /** App slug, used for labels now and for the layout storage key later. */
+  /** 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 the Next adapter, hud#4).
+ * (see `@hansenexus/hud/next`).
  */
-export declare function Hud({ appSlug, envLabel }: HudProps): import("react").JSX.Element;
+export declare function Hud({ appSlug, envLabel, plugins, apiBase, can }: HudProps): import("react").JSX.Element;
 //#endregion
-//#region src/vitals/store.d.ts
-type VitalName = Metric["name"];
-type VitalRating = Metric["rating"];
-interface Vital {
-  name: VitalName;
-  value: number;
-  rating: VitalRating;
-}
-type VitalsSnapshot = Partial<Record<VitalName, Vital>>;
-//#endregion
-export type { HudProps, Vital, VitalName, VitalRating, VitalsSnapshot };
+export { type DefineHudOptions, HudApiError, type HudCapability, type HudCommand, type HudMountProps, type HudPlugin, type HudPluginContext, type HudPluginProps, type HudProps, type PinEdge, defineHud, definePlugin };