@devframes/hub 0.9.8 → 0.9.9

package/dist/node/initiate.mjs

@@ -1,9 +1,9 @@
-import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, r as DEVFRAMES_HUB_BASE } from "../constants-D1zicoJ4.mjs";
-import { a as resolveClientModuleSpecifier } from "../remote-url-Bgc7gtsP.mjs";
-import { m as prepareDevframe, t as createHubContext, y as diagnostics } from "../context-DYUkd3il.mjs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, r as DEVFRAMES_HUB_BASE } from "../constants-BUd6oMci.mjs";
+import { a as resolveClientModuleSpecifier } from "../remote-url-UClKLQ5_.mjs";
+import { m as prepareDevframe, t as createHubContext, y as diagnostics } from "../context-D4L966cN.mjs";
 import { joinURL, withTrailingSlash, withoutLeadingSlash } from "ufo";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_WS_ROUTE } from "devframe/constants";
-import { createH3DevframeHost, createInstanceShell, importRuntimeModule, resolveInstanceRegister } from "devframe/internal";
+import { createH3DevframeHost, createInstanceShell, importRuntimeModule, resolveInstanceRegister, resolveMcpConfig } from "devframe/internal";
 import { resolve } from "pathe";
 import process from "node:process";
 import { existsSync } from "node:fs";
@@ -23,7 +23,7 @@ function assetContentType(key) {
 	if (key.endsWith(".html")) return "text/html; charset=utf-8";
 	return "application/octet-stream";
 }
