@devframes/hub 0.9.8 → 0.9.9

package/dist/client/index.d.mts

@@ -1,6 +1,6 @@
-import { C as DevframeMessageEntryInput, O as DevframeMessagesClient } from "../context-BJFGlcf8.mjs";
-import { A as DevframeViewIframe, C as DevframeDockUserEntry, F as RemoteConnectionInfo, P as NavTarget, S as DevframeDockPanelState, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, g as DevframeDockEntriesGrouped, n as DevframeClientCommand, p as ClientScriptEntry, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-DwxCyeI6.mjs";
-import "../index-OpSX0dK5.mjs";
+import { C as DevframeMessageEntryInput, O as DevframeMessagesClient } from "../context-Di-fhMKP.mjs";
+import { A as DevframeViewIframe, C as DevframeDockUserEntry, F as RemoteConnectionInfo, P as NavTarget, S as DevframeDockPanelState, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, g as DevframeDockEntriesGrouped, n as DevframeClientCommand, p as ClientScriptEntry, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-CWHPzCWS.mjs";
+import "../index-faD2d5iX.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";
@@ -12,10 +12,10 @@ export * from "devframe/client";
  * 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}'`),
+ * 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.
+ * viewer. With neither, it stays unchanged, since a page import map may
+ * still cover it.
  */
 declare function resolveClientModuleSpecifier(specifier: string, options?: {
   resolveClientModule?: (specifier: string) => string | undefined;
@@ -55,21 +55,21 @@ interface DockRendererInstance {
   dispose?: () => void;
 }
 /**
- * A renderer for a dock `type`. The headless hub is renderer-agnostic — a
+ * A renderer for a dock `type`. The headless hub is renderer-agnostic: a
  * host registers renderers at boot (e.g. injecting `@devframes/json-render-ui`
  * for the `'json-render'` type) or serves them as prebuilt modules through the
  * hub's renderer manifest (`initHub({ renderers })`). The renderer owns its
  * framework (Vue, React, …); the hub only routes a dock type to it and
  * disposes it on deactivation.
  *
- * Integration packages narrow `Entry` to export a precisely-typed contract —
+ * Integration packages narrow `Entry` to export a precisely-typed contract,
  * e.g. `@devframes/json-render/hub` exports
  * `JsonRenderDockRenderer = DockRenderer<DevframeJsonRenderDockEntry>`.
  */
 type DockRenderer<Entry extends DevframeDockEntry = DevframeDockEntry> = (options: DockRendererMountOptions<Entry>) => DockRendererInstance | Promise<DockRendererInstance>;
 /**
  * The outcome of {@link DockRenderersContext.mount}. A missing renderer is an
- * expected, non-exceptional state — a viewer renders its "no renderer for this
+ * expected, non-exceptional state: a viewer renders its "no renderer for this
  * dock type" fallback from `missing-renderer`, and its error variant (with a
  * retry affordance) from `load-error`.
  */
@@ -85,8 +85,8 @@ type DockRendererMountResult = {
 /**
  * The dock-renderer registry surfaced on the client host context. A viewer
  * calls {@link DockRenderersContext.mount} to render a dock whose `type` has a
- * renderer — registered locally at boot, or served as a prebuilt module by the
- * hub's renderer manifest — into a container it owns; the host tracks the
+ * renderer (registered locally at boot, or served as a prebuilt module by the
+ * hub's renderer manifest) into a container it owns; the host tracks the
  * instance and disposes it when the entry deactivates.
  */
 interface DockRenderersContext {
@@ -94,13 +94,13 @@ interface DockRenderersContext {
    * Register a renderer for a dock `type`. Returns an unregister function.
    * Accepts a renderer narrowed to any specific entry variant (e.g. a
    * {@link DockRenderer}<DevframeJsonRenderDockEntry> from an integration
-   * package) — the type routes only its own entries to it.
+   * package); the type routes only its own entries to it.
    */
   register: (type: string, renderer: DockRenderer<any>) => () => void;
   /** Look up the locally-registered renderer for a dock `type`, if any. */
   get: (type: string) => DockRenderer | undefined;
   /**
-   * Whether a renderer is available for a dock `type` — registered locally
+   * Whether a renderer is available for a dock `type`, registered locally
    * **or** provided by the hub's renderer manifest. A viewer checks this
    * before mounting to render its missing-renderer fallback declaratively.
    */
@@ -112,14 +112,14 @@ interface DockRenderersContext {
    * registered. The mounted instance is also disposed automatically when the
    * entry deactivates. Resolves `missing-renderer` (with a `console.warn`)
    * when neither source has the type, and `load-error` when the module import
-   * or the renderer itself fails — a failed import is not cached, so a retry
+   * or the renderer itself fails. A failed import is not cached, so a retry
    * re-imports.
    */
   mount: (entry: DevframeDockEntry, container: HTMLElement) => Promise<DockRendererMountResult>;
 }
 /**
  * The renderer manifest published by the hub at the
- * `devframe:dock-renderers` shared-state slot — one {@link ClientScriptEntry}
+ * `devframe:dock-renderers` shared-state slot: one {@link ClientScriptEntry}
  * per dock `type`, whose `importFrom` is a URL path the hub serves
  * (`<base>__renderers/<type>.mjs`). Mirrors the dock client-script
  * convention: the module's `importName` export (default `'default'`) is a
@@ -130,20 +130,20 @@ type DockRendererManifest = Record<string, ClientScriptEntry>;
 interface CreateDockRenderersContextOptions {
   /** The assembled client context handed to renderers at mount. */
   context: () => DevframeClientContext;
-  /** Renderers registered locally at boot — these win over manifest modules. */
+  /** Renderers registered locally at boot; these win over manifest modules. */
   local?: Record<string, DockRenderer<any>>;
   /** The current {@link DockRendererManifest} (live getter). */
   manifest?: () => DockRendererManifest;
   /**
    * Called with each successful mount's disposer so the caller can tie
    * disposal to its own lifecycle (entry deactivation, host teardown). An
-   * optional returned cleanup runs exactly once when the mount is disposed —
+   * optional returned cleanup runs exactly once when the mount is disposed,
    * whichever side (caller or viewer) triggers it first.
    */
   onMounted?: (dispose: () => void, entry: DevframeDockEntry) => (() => void) | void;
 }
 /**
- * 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.
@@ -164,7 +164,7 @@ interface DockPanelStorage {
  * Per-tab UI state of the dock panel, distinct from the browser-shared geometry
  * in {@link DockPanelStorage}. A hub UI provider 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
+ * 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
@@ -183,7 +183,7 @@ interface DockSessionStorage {
   selectedDockRoute: string | null;
   /**
    * The dock entry most recently selected from beyond the float bar's inline
-   * capacity — from the overflow popover or from inside a dock group. A hub UI
+   * capacity, whether from the overflow popover or from inside a dock group. A hub UI
    * provider raises this entry into a dedicated slot between the bar's visible
    * items and the overflow button, so deselecting it (or selecting a visible
    * neighbour) keeps it one click away instead of folding it straight back
@@ -247,7 +247,7 @@ interface DocksConnectionContext {
   /** The most recent connection-level error, or `null` when healthy. */
   readonly error: Error | null;
   /**
-   * The client's event emitter — subscribe to `connection:status`,
+   * The client's event emitter. Subscribe to `connection:status`,
    * `connection:error`, and `rpc:error` to react to changes.
    */
   readonly events: EventEmitter<RpcClientEvents$1>;
@@ -270,7 +270,7 @@ interface DocksPanelContext {
   readonly events: EventEmitter<DocksPanelEvents>;
   store: DockPanelStorage;
   /**
-   * Per-tab session UI state — whether the panel is open, which dock is
+   * 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 hub UI provider that persists it to
    * `sessionStorage`.
@@ -282,7 +282,7 @@ interface DocksPanelContext {
   /**
    * 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
+   * 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.
@@ -297,11 +297,11 @@ interface DocksEntriesContext {
   entryToStateMap: Map<string, DockEntryState>;
   groupedEntries: DevframeDockEntriesGrouped;
   /**
-   * The resolved top-level category ordering — `DEFAULT_CATEGORIES_ORDER`,
+   * 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 `createDevframeClientRuntime({ categoryOrder })`. Fixed
-   * for the life of the session — resolved once at boot.
+   * for the life of the session, resolved once at boot.
    */
   readonly categoryOrder: Record<string, number>;
   settings: SharedState<DevframeDocksUserSettings>;
@@ -327,7 +327,7 @@ interface DocksEntriesContext {
    * {@link entries}. Unlike a dock registered on the node
    * {@link import('../types/docks').DevframeDocksHost}, it never flows into
    * shared state, so it stays local to this client instead of syncing to the
-   * hub or other hub UI providers — for a view the client runtime synthesizes itself.
+   * hub or other hub UI providers, suiting a view the client runtime synthesizes itself.
    *
    * Throws when `id` already names a client dock, unless `force` is set. A
    * client dock sharing an id with a server dock overrides it in the local
@@ -343,7 +343,7 @@ interface DocksEntriesContext {
 }
 interface DockRegistration<T extends DevframeDockEntry = DevframeDockEntry> {
   /**
-   * Patch the registered client dock in place. The `id` is immutable — passing
+   * Patch the registered client dock in place. The `id` is immutable, so passing
    * a differing `id` throws.
    */
   update: (patch: Partial<T>) => void;
@@ -395,6 +395,20 @@ interface CommandsContext {
    * Whether the command palette is open
    */
   paletteOpen: boolean;
+  /**
+   * The command whose children the palette should open drilled into, or `null`
+   * for the root list. Set by {@link CommandsContext.openPalette}; the palette
+   * reads it when it opens and clears it when it closes.
+   */
+  paletteScopeId: string | null;
+  /**
+   * Open the command palette, optionally scoped to one command's children:
+   * e.g. a dock group with no `defaultChildId` opens the palette listing just
+   * that group's members instead of guessing one for the user.
+   *
+   * Passing no id opens the root list, the same as setting `paletteOpen` true.
+   */
+  openPalette: (atCommandId?: string) => void;
 }
 //#endregion
 //#region src/client/client-script.d.ts
@@ -407,7 +421,7 @@ interface DockClientScriptContext extends DocksContext {
    */
   current: DockEntryState;
   /**
-   * Messages client scoped to this dock entry — messages it adds default
+   * Messages client scoped to this dock entry. Messages it adds default
    * their `category` to the entry id, so the feed can attribute them.
    */
   messages: DevframeMessagesClient;
@@ -440,8 +454,8 @@ declare function resolveDockIcon(icon: DevframeDockEntryIcon, connection: Devfra
 /**
  * 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
+ * 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.
@@ -449,21 +463,21 @@ declare function resolveDockIcon(icon: DevframeDockEntryIcon, connection: Devfra
  * {@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;
+ * - `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
+ *   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
+ * report is deduped against the last href, so 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,
+ * A cross-origin frame reports nothing, because 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. */
@@ -511,7 +525,7 @@ declare function watchFrameLocation(options: WatchFrameLocationOptions): () => v
 //#endregion
 //#region src/client/frame-nav.d.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
@@ -527,7 +541,7 @@ declare function watchFrameLocation(options: WatchFrameLocationOptions): () => v
  *   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. */
 declare const FRAME_NAV_CHANNEL: string;
@@ -600,11 +614,11 @@ interface FrameNavListenTarget {
 interface FrameNavClientOptions {
   /** The shared frame id (defaults to the anchor's, else the anchor id). */
   frameId: string;
-  /** The anchor iframe dock entry — supplies url/icon/groupId defaults. */
+  /** The anchor iframe dock entry, supplying url/icon/groupId defaults. */
   anchor: DevframeViewIframe;
   /** The live iframe element hosting the embedded app. */
   iframe: Pick<HTMLIFrameElement, 'contentWindow' | 'src'>;
-  /** Client docks context — to register members and drive selection. */
+  /** Client docks context, used to register members and drive selection. */
   docks: Pick<DocksEntriesContext, 'register' | 'switchEntry' | 'getStateById'>;
   /**
    * Window to receive the frame's `message` events on (the host page window).
@@ -634,7 +648,7 @@ declare function attachFrameNavClient(options: FrameNavClientOptions): FrameNavC
 interface DevframeClientRuntimeOptions {
   /**
    * An already-connected RPC client. When omitted, one is created via
-   * `connectDevframe(connect)` — pass `connect.baseURL` to point at the hub's
+   * `connectDevframe(connect)`, so pass `connect.baseURL` to point at the hub's
    * connection-meta mount (e.g. `/__hub/`).
    */
   rpc?: DevframeRpcClient;
@@ -642,8 +656,8 @@ interface DevframeClientRuntimeOptions {
   connect?: DevframeRpcClientOptions;
   /**
    * Environment the host runs in.
-   * - `'standalone'` (default) — the runtime owns the whole page (a hub UI).
-   * - `'embedded'` — the runtime lives inside a user app alongside a panel.
+   * - `'standalone'` (default): the runtime owns the whole page (a hub UI).
+   * - `'embedded'`: the runtime lives inside a user app alongside a panel.
    */
   clientType?: DockClientType;
   /**
@@ -653,7 +667,7 @@ interface DevframeClientRuntimeOptions {
   loadClientScripts?: boolean;
   /**
    * Resolve a **bare-specifier** client script (`importFrom` naming an npm
-   * module) to a URL this page can import — a hub UI provider's own policy, winning
+   * module) to a URL this page can import, a hub UI provider's own policy that wins
    * 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:
@@ -667,11 +681,11 @@ interface DevframeClientRuntimeOptions {
    * `@devframes/json-render-ui`). The hub ships none by default.
    *
    * Local registrations take precedence over the hub's renderer manifest
-   * (`initHub({ renderers })`) — explicit local code beats wire config.
+   * (`initHub({ renderers })`), since explicit local code beats wire config.
    */
   renderers?: Record<string, DockRenderer<any>>;
   /**
-   * Hub-wide override of the top-level dock-bar category ordering — a map of
+   * Hub-wide override of the top-level dock-bar category ordering: a map of
    * category id → ordering weight (lower sorts earlier), mirroring the shape
    * of {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
    *
@@ -703,24 +717,24 @@ interface DevframeClientRuntime {
  * 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
  * runtime is what gives plugin client scripts a live host context to run in.
  */
 declare function createDevframeClientRuntime(options?: DevframeClientRuntimeOptions): Promise<DevframeClientRuntime>;
-/** @deprecated Renamed — use {@link DevframeClientRuntimeOptions}. */
+/** @deprecated Renamed; use {@link DevframeClientRuntimeOptions}. */
 type DevframeClientHostOptions = DevframeClientRuntimeOptions;
-/** @deprecated Renamed — use {@link DevframeClientRuntime}. */
+/** @deprecated Renamed; use {@link DevframeClientRuntime}. */
 type DevframeClientHost = DevframeClientRuntime;
-/** @deprecated Renamed — use {@link createDevframeClientRuntime}. */
+/** @deprecated Renamed; use {@link createDevframeClientRuntime}. */
 declare const createDevframeClientHost: typeof createDevframeClientRuntime;
 //#endregion
 //#region src/client/messages.d.ts
 interface MessagesClientOptions {
   /**
-   * Default fields merged beneath every `add()` input — the client host passes
+   * Default fields merged beneath every `add()` input. The client host passes
    * `{ category: entry.id }` to scope a dock client script's messages to its
    * entry. Fields set on the input itself win.
    */
@@ -759,7 +773,7 @@ declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | n
  * 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/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-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();
@@ -902,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
@@ -962,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 {
@@ -985,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)}`);
@@ -998,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-D1zicoJ4.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)**
@@ -69,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
@@ -82,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.
@@ -104,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).