@devframes/hub 0.9.0-beta.1 → 0.9.0-beta.10

package/dist/client/index.d.mts

@@ -1,7 +1,6 @@
-import { E as DevframeMessagesClient, x as DevframeMessageEntryInput } from "../context-Dz0j8Eyg.mjs";
-import { D as DevframeViewIframe, M as RemoteConnectionInfo, b as DevframeDockUserEntry, f as ClientScriptEntry, h as DevframeDockEntry, i as DevframeCommandEntry, j as NavTarget, m as DevframeDockEntriesGrouped, o as DevframeCommandKeybinding, t as DevframeClientCommand, v as DevframeDockEntryIcon } from "../commands-CAcTUSlj.mjs";
-import { t as DevframeDocksUserSettings } from "../settings-B1qJ47d5.mjs";
-import "../index-p4BktGvQ.mjs";
+import { E as DevframeMessagesClient, x as DevframeMessageEntryInput } from "../context-D5TJIHwp.mjs";
+import { N as NavTarget, P as RemoteConnectionInfo, S as DevframeDockUserEntry, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, g as DevframeDockEntriesGrouped, k as DevframeViewIframe, n as DevframeClientCommand, p as ClientScriptEntry, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-DfrRa9Wf.mjs";
+import "../index-coDmWngQ.mjs";
 import { DevframeClientRpcHost, DevframeConnection, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientOptions, DevframeRpcContext, RpcClientEvents, RpcClientEvents as RpcClientEvents$1 } from "devframe/client";
 import { EventEmitter } from "devframe/types";
 import { SharedState } from "devframe/utils/shared-state";
@@ -135,9 +134,30 @@ interface DockPanelStorage {
   top: number;
   left: number;
   position: 'left' | 'right' | 'bottom' | 'top';
-  open: boolean;
   inactiveTimeout: number;
 }
+/**
+ * Per-tab UI state of the dock panel, distinct from the browser-shared geometry
+ * in {@link DockPanelStorage}. A viewer persists this to `sessionStorage` so a
+ * reload (or the RPC auth handshake that follows one) restores the panel to
+ * exactly where the developer left it — which dock was open, and the
+ * address-bar route of that dock's iframe. Kept `sessionStorage`-scoped (not
+ * `localStorage`) because it is per-tab navigation state: two tabs open against
+ * the same dev server each keep their own selection rather than fighting over a
+ * shared one. Every field is serializable.
+ */
+interface DockSessionStorage {
+  /** Whether the dock panel is open. */
+  open: boolean;
+  /** The currently selected dock entry id, or `null` when nothing is open. */
+  selectedDockId: string | null;
+  /**
+   * The live address-bar URL of the selected iframe dock, restored as that
+   * iframe's boot `src` on the next load so the deep-linked route survives a
+   * reload. `null` when the selected dock has no iframe route to remember.
+   */
+  selectedDockRoute: string | null;
+}
 type DockClientType = 'embedded' | 'standalone';
 interface DocksContext extends DevframeRpcContext {
   /**
@@ -197,16 +217,41 @@ interface WhenClauseContext {
 type DevframeClientContext = DocksContext;
 interface DocksPanelContext {
   store: DockPanelStorage;
+  /**
+   * Per-tab session UI state — whether the panel is open, which dock is
+   * selected, and that dock's iframe route. Restored across reloads (and the
+   * auth handshake that follows one) by a viewer that persists it to
+   * `sessionStorage`.
+   */
+  session: DockSessionStorage;
   isDragging: boolean;
   isResizing: boolean;
   readonly isVertical: boolean;
+  /**
+   * Claim the persisted {@link DockSessionStorage.selectedDockRoute boot route} for a dock
+   * id, once. Returns the saved address-bar URL only for the dock that was
+   * selected before the last reload — and only on the first call for it — so a
+   * restored iframe boots deep-linked while a later switch to a different dock
+   * (whose live route isn't reflected in {@link DockSessionStorage.selectedDockRoute} yet)
+   * doesn't reuse the stale value. Returns `null` otherwise.
+   */
+  consumeBootRoute?: (id: string) => string | null;
 }
 interface DocksEntriesContext {
   selectedId: string | null;
+  selectedRoute: string | null;
   readonly selected: DevframeDockEntry | null;
   entries: DevframeDockEntry[];
   entryToStateMap: Map<string, DockEntryState>;
   groupedEntries: DevframeDockEntriesGrouped;
+  /**
+   * The resolved top-level category ordering — `DEFAULT_CATEGORIES_ORDER`,
+   * overridden by every installed devframe's own `dock.categoryOrder`
+   * (`ConnectionMeta.configs.dock.categoryOrder`), overridden again by the
+   * host page's own `createDevframeClientHost({ categoryOrder })`. Fixed
+   * for the life of the session — resolved once at boot.
+   */
+  readonly categoryOrder: Record<string, number>;
   settings: SharedState<DevframeDocksUserSettings>;
   /**
    * Get the state of a dock entry by its ID
@@ -339,6 +384,79 @@ declare function resolveDockUrl(url: string, connection: DevframeConnection): st
 /** Resolve URL-backed dock icons while preserving Iconify names and data URLs. */
 declare function resolveDockIcon(icon: DevframeDockEntryIcon, connection: DevframeConnection): DevframeDockEntryIcon;
 //#endregion
+//#region src/client/frame-location.d.ts
+/**
+ * Live location tracking for an iframe dock.
+ *
+ * An iframe dock's address bar — and the route persisted from it into
+ * `DockSessionStorage.selectedDockRoute` — has to follow wherever the embedded
+ * app actually goes. The `load` event only covers whole-document navigations, so
+ * an SPA router moving between routes with `history.pushState()` leaves both
+ * showing the URL the frame booted with.
+ *
+ * {@link watchFrameLocation} closes that gap for a same-origin frame, reporting
+ * `location.href` on every navigation it can observe:
+ *
+ * - `popstate` / `hashchange` — back/forward and hash routing;
+ * - `history.pushState`/`replaceState`, wrapped in place (and restored on
+ *   dispose) because those two fire no event of their own;
+ * - the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API)'s
+ *   `currententrychange` where it exists, which reports post-commit and so also
+ *   catches what a wrapper structurally cannot — a router holding a reference to
+ *   `pushState` captured before this watch attached;
+ * - `load`, which also re-subscribes: a document navigation swaps the frame's
+ *   `history`/`navigation` objects, so the previous subscription dies with them.
+ *
+ * These sources overlap deliberately rather than being chosen between, since a
+ * report is deduped against the last href — the cost of hearing the same
+ * navigation twice is nothing, and the cost of missing one is a stale route.
+ *
+ * A cross-origin frame reports nothing — its location is unreadable by design,
+ * so the caller keeps the last URL it knew.
+ */
+/** The minimal `history` surface the watcher wraps. Injectable for tests. */
+interface FrameLocationHistory {
+  pushState: (...args: any[]) => void;
+  replaceState: (...args: any[]) => void;
+}
+/** The minimal frame-window surface the watcher reads and subscribes to. */
+interface FrameLocationWindow {
+  readonly location: {
+    readonly href: string;
+  };
+  readonly history?: FrameLocationHistory;
+  /** Present only where the Navigation API ships. */
+  readonly navigation?: {
+    addEventListener: (type: 'currententrychange', listener: () => void) => void;
+    removeEventListener: (type: 'currententrychange', listener: () => void) => void;
+  };
+  addEventListener: (type: 'popstate' | 'hashchange', listener: () => void) => void;
+  removeEventListener: (type: 'popstate' | 'hashchange', listener: () => void) => void;
+}
+/** The minimal iframe surface the watcher needs. Injectable for tests. */
+interface FrameLocationTarget {
+  readonly contentWindow: FrameLocationWindow | null;
+  addEventListener: (type: 'load', listener: () => void) => void;
+  removeEventListener: (type: 'load', listener: () => void) => void;
+}
+interface WatchFrameLocationOptions {
+  /** The live iframe whose location is tracked. */
+  iframe: FrameLocationTarget;
+  /** Called with the frame's `location.href` on each observed change. */
+  onChange: (href: string) => void;
+  /**
+   * The href the caller already shows, so an initial report is only made when
+   * the frame is somewhere else (a frame re-attached mid-session, say).
+   */
+  initial?: string;
+}
+/**
+ * Track a frame's location until the returned disposer is called. Disposing
+ * detaches every listener and restores any wrapped `history` method, leaving the
+ * embedded page as it was found.
+ */
+declare function watchFrameLocation(options: WatchFrameLocationOptions): () => void;
+//#endregion
 //#region src/client/frame-nav.d.ts
 /**
  * Shared-iframe soft navigation — the viewer-side half of a host↔iframe
@@ -504,7 +622,7 @@ interface DevframeClientHostOptions {
    *
    * Keys are merged over `DEFAULT_CATEGORIES_ORDER`, so the host app only
    * lists the categories it wants to move; any category absent from the map
-   * keeps its default weight (falling back to `0`).
+   * keeps its default weight.
    *
    * @example
    * ```ts
@@ -580,4 +698,4 @@ declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | n
  */
 declare function connectRemoteDevframe(options?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
 //#endregion
-export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, CreateDockRenderersContextOptions, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockRegistration, DockRenderer, DockRendererInstance, DockRendererManifest, DockRendererMountOptions, DockRendererMountResult, DockRenderersContext, DocksConnectionContext, DocksContext, DocksEntriesContext, DocksPanelContext, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, FrameNavClient, FrameNavClientOptions, FrameNavEnvelope, FrameNavFrameMessage, FrameNavHostMessage, FrameNavHostPayload, FrameNavListenTarget, FrameTab, MessagesClientOptions, type RpcClientEvents, WhenClauseContext, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl };
+export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, CreateDockRenderersContextOptions, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockRegistration, DockRenderer, DockRendererInstance, DockRendererManifest, DockRendererMountOptions, DockRendererMountResult, DockRenderersContext, DockSessionStorage, DocksConnectionContext, DocksContext, DocksEntriesContext, DocksPanelContext, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, FrameLocationHistory, FrameLocationTarget, FrameLocationWindow, FrameNavClient, FrameNavClientOptions, FrameNavEnvelope, FrameNavFrameMessage, FrameNavHostMessage, FrameNavHostPayload, FrameNavListenTarget, FrameTab, MessagesClientOptions, type RpcClientEvents, WatchFrameLocationOptions, WhenClauseContext, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };

package/dist/client/index.mjs

@@ -69,6 +69,88 @@ function resolveDockIcon(icon, connection) {
 	};
 }
 //#endregion
