@devframes/hub 0.8.2 → 0.9.0-beta.10

package/dist/node/initiate.d.mts

@@ -0,0 +1,274 @@
+import { i as InstallDevframeOptions, n as DevframeHubContext, t as CreateHubContextOptions } from "../context-D5TJIHwp.mjs";
+import { DEVFRAMES_HUB_BASE } from "../constants.mjs";
+import { DevframeInstanceRecord } from "devframe/internal";
+import { ConnectionMeta, DevframeDefinition, DevframeSseOptions, DevframeStorageScope, DevframeWsOptions, McpRouteOptions } from "devframe/types";
+import { DevframeAuthHandler } from "devframe/node/auth";
+import { WsOriginRegistry } from "devframe/rpc/transports/ws-server";
+import { Buffer } from "node:buffer";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
+//#region src/node/initiate.d.ts
+/** A `devframes` entry with per-mount dock customization. */
+interface HubDevframeEntry {
+  devframe: DevframeDefinition;
+  /** Per-mount overrides for the auto-synthesized iframe dock entry. */
+  dock?: InstallDevframeOptions['dock'];
+}
+type Thenable<T> = T | Promise<T>;
+type Arrayable<T> = T | readonly T[];
+/**
+ * One dock-type → prebuilt renderer-module registration for
+ * {@link InitHubOptions.renderers}. The hub serves the module at
+ * `<base>__renderers/<type>.mjs` and publishes it in the renderer manifest
+ * (the `devframe:dock-renderers` shared-state slot), so any viewer — the
+ * reference UI, a community viewer, a hand-rolled host page — lazily imports
+ * it the first time a dock of that `type` needs rendering.
+ *
+ * The module must be a **self-contained browser ES module** (its framework
+ * and styles bundled in) whose {@link DockRendererRegistration.importName}
+ * export is a ready `DockRenderer`. Renderer packages ship a node helper
+ * returning this shape — e.g. `jsonRenderUiRenderer()` from
+ * `@devframes/json-render-ui/hub`.
+ */
+interface DockRendererRegistration {
+  /** Dock `type` this renderer handles (e.g. `'json-render'`). */
+  type: string;
+  /** Absolute path of the prebuilt, self-contained browser ES module. */
+  file: string;
+  /**
+   * Named export carrying the renderer.
+   *
+   * @default 'default'
+   */
+  importName?: string;
+}
+/**
+ * The UI slot of a hub instance — pure data, zero policy. The hub itself is
+ * headless: whoever fills this slot decides what a viewer looks like.
+ * `@devframes/hub-ui` ships the reference implementation (`createUi()`);
+ * Vite DevTools or any community viewer supplies its own object to the same
+ * slot and reuses all the infrastructure.
+ */
+interface DevframeHubUi {
+  /**
+   * A standalone viewer SPA (built with relative asset paths) served at the
+   * hub base itself — open `<base>` in a tab and the devtools are there.
+   */
+  viewer?: {
+    /** Directory of the prebuilt viewer SPA. */
+    distDir: string;
+  };
+  /**
+   * A prebuilt, self-contained script served at `<base>embedded.js` — the
+   * floating-devtools bootstrap a host page loads with one
+   * `<script type="module" src="<base>embedded.js">` tag. Visibility policy
+   * (always-on, keyboard-summoned, …) belongs entirely to this entry.
+   */
+  embedded?: {
+    /** File path of the prebuilt single-file module. */
+    entry: string;
+  };
+  /**
+   * Extra UI-owned files the hub serves at `<base><key>`, each produced lazily
+   * from memory. Keys are base-relative paths; the content-type is inferred
+   * from the key's extension. A generic seam a viewer uses to publish
+   * arbitrary runtime documents without teaching the hub anything about
+   * their meaning.
+   */
+  assets?: Record<string, () => string | Uint8Array>;
+  /**
+   * A setup hook run once during hub init with the hub context — the UI
+   * slot's chance to publish its own static, boot-time config through the
+   * generic `ctx.staticConfig` (serialized into `ConnectionMeta.configs`).
+   * The reference UI's `createUi()` uses it to set
+   * `ctx.staticConfig.ui = { branding, … }`, reaching every mounted frame and
+   * the standalone viewer through the one connection handshake they perform.
+   * The hub stays policy-free about what the UI writes.
+   */
+  setup?: (ctx: DevframeHubContext) => void | Promise<void>;
+}
+type DevframesInput = Array<DevframeDefinition | HubDevframeEntry | Thenable<Arrayable<DevframeDefinition | HubDevframeEntry | null | undefined>> | (() => Thenable<Arrayable<DevframeDefinition | HubDevframeEntry | null | undefined>>)>;
+interface InitHubOptions {
+  /**
+   * Name for the hub instance, used in logs and diagnostics, and mcp server.
+   */
+  name?: string;
+  /**
+   * Version for the hub instance, used in logs and diagnostics, and mcp server.
+   */
+  version?: string;
+  /**
+   * Mount base the hub answers under — required so the mount path is
+   * explicit at the call site (pass the exported {@link DEVFRAMES_HUB_BASE}
+   * for the conventional `/__devframes/`). Every mounted devframe lives at
+   * `<base><id>/`, so the host app needs exactly one catch-all route. The
+   * resolved value is echoed back as {@link HubInstance.base} so route and
+   * middleware code references it instead of repeating the string.
+   */
+  base: string;
+  /**
+   * Devframes to mount: each runs its `setup()` against the shared hub
+   * context (one merged RPC registry, one WebSocket, one auth gate), serves
+   * its SPA at `<base><id>/`, and is auto-registered as an iframe dock.
+   * Wrap an entry in `{ devframe, dock }` to customize its synthesized dock
+   * (category, icon, a `clientScript` to run in the host page, …).
+   */
+  devframes?: DevframesInput;
+  /**
+   * Extra RPC declarations registered at context creation, alongside the
+   * hub built-ins — forwarded to `createHubContext`'s
+   * `builtinRpcDeclarations`. Declarative mode only (a pre-built `context`
+   * already made this choice).
+   */
+  rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations'];
+  /**
+   * Bring your own hub context instead of `devframes` — for hosts that
+   * assemble `createHubContext` + `ctx.install` themselves (with their own
+   * `DevframeHost` serving the frames). The instance then serves only the
+   * hub-level endpoints (`__connection.json`, `__index.json`,
+   * `__client-imports.js`, the WS transport, MCP, and the `ui` slot);
+   * serve each frame's meta yourself from {@link HubInstance.connectionMeta}.
+   */
+  context?: DevframeHubContext;
+  /**
+   * Runs once the context exists and every `devframes` entry is mounted —
+   * register docks, commands, terminals, and messages surfaces here.
+   */
+  configure?: (ctx: DevframeHubContext) => void | Promise<void>;
+  /** See {@link DevframeHubUi} — omitted, the hub stays fully headless. */
+  ui?: DevframeHubUi;
+  /**
+   * Prebuilt dock-renderer modules to serve and advertise — the composition
+   * seam that hands a renderer package (e.g. `@devframes/json-render-ui`) to
+   * a prebuilt viewer. Each {@link DockRendererRegistration} is served at
+   * `<base>__renderers/<type>.mjs` and published in the renderer manifest;
+   * clients import a module lazily the first time a dock of its `type`
+   * mounts. Renderers registered directly in client code
+   * (`createDevframeClientHost({ renderers })`) take precedence.
+   *
+   * ```ts
+   * import { jsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
+   *
+   * initHub({ ui: createUi(), renderers: [jsonRenderUiRenderer()] })
+   * ```
+   */
+  renderers?: readonly DockRendererRegistration[];
+  /**
+   * Share the host's `node:http` server for the WebSocket RPC endpoint
+   * (upgrade bound at `<base>__ws`). Hosts whose handlers never see upgrades
+   * (Next.js route handlers, Nitro, Rsbuild) ask for a side-car instead with
+   * `ws: { sidecar: true }`; hosts that get their server later wire
+   * {@link HubInstance.attach} / {@link HubInstance.handleUpgrade}.
+   */
+  server?: Server;
+  /**
+   * Explicit WebSocket control, same contract as `initDevframe`: the local
+   * binding resolves `ws.port` (pinned side-car) > `server` (shared upgrade)
+   * > `ws.sidecar` (auto-port side-car) > the host driving upgrades itself,
+   * while `url` overrides the advertisement (tunnel pattern) and `route`
+   * renames the upgrade segment (default `__ws`). Pass `false` to serve no
+   * WebSocket at all — clients connect over SSE instead (`backend: 'sse'`).
+   */
+  ws?: DevframeWsOptions | false;
+  /**
+   * SSE RPC endpoint control, same contract as `initDevframe` — enabled by
+   * default at `<base>__sse` as the more portable transport alongside the
+   * WebSocket. Pass `false` to disable, or a {@link DevframeSseOptions} to
+   * rename the route.
+   */
+  sse?: boolean | DevframeSseOptions;
+  /** Bind host for a side-car WebSocket server. Default: `localhost`. */
+  host?: string;
+  /**
+   * The hub's **single Auth**: one gate at the one shared transport covers
+   * every mounted frame, the MCP route, and the hub built-ins. Gates by
+   * default (devframe's interactive OTP); `false` opts out; a
+   * {@link DevframeAuthHandler} installs a custom scheme.
+   */
+  auth?: boolean | DevframeAuthHandler;
+  /**
+   * Expose the **aggregate** MCP endpoint at `<base>__mcp` — one
+   * Streamable-HTTP server over the shared context's whole tool registry
+   * (ids are already namespaced per plugin). Disabled by default.
+   */
+  mcp?: boolean | McpRouteOptions;
+  /**
+   * Public origin the host app is reachable at, or a getter. Derived lazily
+   * from the first request when omitted.
+   */
+  origin?: string | (() => string);
+  /**
+   * Publish this hub in the global instance registry
+   * (`~/.devframe/instances/`) so discovery tooling (`devframe connect`, the
+   * inspect plugin's Instances tab) lists it like any standalone devframe.
+   * Registration is a dynamic import that fires once the public origin
+   * resolves and is torn down on {@link HubInstance.close}. Defaults to off;
+   * pass `true` to enable, or an object to override individual record fields
+   * (`id`, `name`, `basePath`, …).
+   */
+  register?: boolean | Partial<DevframeInstanceRecord>;
+  /** Working directory for the hub context. Default: `process.cwd()`. */
+  cwd?: string;
+  /** Override where persisted devframe state lives. */
+  getStorageDir?: (scope: DevframeStorageScope) => string;
+  /** Extra WS-upgrade origins beyond the loopback default; `false` disables the gate. */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+  /** Destroy off-route upgrades on a shared `server` devframe's adapter owns outright. */
+  destroyUnmatchedUpgrades?: boolean;
+}
+interface HubInstance {
+  /**
+   * The normalized mount base this hub answers under (leading and trailing
+   * slash, e.g. `/__devframes/`). Reference it when wiring the mount — route
+   * guards, middleware path checks — instead of repeating the string literal.
+   */
+  base: string;
+  /**
+   * Web-standard request handler for the whole hub — mount it on one
+   * catch-all route under {@link HubInstance.base}.
+   */
+  handler: (request: Request) => Promise<Response>;
+  /** Connect/Express-style middleware over the same surface; `next()`s outside the base. */
+  nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  /**
+   * Route a host server's `upgrade` events to the shared RPC socket,
+   * returning a detach function — the manual counterpart to the `server`
+   * option, for hosts that get their `node:http` server only after the hub
+   * exists. Available on the default tier; a configured transport (`server`,
+   * `ws.port`, `ws.sidecar`, `ws.url`) already owns the socket and reports
+   * `DF0055` / `DF0056` instead.
+   */
+  attach: (server: Server) => () => void;
+  /**
+   * Complete a single `upgrade` event on the shared RPC socket, for hosts
+   * that already own an `upgrade` listener. Same availability as
+   * {@link HubInstance.attach}.
+   */
+  handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  /** Resolves once every frame is mounted and the WebSocket binding is live. */
+  ready: Promise<void>;
+  /** The shared hub context, once initialized. */
+  context: Promise<DevframeHubContext>;
+  /** The `ConnectionMeta` served at `<base>__connection.json` (and every frame base). */
+  connectionMeta: () => ConnectionMeta;
+  /** Tear down: WS transport/side-car, MCP sessions. */
+  close: () => Promise<void>;
+}
+/**
+ * Initiate a hub instance — the whole multi-devframe devtools surface
+ * behind one framework-agnostic, web-standard handler. Every mounted
+ * devframe shares one context (merged RPC registry, shared state, docks /
+ * terminals / messages / commands), one WebSocket transport, and one Auth;
+ * the instance serves each frame's SPA at `<base><id>/`, the discovery
+ * endpoints (`__connection.json`, `__index.json`, `__client-imports.js`),
+ * the aggregate MCP route, and whatever the {@link DevframeHubUi} slot
+ * provides — the hub itself stays headless.
+ *
+ * The factory is synchronous and initializes eagerly, and binds no port of
+ * its own: the WebSocket follows `server` / `ws` (see
+ * {@link InitHubOptions.ws}), or waits for the host to hand upgrades over
+ * through {@link HubInstance.attach}.
+ */
+declare function initHub(options: InitHubOptions): HubInstance;
+//#endregion
+export { DEVFRAMES_HUB_BASE, DevframeHubUi, DevframesInput, DockRendererRegistration, HubDevframeEntry, HubInstance, InitHubOptions, initHub };

package/dist/node/initiate.mjs

@@ -0,0 +1,267 @@
+import { DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase } from "../constants.mjs";
+import { t as createHubContext, v as diagnostics } from "../context-DzqMQ2mI.mjs";
+import { joinURL, withTrailingSlash, withoutLeadingSlash } from "ufo";
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_WS_ROUTE } from "devframe/constants";
+import { createH3DevframeHost, createInstanceShell, resolveInstanceRegister } from "devframe/internal";
+import { resolve } from "pathe";
+import process from "node:process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { mountStaticHandler } from "devframe/utils/serve-static";
+import { H3 } from "h3";
+//#region src/node/initiate.ts
+function normalizeDevframeEntry(entry) {
+	return "devframe" in entry ? entry : { devframe: entry };
+}
+/** Content-type for a UI asset key, inferred from its file extension. */
+function assetContentType(key) {
+	if (key.endsWith(".json")) return "application/json; charset=utf-8";
+	if (key.endsWith(".js") || key.endsWith(".mjs")) return "text/javascript; charset=utf-8";
+	if (key.endsWith(".css")) return "text/css; charset=utf-8";
+	if (key.endsWith(".svg")) return "image/svg+xml";
+	if (key.endsWith(".html")) return "text/html; charset=utf-8";
+	return "application/octet-stream";
+}
+/** Reserved filenames directly under the hub base — a frame id can't shadow them. */
+const RESERVED_HUB_PATHS = [
+	DEVFRAME_CONNECTION_META_FILENAME,
+	DEVFRAME_DOCK_IMPORTS_FILENAME,
+	DEVFRAME_WS_ROUTE,
+	DEVFRAME_MCP_ROUTE,
+	"__index.json",
+	"__renderers",
+	"embedded.js"
+];
+/**
+* Flatten the `devframes` input: await every thenable, call every factory,
+* spread the arrays, and drop the empty slots — so a host can build the list
+* conditionally (`isDev && loadInspect()`) without filtering it first.
+*/
+function resolveDevframesInput(input) {
+	return Promise.all(input.map(async (entry) => {
+		const resolved = await (typeof entry === "function" ? entry() : entry);
+		return (Array.isArray(resolved) ? resolved : [resolved]).filter((slot) => slot != null).map(normalizeDevframeEntry);
+	})).then((arrays) => arrays.flat());
+}
+/**
+* Validate the renderer-module registrations fail-fast: route-safe types
+* (each becomes the `<base>__renderers/<type>.mjs` URL segment), one module
+* per type, and an existing bundle file (renderer packages are prebuilt).
+*/
+function resolveRendererRegistrations(registrations) {
+	const seen = /* @__PURE__ */ new Set();
+	return registrations.map((registration) => {
+		if (!/^[\w.-]+$/.test(registration.type)) throw diagnostics.DF8110({ type: registration.type });
+		if (seen.has(registration.type)) throw diagnostics.DF8108({ type: registration.type });
+		seen.add(registration.type);
+		const file = resolve(registration.file);
+		if (!existsSync(file)) throw diagnostics.DF8109({
+			type: registration.type,
+			file
+		});
+		return {
+			...registration,
+			file
+		};
+	});
+}
+/**
+* Render the dock client-script import map as an ES module — one dynamic
+* import thunk per dock that carries a client script (`clientScript` on
+* iframe docks, `action`, `renderer`). External viewers import this module
+* from `<base>__client-imports.js` to load per-dock client code into the
+* host page; `importFrom` values must be URL paths the host serves.
+*/
+function renderClientImportsModule(ctx) {
+	const entries = [];
+	for (const [id, view] of ctx.docks.views) {
+		const scripts = [];
+		const anyView = view;
+		if (anyView.clientScript) scripts.push(anyView.clientScript);
+		if (anyView.action) scripts.push(anyView.action);
+		if (anyView.renderer) scripts.push(anyView.renderer);
+		if (scripts.length === 0) continue;
+		const thunks = scripts.map((script) => `() => import(${JSON.stringify(script.importFrom)})`);
+		entries.push(`  ${JSON.stringify(id)}: [${thunks.join(", ")}],`);
+	}
+	return `// Generated by @devframes/hub — dock client-script import map.\nexport const clientImports = {\n${entries.join("\n")}\n}\nexport default clientImports\n`;
+}
+/**
+* Initiate a hub instance — the whole multi-devframe devtools surface
+* behind one framework-agnostic, web-standard handler. Every mounted
+* devframe shares one context (merged RPC registry, shared state, docks /
+* terminals / messages / commands), one WebSocket transport, and one Auth;
+* the instance serves each frame's SPA at `<base><id>/`, the discovery
+* endpoints (`__connection.json`, `__index.json`, `__client-imports.js`),
+* the aggregate MCP route, and whatever the {@link DevframeHubUi} slot
+* provides — the hub itself stays headless.
+*
+* The factory is synchronous and initializes eagerly, and binds no port of
+* its own: the WebSocket follows `server` / `ws` (see
+* {@link InitHubOptions.ws}), or waits for the host to hand upgrades over
+* through {@link HubInstance.attach}.
+*/
+function initHub(options) {
+	const base = normalizeHubBase(options.base);
+	const baseNoSlash = base.slice(0, -1);
+	const app = new H3();
+	const cwd = options.cwd ?? process.cwd();
+	const frames = [];
+	const rendererRegistrations = resolveRendererRegistrations(options.renderers ?? []);
+	const shell = createInstanceShell({
+		base,
+		app,
+		host: options.host,
+		origin: options.origin,
+		auth: options.auth,
+		server: options.server,
+		ws: options.ws,
+		sse: options.sse,
+		allowedOrigins: options.allowedOrigins,
+		destroyUnmatchedUpgrades: options.destroyUnmatchedUpgrades,
+		register: resolveInstanceRegister(options.register, {
+			id: options.name ?? "devframes-hub",
+			...options.name !== void 0 ? { name: options.name } : {},
+			rootDir: cwd
+		}),
+		absoluteWsPath: true,
+		resolveSidecarPort: async (sidecarHost) => {
+			const { getPort } = await import("../dist-R0T2g9Vw.mjs");
+			return getPort({
+				port: 9777,
+				portRange: [9777, 9877],
+				host: sidecarHost
+			});
+		},
+		onMetaUnavailable: () => {
+			throw diagnostics.DF8003();
+		},
+		async init(api) {
+			if (options.context && options.devframes?.length) throw diagnostics.DF8002();
+			let ctx;
+			if (options.context) ctx = options.context;
+			else {
+				const host = {
+					...createH3DevframeHost({
+						origin: () => api.origin() ?? "http://localhost",
+						appName: "devframes",
+						workspaceRoot: cwd,
+						mount: (mountBase, dir) => {
+							mountStaticHandler(app, mountBase, dir);
+						}
+					}),
+					...options.getStorageDir ? { getStorageDir: options.getStorageDir } : {},
+					mountConnectionMeta: (frameBase) => {
+						app.use(joinURL(frameBase, DEVFRAME_CONNECTION_META_FILENAME), () => api.connectionMeta());
+					}
+				};
+				ctx = await createHubContext({
+					cwd,
+					workspaceRoot: cwd,
+					mode: "dev",
+					host,
+					...options.rpcDeclarations ? { builtinRpcDeclarations: options.rpcDeclarations } : {}
+				});
+			}
+			const devframes = await resolveDevframesInput(options.devframes ?? []);
+			for (const { devframe: def, dock } of devframes) {
+				if (RESERVED_HUB_PATHS.includes(def.id)) throw diagnostics.DF8000({ id: def.id });
+				if (!/^[\w.-]+$/.test(def.id)) throw diagnostics.DF8004({ id: def.id });
+				const frameBase = withTrailingSlash(joinURL(base, def.id));
+				await ctx.install(def, {
+					base: frameBase,
+					...dock ? { dock } : {}
+				});
+				frames.push({
+					id: def.id,
+					base: frameBase,
+					title: def.name
+				});
+			}
+			await options.configure?.(ctx);
+			await options.ui?.setup?.(ctx);
+			if (rendererRegistrations.length > 0) {
+				const manifest = {};
+				for (const registration of rendererRegistrations) manifest[registration.type] = {
+					importFrom: joinURL(base, "__renderers", `${registration.type}.mjs`),
+					...registration.importName ? { importName: registration.importName } : {}
+				};
+				(await ctx.rpc.sharedState.get(DOCK_RENDERERS_STATE_KEY, { initialValue: {} })).mutate(() => manifest);
+			}
+			const mcpConfig = options.mcp === true ? {} : options.mcp;
+			if (!mcpConfig) return { context: ctx };
+			const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? DEVFRAME_MCP_ROUTE);
+			const { mountMcpHttp } = await import("devframe/adapters/mcp");
+			const mounted = mountMcpHttp(app, ctx, joinURL(base, mcpRoute), {
+				serverName: options.name ?? "devframes-hub",
+				serverVersion: options.version ?? "0.0.0",
+				exposeSharedState: true,
+				allowedOrigins: mcpConfig.allowedOrigins
+			});
+			return {
+				context: ctx,
+				mcp: { path: mcpRoute },
+				dispose: mounted.dispose
+			};
+		},
+		mount(ctx, meta) {
+			app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta);
+			const indexDocument = () => ({
+				name: options.name,
+				version: options.version,
+				base,
+				frames,
+				endpoints: {
+					connection: DEVFRAME_CONNECTION_META_FILENAME,
+					clientImports: DEVFRAME_DOCK_IMPORTS_FILENAME,
+					index: "__index.json",
+					websocket: meta.websocket,
+					...meta.mcp ? { mcp: meta.mcp.path } : {},
+					...options.ui?.embedded ? { embedded: "embedded.js" } : {}
+				}
+			});
+			app.use(joinURL(base, "__index.json"), () => indexDocument());
+			app.use(joinURL(base, DEVFRAME_DOCK_IMPORTS_FILENAME), (event) => {
+				event.res.headers.set("Content-Type", "text/javascript; charset=utf-8");
+				event.res.headers.set("Cache-Control", "no-store");
+				return renderClientImportsModule(ctx);
+			});
+			if (options.ui?.embedded) {
+				const entry = resolve(options.ui.embedded.entry);
+				app.use(joinURL(base, "embedded.js"), async (event) => {
+					event.res.headers.set("Content-Type", "text/javascript; charset=utf-8");
+					event.res.headers.set("Cache-Control", "no-store");
+					return await readFile(entry);
+				});
+			}
+			for (const registration of rendererRegistrations) app.use(joinURL(base, "__renderers", `${registration.type}.mjs`), async (event) => {
+				event.res.headers.set("Content-Type", "text/javascript; charset=utf-8");
+				event.res.headers.set("Cache-Control", "no-store");
+				return await readFile(registration.file);
+			});
+			for (const [key, produce] of Object.entries(options.ui?.assets ?? {})) app.use(joinURL(base, key), (event) => {
+				event.res.headers.set("Content-Type", assetContentType(key));
+				event.res.headers.set("Cache-Control", "no-store");
+				return produce();
+			});
+			if (options.ui?.viewer) mountStaticHandler(app, base, resolve(options.ui.viewer.distDir));
+			else {
+				app.use(baseNoSlash, () => indexDocument());
+				app.use(base, () => indexDocument());
+			}
+		}
+	});
+	return {
+		base: shell.base,
+		handler: shell.handler,
+		nodeMiddleware: shell.nodeMiddleware,
+		attach: shell.attach,
+		handleUpgrade: shell.handleUpgrade,
+		ready: shell.ready,
+		context: shell.context,
+		connectionMeta: shell.connectionMeta,
+		close: shell.close
+	};
+}
+//#endregion
+export { DEVFRAMES_HUB_BASE, initHub };

