@hansenexus/hud 0.2.0 → 0.4.0

package/dist/selector-NSYSe7AZ.js

@@ -0,0 +1,28 @@
+//#region src/core/grabber/selector.ts
+/**
+* `nth-of-type` path from `root` down to `el`. Ported from hn-monorepo
+* `review-kit/anchor`, where console's design comments and the old HUD
+* grabber shared it.
+*/
+function buildAnchorSelector(el, root) {
+	const segments = [];
+	let node = el;
+	while (node && node !== root) {
+		const tag = node.tagName.toLowerCase();
+		const parent = node.parentElement;
+		if (!parent) break;
+		const siblings = [...parent.children].filter((c) => c.tagName === node?.tagName);
+		const index = siblings.indexOf(node) + 1;
+		segments.unshift(siblings.length > 1 ? `${tag}:nth-of-type(${index})` : tag);
+		node = parent;
+	}
+	return segments.join(" > ");
+}
+/** Human label such as `button “Termin buchen”`. */
+function anchorLabelFor(el) {
+	const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
+	const tag = el.tagName.toLowerCase();
+	return text ? `${tag} “${text.slice(0, 32)}${text.length > 32 ? "…" : ""}”` : tag;
+}
+//#endregion
+export { buildAnchorSelector as n, anchorLabelFor as t };

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { a as HudHttpMethod, d as HudRoutes, l as HudRouteContext, o as HudPlugin, p as definePlugin, u as HudRouteHandler } from "./plugins-CQ_0w1ot.js";
+import { a as createHudHandler, i as HudRequestHandler, n as HudHandler, o as developmentOnly, r as HudHandlerOptions, t as HudGuard } from "./handler-WmE4Lu7l.js";
+export { type HudGuard, type HudHandler, type HudHandlerOptions, type HudHttpMethod, type HudPlugin, type HudRequestHandler, type HudRouteContext, type HudRouteHandler, type HudRoutes, createHudHandler, definePlugin, developmentOnly };

package/dist/server.js

@@ -0,0 +1,106 @@
+import { a as resolvePlugins, i as definePlugin, t as HUD_HTTP_METHODS } from "./plugins-DVy_vaYr.js";
+//#region src/server/handler.ts
+function json(status, body, headers) {
+	const res = Response.json(body, { status });
+	if (headers) for (const [key, value] of new Headers(headers)) res.headers.set(key, value);
+	return res;
+}
+function notFound() {
+	return json(404, {
+		ok: false,
+		error: "not found"
+	});
+}
+/**
+* The default guard. Core assumes development, so a deployed build that
+* mounts the route without an `access` guard serves nothing and reveals
+* nothing about which plugins exist.
+*/
+const developmentOnly = () => {
+	return (typeof process === "undefined" ? void 0 : process.env.NODE_ENV) === "development" ? null : notFound();
+};
+function splitPath(path) {
+	return path.split("/").filter(Boolean);
+}
+function compile(plugin) {
+	return Object.entries(plugin.routes ?? {}).map(([path, methods]) => ({
+		segments: splitPath(path),
+		methods
+	}));
+}
+function match(route, segments) {
+	if (route.segments.length !== segments.length) return null;
+	const params = {};
+	for (const [i, pattern] of route.segments.entries()) {
+		const segment = segments[i] ?? "";
+		if (!pattern.startsWith(":")) {
+			if (pattern !== segment) return null;
+			continue;
+		}
+		try {
+			params[pattern.slice(1)] = decodeURIComponent(segment);
+		} catch {
+			return null;
+		}
+	}
+	return params;
+}
+function isMethod(method) {
+	return HUD_HTTP_METHODS.includes(method);
+}
+/**
+* Serves every plugin's routes from one catch-all route
+* (`app/api/hud/[...hud]/route.ts` in Next). A request to
+* `<basePath>/<plugin id>/<path>` reaches that plugin's `routes[path][method]`;
+* unknown plugin or path answers 404, a known path with another method 405.
+*
+* Pass the server halves (`@hansenexus/hud/plugins/<id>/server`): they carry
+* `routes` and no React.
+*/
+function createHudHandler(plugins, options = {}) {
+	const basePath = splitPath(options.basePath ?? "/api/hud");
+	const guard = options.guard ?? developmentOnly;
+	const table = new Map(resolvePlugins(plugins, options.can ?? (() => true)).map((plugin) => [plugin.id, {
+		plugin,
+		routes: compile(plugin)
+	}]));
+	const handle = async (request) => {
+		const segments = splitPath(new URL(request.url).pathname);
+		if (!basePath.every((segment, i) => segments[i] === segment)) return notFound();
+		const [pluginId, ...rest] = segments.slice(basePath.length);
+		const entry = pluginId === void 0 ? void 0 : table.get(pluginId);
+		const refusal = await guard(request, entry?.plugin.capability);
+		if (refusal) return refusal;
+		if (!entry) return notFound();
+		for (const route of entry.routes) {
+			const params = match(route, rest);
+			if (!params) continue;
+			const method = request.method === "HEAD" ? "GET" : request.method;
+			const fn = isMethod(method) ? route.methods[method] : void 0;
+			if (!fn) return json(405, {
+				ok: false,
+				error: "method not allowed"
+			}, { allow: HUD_HTTP_METHODS.filter((m) => route.methods[m]).join(", ") });
+			try {
+				return await fn(request, { params });
+			} catch (error) {
+				console.error(`hud: ${entry.plugin.id} ${request.method} /${rest.join("/")} failed`, error);
+				return json(500, {
+					ok: false,
+					error: "plugin route failed"
+				});
+			}
+		}
+		return notFound();
+	};
+	return {
+		handle,
+		GET: handle,
+		POST: handle,
+		PUT: handle,
+		PATCH: handle,
+		DELETE: handle
+	};
+}
+//#endregion
+export { createHudHandler, definePlugin, developmentOnly };