+//#region src/client/frame-location.ts
+/**
+* Track a frame's location until the returned disposer is called. Disposing
+* detaches every listener and restores any wrapped `history` method, leaving the
+* embedded page as it was found.
+*/
+function watchFrameLocation(options) {
+	const { iframe, onChange } = options;
+	let lastReported = options.initial;
+	let detach;
+	let disposed = false;
+	/**
+	* The frame's window, or `null` when its location can't be read. Touching
+	* `location.href` is the cross-origin probe — it throws for a foreign
+	* document, where there is nothing to observe.
+	*/
+	function readableWindow() {
+		try {
+			const win = iframe.contentWindow;
+			return win && typeof win.location.href === "string" ? win : null;
+		} catch {
+			return null;
+		}
+	}
+	function report() {
+		const href = readableWindow()?.location.href;
+		if (!href || href === "about:blank" || href === lastReported) return;
+		lastReported = href;
+		onChange(href);
+	}
+	function subscribe() {
+		const win = readableWindow();
+		if (!win) return;
+		const listeners = [];
+		win.addEventListener("popstate", report);
+		win.addEventListener("hashchange", report);
+		listeners.push(() => {
+			win.removeEventListener("popstate", report);
+			win.removeEventListener("hashchange", report);
+		});
+		const { navigation, history } = win;
+		if (navigation) {
+			navigation.addEventListener("currententrychange", report);
+			listeners.push(() => navigation.removeEventListener("currententrychange", report));
+		}
+		if (history) {
+			const originals = {
+				pushState: history.pushState,
+				replaceState: history.replaceState
+			};
+			for (const method of ["pushState", "replaceState"]) history[method] = function(...args) {
+				originals[method].apply(this, args);
+				report();
+			};
+			listeners.push(() => {
+				history.pushState = originals.pushState;
+				history.replaceState = originals.replaceState;
+			});
+		}
+		detach = () => {
+			for (const off of listeners) off();
+		};
+	}
+	function onLoad() {
+		if (disposed) return;
+		detach?.();
+		detach = void 0;
+		subscribe();
+		report();
+	}
+	iframe.addEventListener("load", onLoad);
+	subscribe();
+	report();
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		iframe.removeEventListener("load", onLoad);
+		detach?.();
+		detach = void 0;
+	};
+}
+//#endregion
 //#region src/client/frame-nav.ts
 /**
 * Shared-iframe soft navigation — the viewer-side half of a host↔iframe
@@ -445,6 +527,10 @@ async function createDevframeClientHost(options = {}) {
 	const clientDocks = /* @__PURE__ */ new Map();
 	const frameNavAdapters = /* @__PURE__ */ new Map();
 	const loadScriptsEnabled = options.loadClientScripts ?? true;
