@devframes/hub 0.8.2 → 0.9.0-beta.1

package/dist/node/initiate.d.mts

@@ -0,0 +1,267 @@
+import { i as InstallDevframeOptions, n as DevframeHubContext, t as CreateHubContextOptions } from "../context-Dz0j8Eyg.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[];
+/** Default mount base for a hub instance — one namespace, one catch-all. */
+declare const DEVFRAMES_HUB_BASE = "/__devframes/";
+/**
+ * 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 (e.g. `branding.json`); the
+   * content-type is inferred from the key's extension. A generic seam a viewer
+   * uses to publish small runtime documents (the reference UI serves its
+   * branding this way) without teaching the hub anything about their meaning.
+   */
+  assets?: Record<string, () => string | Uint8Array>;
+}
+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.
+   *
+   * @experimental
+   */
+  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,271 @@
+import { DOCK_RENDERERS_STATE_KEY } from "../constants.mjs";
+import { t as createHubContext, v as diagnostics } from "../context-DPdojIW8.mjs";
+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 { cleanDoubleSlashes, joinURL, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
+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 };
+}
+/** Default mount base for a hub instance — one namespace, one catch-all. */
+const DEVFRAMES_HUB_BASE = "/__devframes/";
+/** 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());
+}
+function normalizeBase(base) {
+	return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)));
+}
+/**
+* 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 = normalizeBase(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);
+			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-B1qJ47d5.d.mts

@@ -0,0 +1,13 @@
+import { s as DevframeCommandShortcutOverrides } from "./commands-CAcTUSlj.mjs";
+//#region src/types/settings.d.ts
+interface DevframeDocksUserSettings {
+  docksHidden: string[];
+  docksCategoriesHidden: string[];
+  docksPinned: string[];
+  docksCustomOrder: Record<string, number>;
+  showIframeAddressBar: boolean;
+  closeOnOutsideClick: boolean;
+  commandShortcuts: DevframeCommandShortcutOverrides;
+}
+//#endregion
+export { DevframeDocksUserSettings as t };

package/dist/types/index.d.mts

@@ -1,4 +1,5 @@
-import { A as DevframeViewLauncher, C as DevframeDocksHost, D as DevframeViewGroup, E as DevframeViewCustomRender, F as RemoteDockOptions, I as JsonRenderElement, L as JsonRenderSpec, M as FrameSubTabsConfig, N as NavTarget, O as DevframeViewIframe, P as RemoteConnectionInfo, R as JsonRenderer, S as DevframeDocksActiveState, T as DevframeViewBuiltin, _ as DevframeDockEntryBase, a as DevframeCommandEntry, b as DevframeDockEntryRegistry, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntry, h as DevframeDockEntriesGrouped, i as DevframeCommandBase, j as DevframeViewLauncherStatus, k as DevframeViewJsonRender, l as DevframeCommandsHost, m as DevframeDockActivation, n as DevframeClientCommand, o as DevframeCommandHandle, p as ClientScriptEntry, r as DevframeCommandAgentOptions, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, u as DevframeCommandsHostEvents, v as DevframeDockEntryCategory, w as DevframeViewAction, x as DevframeDockUserEntry, y as DevframeDockEntryIcon } from "../settings-Byh48aCd.mjs";
-import { C as DevframeMessageShortcutInput, D as DevframeMessagesListDelta, E as DevframeMessagesLevelShortcuts, S as DevframeMessageLevel, T as DevframeMessagesHost, _ as DevframeMessageEntry, a as DevframeChildProcessOutput, b as DevframeMessageFilePosition, c as DevframePtyExecuteOptions, d as DevframeTerminalSessionBase, f as DevframeTerminalStatus, g as DevframeMessageElementPosition, h as DevframeMessageActivateAction, i as DevframeChildProcessExecuteOptions, l as DevframePtyTerminalSession, m as DevframeMessageAction, n as DevframeHubContext, o as DevframeChildProcessResult, p as DevframeTerminalsHost, s as DevframeChildProcessTerminalSession, t as CreateHubContextOptions, u as DevframeTerminalSession, v as DevframeMessageEntryFrom, w as DevframeMessagesClient, x as DevframeMessageHandle, y as DevframeMessageEntryInput } from "../context-BSgzLnsu.mjs";
-import { C as RpcStreamingChannel, E as Thenable, S as RpcSharedStateHost, T as RpcStreamingHost, _ as RpcBroadcastOptions, a as DevframeDiagnosticsLogger, b as RpcFunctionsHost, c as DevframeRpcClientFunctions, d as DevframeViewHost, f as EntriesToObject, g as PartialWithoutId, h as EventsMap, i as DevframeDiagnosticsHost, l as DevframeRpcServerFunctions, m as EventUnsubscribe, n as DevframeCapabilities, o as DevframeHost, p as EventEmitter, r as DevframeDiagnosticsDefinition, s as DevframeNodeRpcSession, t as ConnectionMeta, u as DevframeRpcSharedStates, v as RpcDefinitionsFilter, w as RpcStreamingChannelOptions, x as RpcSharedStateGetOptions, y as RpcDefinitionsToFunctions } from "../index-IzywMKfP.mjs";
-export { ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, DevframeChildProcessExecuteOptions, DevframeChildProcessOutput, DevframeChildProcessResult, DevframeChildProcessTerminalSession, DevframeClientCommand, DevframeCommandAgentOptions, DevframeCommandBase, DevframeCommandEntry, DevframeCommandHandle, DevframeCommandKeybinding, DevframeCommandShortcutOverrides, DevframeCommandsHost, DevframeCommandsHostEvents, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, DevframeDockActivation, DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDockEntryBase, DevframeDockEntryCategory, DevframeDockEntryIcon, DevframeDockEntryRegistry, DevframeDockUserEntry, DevframeDocksActiveState, DevframeDocksHost, DevframeDocksUserSettings, type DevframeHost, type DevframeHubContext, DevframeMessageAction, DevframeMessageActivateAction, DevframeMessageElementPosition, DevframeMessageEntry, DevframeMessageEntryFrom, DevframeMessageEntryInput, DevframeMessageFilePosition, DevframeMessageHandle, DevframeMessageLevel, DevframeMessageShortcutInput, DevframeMessagesClient, DevframeMessagesHost, DevframeMessagesLevelShortcuts, DevframeMessagesListDelta, type DevframeNodeRpcSession, DevframePtyExecuteOptions, DevframePtyTerminalSession, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, DevframeServerCommandEntry, DevframeServerCommandInput, DevframeTerminalSession, DevframeTerminalSessionBase, DevframeTerminalStatus, DevframeTerminalsHost, DevframeViewAction, DevframeViewBuiltin, DevframeViewCustomRender, DevframeViewGroup, type DevframeViewHost, DevframeViewIframe, DevframeViewJsonRender, DevframeViewLauncher, DevframeViewLauncherStatus, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, FrameSubTabsConfig, JsonRenderElement, JsonRenderSpec, JsonRenderer, NavTarget, type PartialWithoutId, RemoteConnectionInfo, RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type Thenable };
+import { C as DevframeMessageHandle, D as DevframeMessagesHost, E as DevframeMessagesClient, O as DevframeMessagesLevelShortcuts, S as DevframeMessageFilePosition, T as DevframeMessageShortcutInput, _ as DevframeMessageCommandAction, a as DevframeChildProcessExecuteOptions, b as DevframeMessageEntryFrom, c as DevframeChildProcessTerminalSession, d as DevframeTerminalSession, f as DevframeTerminalSessionBase, g as DevframeMessageActivateAction, h as DevframeMessageAction, k as DevframeMessagesListDelta, l as DevframePtyExecuteOptions, m as DevframeTerminalsHost, n as DevframeHubContext, o as DevframeChildProcessOutput, p as DevframeTerminalStatus, s as DevframeChildProcessResult, t as CreateHubContextOptions, u as DevframePtyTerminalSession, v as DevframeMessageElementPosition, w as DevframeMessageLevel, x as DevframeMessageEntryInput, y as DevframeMessageEntry } from "../context-Dz0j8Eyg.mjs";
+import { A as FrameSubTabsConfig, C as DevframeViewAction, D as DevframeViewIframe, E as DevframeViewGroup, M as RemoteConnectionInfo, N as RemoteDockOptions, O as DevframeViewLauncher, S as DevframeDocksHost, T as DevframeViewCustomRender, _ as DevframeDockEntryCategory, a as DevframeCommandHandle, b as DevframeDockUserEntry, c as DevframeCommandsHost, d as DevframeServerCommandInput, f as ClientScriptEntry, g as DevframeDockEntryBase, h as DevframeDockEntry, i as DevframeCommandEntry, j as NavTarget, k as DevframeViewLauncherStatus, l as DevframeCommandsHostEvents, m as DevframeDockEntriesGrouped, n as DevframeCommandAgentOptions, o as DevframeCommandKeybinding, p as DevframeDockActivation, r as DevframeCommandBase, s as DevframeCommandShortcutOverrides, t as DevframeClientCommand, u as DevframeServerCommandEntry, v as DevframeDockEntryIcon, w as DevframeViewBuiltin, x as DevframeDocksActiveState, y as DevframeDockEntryRegistry } from "../commands-CAcTUSlj.mjs";
+import { t as DevframeDocksUserSettings } from "../settings-B1qJ47d5.mjs";
+import { C as RpcStreamingChannel, E as Thenable, S as RpcSharedStateHost, T as RpcStreamingHost, _ as RpcBroadcastOptions, a as DevframeDiagnosticsLogger, b as RpcFunctionsHost, c as DevframeRpcClientFunctions, d as DevframeViewHost, f as EntriesToObject, g as PartialWithoutId, h as EventsMap, i as DevframeDiagnosticsHost, l as DevframeRpcServerFunctions, m as EventUnsubscribe, n as DevframeCapabilities, o as DevframeHost, p as EventEmitter, r as DevframeDiagnosticsDefinition, s as DevframeNodeRpcSession, t as ConnectionMeta, u as DevframeRpcSharedStates, v as RpcDefinitionsFilter, w as RpcStreamingChannelOptions, x as RpcSharedStateGetOptions, y as RpcDefinitionsToFunctions } from "../index-p4BktGvQ.mjs";
+export { ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, DevframeChildProcessExecuteOptions, DevframeChildProcessOutput, DevframeChildProcessResult, DevframeChildProcessTerminalSession, DevframeClientCommand, DevframeCommandAgentOptions, DevframeCommandBase, DevframeCommandEntry, DevframeCommandHandle, DevframeCommandKeybinding, DevframeCommandShortcutOverrides, DevframeCommandsHost, DevframeCommandsHostEvents, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, DevframeDockActivation, DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDockEntryBase, DevframeDockEntryCategory, DevframeDockEntryIcon, DevframeDockEntryRegistry, DevframeDockUserEntry, DevframeDocksActiveState, DevframeDocksHost, DevframeDocksUserSettings, type DevframeHost, type DevframeHubContext, DevframeMessageAction, DevframeMessageActivateAction, DevframeMessageCommandAction, DevframeMessageElementPosition, DevframeMessageEntry, DevframeMessageEntryFrom, DevframeMessageEntryInput, DevframeMessageFilePosition, DevframeMessageHandle, DevframeMessageLevel, DevframeMessageShortcutInput, DevframeMessagesClient, DevframeMessagesHost, DevframeMessagesLevelShortcuts, DevframeMessagesListDelta, type DevframeNodeRpcSession, DevframePtyExecuteOptions, DevframePtyTerminalSession, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, DevframeServerCommandEntry, DevframeServerCommandInput, DevframeTerminalSession, DevframeTerminalSessionBase, DevframeTerminalStatus, DevframeTerminalsHost, DevframeViewAction, DevframeViewBuiltin, DevframeViewCustomRender, DevframeViewGroup, type DevframeViewHost, DevframeViewIframe, DevframeViewLauncher, DevframeViewLauncherStatus, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, FrameSubTabsConfig, NavTarget, type PartialWithoutId, RemoteConnectionInfo, RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type Thenable };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@devframes/hub",
   "type": "module",
-  "version": "0.8.2",
-  "description": "Framework-neutral hub layer for devframe — docks, terminals, messages, commands.",
+  "version": "0.9.0-beta.1",
+  "description": "Hub layer that orchestrates devframe docks, terminals, messages, and commands on any host.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/devframes/devframe#readme",
@@ -24,6 +24,7 @@
     ".": "./dist/index.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
+    "./initiate": "./dist/node/initiate.mjs",
     "./node": "./dist/node/index.mjs",
     "./types": "./dist/types/index.mjs",
     "./package.json": "./package.json"
@@ -33,23 +34,26 @@
     "dist"
   ],
   "peerDependencies": {
-    "devframe": "0.8.2"
+    "devframe": "0.9.0-beta.1"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "destr": "^2.0.5",
+    "h3": "^2.0.1-rc.26",
     "nostics": "^1.2.0",
     "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
     "tinyexec": "^1.3.0",
+    "ufo": "^1.6.4",
     "zigpty": "^0.2.1"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
+    "get-port-please": "^3.2.0",
     "mlly": "^1.8.2",
     "tsdown": "^0.22.14",
     "valibot": "^1.4.2",
-    "devframe": "0.8.2"
+    "devframe": "0.9.0-beta.1"
   },
   "scripts": {
     "build": "tsdown",

package/dist/define-Pbx8dsKz.mjs

@@ -1,21 +0,0 @@
-import { createDefineWrapperWithContext } from "devframe/rpc";
-//#region src/define.ts
-const defineHubRpcFunction = createDefineWrapperWithContext();
-function defineCommand(command) {
-	return command;
-}
-function defineDockEntry(entry) {
-	return entry;
-}
-/**
-* @deprecated json-render moved out of the hub into the opt-in
-* `@devframes/json-render` integration in 0.7. This identity helper is kept
-* so existing imports keep compiling — pass your spec directly to
-* `createJsonRenderView` (from `@devframes/json-render/node`) instead.
-* Removed in 0.8.
-*/
-function defineJsonRenderSpec(spec) {
-	return spec;
-}
-//#endregion
-export { defineJsonRenderSpec as i, defineDockEntry as n, defineHubRpcFunction as r, defineCommand as t };