package/dist/shortcut-U6ftVY06.js

@@ -0,0 +1,222 @@
+import { n as buildAnchorSelector, t as anchorLabelFor } from "./selector-NSYSe7AZ.js";
+import { useSyncExternalStore } from "react";
+//#region src/core/grabber/store.ts
+const IDLE = {
+	grabbing: false,
+	payload: null
+};
+function createGrabber() {
+	let state = IDLE;
+	const listeners = /* @__PURE__ */ new Set();
+	const set = (next) => {
+		if (next.grabbing === state.grabbing && next.payload === state.payload) return;
+		state = next;
+		for (const listener of listeners) listener();
+	};
+	return {
+		start: () => set({
+			...state,
+			grabbing: true
+		}),
+		cancel: () => set({
+			...state,
+			grabbing: false
+		}),
+		clear: () => set({
+			...state,
+			payload: null
+		}),
+		complete: (payload) => set({
+			grabbing: false,
+			payload
+		}),
+		getState: () => state,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+/** Subscribes a component to a HUD's grab state: `useGrab(ctx.grab)`. */
+function useGrab(grab) {
+	return useSyncExternalStore(grab.subscribe, grab.getState, grab.getState);
+}
+//#endregion
+//#region src/core/grabber/inspect.ts
+const MAX_OWNERS = 5;
+/** React's internal fiber key on a DOM node: `__reactFiber$<random>`. */
+function fiberOf(el) {
+	for (const key of Object.keys(el)) if (key.startsWith("__reactFiber$")) {
+		const fiber = el[key];
+		return fiber && typeof fiber === "object" ? fiber : null;
+	}
+	return null;
+}
+/** Display name of a component fiber's type; null for host elements, fragments, providers. */
+function componentName(type) {
+	if (typeof type === "function") {
+		const fn = type;
+		const name = typeof fn.displayName === "string" ? fn.displayName : fn.name;
+		return typeof name === "string" && name ? name : null;
+	}
+	if (type && typeof type === "object") {
+		const wrapper = type;
+		if (typeof wrapper.displayName === "string" && wrapper.displayName) return wrapper.displayName;
+		return componentName(wrapper.render) ?? componentName(wrapper.type);
+	}
+	return null;
+}
+/** Internal frames between the caller and React: the JSX runtime, React itself, bundler glue. */
+const INTERNAL_FRAME = /react-stack-top-frame|jsx-?dev|jsx-runtime|\/react(-dom)?[./@]|node_modules/;
+/**
+* Turns a frame location such as `http://localhost:5173/src/site.tsx?t=1:12:5`
+* or `webpack-internal:///(app-pages-browser)/./src/hero.tsx:8:3` into
+* `src/site.tsx:12:5`.
+*/
+function cleanSourceLocation(location) {
+	const match = /^(.*?):(\d+)(?::(\d+))?$/.exec(location.trim());
+	if (!match) return location;
+	const [, rawPath = "", line, column] = match;
+	let path = rawPath.replace(/[?#].*$/, "");
+	const bundled = /^webpack-internal:\/\/\/(?:\([^)]*\)\/)?(.*)$/.exec(path);
+	const url = /^[a-z][a-z0-9+.-]*:\/\/[^/]*\/(.*)$/i.exec(path);
+	path = bundled?.[1] ?? url?.[1] ?? path;
+	path = path.replace(/^\.\//, "").replace(/^\/?@fs\//, "/");
+	if (!path) path = rawPath;
+	return column ? `${path}:${line}:${column}` : `${path}:${line}`;
+}
+/** First non-internal frame of a V8 or SpiderMonkey/JSC stack. */
+function sourceFromStack(stack) {
+	for (const line of stack.split("\n").slice(1)) {
+		if (INTERNAL_FRAME.test(line)) continue;
+		const v8 = /^\s*at (?:.*? \()?(.+?)\)?$/.exec(line);
+		const gecko = /@(.+)$/.exec(line);
+		const location = v8?.[1] ?? gecko?.[1];
+		if (location && /:\d+(:\d+)?$/.test(location)) return cleanSourceLocation(location);
+	}
+}
+function sourceOf(fiber) {
+	const legacy = fiber._debugSource;
+	if (legacy?.fileName && legacy.lineNumber) return cleanSourceLocation(`${legacy.fileName}:${legacy.lineNumber}${legacy.columnNumber ? `:${legacy.columnNumber}` : ""}`);
+	const stack = fiber._debugStack?.stack;
+	return typeof stack === "string" ? sourceFromStack(stack) : void 0;
+}
+function inspectComponent(el) {
+	const host = fiberOf(el);
+	if (!host) return null;
+	const names = [];
+	let source = sourceOf(host);
+	for (let fiber = host.return; fiber && names.length <= MAX_OWNERS; fiber = fiber.return) {
+		const name = componentName(fiber.type);
+		if (!name) continue;
+		names.push(name);
+		source ??= sourceOf(fiber);
+	}
+	const [name, ...owners] = names;
+	if (!name) return null;
+	return source ? {
+		name,
+		owners,
+		source
+	} : {
+		name,
+		owners
+	};
+}
+//#endregion
+//#region src/core/grabber/payload.ts
+function pct(part, whole) {
+	return whole > 0 ? Number((part / whole * 100).toFixed(1)) : 0;
+}
+function buildGrabAnchor(el) {
+	const doc = el.ownerDocument;
+	const win = doc.defaultView;
+	const width = win?.innerWidth ?? 0;
+	const height = win?.innerHeight ?? 0;
+	const r = el.getBoundingClientRect();
+	return {
+		selector: buildAnchorSelector(el, doc.body),
+		label: anchorLabelFor(el),
+		tag: el.tagName.toLowerCase(),
+		rect: {
+			x: pct(r.left, width),
+			y: pct(r.top, height),
+			width: pct(r.width, width),
+			height: pct(r.height, height)
+		}
+	};
+}
+function buildGrabPayload(el, { app }) {
+	const win = el.ownerDocument.defaultView;
+	return {
+		app,
+		url: win?.location.href ?? "",
+		route: win?.location.pathname ?? "/",
+		anchor: buildGrabAnchor(el),
+		component: inspectComponent(el),
+		viewport: {
+			width: win?.innerWidth ?? 0,
+			height: win?.innerHeight ?? 0
+		},
+		grabbedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/** The picker's hover label: component and source when React reports them, the tag otherwise. */
+function describeElement(el) {
+	const tag = el.tagName.toLowerCase();
+	const component = inspectComponent(el);
+	if (!component) return tag;
+	const file = component.source?.split("/").pop()?.replace(/(:\d+)+$/, "");
+	return `<${component.name}> ${tag}${file ? ` · ${file}` : ""}`;
+}
+/**
+* Scores manifest entries against the route and anchor label. Pure token
+* overlap: a hint for the agent, not a resolution. Ported from the old HUD's
+* `grabber/payload.ts`.
+*/
+function matchComponentHints(hints, route, label, max = 5) {
+	if (!hints?.length) return [];
+	const tokens = `${route} ${label}`.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2);
+	if (tokens.length === 0) return hints.slice(0, max);
+	return hints.map((hint) => {
+		const haystack = `${hint.name} ${hint.path}`.toLowerCase();
+		return {
+			hint,
+			score: tokens.reduce((n, token) => haystack.includes(token) ? n + 1 : n, 0)
+		};
+	}).filter((h) => h.score > 0).sort((a, b) => b.score - a.score).slice(0, max).map((h) => h.hint);
+}
+//#endregion
+//#region src/shell/commands/shortcut.ts
+function parseShortcut(spec) {
+	const parts = spec.toLowerCase().split("+");
+	return {
+		key: parts.at(-1) ?? "",
+		mod: parts.includes("mod"),
+		shift: parts.includes("shift"),
+		alt: parts.includes("alt")
+	};
+}
+function isApplePlatform() {
+	return typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent);
+}
+function matchesShortcut(event, shortcut, apple) {
+	if ((apple ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey) !== shortcut.mod) return false;
+	if (event.shiftKey !== shortcut.shift || event.altKey !== shortcut.alt) return false;
+	if (event.key.toLowerCase() === shortcut.key) return true;
+	if (/^[a-z]$/.test(shortcut.key)) return event.code === `Key${shortcut.key.toUpperCase()}`;
+	if (/^\d$/.test(shortcut.key)) return event.code === `Digit${shortcut.key}`;
+	return false;
+}
+function formatShortcut(shortcut, apple) {
+	const key = shortcut.key.toUpperCase();
+	if (apple) return `${shortcut.mod ? "⌘" : ""}${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${key}`;
+	return [
+		shortcut.mod && "Ctrl",
+		shortcut.alt && "Alt",
+		shortcut.shift && "Shift",
+		key
+	].filter(Boolean).join("+");
+}
+//#endregion
+export { buildGrabPayload as a, createGrabber as c, parseShortcut as i, useGrab as l, isApplePlatform as n, describeElement as o, matchesShortcut as r, matchComponentHints as s, formatShortcut as t };

package/dist/state-boundary.d.ts

@@ -0,0 +1,26 @@
+import { i as ForcedState } from "./force-state-CCqoTfVB.js";
+import { ReactNode } from "react";
+//#region src/plugins/design/state-boundary.d.ts
+export interface StateBoundaryProps {
+  /** Stable, page-unique id; the HUD States panel lists boundaries by it. */
+  id: string;
+  /** Renders the boundary; `forced` is the state to show instead of the real one, or null. */
+  children: (forced: ForcedState | null) => ReactNode;
+}
+/**
+ * Registers a loading/empty/error boundary with the HUD States panel
+ * (`forceState()` from `@hansenexus/hud/plugins/design`) and `?__state=`.
+ * Wrap the part of a page that branches on a query result:
+ *
+ * ```tsx
+ * <StateBoundary id="blog-post">
+ *   {(forced) => forced === "loading" || post === undefined ? <Skeleton /> : …}
+ * </StateBoundary>
+ * ```
+ *
+ * Production-safe to import: outside development it renders `children(null)`
+ * and nothing else.
+ */
+export declare function StateBoundary({ id, children }: StateBoundaryProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+//#endregion
+export type { ForcedState };

package/dist/state-boundary.js

@@ -0,0 +1,61 @@
+import { a as getForceStateSnapshot, c as subscribeForceState, o as getForceStateStore, s as resolveForcedState } from "./force-state-BaqWsmrf.js";
+import { createContext, useContext, useEffect, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/plugins/design/state-boundary.tsx
+/**
+* Build-time gate. A literal once the consumer's bundler inlines NODE_ENV, so
+* a production build folds `StateBoundary` to `children(null)` and drops
+* everything below, the store included: no production code path reads
+* `?__state=`.
+*/
+const FORCE_STATE_ENABLED = process.env.NODE_ENV === "development";
+/**
+* Registers a loading/empty/error boundary with the HUD States panel
+* (`forceState()` from `@hansenexus/hud/plugins/design`) and `?__state=`.
+* Wrap the part of a page that branches on a query result:
+*
+* ```tsx
+* <StateBoundary id="blog-post">
+*   {(forced) => forced === "loading" || post === undefined ? <Skeleton /> : …}
+* </StateBoundary>
+* ```
+*
+* Production-safe to import: outside development it renders `children(null)`
+* and nothing else.
+*/
+function StateBoundary({ id, children }) {
+	if (!FORCE_STATE_ENABLED) return children(null);
+	return /* @__PURE__ */ jsx(DevStateBoundary, {
+		id,
+		children
+	});
+}
+/** The enclosing boundary's id, so the store knows which boundaries are top-level. */
+const ParentBoundary = /* @__PURE__ */ createContext(null);
+const SERVER_SNAPSHOT = {
+	boundaries: [],
+	overrides: {},
+	param: null
+};
+function getServerSnapshot() {
+	return SERVER_SNAPSHOT;
+}
+function DevStateBoundary({ id, children }) {
+	const parentId = useContext(ParentBoundary);
+	const snapshot = useSyncExternalStore(subscribeForceState, getForceStateSnapshot, getServerSnapshot);
+	useEffect(() => {
+		const store = getForceStateStore();
+		store.syncSearch(window.location.search);
+		return store.register(id, parentId);
+	}, [id, parentId]);
+	const forced = resolveForcedState(snapshot, {
+		id,
+		parentId
+	});
+	return /* @__PURE__ */ jsx(ParentBoundary.Provider, {
+		value: id,
+		children: children(forced)
+	});
+}
+//#endregion
+export { StateBoundary };