+	const categoryOrder = {
+		...DEFAULT_CATEGORIES_ORDER,
+		...options.categoryOrder
+	};
 	const panel = createPanelContext(clientType);
 	const docks = createDocksContext();
 	const commands = createCommandsContext();
@@ -458,7 +544,7 @@ async function createDevframeClientHost(options = {}) {
 		when: { get context() {
 			return {
 				clientType,
-				dockOpen: panel.store.open,
+				dockOpen: panel.session.open,
 				paletteOpen: commands.paletteOpen,
 				dockSelectedId: selectedId ?? ""
 			};
@@ -579,8 +665,12 @@ async function createDevframeClientHost(options = {}) {
 			}
 		}
 		docks.entries = entries;
-		docks.groupedEntries = groupByCategory(entries);
-		if (selectedId && !entryToStateMap.has(selectedId)) selectedId = null;
+		docks.groupedEntries = groupByCategory(entries, categoryOrder);
+		if (selectedId && !entryToStateMap.has(selectedId)) {
+			selectedId = null;
+			panel.session.selectedDockId = null;
+			panel.session.selectedDockRoute = null;
+		}
 	}
 	function createDocksContext() {
 		return {
@@ -590,12 +680,19 @@ async function createDevframeClientHost(options = {}) {
 			set selectedId(id) {
 				switchEntry(id);
 			},
+			get selectedRoute() {
+				return panel.session.selectedDockRoute;
+			},
+			set selectedRoute(route) {
+				panel.session.selectedDockRoute = route;
+			},
 			get selected() {
 				return selectedId && entryToStateMap.get(selectedId)?.entryMeta || null;
 			},
 			entries: [],
 			entryToStateMap,
 			groupedEntries: [],
+			categoryOrder,
 			settings,
 			getStateById: (id) => entryToStateMap.get(id),
 			switchEntry,
@@ -633,6 +730,8 @@ async function createDevframeClientHost(options = {}) {
 		if (next !== null && !entryToStateMap.has(next)) return false;
 		const previous = selectedId;
 		selectedId = next;
+		panel.session.selectedDockId = next;
+		if (next === null || entryToStateMap.get(next)?.entryMeta.type !== "iframe") panel.session.selectedDockRoute = null;
 		if (previous) entryToStateMap.get(previous)?.events.emit("entry:deactivated");
 		if (next) entryToStateMap.get(next)?.events.emit("entry:activated");
 		return true;
@@ -729,11 +828,15 @@ function createPanelContext(clientType) {
 		top: 0,
 		left: 0,
 		position: "right",
-		open: clientType === "standalone",
 		inactiveTimeout: 0
 	};
 	return {
 		store,
+		session: {
+			open: clientType === "standalone",
+			selectedDockId: null,
+			selectedDockRoute: null
+		},
 		isDragging: false,
 		isResizing: false,
 		get isVertical() {
@@ -741,7 +844,7 @@ function createPanelContext(clientType) {
 		}
 	};
 }
-function groupByCategory(entries) {
+function groupByCategory(entries, categoryOrder) {
 	const groupsById = /* @__PURE__ */ new Map();
 	for (const entry of entries) if (entry.type === "group") groupsById.set(entry.id, entry);
 	const groups = /* @__PURE__ */ new Map();
@@ -755,7 +858,7 @@ function groupByCategory(entries) {
 		}
 		list.push(entry);
 	}
-	return [...groups.entries()].sort(([a], [b]) => (DEFAULT_CATEGORIES_ORDER[a] ?? 0) - (DEFAULT_CATEGORIES_ORDER[b] ?? 0));
+	return [...groups.entries()].sort(([a], [b]) => (categoryOrder[a] ?? 0) - (categoryOrder[b] ?? 0));
 }
 //#endregion
 //#region src/client/remote.ts
@@ -864,4 +967,4 @@ async function connectRemoteDevframe(options = {}) {
 	});
 }
 //#endregion
-export { CLIENT_CONTEXT_KEY, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl };
+export { CLIENT_CONTEXT_KEY, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };

package/dist/constants.d.mts

@@ -1,6 +1,16 @@
-import { t as DevframeDocksUserSettings } from "./settings-B1qJ47d5.mjs";
+import { t as DevframeDocksUserSettings } from "./settings-DfrRa9Wf.mjs";
 export * from "devframe/constants";
 //#region src/constants.d.ts
+/** Default mount base for a hub instance — one namespace, one catch-all. */
+declare const DEVFRAMES_HUB_BASE = "/__devframes/";
+/**
+ * Normalize a hub mount base to an absolute path with leading and trailing
+ * slashes (e.g. `devframes` → `/devframes/`), collapsing any doubled
+ * slashes the input introduced. The one implementation every hub-aware
+ * host (`@devframes/hub` itself, and the Vite/Nuxt/Next adapters) resolves
+ * `options.base` through.
+ */
+declare function normalizeHubBase(base: string): string;
 /**
  * The default ordering weight for each known dock category — lower sorts
  * earlier. Downstream viewers (e.g. `@vitejs/devtools-kit`) import this as the
@@ -21,4 +31,4 @@ declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
 declare const DOCK_RENDERERS_STATE_KEY = "devframe:dock-renderers";
 declare const DEFAULT_STATE_USER_SETTINGS: () => DevframeDocksUserSettings;
 //#endregion
-export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY };
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase };

package/dist/constants.mjs

@@ -1,5 +1,18 @@
+import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash } from "ufo";
 export * from "devframe/constants";
 //#region src/constants.ts
+/** Default mount base for a hub instance — one namespace, one catch-all. */
+const DEVFRAMES_HUB_BASE = "/__devframes/";
+/**
+* Normalize a hub mount base to an absolute path with leading and trailing
+* slashes (e.g. `devframes` → `/devframes/`), collapsing any doubled
+* slashes the input introduced. The one implementation every hub-aware
+* host (`@devframes/hub` itself, and the Vite/Nuxt/Next adapters) resolves
+* `options.base` through.
+*/
+function normalizeHubBase(base) {
+	return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)));
+}
 /**
 * The default ordering weight for each known dock category — lower sorts
 * earlier. Downstream viewers (e.g. `@vitejs/devtools-kit`) import this as the
@@ -34,9 +47,7 @@ const DEFAULT_STATE_USER_SETTINGS = () => ({
 	docksCategoriesHidden: [],
 	docksPinned: [],
 	docksCustomOrder: {},
-	showIframeAddressBar: false,
-	closeOnOutsideClick: false,
 	commandShortcuts: {}
 });
 //#endregion
-export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY };
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase };

package/dist/{context-Dz0j8Eyg.d.mts → context-D5TJIHwp.d.mts}

@@ -1,4 +1,4 @@
-import { D as DevframeViewIframe, S as DevframeDocksHost, c as DevframeCommandsHost, p as DevframeDockActivation, v as DevframeDockEntryIcon } from "./commands-CAcTUSlj.mjs";
+import { b as DevframeDockEntryIcon, k as DevframeViewIframe, l as DevframeCommandsHost, m as DevframeDockActivation, w as DevframeDocksHost } from "./settings-DfrRa9Wf.mjs";
 import { CreateHostContextOptions } from "devframe/node";
 import { DevframeDefinition, DevframeHost, DevframeNodeContext, EventEmitter } from "devframe/types";
 import { ChildProcess } from "node:child_process";

package/dist/{context-DPdojIW8.mjs → context-DzqMQ2mI.mjs}

@@ -3,25 +3,16 @@ import { DEFAULT_STATE_USER_SETTINGS } from "./constants.mjs";
 import { t as buildRemoteConnectionUrl } from "./remote-url-KVXtKP47.mjs";
 import { createEventEmitter } from "devframe/utils/events";
 import { createHostContext, createStorage } from "devframe/node";
+import { getInternalContext, resolveBasePath } from "devframe/node/hub-internals";
 import { debounce } from "perfect-debounce";
 import { coerceAgentPositionalArgs } from "devframe/internal";
-import { defineDiagnostics } from "nostics";
-import { colors } from "devframe/utils/colors";
-import { ansiFormatter } from "nostics/formatters/ansi";
-import { getInternalContext, resolveBasePath } from "devframe/node/hub-internals";
+import { defineDiagnostics } from "devframe/utils/nostics";
 import { join, resolve } from "pathe";
 import { nanoid } from "devframe/utils/nanoid";
 import process from "node:process";
-//#region src/utils/diagnostics-reporter.ts
-const formatAnsi = ansiFormatter(colors);
-function hubReporter(d, { method = "warn" } = {}) {
-	console[method](formatAnsi(d));
-}
-//#endregion
 //#region src/node/diagnostics.ts
 const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
-	reporters: [hubReporter],
 	codes: {
 		DF8000: {
 			why: (p) => `Devframe id "${p.id}" collides with a reserved hub path — it cannot be mounted directly under the hub base.`,
@@ -920,7 +911,8 @@ async function installDevframe(ctx, d, options = {}) {
 			name: d.name,
 			base
 		});
-		ctx.views.hostStatic(base, resolve(d.cli.distDir));
+		const distSource = d.cli.distDir;
+		ctx.views.hostStatic(base, typeof distSource === "string" ? resolve(distSource) : distSource);
 	}
 	ctx.docks.register({
 		id,
@@ -1146,6 +1138,7 @@ async function createHubContext(options) {
 		docksSharedState.mutate(() => docks.values());
 	}, debounceMs);
 	docks.events.on("dock:entry:updated", refreshDocks);
+	getInternalContext(context).onWsEndpointChange(refreshDocks);
 	docksSharedState.mutate(() => docks.values());
 	const activeDockSharedState = await context.rpc.sharedState.get("devframe:docks:active", { initialValue: { activation: null } });
 	docks.events.on("dock:activate", (activation) => {

package/dist/index-coDmWngQ.d.mts

@@ -0,0 +1,5 @@
+import "./context-D5TJIHwp.mjs";
+import "./settings-DfrRa9Wf.mjs";
+import { RpcDefinitionsFilter, RpcDefinitionsToFunctions } from "devframe/rpc";
+import { ConnectionMeta as ConnectionMeta$1, DevframeCapabilities, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeHost as DevframeHost$1, DevframeNodeRpcSession, DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeViewHost, EventEmitter as EventEmitter$1, EventUnsubscribe, EventsMap, RpcBroadcastOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost } from "devframe/types";
+export { RpcStreamingHost as S, RpcFunctionsHost as _, DevframeHost$1 as a, RpcStreamingChannel as b, DevframeRpcServerFunctions as c, EventEmitter$1 as d, EventUnsubscribe as f, RpcDefinitionsToFunctions as g, RpcDefinitionsFilter as h, DevframeDiagnosticsLogger as i, DevframeRpcSharedStates as l, RpcBroadcastOptions as m, DevframeCapabilities as n, DevframeNodeRpcSession as o, EventsMap as p, DevframeDiagnosticsHost as r, DevframeRpcClientFunctions as s, ConnectionMeta$1 as t, DevframeViewHost as u, RpcSharedStateGetOptions as v, RpcStreamingChannelOptions as x, RpcSharedStateHost as y };

package/dist/index.d.mts

@@ -1,7 +1,6 @@
-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";
+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-D5TJIHwp.mjs";
+import { A as DevframeViewLauncher, C as DevframeDocksActiveState, D as DevframeViewCustomRender, E as DevframeViewBuiltin, F as RemoteDockOptions, M as FrameSubTabsConfig, N as NavTarget, O as DevframeViewGroup, P as RemoteConnectionInfo, S as DevframeDockUserEntry, T as DevframeViewAction, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncherStatus, k as DevframeViewIframe, 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 DevframeDockEntryBase, w as DevframeDocksHost, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "./settings-DfrRa9Wf.mjs";
+import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "./index-coDmWngQ.mjs";
 import { WhenContext, WhenExpression } from "devframe/utils/when";
 //#region src/define.d.ts
 declare const defineHubRpcFunction: <NAME extends string, TYPE extends import("devframe/rpc").RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends import("devframe/rpc").RpcArgsSchema | undefined = undefined, const RS extends import("devframe/rpc").RpcReturnSchema | undefined = undefined>(definition: import("devframe/rpc").RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeHubContext>) => import("devframe/rpc").RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeHubContext>;
@@ -13,4 +12,4 @@ declare function defineDockEntry<const T extends DevframeDockUserEntry, const W
   visibility?: WhenExpression<WhenContext, V>;
 }): T;
 //#endregion
-export { type ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, type DevframeChildProcessExecuteOptions, type DevframeChildProcessOutput, type DevframeChildProcessResult, type DevframeChildProcessTerminalSession, type DevframeClientCommand, type DevframeCommandAgentOptions, type DevframeCommandBase, type DevframeCommandEntry, type DevframeCommandHandle, type DevframeCommandKeybinding, type DevframeCommandShortcutOverrides, type DevframeCommandsHost, type DevframeCommandsHostEvents, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockActivation, type DevframeDockEntriesGrouped, type DevframeDockEntry, type DevframeDockEntryBase, type DevframeDockEntryCategory, type DevframeDockEntryIcon, type DevframeDockEntryRegistry, type DevframeDockUserEntry, type DevframeDocksActiveState, type DevframeDocksHost, type DevframeDocksUserSettings, type DevframeHost, type DevframeHubContext, type DevframeMessageAction, type DevframeMessageActivateAction, type DevframeMessageCommandAction, type DevframeMessageElementPosition, type DevframeMessageEntry, type DevframeMessageEntryFrom, type DevframeMessageEntryInput, type DevframeMessageFilePosition, type DevframeMessageHandle, type DevframeMessageLevel, type DevframeMessageShortcutInput, type DevframeMessagesClient, type DevframeMessagesHost, type DevframeMessagesLevelShortcuts, type DevframeMessagesListDelta, type DevframeNodeRpcSession, type DevframePtyExecuteOptions, type DevframePtyTerminalSession, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeServerCommandEntry, type DevframeServerCommandInput, type DevframeTerminalSession, type DevframeTerminalSessionBase, type DevframeTerminalStatus, type DevframeTerminalsHost, type DevframeViewAction, type DevframeViewBuiltin, type DevframeViewCustomRender, type DevframeViewGroup, type DevframeViewHost, type DevframeViewIframe, type DevframeViewLauncher, type DevframeViewLauncherStatus, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type FrameSubTabsConfig, type NavTarget, type PartialWithoutId, type RemoteConnectionInfo, type RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type Thenable, defineCommand, defineDockEntry, defineHubRpcFunction };
+export { type ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, type DevframeChildProcessExecuteOptions, type DevframeChildProcessOutput, type DevframeChildProcessResult, type DevframeChildProcessTerminalSession, type DevframeClientCommand, type DevframeCommandAgentOptions, type DevframeCommandBase, type DevframeCommandEntry, type DevframeCommandHandle, type DevframeCommandKeybinding, type DevframeCommandShortcutOverrides, type DevframeCommandsHost, type DevframeCommandsHostEvents, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockActivation, type DevframeDockBadgeVariant, type DevframeDockEntriesGrouped, type DevframeDockEntry, type DevframeDockEntryBase, type DevframeDockEntryCategory, type DevframeDockEntryIcon, type DevframeDockEntryRegistry, type DevframeDockUserEntry, type DevframeDocksActiveState, type DevframeDocksHost, type DevframeDocksUserSettings, type DevframeHost, type DevframeHubContext, type DevframeMessageAction, type DevframeMessageActivateAction, type DevframeMessageCommandAction, type DevframeMessageElementPosition, type DevframeMessageEntry, type DevframeMessageEntryFrom, type DevframeMessageEntryInput, type DevframeMessageFilePosition, type DevframeMessageHandle, type DevframeMessageLevel, type DevframeMessageShortcutInput, type DevframeMessagesClient, type DevframeMessagesHost, type DevframeMessagesLevelShortcuts, type DevframeMessagesListDelta, type DevframeNodeRpcSession, type DevframePtyExecuteOptions, type DevframePtyTerminalSession, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeServerCommandEntry, type DevframeServerCommandInput, type DevframeTerminalSession, type DevframeTerminalSessionBase, type DevframeTerminalStatus, type DevframeTerminalsHost, type DevframeViewAction, type DevframeViewBuiltin, type DevframeViewCustomRender, type DevframeViewGroup, type DevframeViewHost, type DevframeViewIframe, type DevframeViewLauncher, type DevframeViewLauncherStatus, type EventEmitter, type EventUnsubscribe, type EventsMap, type FrameSubTabsConfig, type NavTarget, type RemoteConnectionInfo, type RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, defineCommand, defineDockEntry, defineHubRpcFunction };

package/dist/node/index.d.mts

@@ -1,6 +1,5 @@
-import { C as DevframeMessageHandle, D as DevframeMessagesHost$1, T as DevframeMessageShortcutInput, a as DevframeChildProcessExecuteOptions, c as DevframeChildProcessTerminalSession, d as DevframeTerminalSession, f as DevframeTerminalSessionBase, i as InstallDevframeOptions, k as DevframeMessagesListDelta, l as DevframePtyExecuteOptions, m as DevframeTerminalsHost$1, n as DevframeHubContext, r as createHubContext, t as CreateHubContextOptions, u as DevframePtyTerminalSession, x as DevframeMessageEntryInput, y as DevframeMessageEntry } from "../context-Dz0j8Eyg.mjs";
-import { S as DevframeDocksHost$1, a as DevframeCommandHandle, b as DevframeDockUserEntry, c as DevframeCommandsHost$1, d as DevframeServerCommandInput, f as ClientScriptEntry, h as DevframeDockEntry, u as DevframeServerCommandEntry } from "../commands-CAcTUSlj.mjs";
-import { t as DevframeDocksUserSettings } from "../settings-B1qJ47d5.mjs";
+import { C as DevframeMessageHandle, D as DevframeMessagesHost$1, T as DevframeMessageShortcutInput, a as DevframeChildProcessExecuteOptions, c as DevframeChildProcessTerminalSession, d as DevframeTerminalSession, f as DevframeTerminalSessionBase, i as InstallDevframeOptions, k as DevframeMessagesListDelta, l as DevframePtyExecuteOptions, m as DevframeTerminalsHost$1, n as DevframeHubContext, r as createHubContext, t as CreateHubContextOptions, u as DevframePtyTerminalSession, x as DevframeMessageEntryInput, y as DevframeMessageEntry } from "../context-D5TJIHwp.mjs";
+import { S as DevframeDockUserEntry, _ as DevframeDockEntry, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, l as DevframeCommandsHost$1, o as DevframeCommandHandle, p as ClientScriptEntry, t as DevframeDocksUserSettings, w as DevframeDocksHost$1 } from "../settings-DfrRa9Wf.mjs";
 import { RpcFunctionDefinitionAny } from "devframe/rpc";
 import { SharedState } from "devframe/utils/shared-state";
 //#region src/node/host-commands.d.ts

package/dist/node/index.mjs

@@ -1,9 +1,9 @@
-import { _ as DevframeCommandsHost, a as hubMessagesAdd, c as hubMessagesUpdate, d as hubTerminalsRestart, f as hubTerminalsTerminate, g as DevframeDocksHost, h as DevframeMessagesHost, i as hubDocksActivate, l as hubTerminalsRemove, m as DevframeTerminalsHost, n as builtinHubRpcDeclarations, o as hubMessagesClear, p as hubTerminalsWrite, r as hubCommandsExecute, s as hubMessagesRemove, t as createHubContext, u as hubTerminalsResize } from "../context-DPdojIW8.mjs";
+import { _ as DevframeCommandsHost, a as hubMessagesAdd, c as hubMessagesUpdate, d as hubTerminalsRestart, f as hubTerminalsTerminate, g as DevframeDocksHost, h as DevframeMessagesHost, i as hubDocksActivate, l as hubTerminalsRemove, m as DevframeTerminalsHost, n as builtinHubRpcDeclarations, o as hubMessagesClear, p as hubTerminalsWrite, r as hubCommandsExecute, s as hubMessagesRemove, t as createHubContext, u as hubTerminalsResize } from "../context-DzqMQ2mI.mjs";
+import "ufo";
 import "pathe";
 import "node:process";
 import { builtinModules } from "node:module";
 import "node:fs";
-import "ufo";
 import "node:url";
 import assert from "node:assert";
 import "node:path";

package/dist/node/initiate.d.mts

@@ -1,4 +1,5 @@
-import { i as InstallDevframeOptions, n as DevframeHubContext, t as CreateHubContextOptions } from "../context-Dz0j8Eyg.mjs";
+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";
@@ -15,8 +16,6 @@ interface HubDevframeEntry {
 }
 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
@@ -71,12 +70,22 @@ interface DevframeHubUi {
   };
   /**
    * 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.
+   * 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 {
@@ -181,8 +190,6 @@ interface InitHubOptions {
    * 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;
   /**

package/dist/node/initiate.mjs

@@ -1,11 +1,11 @@
-import { DOCK_RENDERERS_STATE_KEY } from "../constants.mjs";
-import { t as createHubContext, v as diagnostics } from "../context-DPdojIW8.mjs";
+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 { cleanDoubleSlashes, joinURL, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
 import { readFile } from "node:fs/promises";
 import { mountStaticHandler } from "devframe/utils/serve-static";
 import { H3 } from "h3";
@@ -13,8 +13,6 @@ import { H3 } from "h3";
 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";
@@ -45,9 +43,6 @@ function resolveDevframesInput(input) {
 		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
@@ -107,7 +102,7 @@ function renderClientImportsModule(ctx) {
 * through {@link HubInstance.attach}.
 */
 function initHub(options) {
-	const base = normalizeBase(options.base);
+	const base = normalizeHubBase(options.base);
 	const baseNoSlash = base.slice(0, -1);
 	const app = new H3();
 	const cwd = options.cwd ?? process.cwd();
@@ -184,6 +179,7 @@ function initHub(options) {
 				});
 			}
 			await options.configure?.(ctx);
