@devframes/hub 0.9.0-beta.9 → 0.9.1

package/dist/client/index.d.mts

@@ -1,11 +1,35 @@
-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 { E as DevframeMessagesClient, x as DevframeMessageEntryInput } from "../context-BVkxwz5k.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-D7whfcx2.mjs";
+import "../index-CyEyZHB3.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";
 import { WhenContext } from "devframe/utils/when";
 export * from "devframe/client";
+//#region src/client-modules.d.ts
+/**
+ * Resolve a dock client script's `importFrom` to the URL to import. URL
+ * specifiers pass through untouched; a **bare** specifier resolves through
+ * the explicit `resolveClientModule` callback (a viewer's own policy), then
+ * the host-advertised `template` (`ConnectionMeta.configs.dock.clientModuleResolution`,
+ * its `{specifier}` token replaced — e.g. Vite's `'/@id/{specifier}'`),
+ * resolved against `metaBaseUrl` so it targets the host's origin from any
+ * viewer. With neither, it stays unchanged — a page import map may still
+ * cover it.
+ */
+declare function resolveClientModuleSpecifier(specifier: string, options?: {
+  resolveClientModule?: (specifier: string) => string | undefined;
+  template?: string;
+  metaBaseUrl?: string;
+}): string;
+/**
+ * Diagnose a failed client-script import: name the likely cause instead of
+ * leaving only the browser's opaque `TypeError`. `importFrom` is the entry's
+ * declared specifier, `specifier` what was actually imported (after
+ * {@link resolveClientModuleSpecifier}).
+ */
+declare function clientScriptFailureHint(importFrom: string, specifier: string): string;
+//#endregion
 //#region src/client/renderers.d.ts
 /**
  * Options handed to a dock renderer when the client host mounts a dock entry.
@@ -134,9 +158,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 {
   /**
@@ -196,12 +241,29 @@ 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>;
@@ -346,6 +408,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
@@ -367,7 +502,7 @@ declare function resolveDockIcon(icon: DevframeDockEntryIcon, connection: Devfra
  * decoupled — the embedded app takes no hub/RPC dependency, only the shim.
  */
 /** `postMessage` channel tag shared by both halves of the protocol. */
-declare const FRAME_NAV_CHANNEL = "devframe:frame-nav";
+declare const FRAME_NAV_CHANNEL: string;
 /** Protocol version. */
 declare const FRAME_NAV_VERSION = 1;
 /** Envelope every frame-nav message carries. */
@@ -488,6 +623,15 @@ interface DevframeClientHostOptions {
    * `custom-render`, and iframe `clientScript`). Default `true`.
    */
   loadClientScripts?: boolean;
+  /**
+   * Resolve a **bare-specifier** client script (`importFrom` naming an npm
+   * module) to a URL this page can import — a viewer's own policy, winning
+   * over the host-advertised `ConnectionMeta.configs.dock.clientModuleResolution`
+   * template (return `undefined` to fall through to it). URL specifiers never
+   * reach this hook. E.g. on a Vite-served page:
+   * `resolveClientModule: s => `/@id/${s}``.
+   */
+  resolveClientModule?: (specifier: string) => string | undefined;
   /**
    * Dock renderers to register at boot, keyed by dock `type`. The host
    * application injects the ones it wants (e.g.
@@ -587,4 +731,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, clientScriptFailureHint, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveClientModuleSpecifier, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };

package/dist/client/index.mjs

@@ -1,5 +1,5 @@
-import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY } from "../constants.mjs";
-import { n as stripRemoteConnectionFromUrl, t as buildRemoteConnectionUrl } from "../remote-url-KVXtKP47.mjs";
+import { i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, t as DEFAULT_CATEGORIES_ORDER } from "../constants-C2b2cACy.mjs";
+import { a as resolveClientModuleSpecifier, n as stripRemoteConnectionFromUrl, r as clientScriptFailureHint, t as buildRemoteConnectionUrl } from "../remote-url-Bgc7gtsP.mjs";
 import { REMOTE_CONNECTION_KEY } from "devframe/constants";
 import { connectDevframe, getDevframeRpcClient, resolveWsUrl } from "devframe/client";
 import { createEventEmitter } from "devframe/utils/events";
@@ -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
@@ -90,7 +172,7 @@ function resolveDockIcon(icon, connection) {
 * decoupled — the embedded app takes no hub/RPC dependency, only the shim.
 */
 /** `postMessage` channel tag shared by both halves of the protocol. */
