@devframes/hub 0.9.8 → 0.9.10

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-D1zicoJ4.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-Da23JxCZ.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
 /**
@@ -361,6 +362,7 @@ function deriveFallbackUrl(base, navTarget) {
 * dock client script reports into the very feed the server writes to.
 */
 function createMessagesClient(rpc, options = {}) {
+	if (rpc.connectionMeta?.backend === "static") return createLocalMessagesClient(options);
 	const { call } = rpc;
 	function makeHandle(entry) {
 		let current = entry;
@@ -403,10 +405,62 @@ function createMessagesClient(rpc, options = {}) {
 		debug: levelShortcut("debug")
 	};
 }
+/** In-page-only writes for a static backend: same surface, no wire. */
+function createLocalMessagesClient(options) {
+	let nextId = 0;
+	function makeEntry(input) {
+		return {
+			timestamp: Date.now(),
+			...options.defaults,
+			...input,
+			id: input.id ?? `local-${++nextId}`,
+			from: "browser"
+		};
+	}
+	function makeHandle(entry) {
+		let current = entry;
+		return {
+			get entry() {
+				return current;
+			},
+			get id() {
+				return current.id;
+			},
+			async update(patch) {
+				current = {
+					...current,
+					...patch,
+					id: current.id,
+					from: current.from
+				};
+				return current;
+			},
+			dismiss: async () => {}
+		};
+	}
+	const add = async (input) => makeHandle(makeEntry(input));
+	function levelShortcut(level) {
+		return (message, extra) => add({
+			...extra,
+			message,
+			level
+		});
+	}
+	return {
+		add,
+		remove: async () => {},
+		clear: async () => {},
+		info: levelShortcut("info"),
+		warn: levelShortcut("warn"),
+		error: levelShortcut("error"),
+		success: levelShortcut("success"),
+		debug: levelShortcut("debug")
+	};
+}
 //#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 +558,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 +629,12 @@ 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 (rpc.connectionMeta?.backend === "static" && typeof BroadcastChannel !== "undefined") {
+		const activateChannel = new BroadcastChannel(HUB_EVENTS.broadcastChannel.docksActivate);
+		activateChannel.onmessage = (event) => activateHandler(event.data);
+		disposers.push(() => activateChannel.close());
+	}
+	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 +737,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 +759,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 +779,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 +802,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 +824,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();
@@ -902,7 +978,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
@@ -962,22 +1038,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 {
@@ -985,6 +1048,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)}`);
@@ -998,7 +1092,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-DJrPlLi0.d.mts → constants-Bz4yclHo.d.mts}

@@ -1,8 +1,8 @@
-import { t as DevframeDocksUserSettings } from "./settings-DwxCyeI6.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)**
@@ -72,10 +72,19 @@ declare const HUB_EVENTS: {
   readonly postMessage: {
     readonly frameNav: "devframe:frame-nav";
   };
+  /**
+   * Same-origin `BroadcastChannel` names, `devframe:` prefix. Used on a
+   * `static` backend, where no live server can relay a client's request to
+   * its sibling browsing contexts (e.g. a panel iframe steering the host
+   * page's dock selection).
+   */
+  readonly broadcastChannel: {
+    readonly docksActivate: "devframe:docks:activate";
+  };
 };
 //#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
@@ -86,7 +95,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.
@@ -97,7 +106,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-D1zicoJ4.mjs → constants-Da23JxCZ.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)**
@@ -65,11 +65,18 @@ const HUB_EVENTS = {
 	/** Streaming channel ids (server → client), `devframe:` prefix. */
 	stream: { terminals: "devframe:terminals" },
 	/** `postMessage` channels for host ↔ iframe protocols, `devframe:` prefix. */
-	postMessage: { frameNav: "devframe:frame-nav" }
+	postMessage: { frameNav: "devframe:frame-nav" },
+	/**
+	* Same-origin `BroadcastChannel` names, `devframe:` prefix. Used on a
+	* `static` backend, where no live server can relay a client's request to
+	* its sibling browsing contexts (e.g. a panel iframe steering the host
+	* page's dock selection).
+	*/
+	broadcastChannel: { docksActivate: "devframe:docks:activate" }
 };
 //#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
@@ -82,7 +89,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.
@@ -104,7 +111,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.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-DJrPlLi0.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-Bz4yclHo.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-D1zicoJ4.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-Da23JxCZ.mjs";
 export * from "devframe/constants";
 export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS, normalizeHubBase };