+			await options.ui?.setup?.(ctx);
 			if (rendererRegistrations.length > 0) {
 				const manifest = {};
 				for (const registration of rendererRegistrations) manifest[registration.type] = {

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

@@ -50,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;
@@ -114,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
@@ -460,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 {
   /**
@@ -499,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;
   /**
@@ -572,4 +574,36 @@ interface DevframeCommandShortcutOverrides {
   [commandId: string]: DevframeCommandKeybinding[];
 }
 //#endregion
-export { FrameSubTabsConfig as A, DevframeViewAction as C, DevframeViewIframe as D, DevframeViewGroup as E, RemoteConnectionInfo as M, RemoteDockOptions as N, DevframeViewLauncher as O, DevframeDocksHost as S, DevframeViewCustomRender as T, DevframeDockEntryCategory as _, DevframeCommandHandle as a, DevframeDockUserEntry as b, DevframeCommandsHost as c, DevframeServerCommandInput as d, ClientScriptEntry as f, DevframeDockEntryBase as g, DevframeDockEntry as h, DevframeCommandEntry as i, NavTarget as j, DevframeViewLauncherStatus as k, DevframeCommandsHostEvents as l, DevframeDockEntriesGrouped as m, DevframeCommandAgentOptions as n, DevframeCommandKeybinding as o, DevframeDockActivation as p, DevframeCommandBase as r, DevframeCommandShortcutOverrides as s, DevframeClientCommand as t, DevframeServerCommandEntry as u, DevframeDockEntryIcon as v, DevframeViewBuiltin as w, DevframeDocksActiveState as x, DevframeDockEntryRegistry as y };
+//#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>;
+  /** Per-command keybinding overrides (empty array = shortcut disabled). */
+  commandShortcuts: DevframeCommandShortcutOverrides;
+}
+//#endregion
+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 };

package/dist/types/index.d.mts

@@ -1,5 +1,4 @@
-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 };
+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-D5TJIHwp.mjs";
+import { A as DevframeViewLauncher, C as DevframeDocksActiveState, D as DevframeViewCustomRender, E as DevframeViewBuiltin, F as RemoteDockOptions, M as FrameSubTabsConfig, N as NavTarget, O as DevframeViewGroup, P as RemoteConnectionInfo, S as DevframeDockUserEntry, T as DevframeViewAction, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncherStatus, k as DevframeViewIframe, 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 DevframeDockEntryBase, w as DevframeDocksHost, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "../settings-DfrRa9Wf.mjs";
+import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "../index-coDmWngQ.mjs";
+export { ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, DevframeChildProcessExecuteOptions, DevframeChildProcessOutput, DevframeChildProcessResult, DevframeChildProcessTerminalSession, DevframeClientCommand, DevframeCommandAgentOptions, DevframeCommandBase, DevframeCommandEntry, DevframeCommandHandle, DevframeCommandKeybinding, DevframeCommandShortcutOverrides, DevframeCommandsHost, DevframeCommandsHostEvents, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, DevframeDockActivation, DevframeDockBadgeVariant, 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 EventEmitter, type EventUnsubscribe, type EventsMap, FrameSubTabsConfig, NavTarget, RemoteConnectionInfo, RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/hub",
   "type": "module",
-  "version": "0.9.0-beta.1",
+  "version": "0.9.0-beta.10",
   "description": "Hub layer that orchestrates devframe docks, terminals, messages, and commands on any host.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -34,13 +34,12 @@
     "dist"
   ],
   "peerDependencies": {
-    "devframe": "0.9.0-beta.1"
+    "devframe": "0.9.0-beta.10"
   },
   "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",
@@ -53,7 +52,7 @@
     "mlly": "^1.8.2",
     "tsdown": "^0.22.14",
     "valibot": "^1.4.2",
-    "devframe": "0.9.0-beta.1"
+    "devframe": "0.9.0-beta.10"
   },
   "scripts": {
     "build": "tsdown",

package/dist/index-p4BktGvQ.d.mts

@@ -1,6 +0,0 @@
-import "./context-Dz0j8Eyg.mjs";
-import "./commands-CAcTUSlj.mjs";
-import "./settings-B1qJ47d5.mjs";
-import { RpcDefinitionsFilter, RpcDefinitionsToFunctions } from "devframe/rpc";
-import { ConnectionMeta as ConnectionMeta$1, DevframeCapabilities, DevframeDiagnosticsDefinition, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeHost as DevframeHost$1, DevframeNodeRpcSession, DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeViewHost, EntriesToObject, EventEmitter as EventEmitter$1, EventUnsubscribe, EventsMap, PartialWithoutId, RpcBroadcastOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, Thenable } from "devframe/types";
-export { RpcStreamingChannel as C, Thenable as E, RpcSharedStateHost as S, RpcStreamingHost as T, RpcBroadcastOptions as _, DevframeDiagnosticsLogger as a, RpcFunctionsHost as b, DevframeRpcClientFunctions as c, DevframeViewHost as d, EntriesToObject as f, PartialWithoutId as g, EventsMap as h, DevframeDiagnosticsHost as i, DevframeRpcServerFunctions as l, EventUnsubscribe as m, DevframeCapabilities as n, DevframeHost$1 as o, EventEmitter$1 as p, DevframeDiagnosticsDefinition as r, DevframeNodeRpcSession as s, ConnectionMeta$1 as t, DevframeRpcSharedStates as u, RpcDefinitionsFilter as v, RpcStreamingChannelOptions as w, RpcSharedStateGetOptions as x, RpcDefinitionsToFunctions as y };

package/dist/settings-B1qJ47d5.d.mts

@@ -1,13 +0,0 @@
-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 };