-const FRAME_NAV_CHANNEL = "devframe:frame-nav";
+const FRAME_NAV_CHANNEL = HUB_EVENTS.postMessage.frameNav;
 /** Protocol version. */
 const FRAME_NAV_VERSION = 1;
 /**
@@ -121,16 +203,14 @@ function attachFrameNavClient(options) {
 		if (disposed) return;
 		if (expectedOrigin !== "*" && ev.origin !== expectedOrigin) return;
 		const data = ev.data;
-		if (!data || data.channel !== "devframe:frame-nav" || data.v !== 1 || data.frameId !== frameId || data.from !== "frame") return;
+		if (!data || data.channel !== FRAME_NAV_CHANNEL || data.v !== 1 || data.frameId !== frameId || data.from !== "frame") return;
 		switch (data.type) {
 			case "ready":
 			case "manifest":
 				markReady();
 				reconcileManifest(data.tabs ?? [], data.current);
 				break;
-			case "navigated":
-				onNavigated(data.tabId);
-				break;
+			case "navigated": onNavigated(data.tabId);
 		}
 	}
 	function markReady() {
@@ -416,10 +496,10 @@ function createDockRenderersContext(options) {
 }
 //#endregion
 //#region src/client/host.ts
-const DOCKS_STATE_KEY = "devframe:docks";
-const COMMANDS_STATE_KEY = "devframe:commands";
-const USER_SETTINGS_STATE_KEY = "devframe:user-settings";
-const DOCKS_ACTIVATE_EVENT = "devframe:docks:activate";
+const DOCKS_STATE_KEY = HUB_EVENTS.sharedState.docks;
+const COMMANDS_STATE_KEY = HUB_EVENTS.sharedState.commands;
+const USER_SETTINGS_STATE_KEY = HUB_EVENTS.sharedState.userSettings;
+const DOCKS_ACTIVATE_EVENT = HUB_EVENTS.broadcast.docksActivate;
 /**
 * Boot the framework-level client host: connect RPC, assemble the full
 * {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
@@ -462,7 +542,7 @@ async function createDevframeClientHost(options = {}) {
 		when: { get context() {
 			return {
 				clientType,
-				dockOpen: panel.store.open,
+				dockOpen: panel.session.open,
 				paletteOpen: commands.paletteOpen,
 				dockSelectedId: selectedId ?? ""
 			};
@@ -584,7 +664,11 @@ async function createDevframeClientHost(options = {}) {
 		}
 		docks.entries = entries;
 		docks.groupedEntries = groupByCategory(entries, categoryOrder);
-		if (selectedId && !entryToStateMap.has(selectedId)) selectedId = null;
+		if (selectedId && !entryToStateMap.has(selectedId)) {
+			selectedId = null;
+			panel.session.selectedDockId = null;
+			panel.session.selectedDockRoute = null;
+		}
 	}
 	function createDocksContext() {
 		return {
@@ -594,6 +678,12 @@ 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;
 			},
@@ -638,6 +728,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;
@@ -704,12 +796,17 @@ async function createDevframeClientHost(options = {}) {
 		}
 	}
 	async function runClientScript(entryId, script) {
+		const specifier = resolveClientModuleSpecifier(script.importFrom, {
+			resolveClientModule: options.resolveClientModule,
+			template: rpc.connectionMeta?.configs?.dock?.clientModuleResolution,
+			metaBaseUrl: rpc.connection?.metaBaseUrl
+		});
 		try {
 			const fn = (await import(
 				/* @vite-ignore */
 				/* webpackIgnore: true */
 				/* turbopackIgnore: true */
-				script.importFrom
+				specifier
 ))[script.importName ?? "default"];
 			if (typeof fn !== "function") return;
 			const current = entryToStateMap.get(entryId);
@@ -722,7 +819,7 @@ async function createDevframeClientHost(options = {}) {
 			});
 		} catch (error) {
 			loadedScripts.delete(entryId);
-			console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${script.importFrom}`, error);
+			console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${specifier}${clientScriptFailureHint(script.importFrom, specifier)}`, error);
 		}
 	}
 }
@@ -734,11 +831,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() {
@@ -785,10 +886,11 @@ function buildRemoteDevframeUrl(url, connection) {
 	} catch {
 		return url;
 	}
+	const websocket = resolveWsUrl(connection.connectionMeta.websocket, connection.metaBaseUrl, base);
 	return buildRemoteConnectionUrl(url, {
 		v: 1,
 		backend: "websocket",
-		websocket: resolveWsUrl(connection.connectionMeta.websocket, connection.metaBaseUrl, base),
+		websocket,
 		authToken: connection.authToken,
 		origin: base.origin
 	});
@@ -869,4 +971,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, clientScriptFailureHint, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveClientModuleSpecifier, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };

package/dist/constants-C2b2cACy.mjs