-/** Reserved filenames directly under the hub base — a frame id can't shadow them. */
+/** Reserved filenames directly under the hub base; a frame id can't shadow them. */
 const RESERVED_HUB_PATHS = [
 	DEVFRAME_CONNECTION_META_FILENAME,
 	DEVFRAME_DOCK_IMPORTS_FILENAME,
@@ -35,7 +35,7 @@ const RESERVED_HUB_PATHS = [
 ];
 /**
 * Flatten the `devframes` input: await every thenable, call every factory,
-* spread the arrays, and drop the empty slots — so a host can build the list
+* spread the arrays, and drop the empty slots, so a host can build the list
 * conditionally (`isDev && loadInspect()`) without filtering it first.
 */
 function resolveDevframesInput(input) {
@@ -67,7 +67,7 @@ function resolveRendererRegistrations(registrations) {
 	});
 }
 /**
-* Render the dock client-script import map as an ES module — one dynamic
+* Render the dock client-script import map as an ES module: one dynamic
 * import thunk per dock that carries a client script (`clientScript` on
 * iframe docks, `action`, `renderer`). External viewers import this module
 * from `<base>__client-imports.js` to load per-dock client code into the
@@ -87,17 +87,78 @@ function renderClientImportsModule(ctx) {
 		const thunks = scripts.map((script) => `() => import(${JSON.stringify(resolveClientModuleSpecifier(script.importFrom, { template }))})`);
 		entries.push(`  ${JSON.stringify(id)}: [${thunks.join(", ")}],`);
 	}
-	return `// Generated by @devframes/hub — dock client-script import map.\nexport const clientImports = {\n${entries.join("\n")}\n}\nexport default clientImports\n`;
+	return `// Generated by @devframes/hub: dock client-script import map.\nexport const clientImports = {\n${entries.join("\n")}\n}\nexport default clientImports\n`;
 }
 /**
-* Initiate a hub instance — the whole multi-devframe devtools surface
+* Resolve the shared hub context: reuse a caller-supplied one, or build an
+* h3-backed context that serves the hub's connection meta under every frame.
+*/
+async function resolveHubContext(options, app, cwd, api) {
+	if (options.context && options.devframes?.length) throw diagnostics.DF8002();
+	if (options.context) return options.context;
+	const host = {
+		...createH3DevframeHost({
+			origin: () => api.origin() ?? "http://localhost",
+			appName: "devframes",
+			workspaceRoot: cwd,
+			mount: (mountBase, dir) => {
+				mountStaticHandler(app, mountBase, dir);
+			}
+		}),
+		...options.getStorageDir ? { getStorageDir: options.getStorageDir } : {},
+		/**
+		* Serve the hub's own connection meta under every mounted frame's
+		* base, so each SPA discovers the shared RPC endpoint via its
+		* relative `./__connection.json` fetch; the meta's WS path is
+		* hub-base-absolute, so it resolves to the one shared socket no
+		* matter how deep the frame base is.
+		*/
+		mountConnectionMeta: (frameBase) => {
+			app.use(joinURL(frameBase, DEVFRAME_CONNECTION_META_FILENAME), () => api.connectionMeta());
+		}
+	};
+	return createHubContext({
+		cwd,
+		workspaceRoot: cwd,
+		mode: "dev",
+		host,
+		...options.rpcDeclarations ? { builtinRpcDeclarations: options.rpcDeclarations } : {}
+	});
+}
+/**
+* Pass 1: mount each devframe under `<base><id>/` (SPA, meta, iframe dock)
+* and queue its declared services, guarding the id against reserved hub
+* filenames and route-pattern characters. Returns the deferred setup thunks.
+*/
+async function mountDevframes(ctx, devframes, base, frames, hubMcpEnabled) {
+	const setups = [];
+	for (const { devframe: def, dock } of devframes) {
+		if (RESERVED_HUB_PATHS.includes(def.id)) throw diagnostics.DF8000({ id: def.id });
+		if (!/^[\w.-]+$/.test(def.id)) throw diagnostics.DF8004({ id: def.id });
+		if (!hubMcpEnabled && def.cli?.mcp) diagnostics.DF8005({ id: def.id });
+		const frameBase = withTrailingSlash(joinURL(base, def.id));
+		const run = await prepareDevframe(ctx, def, {
+			base: frameBase,
+			...dock ? { dock } : {}
+		});
+		if (run) setups.push(run);
+		frames.push({
+			id: def.id,
+			base: frameBase,
+			title: def.name
+		});
+	}
+	return setups;
+}
+/**
+* Initiate a hub instance: the whole multi-devframe devtools surface
 * behind one framework-agnostic, web-standard handler. Every mounted
 * devframe shares one context (merged RPC registry, shared state, docks /
 * terminals / messages / commands), one WebSocket transport, and one Auth;
 * the instance serves each frame's SPA at `<base><id>/`, the discovery
 * endpoints (`__connection.json`, `__index.json`, `__client-imports.js`),
 * the aggregate MCP route, and whatever the {@link DevframeHubUi} slot
-* provides — the hub itself stays headless.
+* provides, while the hub itself stays headless.
 *
 * The factory is synchronous and initializes eagerly, and binds no port of
 * its own: the WebSocket follows `server` / `ws` (see
@@ -127,6 +188,11 @@ function initHub(options) {
 			...options.name !== void 0 ? { name: options.name } : {},
 			rootDir: cwd
 		}),
+		/**
+		* One meta document is served from the hub base *and* from every frame
+		* base, so the advertised WS path has to be base-absolute to resolve to
+		* the same socket from any depth.
+		*/
 		absoluteWsPath: true,
 		resolveSidecarPort: async (sidecarHost) => {
 			const { getPort } = await import("../dist-R0T2g9Vw.mjs");
@@ -140,54 +206,14 @@ function initHub(options) {
 			throw diagnostics.DF8003();
 		},
 		async init(api) {
-			if (options.context && options.devframes?.length) throw diagnostics.DF8002();
-			let ctx;
-			if (options.context) ctx = options.context;
-			else {
-				const host = {
-					...createH3DevframeHost({
-						origin: () => api.origin() ?? "http://localhost",
-						appName: "devframes",
-						workspaceRoot: cwd,
-						mount: (mountBase, dir) => {
-							mountStaticHandler(app, mountBase, dir);
-						}
-					}),
-					...options.getStorageDir ? { getStorageDir: options.getStorageDir } : {},
-					mountConnectionMeta: (frameBase) => {
-						app.use(joinURL(frameBase, DEVFRAME_CONNECTION_META_FILENAME), () => api.connectionMeta());
-					}
-				};
-				ctx = await createHubContext({
-					cwd,
-					workspaceRoot: cwd,
-					mode: "dev",
-					host,
-					...options.rpcDeclarations ? { builtinRpcDeclarations: options.rpcDeclarations } : {}
-				});
-			}
+			const ctx = await resolveHubContext(options, app, cwd, api);
 			if (options.clientModuleResolution) ctx.staticConfig.dock = {
 				...ctx.staticConfig.dock,
 				clientModuleResolution: options.clientModuleResolution
 			};
 			const devframes = await resolveDevframesInput(options.devframes ?? []);
 			for (const input of options.services ?? []) ctx.services.install(input);
-			const setups = [];
-			for (const { devframe: def, dock } of devframes) {
-				if (RESERVED_HUB_PATHS.includes(def.id)) throw diagnostics.DF8000({ id: def.id });
-				if (!/^[\w.-]+$/.test(def.id)) throw diagnostics.DF8004({ id: def.id });
-				const frameBase = withTrailingSlash(joinURL(base, def.id));
-				const run = await prepareDevframe(ctx, def, {
-					base: frameBase,
-					...dock ? { dock } : {}
-				});
-				if (run) setups.push(run);
-				frames.push({
-					id: def.id,
-					base: frameBase,
-					title: def.name
-				});
-			}
+			const setups = await mountDevframes(ctx, devframes, base, frames, !!options.mcp);
 			await ctx.services.ready();
 			for (const run of setups) await run();
 			await options.configure?.(ctx);
@@ -198,7 +224,7 @@ function initHub(options) {
 				...registration.importName ? { importName: registration.importName } : {}
 			};
 			(await ctx.rpc.sharedState.get(DOCK_RENDERERS_STATE_KEY, { initialValue: {} })).mutate(() => manifest);
-			const mcpConfig = options.mcp === true ? {} : options.mcp;
+			const mcpConfig = resolveMcpConfig(options.mcp);
 			if (!mcpConfig) return { context: ctx };
 			const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? DEVFRAME_MCP_ROUTE);
 			const { mountMcpHttp } = await importRuntimeModule("devframe/adapters/mcp");
@@ -206,6 +232,7 @@ function initHub(options) {
 				serverName: options.name ?? "devframes-hub",
 				serverVersion: options.version ?? "0.0.0",
 				exposeSharedState: true,
+				authorization: mcpConfig.authorization,
 				allowedOrigins: mcpConfig.allowedOrigins
 			});
 			return {

package/dist/{remote-url-Bgc7gtsP.mjs → remote-url-UClKLQ5_.mjs}

@@ -2,7 +2,7 @@ import { REMOTE_CONNECTION_KEY } from "devframe/constants";
 //#region src/client-modules.ts
 const URL_SCHEME_RE = /^[a-z][a-z\d+.-]*:/i;
 /**
-* Whether a client-script `importFrom` is a **bare module specifier** — an
+* Whether a client-script `importFrom` is a **bare module specifier**: an
 * npm-style name (`vite-plugin-vue-tracer/client/vite-devtools`) rather than
 * a URL the browser can resolve natively.
 */
@@ -15,10 +15,10 @@ function isBareModuleSpecifier(specifier) {
 * 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.
 */
 function resolveClientModuleSpecifier(specifier, options = {}) {
 	if (!isBareModuleSpecifier(specifier)) return specifier;
@@ -40,8 +40,8 @@ function resolveClientModuleSpecifier(specifier, options = {}) {
 */
 function clientScriptFailureHint(importFrom, specifier) {
 	if (!isBareModuleSpecifier(importFrom)) return "";
-	if (specifier === importFrom) return " — the specifier is a bare npm specifier and this host advertises no client-module resolution (`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained bundle by URL, pass `resolveClientModule` to this client host, or run under a host that resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).";
-	return ` — the host resolved the bare specifier "${importFrom}" to this URL but could not serve the module. Check the package is installed and resolvable from the host project's root (and built, if its exports point at build output).`;
+	if (specifier === importFrom) return ". The specifier is a bare npm specifier and this host advertises no client-module resolution (`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained bundle by URL, pass `resolveClientModule` to this client host, or run under a host that resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).";
+	return `. The host resolved the bare specifier "${importFrom}" to this URL but could not serve the module. Check the package is installed and resolvable from the host project's root (and built, if its exports point at build output).`;
 }
 //#endregion
 //#region src/remote-url.ts
@@ -77,42 +77,37 @@ function buildRemoteConnectionUrl(baseUrl, payload, transport = "fragment") {
 	const beforeHash = hashIdx === -1 ? baseUrl : baseUrl.slice(0, hashIdx);
 	return `${beforeHash}${beforeHash.includes("?") ? "&" : "?"}${param}${hash}`;
 }
+function stripParamList(value) {
+	const parts = value.split("&");
+	const filtered = parts.filter((part) => part.split("=")[0] !== REMOTE_CONNECTION_KEY);
+	return [filtered.join("&"), filtered.length !== parts.length];
+}
+/** Strip the descriptor from a URL fragment, preserving its route/query split. */
+function stripHashParams(hash) {
+	const routeQueryIdx = hash.indexOf("?");
+	if (routeQueryIdx === -1) return stripParamList(hash);
+	const route = hash.slice(0, routeQueryIdx);
+	const [query, changed] = stripParamList(hash.slice(routeQueryIdx + 1));
+	if (!changed) return [hash, false];
+	return [query ? `${route}?${query}` : route, true];
+}
+/** Strip the descriptor from a URL query string (the part before any fragment). */
+function stripQueryParams(beforeHash) {
+	const queryIdx = beforeHash.indexOf("?");
+	if (queryIdx === -1) return [beforeHash, false];
+	const path = beforeHash.slice(0, queryIdx);
+	const [query, changed] = stripParamList(beforeHash.slice(queryIdx + 1));
+	if (!changed) return [beforeHash, false];
+	return [query ? `${path}?${query}` : path, true];
+}
 /** Remove the remote connection descriptor from a URL before displaying or copying it. */
 function stripRemoteConnectionFromUrl(input) {
-	function stripParamList(value) {
-		const parts = value.split("&");
-		const filtered = parts.filter((part) => part.split("=")[0] !== REMOTE_CONNECTION_KEY);
-		return [filtered.join("&"), filtered.length !== parts.length];
-	}
 	const hashIdx = input.indexOf("#");
-	let beforeHash = hashIdx === -1 ? input : input.slice(0, hashIdx);
-	let hash = hashIdx === -1 ? void 0 : input.slice(hashIdx + 1);
-	let changed = false;
-	if (hash !== void 0) {
-		const routeQueryIdx = hash.indexOf("?");
-		if (routeQueryIdx === -1) {
-			const [nextHash, didChange] = stripParamList(hash);
-			hash = nextHash;
-			changed ||= didChange;
-		} else {
-			const route = hash.slice(0, routeQueryIdx);
-			const [query, didChange] = stripParamList(hash.slice(routeQueryIdx + 1));
-			if (didChange) {
-				hash = query ? `${route}?${query}` : route;
-				changed = true;
-			}
-		}
-	}
-	const queryIdx = beforeHash.indexOf("?");
-	if (queryIdx !== -1) {
-		const path = beforeHash.slice(0, queryIdx);
-		const [query, didChange] = stripParamList(beforeHash.slice(queryIdx + 1));
-		if (didChange) {
-			beforeHash = query ? `${path}?${query}` : path;
-			changed = true;
-		}
-	}
-	if (!changed) return input;
+	const rawHash = hashIdx === -1 ? void 0 : input.slice(hashIdx + 1);
+	const rawBeforeHash = hashIdx === -1 ? input : input.slice(0, hashIdx);
+	const [hash, hashChanged] = rawHash === void 0 ? [void 0, false] : stripHashParams(rawHash);
+	const [beforeHash, queryChanged] = stripQueryParams(rawBeforeHash);
+	if (!hashChanged && !queryChanged) return input;
 	return hash ? `${beforeHash}#${hash}` : beforeHash;
 }
 //#endregion

package/dist/{settings-DwxCyeI6.d.mts → settings-CWHPzCWS.d.mts}

@@ -17,7 +17,7 @@ interface DevframeDocksHost {
    * carrying `params` for the target dock to interpret (e.g. a terminals
    * session id).
    *
-   * Any connected client may drive this via the `hub:docks:activate` RPC — a
+   * Any connected client may drive this via the `hub:docks:activate` RPC, so a
    * mounted devframe running in its own iframe can steer the host shell's dock
    * selection, which is otherwise client-local. The request is delivered live
    * to connected clients (broadcast) and mirrored into the
@@ -34,7 +34,7 @@ interface DevframeDockPanelState {
 }
 /**
  * A request to switch the active dock. `params` is an opaque, serializable
- * bag the target dock interprets — the terminals dock reads `params.sessionId`
+ * bag the target dock interprets; the terminals dock reads `params.sessionId`
  * to focus a specific session.
  */
 interface DevframeDockActivation {
@@ -42,7 +42,7 @@ interface DevframeDockActivation {
   params?: Record<string, unknown>;
 }
 /**
- * Shape of the `devframe:docks:active` shared-state slot — the most recent
+ * Shape of the `devframe:docks:active` shared-state slot: the most recent
  * {@link DevframeDockActivation}, or `null` before any activation. Mirrored
  * so a dock that mounts in response to an activation can still converge on the
  * request instead of missing the live broadcast.
@@ -50,12 +50,19 @@ interface DevframeDockActivation {
 interface DevframeDocksActiveState {
   activation: DevframeDockActivation | null;
 }
+/**
+ * Known categories the hub orders by default (see
+ * {@link import('../constants').DEFAULT_CATEGORIES_ORDER}). Kits may pass their
+ * own category ids; `(string & {})` keeps autocomplete on the known set while
+ * allowing arbitrary string values. `~builtin` is reserved for the viewer's
+ * own built-in views (see {@link DevframeViewBuiltin}) and always sorts last.
+ */
 type DevframeDockEntryCategory = 'framework' | 'app' | 'ui' | 'data' | 'web' | 'performance' | 'advanced' | 'docs' | 'default' | '~builtin' | (string & {});
 type DevframeDockEntryIcon = string | {
   light: string;
   dark: string;
 };
-/** Color for a dock-bar entry's {@link DevframeDockEntryBase.badge} — mirrors json-render's `TabDescriptor.badgeVariant`. */
+/** Color for a dock-bar entry's {@link DevframeDockEntryBase.badge}, mirroring json-render's `TabDescriptor.badgeVariant`. */
 type DevframeDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger';
 interface DevframeDockEntryBase {
   id: string;
@@ -68,17 +75,17 @@ interface DevframeDockEntryBase {
    */
   defaultOrder?: number;
   /**
-   * The category of the entry — a field with a dual role that depends on
+   * The category of the entry, a field with a dual role that depends on
    * whether {@link groupId} resolves to a registered {@link DevframeViewGroup}:
    *
-   * - **Ungrouped (or orphan) entry** — `category` is the entry's OUTER bucket
+   * - **Ungrouped (or orphan) entry**: `category` is the entry's OUTER bucket
    *   on the dock bar, ordered by {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
-   * - **Grouped entry** (a `groupId` that resolves to a registered group) —
+   * - **Grouped entry** (a `groupId` that resolves to a registered group):
    *   the OUTER bucket is instead the group's own `category`, and this field is
    *   reinterpreted as the entry's IN-GROUP sub-category, used to sub-divide and
    *   sort members inside the group's popover / sub-navigation.
    *
-   * Falls back to `'default'` when omitted — both as an outer bucket and, for a
+   * Falls back to `'default'` when omitted, both as an outer bucket and, for a
    * grouped member, as its in-group sub-bucket.
    *
    * @default 'default'
@@ -98,13 +105,13 @@ interface DevframeDockEntryBase {
   /**
    * Render-only conditional visibility expression, same syntax as {@link when}.
    * When it evaluates to `false`, a viewer omits the entry from the rendered
-   * dock bar / list, but the entry stays registered and fully reachable —
+   * dock bar / list, but the entry stays registered and fully reachable:
    * `docks.activate()`/`switchEntry()` by id, RPC lookups, and anything else
    * that walks the raw entry list (e.g. the {@link DevframeViewIframe.subTabs}
    * frame-nav adapter) keep working exactly as if it were visible.
    *
    * Use this instead of {@link when} when an entry must remain part of the
-   * model without a dock-bar button of its own — the canonical case is a
+   * model without a dock-bar button of its own; the canonical case is a
    * shared-frame {@link DevframeViewIframe.subTabs anchor}: set
    * `visibility: 'false'` on the anchor so only its synthesized member tabs
    * render, while the anchor itself keeps driving the postMessage nav loop.
@@ -131,7 +138,7 @@ interface DevframeDockEntryBase {
    * under the matching group's button instead of showing it directly on the
    * dock bar.
    *
-   * This is a flat pointer — membership, not containment. The entry stays an
+   * This is a flat pointer: membership, not containment. The entry stays an
    * independently-registered, top-level entry; only its rendering is grouped
    * downstream.
    *
@@ -148,7 +155,7 @@ interface DevframeDockEntryBase {
 }
 interface ClientScriptEntry {
   /**
-   * What to import — either a **URL the host serves** (a self-contained ES
+   * What to import: either a **URL the host serves** (a self-contained ES
    * module, e.g. `/@fs/<abs path>` under Vite or a statically-mounted bundle
    * path), or a **bare npm specifier** (e.g.
    * `'vite-plugin-vue-tracer/client/vite-devtools'`), a host-runtime
@@ -171,7 +178,7 @@ declare module 'devframe/types' {
     dock: {
       /**
        * URL template resolving a **bare-specifier** client script to an
-       * importable URL on this host — `{specifier}` replaced with the bare
+       * importable URL on this host, with `{specifier}` replaced with the bare
        * specifier (a token-less template is used as a prefix). Declaring it
        * advertises the host runtime can serve npm modules to the browser:
        * Vite hosts declare `'/@id/{specifier}'`, routing the import (and its
@@ -185,6 +192,15 @@ declare module 'devframe/types' {
 interface DevframeViewIframe extends DevframeDockEntryBase {
   type: 'iframe';
   url: string;
+  /** Request the address bar for this iframe dock. Pass an object to configure its controls. The user's global always-show setting forces it on for every iframe. */
+  addressBar?: boolean | {
+    /** Override Back visibility. Cross-origin history access may still be blocked by the browser. */
+    back?: boolean;
+    /** Override Reload visibility. */
+    reload?: boolean;
+    /** Override Open externally visibility. */
+    openExternal?: boolean;
+  };
   /**
    * The id of the iframe, if multiple tabs is assigned with the same id, the iframe will be shared.
    *
@@ -228,10 +244,10 @@ interface DevframeViewIframe extends DevframeDockEntryBase {
    * Enable remote-UI mode: the hub injects a connection descriptor
    * (WS URL + pre-approved auth token) into the iframe URL so a hosted
    * page can connect back via `connectRemoteDevframe()` from
-   * `@devframes/hub/client` — without needing to ship a dist with the
+   * `@devframes/hub/client`, without needing to ship a dist with the
    * plugin.
    *
-   * Requires dev mode (no effect in build mode — no WS server exists).
+   * Requires dev mode (no effect in build mode, where no WS server exists).
    * When enabled, the dock is automatically hidden in build mode unless
    * the author provides an explicit `when` clause.
    */
@@ -239,16 +255,21 @@ interface DevframeViewIframe extends DevframeDockEntryBase {
 }
 /**
  * A structured, soft-navigation target within a shared frame. `path` is opaque
- * to the hub — the embedded app maps it onto its own router.
+ * to the hub, which the embedded app maps onto its own router.
  *
  * Kept to `path` + `query` so the shape survives shared-state's `Immutable`
  * projection cleanly (a `DevframeViewIframe` must still narrow back from its
  * immutable form). An `unknown`/recursive history-`state` field breaks that
  * round-trip, so richer per-navigation state is intentionally out of scope for
- * now — carry it in `query` or the app's own store.
+ * now; carry it in `query` or the app's own store.
  */
 interface NavTarget {
   path: string;
+  /**
+   * `readonly` arrays keep this shape stable under the shared-state `Immutable`
+   * projection, so a `Immutable<DevframeViewIframe>` still narrows back to
+   * `DevframeViewIframe` (a mutable `string[]` would not).
+   */
   query?: Record<string, string | readonly string[]>;
 }
 /**
@@ -271,7 +292,7 @@ interface RemoteDockOptions {
    * How to pass the connection descriptor to the hosted page.
    *
    * - `'fragment'` (default): appended as a URL fragment.
-   *   Not sent in HTTP requests or Referer headers — safest for auth tokens.
+   *   Not sent in HTTP requests or Referer headers, so safest for auth tokens.
    * - `'query'`: appended as a URL query parameter. Use when your hosting
    *   platform rewrites fragments or your SPA router repurposes the fragment
    *   for navigation. The token will appear in server access logs and
@@ -310,7 +331,7 @@ interface DevframeViewLauncher extends DevframeDockEntryBase {
     /**
      * Bound command id: the launch button, command palette entry, and any
      * keybinding all resolve to this one handler. A viewer running out of
-     * process dispatches it over the `hub:commands:execute` RPC — the
+     * process dispatches it over the `hub:commands:execute` RPC, the
      * serializable path {@link onLaunch} can't cross, since a function is
      * dropped when the entry is projected into the `devframe:docks` shared
      * state. Register the command (with its handler) via `ctx.commands`.
@@ -348,7 +369,7 @@ interface DevframeViewCustomRender extends DevframeDockEntryBase {
   renderer: ClientScriptEntry;
 }
 /**
- * A view rendered natively by the viewer rather than by a plugin — the
+ * A view rendered natively by the viewer rather than by a plugin: the
  * settings panel, the terminals feed, the messages feed, etc. A high-level
  * integration registers the built-in views it wants; the viewer recognizes the
  * reserved `id` and renders its own UI for it.
@@ -367,12 +388,12 @@ interface DevframeViewBuiltin extends DevframeDockEntryBase {
  *
  * A group carries its own `title`/`icon`/`category`/`defaultOrder`/`when`
  * (inherited from {@link DevframeDockEntryBase}) and has no view payload of its
- * own — hosts render its members in a popover / sub-navigation. It flows
+ * own; hosts render its members in a popover / sub-navigation. It flows
  * through the same `register`/`update`/`values` machinery as every other entry,
  * keyed by `id`.
  *
  * The group's `category` is the OUTER bucket for the group button itself AND
- * for every one of its members — a member's own `category` no longer decides
+ * for every one of its members; a member's own `category` no longer decides
  * its outer bucket, but is reinterpreted as an in-group sub-category that
  * sub-divides and sorts members inside this group. A group with no `category`
  * buckets itself and its members under `'default'`.
@@ -388,7 +409,7 @@ interface DevframeViewGroup extends DevframeDockEntryBase {
    */
   defaultChildId?: string;
   /**
-   * Per-group override of the in-group sub-category ordering — a map of
+   * Per-group override of the in-group sub-category ordering: a map of
    * sub-category id → ordering weight (lower sorts earlier), mirroring the
    * shape of {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
    *
@@ -420,7 +441,7 @@ interface DevframeViewGroup extends DevframeDockEntryBase {
 /**
  * The **open** registry of dock entry variants, keyed by their `type`
  * discriminator. The hub ships the framework-neutral built-ins; opt-in
- * integrations contribute their own variants through declaration merging —
+ * integrations contribute their own variants through declaration merging,
  * e.g. `@devframes/json-render/hub` adds a `'json-render'` entry. The hub
  * itself stays agnostic: it hard-codes no integration-specific variant.
  *
@@ -464,16 +485,16 @@ interface DevframeCommandBase {
   description?: string;
   /**
    * Icon for the command. Either an Iconify icon string (e.g. "ph:pencil-duotone")
-   * or a theme-specific pair `{ light, dark }` — the same shape as dock icons.
+   * or a theme-specific pair `{ light, dark }`, the same shape as dock icons.
    */
   icon?: DevframeDockEntryIcon;
   category?: string;
   /**
    * Whether to show in command palette. Default: true
    *
-   * - `true` — show the command and flatten its children into search results
-   * - `false` — hide the command entirely from the palette
-   * - `'without-children'` — show the command but don't flatten children into top-level search (children are still accessible via drill-down)
+   * - `true`: show the command and flatten its children into search results
+   * - `false`: hide the command entirely from the palette
+   * - `'without-children'`: show the command but don't flatten children into top-level search (children are still accessible via drill-down)
    */
   showInPalette?: boolean | 'without-children';
   /**
@@ -488,13 +509,13 @@ interface DevframeCommandBase {
   keybindings?: DevframeCommandKeybinding[];
 }
 /**
- * Opt-in agent exposure for a server command — mirrors the `agent` field on
+ * Opt-in agent exposure for a server command, mirroring the `agent` field on
  * `defineRpcFunction`. A command carrying this field (and a `handler`) is
  * projected into `ctx.agent` as a callable tool, reaching MCP clients through
  * the devframe MCP adapter.
  *
  * `when` clauses are evaluated client-side only and are **not** enforced for
- * agent calls — opt in a `when`-gated command only if running it outside its
+ * agent calls; opt in a `when`-gated command only if running it outside its
  * UI context is safe.
  */
 interface DevframeCommandAgentOptions {
@@ -506,7 +527,7 @@ interface DevframeCommandAgentOptions {
   /** Display title (falls back to the command's `title`). */
   title?: string;
   /**
-   * Safety classification — drives MCP hint annotations.
+   * Safety classification that drives MCP hint annotations.
    * @default 'action'
    */
   safety?: 'read' | 'action' | 'destructive';
@@ -514,7 +535,7 @@ interface DevframeCommandAgentOptions {
   tags?: readonly string[];
   /**
    * Positional [Standard Schema](https://standardschema.dev/) validators for
-   * the handler's arguments — the same shape RPC definitions carry (valibot,
+   * the handler's arguments, the same shape RPC definitions carry (valibot,
    * zod, arktype, devframe's built-in `s` builder, …). Each is advertised
    * under `arg0` / `arg1` / … on the tool's JSON-Schema input. Omitted: the
    * tool takes no arguments.
@@ -522,7 +543,7 @@ interface DevframeCommandAgentOptions {
   args?: readonly StandardSchemaV1[];
 }
 /**
- * Server command input — what plugins pass to `ctx.commands.register()`.
+ * Server command input: what plugins pass to `ctx.commands.register()`.
  */
 interface DevframeServerCommandInput extends DevframeCommandBase {
   /**
@@ -535,20 +556,20 @@ interface DevframeServerCommandInput extends DevframeCommandBase {
    */
   agent?: DevframeCommandAgentOptions;
   /**
-   * Static sub-commands. Two levels max (parent → children).
+   * Static sub-commands, nested arbitrarily deep.
    * Each child must have a globally unique `id`.
    */
   children?: DevframeServerCommandInput[];
 }
 /**
- * Serializable server command entry — sent over RPC (no handler).
+ * Serializable server command entry, sent over RPC (no handler).
  */
 interface DevframeServerCommandEntry extends DevframeCommandBase {
   source: 'server';
   children?: DevframeServerCommandEntry[];
 }
 /**
- * Client command — registered in the webcomponent context.
+ * Client command, registered in the webcomponent context.
  */
 interface DevframeClientCommand extends DevframeCommandBase {
   source: 'client';
@@ -558,7 +579,7 @@ interface DevframeClientCommand extends DevframeCommandBase {
    */
   action?: (...args: any[]) => void | DevframeClientCommand[] | Promise<void | DevframeClientCommand[]>;
   /**
-   * Static sub-commands. Two levels max (parent → children).
+   * Static sub-commands, nested arbitrarily deep.
    */
   children?: DevframeClientCommand[];
 }
@@ -619,7 +640,7 @@ interface DevframeCommandShortcutOverrides {
  * ```
  *
  * Augmented fields are optional so the hub's `DEFAULT_STATE_USER_SETTINGS()`
- * (which knows nothing about them) stays assignable — an absent value reads
+ * (which knows nothing about them) stays assignable, so an absent value reads
  * as the viewer's documented default.
  */
 interface DevframeDocksUserSettings {

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { A as DevframeMessagesLevelShortcuts, C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, E as DevframeMessageLevel, O as DevframeMessagesClient, S as DevframeMessageEntryFrom, T as DevframeMessageHandle, _ as DevframeMessageAction, a as DevframeChildProcessExecuteOptions, b as DevframeMessageElementPosition, c as DevframeChildProcessTerminalSession, d as DevframePtyResult, f as DevframePtyTerminalSession, g as DevframeTerminalsHost, h as DevframeTerminalStatus, j as DevframeMessagesListDelta, k as DevframeMessagesHost, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, o as DevframeChildProcessOutput, p as DevframeTerminalSession, s as DevframeChildProcessResult, t as CreateHubContextOptions, u as DevframePtyOutput, v as DevframeMessageActivateAction, w as DevframeMessageFilePosition, x as DevframeMessageEntry, y as DevframeMessageCommandAction } from "../context-BJFGlcf8.mjs";
-import { A as DevframeViewIframe, C as DevframeDockUserEntry, D as DevframeViewBuiltin, E as DevframeViewAction, F as RemoteConnectionInfo, I as RemoteDockOptions, M as DevframeViewLauncherStatus, N as FrameSubTabsConfig, O as DevframeViewCustomRender, P as NavTarget, S as DevframeDockPanelState, T as DevframeDocksHost, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncher, k as DevframeViewGroup, l as DevframeCommandsHost, m as DevframeDockActivation, n as DevframeClientCommand, o as DevframeCommandHandle, p as ClientScriptEntry, r as DevframeCommandAgentOptions, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, u as DevframeCommandsHostEvents, v as DevframeDockEntryBase, w as DevframeDocksActiveState, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "../settings-DwxCyeI6.mjs";
-import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "../index-OpSX0dK5.mjs";
+import { A as DevframeMessagesLevelShortcuts, C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, E as DevframeMessageLevel, O as DevframeMessagesClient, S as DevframeMessageEntryFrom, T as DevframeMessageHandle, _ as DevframeMessageAction, a as DevframeChildProcessExecuteOptions, b as DevframeMessageElementPosition, c as DevframeChildProcessTerminalSession, d as DevframePtyResult, f as DevframePtyTerminalSession, g as DevframeTerminalsHost, h as DevframeTerminalStatus, j as DevframeMessagesListDelta, k as DevframeMessagesHost, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, o as DevframeChildProcessOutput, p as DevframeTerminalSession, s as DevframeChildProcessResult, t as CreateHubContextOptions, u as DevframePtyOutput, v as DevframeMessageActivateAction, w as DevframeMessageFilePosition, x as DevframeMessageEntry, y as DevframeMessageCommandAction } from "../context-Di-fhMKP.mjs";
+import { A as DevframeViewIframe, C as DevframeDockUserEntry, D as DevframeViewBuiltin, E as DevframeViewAction, F as RemoteConnectionInfo, I as RemoteDockOptions, M as DevframeViewLauncherStatus, N as FrameSubTabsConfig, O as DevframeViewCustomRender, P as NavTarget, S as DevframeDockPanelState, T as DevframeDocksHost, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncher, k as DevframeViewGroup, l as DevframeCommandsHost, m as DevframeDockActivation, n as DevframeClientCommand, o as DevframeCommandHandle, p as ClientScriptEntry, r as DevframeCommandAgentOptions, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, u as DevframeCommandsHostEvents, v as DevframeDockEntryBase, w as DevframeDocksActiveState, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "../settings-CWHPzCWS.mjs";
+import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "../index-faD2d5iX.mjs";
 export { ClientScriptEntry, type ConnectionMeta, type CreateHubContextOptions, type DevframeCapabilities, DevframeChildProcessExecuteOptions, DevframeChildProcessOutput, DevframeChildProcessResult, DevframeChildProcessTerminalSession, DevframeClientCommand, DevframeCommandAgentOptions, DevframeCommandBase, DevframeCommandEntry, DevframeCommandHandle, DevframeCommandKeybinding, DevframeCommandShortcutOverrides, DevframeCommandsHost, DevframeCommandsHostEvents, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, DevframeDockActivation, DevframeDockBadgeVariant, DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDockEntryBase, DevframeDockEntryCategory, DevframeDockEntryIcon, DevframeDockEntryRegistry, DevframeDockPanelState, DevframeDockUserEntry, DevframeDocksActiveState, DevframeDocksHost, DevframeDocksUserSettings, type DevframeHost, type DevframeHubContext, DevframeMessageAction, DevframeMessageActivateAction, DevframeMessageCommandAction, DevframeMessageElementPosition, DevframeMessageEntry, DevframeMessageEntryFrom, DevframeMessageEntryInput, DevframeMessageFilePosition, DevframeMessageHandle, DevframeMessageLevel, DevframeMessageShortcutInput, DevframeMessagesClient, DevframeMessagesHost, DevframeMessagesLevelShortcuts, DevframeMessagesListDelta, type DevframeNodeRpcSession, DevframePtyExecuteOptions, DevframePtyOutput, DevframePtyResult, DevframePtyTerminalSession, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, DevframeServerCommandEntry, DevframeServerCommandInput, DevframeTerminalSession, DevframeTerminalSessionBase, DevframeTerminalStatus, DevframeTerminalsHost, DevframeViewAction, DevframeViewBuiltin, DevframeViewCustomRender, DevframeViewGroup, type DevframeViewHost, DevframeViewIframe, DevframeViewLauncher, DevframeViewLauncherStatus, type EventEmitter, type EventUnsubscribe, type EventsMap, FrameSubTabsConfig, NavTarget, RemoteConnectionInfo, RemoteDockOptions, type RpcBroadcastOptions, type RpcDefinitionsFilter, type RpcDefinitionsToFunctions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost };