@hansenexus/hud 0.3.0 → 0.4.0

package/dist/plugins/agent.js

@@ -0,0 +1,411 @@
+import { i as parseShortcut, l as useGrab, n as isApplePlatform, s as matchComponentHints, t as formatShortcut } from "../shortcut-U6ftVY06.js";
+import { i as definePlugin, n as HudApiError } from "../plugins-DVy_vaYr.js";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/plugins/agent/styles.ts
+/**
+* The agent panels' styles. Each panel renders them in a `<style>` inside the
+* HUD's shadow root, so the plugin brings its CSS without touching core's.
+*/
+const AGENT_CSS = `
+.agent { display: grid; gap: 10px; }
+.agent-row { display: flex; align-items: center; gap: 8px; }
+.agent-grow { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.agent-muted { color: var(--hud-fg-muted); }
+.agent-mono { font-family: var(--hud-mono); font-size: 11px; }
+.hud .agent-btn {
+  padding: 3px 10px;
+  border: 1px solid var(--hud-border);
+  border-radius: 6px;
+  background: var(--hud-bg-subtle);
+}
+.hud .agent-btn[data-primary] { background: var(--hud-accent); color: var(--hud-accent-fg); border-color: transparent; }
+.hud .agent-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+.agent-card {
+  display: grid;
+  gap: 2px;
+  padding: 6px 8px;
+  border: 1px solid var(--hud-border);
+  border-radius: 6px;
+  background: var(--hud-bg-subtle);
+}
+.agent textarea {
+  font: inherit;
+  color: inherit;
+  background: var(--hud-bg);
+  border: 1px solid var(--hud-border);
+  border-radius: 6px;
+  padding: 6px 8px;
+  min-height: 56px;
+  resize: vertical;
+}
+.agent fieldset { border: 0; margin: 0; padding: 0; display: grid; gap: 4px; }
+.agent label.agent-target { display: flex; gap: 6px; align-items: flex-start; cursor: pointer; }
+.agent label.agent-target[data-disabled] { opacity: 0.55; cursor: not-allowed; }
+.agent-list { display: grid; gap: 4px; margin: 0; padding: 0; list-style: none; }
+.agent-badge {
+  flex: none;
+  padding: 0 6px;
+  border-radius: 999px;
+  border: 1px solid currentColor;
+  font-size: 10px;
+  line-height: 16px;
+  color: var(--hud-fg-muted);
+}
+.agent-badge[data-status="running"], .agent-badge[data-status="dispatched"] { color: var(--hud-good); }
+.agent-badge[data-status="sending"], .agent-badge[data-status="queued"] { color: var(--hud-warn); }
+.agent-badge[data-status="failed"] { color: var(--hud-poor); }
+.agent details pre { max-height: 160px; overflow: auto; margin: 4px 0 0; font-size: 10px; }
+`;
+//#endregion
+//#region src/plugins/agent/dispatch-panel.tsx
+/**
+* Runs dispatched from this page. It outlives the panel (closing it unmounts
+* the component), so it lives with the plugin instance.
+*/
+function createRunLog() {
+	let runs = [];
+	const listeners = /* @__PURE__ */ new Set();
+	const set = (next) => {
+		runs = next;
+		for (const listener of listeners) listener();
+	};
+	return {
+		get: () => runs,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		add: (run) => set([run, ...runs].slice(0, 20)),
+		update: (id, patch) => set(runs.map((run) => run.id === id ? {
+			...run,
+			...patch
+		} : run))
+	};
+}
+function errorText(error) {
+	if (error instanceof HudApiError) return error.body?.error ?? `HTTP ${error.status}`;
+	return error instanceof Error ? error.message : String(error);
+}
+function DispatchPanel({ ctx, log, componentHints }) {
+	const { grabbing, payload } = useGrab(ctx.grab);
+	const runs = useSyncExternalStore(log.subscribe, log.get, log.get);
+	const [targets, setTargets] = useState(null);
+	const [targetsError, setTargetsError] = useState(null);
+	const [target, setTarget] = useState(null);
+	const [note, setNote] = useState("");
+	useEffect(() => {
+		let cancelled = false;
+		ctx.api("/targets").then((list) => {
+			if (cancelled) return;
+			setTargets(list);
+			setTarget((current) => current ?? list.find((t) => t.available)?.id ?? null);
+		}).catch((error) => {
+			if (!cancelled) setTargetsError(errorText(error));
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [ctx]);
+	const hints = payload ? matchComponentHints(componentHints, payload.route, payload.anchor.label) : [];
+	const canSend = target !== null && (payload !== null || note.trim() !== "");
+	async function send() {
+		if (!target || !canSend) return;
+		const id = `${Date.now()}`;
+		const title = [payload?.anchor.label, note.trim().split("\n")[0]].filter(Boolean).join(" · ");
+		const body = {
+			target,
+			note,
+			payload,
+			hints
+		};
+		log.add({
+			id,
+			title: title || "dispatch",
+			target,
+			status: "sending"
+		});
+		ctx.grab.clear();
+		setNote("");
+		try {
+			const receipt = await ctx.api("/dispatch", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body)
+			});
+			log.update(id, {
+				status: "dispatched",
+				detail: [receipt.runId, receipt.detail].filter(Boolean).join(" · ")
+			});
+		} catch (error) {
+			log.update(id, {
+				status: "failed",
+				detail: errorText(error)
+			});
+		}
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		className: "agent",
+		children: [
+			/* @__PURE__ */ jsx("style", { children: AGENT_CSS }),
+			payload ? /* @__PURE__ */ jsxs("div", {
+				className: "agent-card",
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "agent-row",
+						children: [/* @__PURE__ */ jsxs("strong", {
+							className: "agent-grow",
+							title: payload.anchor.label,
+							children: [payload.component ? `<${payload.component.name}> ` : "", payload.anchor.label]
+						}), /* @__PURE__ */ jsx("button", {
+							type: "button",
+							className: "agent-btn",
+							"aria-label": "Discard grab",
+							onClick: ctx.grab.clear,
+							children: "✕"
+						})]
+					}),
+					payload.component?.source && /* @__PURE__ */ jsx("span", {
+						className: "agent-mono agent-muted",
+						children: payload.component.source
+					}),
+					/* @__PURE__ */ jsxs("span", {
+						className: "agent-mono agent-muted agent-grow",
+						title: payload.anchor.selector,
+						children: [
+							payload.route,
+							" · ",
+							payload.anchor.selector || payload.anchor.tag
+						]
+					}),
+					/* @__PURE__ */ jsxs("details", { children: [/* @__PURE__ */ jsx("summary", {
+						className: "agent-muted",
+						children: "Payload"
+					}), /* @__PURE__ */ jsx("pre", {
+						className: "agent-mono",
+						children: JSON.stringify({
+							...payload,
+							hints
+						}, null, 2)
+					})] })
+				]
+			}) : /* @__PURE__ */ jsxs("div", {
+				className: "agent-row",
+				children: [/* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "agent-btn",
+					"data-primary": "",
+					"aria-pressed": grabbing,
+					onClick: grabbing ? ctx.grab.cancel : ctx.grab.start,
+					children: grabbing ? "Cancel grab" : "⌖ Grab element"
+				}), /* @__PURE__ */ jsxs("span", {
+					className: "agent-muted",
+					children: [
+						"or ",
+						formatShortcut(parseShortcut("mod+shift+g"), isApplePlatform()),
+						", then click anything on the page"
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("textarea", {
+				"aria-label": "Instruction",
+				placeholder: "Instruction, e.g. the CTA feels heavy, try the ghost variant",
+				value: note,
+				onChange: (e) => setNote(e.target.value)
+			}),
+			targetsError && /* @__PURE__ */ jsxs("p", {
+				className: "empty",
+				children: ["Targets unavailable: ", targetsError]
+			}),
+			targets && targets.length === 0 && /* @__PURE__ */ jsx("p", {
+				className: "empty",
+				children: "No dispatch provider configured on the server."
+			}),
+			targets && targets.length > 0 && /* @__PURE__ */ jsx("fieldset", { children: targets.map((t) => /* @__PURE__ */ jsxs("label", {
+				className: "agent-target",
+				...t.available ? {} : { "data-disabled": "" },
+				children: [/* @__PURE__ */ jsx("input", {
+					type: "radio",
+					name: "agent-target",
+					checked: target === t.id,
+					disabled: !t.available,
+					onChange: () => setTarget(t.id)
+				}), /* @__PURE__ */ jsxs("span", { children: [
+					/* @__PURE__ */ jsx("span", { children: t.label }),
+					/* @__PURE__ */ jsx("br", {}),
+					/* @__PURE__ */ jsx("span", {
+						className: "agent-muted",
+						children: t.available ? t.description ?? t.id : t.reason
+					})
+				] })]
+			}, t.id)) }),
+			/* @__PURE__ */ jsx("div", {
+				className: "agent-row",
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "agent-btn",
+					"data-primary": "",
+					disabled: !canSend,
+					onClick: send,
+					children: "Dispatch"
+				})
+			}),
+			runs.length > 0 && /* @__PURE__ */ jsx("ul", {
+				className: "agent-list",
+				"aria-label": "Dispatched runs",
+				children: runs.map((run) => /* @__PURE__ */ jsxs("li", {
+					className: "agent-row agent-mono",
+					children: [
+						/* @__PURE__ */ jsx("span", {
+							className: "agent-badge",
+							"data-status": run.status,
+							children: run.status
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: "agent-grow",
+							title: run.title,
+							children: run.title
+						}),
+						/* @__PURE__ */ jsxs("span", {
+							className: "agent-muted agent-grow",
+							title: run.detail,
+							children: [run.target, run.detail ? ` · ${run.detail}` : ""]
+						})
+					]
+				}, run.id))
+			})
+		]
+	});
+}
+//#endregion
+//#region src/plugins/agent/sessions-panel.tsx
+function age(iso) {
+	if (!iso) return "";
+	const seconds = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1e3));
+	if (seconds < 60) return `${seconds}s`;
+	if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+	if (seconds < 86400) return `${Math.round(seconds / 3600)}h`;
+	return `${Math.round(seconds / 86400)}d`;
+}
+function SessionRow({ session }) {
+	return /* @__PURE__ */ jsxs("li", {
+		className: "agent-row agent-mono",
+		title: session.detail ?? session.id,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "agent-badge",
+				"data-status": session.status,
+				children: session.status
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "agent-grow",
+				children: session.title
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				className: "agent-muted",
+				children: [
+					session.provider,
+					" ",
+					age(session.updatedAt ?? session.startedAt)
+				]
+			})
+		]
+	});
+}
+function SessionsPanel({ ctx, intervalMs }) {
+	const [data, setData] = useState(null);
+	const [error, setError] = useState(null);
+	const load = useCallback(async () => {
+		try {
+			setData(await ctx.api("/sessions"));
+			setError(null);
+		} catch (e) {
+			setError(e instanceof HudApiError ? `HTTP ${e.status}` : String(e));
+		}
+	}, [ctx]);
+	useEffect(() => {
+		load();
+		const timer = setInterval(() => {
+			if (!document.hidden) load();
+		}, intervalMs);
+		return () => clearInterval(timer);
+	}, [load, intervalMs]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "agent",
+		children: [
+			/* @__PURE__ */ jsx("style", { children: AGENT_CSS }),
+			/* @__PURE__ */ jsxs("div", {
+				className: "agent-row",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "agent-grow agent-muted",
+					children: data ? `${data.sessions.length} sessions` : "Loading…"
+				}), /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "agent-btn",
+					onClick: () => void load(),
+					children: "Refresh"
+				})]
+			}),
+			error && /* @__PURE__ */ jsxs("p", {
+				className: "empty",
+				children: ["Sessions unavailable: ", error]
+			}),
+			data?.errors.map((e) => /* @__PURE__ */ jsxs("p", {
+				className: "empty",
+				children: [
+					e.provider,
+					": ",
+					e.error
+				]
+			}, e.provider)),
+			data && data.sessions.length === 0 && /* @__PURE__ */ jsx("p", {
+				className: "empty",
+				children: "No sessions."
+			}),
+			data && data.sessions.length > 0 && /* @__PURE__ */ jsx("ul", {
+				className: "agent-list",
+				"aria-label": "Agent sessions",
+				children: data.sessions.map((session) => /* @__PURE__ */ jsx(SessionRow, { session }, `${session.provider}:${session.id}`))
+			})
+		]
+	});
+}
+//#endregion
+//#region src/plugins/agent/index.tsx
+/**
+* Dispatch panel: the last grab plus an instruction, sent to one of the
+* server's providers (`hermes()`, `claudeCode()`). Mount the server half from
+* `@hansenexus/hud/plugins/agent/server` in the catch-all route.
+*/
+function agentDispatch({ componentHints, openOnGrab = true } = {}) {
+	const log = createRunLog();
+	function Panel({ ctx }) {
+		return /* @__PURE__ */ jsx(DispatchPanel, {
+			ctx,
+			log,
+			componentHints
+		});
+	}
+	return definePlugin({
+		id: "agent-dispatch",
+		title: "Dispatch",
+		panel: Panel,
+		...openOnGrab ? { onGrab: (_payload, ctx) => ctx.open() } : {}
+	});
+}
+/** Sessions panel: runs and sessions of every provider that lists them. */
+function agentSessions({ intervalMs = 1e4 } = {}) {
+	function Panel({ ctx }) {
+		return /* @__PURE__ */ jsx(SessionsPanel, {
+			ctx,
+			intervalMs
+		});
+	}
+	return definePlugin({
+		id: "agent-sessions",
+		title: "Sessions",
+		panel: Panel
+	});
+}
+//#endregion
+export { agentDispatch, agentSessions };

package/dist/plugins/design.d.ts

@@ -0,0 +1,125 @@
+import { c as HudPluginProps } from "../plugins-CQ_0w1ot.js";
+import { i as ForcedState, n as FORCE_STATE_MARKER, r as FORCE_STATE_PARAM, t as FORCED_STATES } from "../force-state-CCqoTfVB.js";
+//#region src/plugins/design/force-state-panel.d.ts
+/**
+ * Pill content: how many boundaries are forced, by toggle or param. Uses the
+ * core `.dot`, since the plugin stylesheet only loads with the panel.
+ */
+declare function ForceStatePill(): import("react").JSX.Element;
+/**
+ * Toggles every mounted `StateBoundary` 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 page.
+ */
+declare function ForceStatePanel(): import("react").JSX.Element;
+//#endregion
+//#region src/plugins/design/tokens.d.ts
+interface HudTokenDescriptor {
+  /** CSS custom property, including the leading dashes (e.g. `--primary`). */
+  cssVar: string;
+  /** Short display label; defaults to the var name without its leading dashes. */
+  label?: string;
+}
+/**
+ * Scope attribute the design system hangs its tokens on, with an optional
+ * value: `{ attribute: "data-theme", value: "brand" }` matches
+ * `[data-theme="brand"] { --primary: … }`. Omit for `:root`-scoped tokens.
+ */
+interface HudTokenScope {
+  attribute: string;
+  value?: string;
+}
+interface HudTokenGroup {
+  label: string;
+  /** Var names (`"--primary"`) or descriptors with a label. */
+  tokens: readonly (string | HudTokenDescriptor)[];
+  scope?: HudTokenScope;
+}
+/** What an app tells the Tokens panel about its design system. */
+interface HudTokensAdapter {
+  groups: readonly HudTokenGroup[];
+  /** Where the tokens live, shown as a hint (e.g. `src/app/globals.css`). */
+  sourceHint?: string;
+}
+//#endregion
+//#region src/plugins/design/variants-panel.d.ts
+interface HudVariantCategory {
+  id: string;
+  name: string;
+  /** Registry status: "active" renders as votable, "decided" as settled. */
+  status: string;
+  alternativeCount: number;
+  /** Domain bucket (marketing, admin, shared …) for grouping. Default "shared". */
+  domain?: string;
+}
+interface HudGenerateRequest {
+  /** Repo-relative component path. */
+  path: string;
+  brief: string;
+  count: number;
+}
+interface HudGenerateResult {
+  ok: boolean;
+  /** Where the queued brief landed, on success. */
+  markerPath?: string;
+  error?: string;
+}
+/**
+ * What an app tells the Variants panel about its variant registry. The HUD
+ * owns no registry: an app maps its own (a static list, or a loader against
+ * hn-monorepo#2552's variant groups) onto this shape.
+ */
+interface HudVariantsAdapter {
+  /** The categories, or a loader the panel calls each time it opens. */
+  categories: readonly HudVariantCategory[] | (() => Promise<readonly HudVariantCategory[]>);
+  /** Deep link to the full review dashboard, where voting happens. */
+  reviewHref?: string;
+  /** Deep link for one category's drill-in page. */
+  categoryHref?: (categoryId: string) => string;
+  /** Opens an in-page preview for a category; wins over `categoryHref`. */
+  openPreview?: (categoryId: string) => void;
+  /**
+   * Queues a variant-generation brief. Shown only when the tier grants
+   * `variants.generate`. The human stays in the loop: queue, not dispatch.
+   */
+  generate?: (request: HudGenerateRequest) => Promise<HudGenerateResult>;
+}
+//#endregion
+//#region src/plugins/design/index.d.ts
+/**
+ * Live swatches of the host app's design tokens. Values are read from the
+ * host document, outside the HUD's shadow root, so scoped and themed tokens
+ * show what the page actually renders. Client only.
+ */
+export declare function tokens(adapter: HudTokensAdapter): {
+  readonly id: "tokens";
+  readonly title: "Tokens";
+  readonly panel: () => import("react").JSX.Element;
+};
+/**
+ * The app's variant categories and the generate-brief queue, over an adapter
+ * onto the app's own registry. Generating needs `variants.generate`. Client only.
+ */
+export declare function variants(adapter: HudVariantsAdapter): {
+  readonly id: "variants";
+  readonly title: "Variants";
+  readonly panel: ({ ctx }: HudPluginProps) => import("react").JSX.Element;
+};
+/**
+ * Forces the page's `StateBoundary`s (`@hansenexus/hud/state-boundary`) to
+ * loading, empty or error. The pill shows how many are forced. Client only.
+ */
+export declare function forceState(): {
+  readonly id: "states";
+  readonly title: "States";
+  readonly capability: "state.force";
+  readonly pill: typeof ForceStatePill;
+  readonly panel: typeof ForceStatePanel;
+  readonly commands: readonly [{
+    readonly id: "reset";
+    readonly title: "Reset forced states";
+    readonly run: () => void;
+  }];
+};
+//#endregion
+export { FORCED_STATES, FORCE_STATE_MARKER, FORCE_STATE_PARAM, type ForcedState, type HudGenerateRequest, type HudGenerateResult, type HudTokenDescriptor, type HudTokenGroup, type HudTokenScope, type HudTokensAdapter, type HudVariantCategory, type HudVariantsAdapter };