@devframes/hub 0.9.7 → 0.9.9

package/dist/client/index.mjs

@@ -1,5 +1,5 @@
-import { i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, t as DEFAULT_CATEGORIES_ORDER } from "../constants-DrF61GFx.mjs";
-import { a as resolveClientModuleSpecifier, n as stripRemoteConnectionFromUrl, r as clientScriptFailureHint, t as buildRemoteConnectionUrl } from "../remote-url-Bgc7gtsP.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-BUd6oMci.mjs";
+import { a as resolveClientModuleSpecifier, n as stripRemoteConnectionFromUrl, r as clientScriptFailureHint, t as buildRemoteConnectionUrl } from "../remote-url-UClKLQ5_.mjs";
 import { REMOTE_CONNECTION_KEY } from "devframe/constants";
 import { connectDevframe, getDevframeRpcClient, resolveWsUrl } from "devframe/client";
 import { createEventEmitter } from "devframe/utils/events";
@@ -82,7 +82,7 @@ function watchFrameLocation(options) {
 	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
+	* `location.href` is the cross-origin probe, since it throws for a foreign
 	* document, where there is nothing to observe.
 	*/
 	function readableWindow() {
@@ -153,7 +153,7 @@ function watchFrameLocation(options) {
 //#endregion
 //#region src/client/frame-nav.ts
 /**
-* Shared-iframe soft navigation — the hub-UI-provider-side half of a host-page↔iframe
+* Shared-iframe soft navigation: the hub-UI-provider-side half of a host-page↔iframe
 * `postMessage` protocol.
 *
 * An {@link DevframeViewIframe.subTabs anchor} iframe dock owns one live iframe
@@ -169,7 +169,7 @@ function watchFrameLocation(options) {
 *   highlight to match.
 *
 * The protocol is server-free (works cross-origin and in static builds) and
-* decoupled — the embedded app takes no hub/RPC dependency, only the shim.
+* decoupled, so 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 = HUB_EVENTS.postMessage.frameNav;
@@ -341,17 +341,18 @@ function deriveFallbackUrl(base, navTarget) {
 	}
 	const path = navTarget.path.startsWith("#") ? navTarget.path.slice(1) : navTarget.path;
 	let hash = `#${path}`;
-	const query = navTarget.query;
-	if (query) {
-		const params = new URLSearchParams();
-		for (const [key, value] of Object.entries(query)) if (typeof value === "string") params.set(key, value);
-		else for (const v of value) params.append(key, v);
-		const qs = params.toString();
-		if (qs) hash += (path.includes("?") ? "&" : "?") + qs;
-	}
+	const qs = navTarget.query ? serializeNavQuery(navTarget.query) : "";
+	if (qs) hash += (path.includes("?") ? "&" : "?") + qs;
 	url.hash = hash;
 	return url.toString();
 }
+/** Serialize a {@link NavTarget.query} into a URL query string. */
+function serializeNavQuery(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) if (typeof value === "string") params.set(key, value);
+	else for (const v of value) params.append(key, v);
+	return params.toString();
+}
 //#endregion
 //#region src/client/messages.ts
 /**
@@ -406,7 +407,7 @@ function createMessagesClient(rpc, options = {}) {
 //#endregion
 //#region src/client/renderers.ts
 /**
-* Build the {@link DockRenderersContext} shared by every hub-aware client —
+* Build the {@link DockRenderersContext} shared by every hub-aware client.
 * `createDevframeClientRuntime` and hub UI providers that assemble their own context
 * (`@devframes/hub-ui`) both delegate here so local-first resolution, lazy
 * manifest imports, and the typed mount result behave identically everywhere.
@@ -504,7 +505,7 @@ const DOCKS_ACTIVATE_EVENT = HUB_EVENTS.broadcast.docksActivate;
 * Boot the client runtime: connect RPC, assemble the full
 * {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
 * shared state, publish it at `__DEVFRAME_HUB_CLIENT_CONTEXT__`, and load every
-* dock entry's client script into this page — the devframe equivalent of the
+* dock entry's client script into this page, the devframe equivalent of the
 * runtime `@vitejs/devtools-kit` injects into a host app.
 *
 * A hub UI provider keeps rendering its own dock UI (reading the same shared state); this
@@ -575,7 +576,7 @@ async function createDevframeClientRuntime(options = {}) {
 		type: "action",
 		handler: (activation) => activateHandler(activation)
 	});
-	if (getDevframeClientContext()) console.warn("[@devframes/hub] A client context is already published on this page — replacing it. Boot createDevframeClientRuntime() once per page (e.g. HTML injection combined with a manual import boots it twice).");
+	if (getDevframeClientContext()) console.warn("[@devframes/hub] A client context is already published on this page; replacing it. Boot createDevframeClientRuntime() once per page (e.g. HTML injection combined with a manual import boots it twice).");
 	setDevframeClientContext(context);
 	const loadedScripts = /* @__PURE__ */ new Set();
 	if (loadScriptsEnabled) {
@@ -678,6 +679,10 @@ async function createDevframeClientRuntime(options = {}) {
 			set selectedId(id) {
 				switchEntry(id);
 			},
+			/**
+			* A mirror of the session field, so a persisting host reads and writes the
+			* selected iframe's route through the same context every hub UI provider uses.
+			*/
 			get selectedRoute() {
 				return panel.session.selectedDockRoute;
 			},
@@ -696,14 +701,14 @@ async function createDevframeClientRuntime(options = {}) {
 			switchEntry,
 			toggleEntry: (id) => selectedId === id ? switchEntry(null) : switchEntry(id),
 			register(entry, force) {
-				if (clientDocks.has(entry.id) && !force) throw new Error(`[@devframes/hub] a client dock "${entry.id}" is already registered — pass force to overwrite`);
+				if (clientDocks.has(entry.id) && !force) throw new Error(`[@devframes/hub] a client dock "${entry.id}" is already registered; pass force to overwrite`);
 				clientDocks.set(entry.id, entry);
 				refreshEntries();
 				return {
 					update: (patch) => {
 						if (patch.id && patch.id !== entry.id) throw new Error(`[@devframes/hub] cannot change a dock id ("${entry.id}" → "${patch.id}")`);
 						const existing = clientDocks.get(entry.id);
-						if (!existing) throw new Error(`[@devframes/hub] client dock "${entry.id}" was removed — register it again to update`);
+						if (!existing) throw new Error(`[@devframes/hub] client dock "${entry.id}" was removed; register it again to update`);
 						clientDocks.set(entry.id, {
 							...existing,
 							...patch
@@ -716,7 +721,7 @@ async function createDevframeClientRuntime(options = {}) {
 				};
 			},
 			update(entry) {
-				if (!clientDocks.has(entry.id)) throw new Error(`[@devframes/hub] no client dock "${entry.id}" to update — register it first`);
+				if (!clientDocks.has(entry.id)) throw new Error(`[@devframes/hub] no client dock "${entry.id}" to update; register it first`);
 				clientDocks.set(entry.id, entry);
 				refreshEntries();
 			}
@@ -739,7 +744,14 @@ async function createDevframeClientRuntime(options = {}) {
 		function allCommands() {
 			return [...commandsState.value(), ...clientCommands.values()];
 		}
-		return {
+		function findCommand(commands, id) {
+			for (const command of commands) {
+				if (command.id === id) return command;
+				const child = findCommand(command.children ?? [], id);
+				if (child) return child;
+			}
+		}
+		const ctx = {
 			get commands() {
 				return allCommands();
 			},
@@ -754,18 +766,24 @@ async function createDevframeClientRuntime(options = {}) {
 				};
 			},
 			async execute(id, ...args) {
-				const client = clientCommands.get(id);
-				if (client?.action) return client.action(...args);
+				const client = findCommand(clientCommands.values(), id);
+				if (client?.source === "client" && client.action) return client.action(...args);
 				return rpc.call("hub:commands:execute", id, ...args);
 			},
 			getKeybindings(id) {
 				const override = settings.value().commandShortcuts?.[id];
 				if (override) return override;
-				return allCommands().find((c) => c.id === id)?.keybindings ?? [];
+				return findCommand(allCommands(), id)?.keybindings ?? [];
 			},
 			settings,
-			paletteOpen: false
+			paletteOpen: false,
+			paletteScopeId: null,
+			openPalette(atCommandId) {
+				ctx.paletteScopeId = atCommandId ?? null;
+				ctx.paletteOpen = true;
+			}
 		};
+		return ctx;
 	}
 	function createRenderersContext() {
 		const mountedDisposers = /* @__PURE__ */ new Set();
@@ -833,11 +851,50 @@ function createPanelContext(clientType) {
 		position: "right",
 		inactiveTimeout: 0
 	};
+	let open = clientType === "standalone";
+	let selectedDockId = null;
+	const events = createEventEmitter();
+	let panelStateChangePending = false;
+	function createDockPanelState() {
+		const panelState = { state: open ? "open" : "closed" };
+		if (selectedDockId !== null) panelState.selectedDockId = selectedDockId;
+		return panelState;
+	}
+	let previousPanelState = createDockPanelState();
+	function schedulePanelStateChange() {
+		if (panelStateChangePending) return;
+		panelStateChangePending = true;
+		queueMicrotask(() => {
+			panelStateChangePending = false;
+			const panelState = createDockPanelState();
+			if (panelState.state === previousPanelState.state && panelState.selectedDockId === previousPanelState.selectedDockId) return;
+			previousPanelState = panelState;
+			events.emit(HUB_EVENTS.client.docksPanelStateChanged, panelState);
+		});
+	}
 	return {
+		get state() {
+			return createDockPanelState();
+		},
+		events,
 		store,
 		session: {
-			open: clientType === "standalone",
-			selectedDockId: null,
+			get open() {
+				return open;
+			},
+			set open(nextOpen) {
+				if (nextOpen === open) return;
+				open = nextOpen;
+				schedulePanelStateChange();
+			},
+			get selectedDockId() {
+				return selectedDockId;
+			},
+			set selectedDockId(nextSelectedDockId) {
+				if (nextSelectedDockId === selectedDockId) return;
+				selectedDockId = nextSelectedDockId;
+				schedulePanelStateChange();
+			},
 			selectedDockRoute: null
 		},
 		isDragging: false,
@@ -863,7 +920,7 @@ function groupByCategory(entries, categoryOrder) {
 	}
 	return [...groups.entries()].sort(([a], [b]) => (categoryOrder[a] ?? 0) - (categoryOrder[b] ?? 0));
 }
-/** @deprecated Renamed — use {@link createDevframeClientRuntime}. */
+/** @deprecated Renamed; use {@link createDevframeClientRuntime}. */
 const createDevframeClientHost = createDevframeClientRuntime;
 //#endregion
 //#region src/client/remote.ts
@@ -923,22 +980,9 @@ function extractKeyFromQuery(search) {
 * Throws if the descriptor is malformed or its schema version is unsupported.
 */
 function parseRemoteConnection(input) {
-	let hash = "";
-	let search = "";
-	if (input === void 0) {
-		if (typeof location === "undefined") return null;
-		hash = location.hash;
-		search = location.search;
-	} else try {
-		const parsed = new URL(input, "http://_");
-		hash = parsed.hash;
-		search = parsed.search;
-	} catch {
-		if (input.startsWith("#")) hash = input;
-		else if (input.startsWith("?")) search = input;
-		else return null;
-	}
-	const encoded = extractKeyFromFragment(hash) ?? extractKeyFromQuery(search);
+	const parts = resolveUrlParts(input);
+	if (!parts) return null;
+	const encoded = extractKeyFromFragment(parts.hash) ?? extractKeyFromQuery(parts.search);
 	if (!encoded) return null;
 	let payload;
 	try {
@@ -946,6 +990,37 @@ function parseRemoteConnection(input) {
 	} catch (cause) {
 		throw new Error("[@devframes/hub] Failed to decode remote connection descriptor.", { cause });
 	}
+	return validateConnectionDescriptor(payload);
+}
+/** Resolve the URL fragment/query to inspect, from an explicit input or `location`. */
+function resolveUrlParts(input) {
+	if (input === void 0) {
+		if (typeof location === "undefined") return null;
+		return {
+			hash: location.hash,
+			search: location.search
+		};
+	}
+	try {
+		const parsed = new URL(input, "http://_");
+		return {
+			hash: parsed.hash,
+			search: parsed.search
+		};
+	} catch {
+		if (input.startsWith("#")) return {
+			hash: input,
+			search: ""
+		};
+		if (input.startsWith("?")) return {
+			hash: "",
+			search: input
+		};
+		return null;
+	}
+}
+/** Validate a decoded payload as a {@link RemoteConnectionInfo}, throwing on any mismatch. */
+function validateConnectionDescriptor(payload) {
 	if (!payload || typeof payload !== "object") throw new Error("[@devframes/hub] Remote connection descriptor must be an object.");
 	const info = payload;
 	if (info.v !== 1) throw new Error(`[@devframes/hub] Unsupported remote connection descriptor version: ${String(info.v)}`);
@@ -959,7 +1034,7 @@ function parseRemoteConnection(input) {
 * the current URL and returns a connected {@link DevframeRpcClient}.
 *
 * Pairs with `remote: true` on a `DevframeViewIframe` registered on the node
-* side — the hub injects the descriptor into the iframe URL.
+* side, where the hub injects the descriptor into the iframe URL.
 *
 * @throws if no descriptor is present in the URL.
 */

package/dist/{constants-DrF61GFx.mjs → constants-BUd6oMci.mjs}

@@ -2,7 +2,7 @@ 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
+* 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/content/8.references/3.events.md`](../../../docs/content/8.references/3.events.md)**
@@ -11,10 +11,9 @@ import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash } from "ufo";
 * 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.
+* The `.events` EventEmitter maps and RPC augmentation interfaces 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 = {
 	/**
@@ -47,6 +46,8 @@ const HUB_EVENTS = {
 		terminalsRestart: "hub:terminals:restart",
 		terminalsRemove: "hub:terminals:remove"
 	},
+	/** Client-context events emitted inside the host page. */
+	client: { docksPanelStateChanged: "panel:state:changed" },
 	/** Broadcast notifications the server pushes to clients (server → client), `devframe:` prefix. */
 	broadcast: {
 		docksActivate: "devframe:docks:activate",
@@ -68,7 +69,7 @@ const HUB_EVENTS = {
 };
 //#endregion
 //#region src/constants.ts
-/** Default mount base for a hub instance — one namespace, one catch-all. */
+/** 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
@@ -81,7 +82,7 @@ function normalizeHubBase(base) {
 	return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)));
 }
 /**
-* The default ordering weight for each known dock category — lower sorts
+* The default ordering weight for each known dock category, where 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.
@@ -103,7 +104,7 @@ const DEFAULT_CATEGORIES_ORDER = {
 	"~builtin": 1e3
 };
 /**
-* Shared-state slot carrying the hub's renderer manifest — one
+* 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).

package/dist/{constants-C5t0DeZ0.d.mts → constants-Coo1p3ja.d.mts}

@@ -1,8 +1,8 @@
-import { t as DevframeDocksUserSettings } from "./settings-D7whfcx2.mjs";
+import { t as DevframeDocksUserSettings } from "./settings-CWHPzCWS.mjs";
 //#region src/events.d.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
+ * 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/content/8.references/3.events.md`](../../../docs/content/8.references/3.events.md)**
@@ -11,10 +11,9 @@ import { t as DevframeDocksUserSettings } from "./settings-D7whfcx2.mjs";
  * 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.
+ * The `.events` EventEmitter maps and RPC augmentation interfaces 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.
  */
 declare const HUB_EVENTS: {
   /**
@@ -47,6 +46,10 @@ declare const HUB_EVENTS: {
     readonly terminalsRestart: "hub:terminals:restart";
     readonly terminalsRemove: "hub:terminals:remove";
   };
+  /** Client-context events emitted inside the host page. */
+  readonly client: {
+    readonly docksPanelStateChanged: "panel:state:changed";
+  };
   /** Broadcast notifications the server pushes to clients (server → client), `devframe:` prefix. */
   readonly broadcast: {
     readonly docksActivate: "devframe:docks:activate";
@@ -72,7 +75,7 @@ declare const HUB_EVENTS: {
 };
 //#endregion
 //#region src/constants.d.ts
-/** Default mount base for a hub instance — one namespace, one catch-all. */
+/** 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
@@ -83,7 +86,7 @@ declare const DEVFRAMES_HUB_BASE = "/__devframes/";
  */
 declare function normalizeHubBase(base: string): string;
 /**
- * The default ordering weight for each known dock category — lower sorts
+ * The default ordering weight for each known dock category, where 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.
@@ -94,7 +97,7 @@ declare function normalizeHubBase(base: string): string;
  */
 declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
 /**
- * Shared-state slot carrying the hub's renderer manifest — one
+ * 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).

package/dist/constants.d.mts

@@ -1,3 +1,3 @@
-import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-C5t0DeZ0.mjs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-Coo1p3ja.mjs";
 export * from "devframe/constants";
 export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS, normalizeHubBase };

package/dist/constants.mjs

@@ -1,3 +1,3 @@
-import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-DrF61GFx.mjs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-BUd6oMci.mjs";
 export * from "devframe/constants";
 export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS, normalizeHubBase };