@@ -0,0 +1,120 @@
+import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash } from "ufo";
+//#region src/events.ts
+/**
+* Centralized registry of every event, broadcast, RPC method, shared-state
+* key, and channel name the hub uses — the single source of truth that keeps
+* these names out of scattered string literals.
+*
+* **Keep this in sync with [`docs/guide/events.md`](../../../docs/guide/events.md)**
+* (the Hub Events Reference): every name here appears in that page's tables, and
+* every name there resolves to an entry here. Add, rename, or remove a name in
+* both places in the same change, and reference `HUB_EVENTS.*` from call sites
+* instead of re-typing a literal.
+*
+* The `.events` EventEmitter maps in `types/{docks,terminals,messages,commands}.ts`
+* and the RPC augmentation interfaces in `node/context.ts` declare these same
+* names as type-level keys (a literal is unavoidable in a type position); those
+* declarations mirror this map and move with it.
+*/
+const HUB_EVENTS = {
+	/**
+	* Internal node `EventEmitter` events on `ctx.<subsystem>.events`. Emitted
+	* and consumed inside the node process (chiefly by `createHubContext`, which
+	* fans them out onto the wire); they never cross to the browser.
+	*/
+	bus: {
+		docksEntryUpdated: "docks:entry:updated",
+		docksActivate: "docks:activate",
+		terminalsSessionUpdated: "terminals:session:updated",
+		messagesAdded: "messages:added",
+		messagesUpdated: "messages:updated",
+		messagesRemoved: "messages:removed",
+		messagesCleared: "messages:cleared",
+		commandsRegistered: "commands:registered",
+		commandsUnregistered: "commands:unregistered"
+	},
+	/** Server RPC methods a connected client calls (client → server), `hub:` prefix. */
+	rpc: {
+		docksActivate: "hub:docks:activate",
+		commandsExecute: "hub:commands:execute",
+		messagesAdd: "hub:messages:add",
+		messagesUpdate: "hub:messages:update",
+		messagesRemove: "hub:messages:remove",
+		messagesClear: "hub:messages:clear",
+		terminalsWrite: "hub:terminals:write",
+		terminalsResize: "hub:terminals:resize",
+		terminalsTerminate: "hub:terminals:terminate",
+		terminalsRestart: "hub:terminals:restart",
+		terminalsRemove: "hub:terminals:remove"
+	},
+	/** Broadcast notifications the server pushes to clients (server → client), `devframe:` prefix. */
+	broadcast: {
+		docksActivate: "devframe:docks:activate",
+		terminalsUpdated: "devframe:terminals:updated",
+		messagesUpdated: "devframe:messages:updated"
+	},
+	/** Shared-state slot keys a hub-aware client reads (server → client), `devframe:` prefix. */
+	sharedState: {
+		docks: "devframe:docks",
+		docksActive: "devframe:docks:active",
+		commands: "devframe:commands",
+		userSettings: "devframe:user-settings",
+		dockRenderers: "devframe:dock-renderers"
+	},
+	/** Streaming channel ids (server → client), `devframe:` prefix. */
+	stream: { terminals: "devframe:terminals" },
+	/** `postMessage` channels for host ↔ iframe protocols, `devframe:` prefix. */
+	postMessage: { frameNav: "devframe:frame-nav" }
+};
+//#endregion
+//#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
+* single source of truth so the hub and its viewers agree on category order.
+* `framework` sorts first; `~builtin` (the viewer's own built-in views) last.
+*
+* The buckets read from "closest to your app" → "platform / analysis" →
+* "peripheral". Gaps between the weights are intentional: a kit can interleave
+* its own categories (or override these) without editing this table.
+*/
+const DEFAULT_CATEGORIES_ORDER = {
+	"framework": -100,
+	"default": 0,
+	"app": 100,
+	"ui": 150,
+	"data": 250,
+	"web": 300,
+	"performance": 350,
+	"advanced": 400,
+	"docs": 500,
+	"~builtin": 1e3
+};
+/**
+* Shared-state slot carrying the hub's renderer manifest — one
+* {@link import('./client/renderers').DockRendererManifest} entry per dock
+* `type`, published by `initHub({ renderers })` and consumed by every
+* hub-aware client (the headless client host and viewers alike).
+*/
+const DOCK_RENDERERS_STATE_KEY = HUB_EVENTS.sharedState.dockRenderers;
+const DEFAULT_STATE_USER_SETTINGS = () => ({
+	docksHidden: [],
+	docksCategoriesHidden: [],
+	docksPinned: [],
+	docksCustomOrder: {},
+	commandShortcuts: {}
+});
+//#endregion
+export { normalizeHubBase as a, DOCK_RENDERERS_STATE_KEY as i, DEFAULT_STATE_USER_SETTINGS as n, HUB_EVENTS as o, DEVFRAMES_HUB_BASE as r, DEFAULT_CATEGORIES_ORDER as t };