package/dist/{settings-Byh48aCd.d.mts → settings-DfrRa9Wf.d.mts}

@@ -1,37 +1,5 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
 import { ConnectionMeta, EventEmitter } from "devframe/types";
-//#region src/types/json-render.d.ts
-/** @deprecated Use `DevframeJsonRenderSpec`'s element shape from `@devframes/json-render` instead. Removed in 0.8. */
-interface JsonRenderElement {
-  type: string;
-  props?: Record<string, unknown>;
-  children?: string[];
-  /** json-render event bindings (e.g. `{ press: { action: "my:action" } }`) */
-  on?: Record<string, unknown>;
-  /** json-render visibility condition */
-  visible?: unknown;
-  /** json-render repeat binding */
-  repeat?: unknown;
-  /** Allow additional json-render element fields */
-  [key: string]: unknown;
-}
-/** @deprecated Use `DevframeJsonRenderSpec` from `@devframes/json-render` instead. Removed in 0.8. */
-interface JsonRenderSpec {
-  root: string;
-  elements: Record<string, JsonRenderElement>;
-  /** Initial client-side state model for $state/$bindState expressions */
-  state?: Record<string, unknown>;
-}
-/** @deprecated Use `JsonRenderView` from `@devframes/json-render` instead. Removed in 0.8. */
-interface JsonRenderer {
-  /** Replace the entire spec */
-  updateSpec: (spec: JsonRenderSpec) => void | Promise<void>;
-  /** Update json-render state values (shallow merge into spec.state) */
-  updateState: (state: Record<string, unknown>) => void | Promise<void>;
-  /** Internal: shared state key used by the client to subscribe */
-  readonly _stateKey: string;
-}
-//#endregion
+import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/types/docks.d.ts
 interface DevframeDocksHost {
   readonly views: Map<string, DevframeDockUserEntry>;
@@ -82,6 +50,8 @@ type DevframeDockEntryIcon = string | {
   light: string;
   dark: string;
 };
+/** Color for a dock-bar entry's {@link DevframeDockEntryBase.badge} — mirrors json-render's `TabDescriptor.badgeVariant`. */
+type DevframeDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger';
 interface DevframeDockEntryBase {
   id: string;
   title: string;
@@ -146,6 +116,11 @@ interface DevframeDockEntryBase {
    * Badge text to display on the dock icon (e.g., unread count)
    */
   badge?: string;
+  /**
+   * Colors {@link badge}. Omitted (or `'default'`) keeps the existing neutral
+   * fill, so every pre-existing badge consumer keeps its current look.
+   */
+  badgeVariant?: DevframeDockBadgeVariant;
   /**
    * Id of the group this entry belongs to. When set, hosts collapse this entry
    * under the matching group's button instead of showing it directly on the
@@ -357,20 +332,6 @@ interface DevframeViewBuiltin extends DevframeDockEntryBase {
   type: '~builtin';
   id: string;
 }
-/**
- * @deprecated json-render moved out of the hub into the opt-in
- * `@devframes/json-render` integration in 0.7, which contributes its own
- * `'json-render'` entry (carrying a serializable view ref, not a live
- * `JsonRenderer` handle) to {@link DevframeDockEntryRegistry} via declaration
- * merging. This type is kept for compatibility but is no longer a member of
- * {@link DevframeDockUserEntry} — use `@devframes/json-render/hub` instead.
- * Removed in 0.8.
- */
-interface DevframeViewJsonRender extends DevframeDockEntryBase {
-  type: 'json-render';
-  /** JsonRenderer handle created by the deprecated ctx.createJsonRenderer() */
-  ui: JsonRenderer;
-}
 /**
  * A dock group: a single dock-bar button that collapses every entry whose
  * {@link DevframeDockEntryBase.groupId} matches this group's `id`.
@@ -506,9 +467,6 @@ interface DevframeCommandBase {
  * `when` clauses are evaluated client-side only and are **not** enforced for
  * agent calls — opt in a `when`-gated command only if running it outside its
  * UI context is safe.
- *
- * @experimental The agent-native surface is experimental and may change
- * without a major version bump until it stabilizes.
  */
 interface DevframeCommandAgentOptions {
   /**
@@ -545,8 +503,6 @@ interface DevframeServerCommandInput extends DevframeCommandBase {
   /**
    * Opt this command in to the agent surface (`ctx.agent` → MCP). Requires a
    * `handler`. See {@link DevframeCommandAgentOptions}.
-   *
-   * @experimental
    */
   agent?: DevframeCommandAgentOptions;
   /**
@@ -619,14 +575,35 @@ interface DevframeCommandShortcutOverrides {
 }
 //#endregion
 //#region src/types/settings.d.ts
+/**
+ * Persisted per-user dock + command settings, synced over the
+ * `devframe:user-settings` shared state. The generic base carries the hub's
+ * own dock-registry and command model that every viewer shares; a viewer
+ * augments it with its own reference-UI toggles via declaration merging:
+ *
+ * ```ts
+ * declare module '@devframes/hub/types' {
+ *   interface DevframeDocksUserSettings {
+ *     myViewerToggle?: boolean
+ *   }
+ * }
+ * ```
+ *
+ * Augmented fields are optional so the hub's `DEFAULT_STATE_USER_SETTINGS()`
+ * (which knows nothing about them) stays assignable — an absent value reads
+ * as the viewer's documented default.
+ */
 interface DevframeDocksUserSettings {
+  /** Ids of dock entries the user has hidden from the bar. */
   docksHidden: string[];
+  /** Category ids the user has collapsed/hidden on the bar. */
   docksCategoriesHidden: string[];
+  /** Ids of dock entries the user has pinned. */
   docksPinned: string[];
+  /** Per-entry sort weight overriding the registry's default order. */
   docksCustomOrder: Record<string, number>;
-  showIframeAddressBar: boolean;
-  closeOnOutsideClick: boolean;
+  /** Per-command keybinding overrides (empty array = shortcut disabled). */
   commandShortcuts: DevframeCommandShortcutOverrides;
 }
 //#endregion
-export { DevframeViewLauncher as A, DevframeDocksHost as C, DevframeViewGroup as D, DevframeViewCustomRender as E, RemoteDockOptions as F, JsonRenderElement as I, JsonRenderSpec as L, FrameSubTabsConfig as M, NavTarget as N, DevframeViewIframe as O, RemoteConnectionInfo as P, JsonRenderer as R, DevframeDocksActiveState as S, DevframeViewBuiltin as T, DevframeDockEntryBase as _, DevframeCommandEntry as a, DevframeDockEntryRegistry as b, DevframeCommandShortcutOverrides as c, DevframeServerCommandEntry as d, DevframeServerCommandInput as f, DevframeDockEntry as g, DevframeDockEntriesGrouped as h, DevframeCommandBase as i, DevframeViewLauncherStatus as j, DevframeViewJsonRender as k, DevframeCommandsHost as l, DevframeDockActivation as m, DevframeClientCommand as n, DevframeCommandHandle as o, ClientScriptEntry as p, DevframeCommandAgentOptions as r, DevframeCommandKeybinding as s, DevframeDocksUserSettings as t, DevframeCommandsHostEvents as u, DevframeDockEntryCategory as v, DevframeViewAction as w, DevframeDockUserEntry as x, DevframeDockEntryIcon as y };
+export { DevframeViewLauncher as A, DevframeDocksActiveState as C, DevframeViewCustomRender as D, DevframeViewBuiltin as E, RemoteDockOptions as F, FrameSubTabsConfig as M, NavTarget as N, DevframeViewGroup as O, RemoteConnectionInfo as P, DevframeDockUserEntry as S, DevframeViewAction as T, DevframeDockEntry as _, DevframeCommandEntry as a, DevframeDockEntryIcon as b, DevframeCommandShortcutOverrides as c, DevframeServerCommandEntry as d, DevframeServerCommandInput as f, DevframeDockEntriesGrouped as g, DevframeDockBadgeVariant as h, DevframeCommandBase as i, DevframeViewLauncherStatus as j, DevframeViewIframe as k, DevframeCommandsHost as l, DevframeDockActivation as m, DevframeClientCommand as n, DevframeCommandHandle as o, ClientScriptEntry as p, DevframeCommandAgentOptions as r, DevframeCommandKeybinding as s, DevframeDocksUserSettings as t, DevframeCommandsHostEvents as u, DevframeDockEntryBase as v, DevframeDocksHost as w, DevframeDockEntryRegistry as x, DevframeDockEntryCategory as y };