@devframes/hub 0.9.8 → 0.9.10

package/dist/node/initiate.d.mts

@@ -1,7 +1,7 @@
-import { i as InstallDevframeOptions, n as DevframeHubContext, t as CreateHubContextOptions } from "../context-BJFGlcf8.mjs";
-import { r as DEVFRAMES_HUB_BASE } from "../constants-DJrPlLi0.mjs";
+import { i as InstallDevframeOptions, n as DevframeHubContext, t as CreateHubContextOptions } from "../context-Di-fhMKP.mjs";
+import { r as DEVFRAMES_HUB_BASE } from "../constants-Bz4yclHo.mjs";
 import { DevframeInstanceRecord } from "devframe/internal";
-import { ConnectionMeta, DevframeDefinition, DevframeServiceInput, DevframeSseOptions, DevframeStorageScope, DevframeWsOptions, McpRouteOptions } from "devframe/types";
+import { ConnectionMeta, DevframeDefinition, DevframeServiceInput, DevframeSseOptions, DevframeStorageScope, DevframeWsOptions, McpSetting } from "devframe/types";
 import { DevframeAuthHandler } from "devframe/node/auth";
 import { WsOriginRegistry } from "devframe/rpc/transports/ws-server";
 import { Buffer } from "node:buffer";
@@ -20,14 +20,14 @@ type Arrayable<T> = T | readonly T[];
  * One dock-type → prebuilt renderer-module registration for
  * {@link InitHubOptions.renderers}. The hub serves the module at
  * `<base>__renderers/<type>.mjs` and publishes it in the renderer manifest
- * (the `devframe:dock-renderers` shared-state slot), so any viewer — the
- * reference UI, a community viewer, a hand-rolled host page — lazily imports
+ * (the `devframe:dock-renderers` shared-state slot), so any viewer (the
+ * reference UI, a community viewer, a hand-rolled host page) lazily imports
  * it the first time a dock of that `type` needs rendering.
  *
  * The module must be a **self-contained browser ES module** (its framework
  * and styles bundled in) whose {@link DockRendererRegistration.importName}
  * export is a ready `DockRenderer`. Renderer packages ship a node helper
- * returning this shape — e.g. `jsonRenderUiRenderer()` from
+ * returning this shape, e.g. `jsonRenderUiRenderer()` from
  * `@devframes/json-render-ui/hub`.
  */
 interface DockRendererRegistration {
@@ -43,7 +43,7 @@ interface DockRendererRegistration {
   importName?: string;
 }
 /**
- * The UI slot of a hub instance — pure data, zero policy. The hub itself is
+ * The UI slot of a hub instance: pure data, zero policy. The hub itself is
  * headless: whoever fills this slot decides what a viewer looks like.
  * `@devframes/hub-ui` ships the reference implementation (`createUi()`);
  * Vite DevTools or any community viewer supplies its own object to the same
@@ -52,14 +52,14 @@ interface DockRendererRegistration {
 interface DevframeHubUi {
   /**
    * A standalone viewer SPA (built with relative asset paths) served at the
-   * hub base itself — open `<base>` in a tab and the devtools are there.
+   * hub base itself; open `<base>` in a tab and the devtools are there.
    */
   viewer?: {
     /** Directory of the prebuilt viewer SPA. */
     distDir: string;
   };
   /**
-   * A prebuilt, self-contained script served at `<base>embedded.js` — the
+   * A prebuilt, self-contained script served at `<base>embedded.js`: the
    * floating-devtools bootstrap a host page loads with one
    * `<script type="module" src="<base>embedded.js">` tag. Visibility policy
    * (always-on, keyboard-summoned, …) belongs entirely to this entry.
@@ -77,8 +77,8 @@ interface DevframeHubUi {
    */
   assets?: Record<string, () => string | Uint8Array>;
   /**
-   * A setup hook run once during hub init with the hub context — the UI
-   * slot's chance to publish its own static, boot-time config through the
+   * A setup hook run once during hub init with the hub context, giving the UI
+   * slot a chance to publish its own static, boot-time config through the
    * generic `ctx.staticConfig` (serialized into `ConnectionMeta.configs`).
    * The reference UI's `createUi()` uses it to set
    * `ctx.staticConfig.ui = { branding, … }`, reaching every mounted frame and
@@ -98,7 +98,7 @@ interface InitHubOptions {
    */
   version?: string;
   /**
-   * Mount base the hub answers under — required so the mount path is
+   * Mount base the hub answers under, required so the mount path is
    * explicit at the call site (pass the exported {@link DEVFRAMES_HUB_BASE}
    * for the conventional `/__devframes/`). Every mounted devframe lives at
    * `<base><id>/`, so the host app needs exactly one catch-all route. The
@@ -118,19 +118,19 @@ interface InitHubOptions {
    * Host-level wire services to install, on top of whatever the mounted
    * devframes declare. Constructed (option sets merged) at the pre-setup
    * barrier, so every devframe's `setup` sees them ready. Reach for this to
-   * configure a shared service centrally — e.g.
+   * configure a shared service centrally, e.g.
    * `services: [createShikiService({ themes })]`.
    */
   services?: DevframeServiceInput[];
   /**
    * Extra RPC declarations registered at context creation, alongside the
-   * hub built-ins — forwarded to `createHubContext`'s
+   * hub built-ins, forwarded to `createHubContext`'s
    * `builtinRpcDeclarations`. Declarative mode only (a pre-built `context`
    * already made this choice).
    */
   rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations'];
   /**
-   * Bring your own hub context instead of `devframes` — for hosts that
+   * Bring your own hub context instead of `devframes`, for hosts that
    * assemble `createHubContext` + `ctx.install` themselves (with their own
    * `DevframeHost` serving the frames). The instance then serves only the
    * hub-level endpoints (`__connection.json`, `__index.json`,
@@ -139,14 +139,14 @@ interface InitHubOptions {
    */
   context?: DevframeHubContext;
   /**
-   * Runs once the context exists and every `devframes` entry is mounted —
+   * Runs once the context exists and every `devframes` entry is mounted;
    * register docks, commands, terminals, and messages surfaces here.
    */
   configure?: (ctx: DevframeHubContext) => void | Promise<void>;
-  /** See {@link DevframeHubUi} — omitted, the hub stays fully headless. */
+  /** See {@link DevframeHubUi}; omitted, the hub stays fully headless. */
   ui?: DevframeHubUi;
   /**
-   * Prebuilt dock-renderer modules to serve and advertise — the composition
+   * Prebuilt dock-renderer modules to serve and advertise: the composition
    * seam that hands a renderer package (e.g. `@devframes/json-render-ui`) to
    * a prebuilt viewer. Each {@link DockRendererRegistration} is served at
    * `<base>__renderers/<type>.mjs` and published in the renderer manifest;
@@ -175,11 +175,11 @@ interface InitHubOptions {
    * > `ws.sidecar` (auto-port side-car) > the host driving upgrades itself,
    * while `url` overrides the advertisement (tunnel pattern) and `route`
    * renames the upgrade segment (default `__ws`). Pass `false` to serve no
-   * WebSocket at all — clients connect over SSE instead (`backend: 'sse'`).
+   * WebSocket at all, so clients connect over SSE instead (`backend: 'sse'`).
    */
   ws?: DevframeWsOptions | false;
   /**
-   * SSE RPC endpoint control, same contract as `initDevframe` — enabled by
+   * SSE RPC endpoint control, same contract as `initDevframe`, enabled by
    * default at `<base>__sse` as the more portable transport alongside the
    * WebSocket. Pass `false` to disable, or a {@link DevframeSseOptions} to
    * rename the route.
@@ -195,11 +195,18 @@ interface InitHubOptions {
    */
   auth?: boolean | DevframeAuthHandler;
   /**
-   * Expose the **aggregate** MCP endpoint at `<base>__mcp` — one
+   * Expose the **aggregate** MCP endpoint at `<base>__mcp`: one
    * Streamable-HTTP server over the shared context's whole tool registry
-   * (ids are already namespaced per plugin). Disabled by default.
+   * (ids are already namespaced per plugin). Defaults to `'auto'`: the route
+   * mounts once any mounted devframe (or an agent-flagged hub command)
+   * exposes an agent surface. `true` mounts it
+   * unconditionally with the loopback origin gate (trusting same-machine
+   * callers), an object opts into an {@link McpRouteOptions.authorization}
+   * identity check, `false` keeps it off. A mounted devframe's own `mcp`
+   * setting is ignored: the hub's aggregate route covers them all (`DF8005`
+   * warns when one asks for MCP while this is `false`).
    */
-  mcp?: boolean | McpRouteOptions;
+  mcp?: McpSetting;
   /**
    * Public origin the host app is reachable at, or a getter. Derived lazily
    * from the first request when omitted.
@@ -217,14 +224,14 @@ interface InitHubOptions {
   register?: boolean | Partial<DevframeInstanceRecord>;
   /**
    * Advertise that this host runtime resolves **bare-specifier** client
-   * scripts (`ClientScriptEntry.importFrom` naming an npm module) — a URL
+   * scripts (`ClientScriptEntry.importFrom` naming an npm module): a URL
    * template whose `{specifier}` token is replaced with the specifier,
    * published as `ConnectionMeta.configs.dock.clientModuleResolution` and
    * applied by every client-script loader. Declare it only when the host can
-   * actually serve npm modules to the browser — a Vite host passes
+   * actually serve npm modules to the browser; a Vite host passes
    * `'/@id/{specifier}'` to route imports through its own module graph
    * (`@devframes/vite/hub` does). Left undeclared, registering a
-   * bare-specifier client script warns `DF8111` — ship a self-contained
+   * bare-specifier client script warns `DF8111`; ship a self-contained
    * bundle and pass its URL instead.
    */
   clientModuleResolution?: string;
@@ -240,12 +247,12 @@ interface InitHubOptions {
 interface HubInstance {
   /**
    * The normalized mount base this hub answers under (leading and trailing
-   * slash, e.g. `/__devframes/`). Reference it when wiring the mount — route
-   * guards, middleware path checks — instead of repeating the string literal.
+   * slash, e.g. `/__devframes/`). Reference it when wiring the mount (route
+   * guards, middleware path checks) instead of repeating the string literal.
    */
   base: string;
   /**
-   * Web-standard request handler for the whole hub — mount it on one
+   * Web-standard request handler for the whole hub; mount it on one
    * catch-all route under {@link HubInstance.base}.
    */
   handler: (request: Request) => Promise<Response>;
@@ -253,7 +260,7 @@ interface HubInstance {
   nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
   /**
    * Route a host server's `upgrade` events to the shared RPC socket,
-   * returning a detach function — the manual counterpart to the `server`
+   * returning a detach function, the manual counterpart to the `server`
    * option, for hosts that get their `node:http` server only after the hub
    * exists. Available on the default tier; a configured transport (`server`,
    * `ws.port`, `ws.sidecar`, `ws.url`) already owns the socket and reports
@@ -276,14 +283,14 @@ interface HubInstance {
   close: () => Promise<void>;
 }
 /**
- * Initiate a hub instance — the whole multi-devframe devtools surface
+ * 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

package/dist/node/initiate.mjs

@@ -1,19 +1,15 @@
-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 { 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 { resolve } from "pathe";
-import process from "node:process";
-import { existsSync } from "node:fs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, r as DEVFRAMES_HUB_BASE } from "../constants-Da23JxCZ.mjs";
+import { b as diagnostics, t as createHubContext } from "../context-BWaW6N53.mjs";
+import { i as resolveRendererRegistrations, n as renderClientImportsModule, r as resolveDevframesInput, t as mountDevframes } from "../assemble-Hj36CCzH.mjs";
+import { joinURL, withoutLeadingSlash } from "ufo";
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE } from "devframe/constants";
 import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { createH3DevframeHost, createInstanceShell, importRuntimeModule, loadAutoMcpAdapter, resolveInstanceRegister, resolveMcpConfig } from "devframe/internal";
+import { resolve } from "pathe";
 import { mountStaticHandler } from "devframe/utils/serve-static";
 import { H3 } from "h3";
 //#region src/node/initiate.ts
-function normalizeDevframeEntry(entry) {
-	return "devframe" in entry ? entry : { devframe: entry };
-}
 /** Content-type for a UI asset key, inferred from its file extension. */
 function assetContentType(key) {
 	if (key.endsWith(".json")) return "application/json; charset=utf-8";
@@ -23,81 +19,51 @@ 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. */
-const RESERVED_HUB_PATHS = [
-	DEVFRAME_CONNECTION_META_FILENAME,
-	DEVFRAME_DOCK_IMPORTS_FILENAME,
-	DEVFRAME_WS_ROUTE,
-	DEVFRAME_MCP_ROUTE,
-	"__index.json",
-	"__renderers",
-	"embedded.js"
-];
 /**
-* 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
-* conditionally (`isDev && loadInspect()`) without filtering it first.
+* 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.
 */
-function resolveDevframesInput(input) {
-	return Promise.all(input.map(async (entry) => {
-		const resolved = await (typeof entry === "function" ? entry() : entry);
-		return (Array.isArray(resolved) ? resolved : [resolved]).filter((slot) => slot != null).map(normalizeDevframeEntry);
-	})).then((arrays) => arrays.flat());
-}
-/**
-* Validate the renderer-module registrations fail-fast: route-safe types
-* (each becomes the `<base>__renderers/<type>.mjs` URL segment), one module
-* per type, and an existing bundle file (renderer packages are prebuilt).
-*/
-function resolveRendererRegistrations(registrations) {
-	const seen = /* @__PURE__ */ new Set();
-	return registrations.map((registration) => {
-		if (!/^[\w.-]+$/.test(registration.type)) throw diagnostics.DF8110({ type: registration.type });
-		if (seen.has(registration.type)) throw diagnostics.DF8108({ type: registration.type });
-		seen.add(registration.type);
-		const file = resolve(registration.file);
-		if (!existsSync(file)) throw diagnostics.DF8109({
-			type: registration.type,
-			file
-		});
-		return {
-			...registration,
-			file
-		};
+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 } : {}
 	});
 }
 /**
-* 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
-* host page; `importFrom` values are URL paths the host serves, or bare npm
-* specifiers resolved through the host's `clientModuleResolution` template.
-*/
-function renderClientImportsModule(ctx) {
-	const template = ctx.staticConfig.dock?.clientModuleResolution;
-	const entries = [];
-	for (const [id, view] of ctx.docks.views) {
-		const scripts = [];
-		const anyView = view;
-		if (anyView.clientScript) scripts.push(anyView.clientScript);
-		if (anyView.action) scripts.push(anyView.action);
-		if (anyView.renderer) scripts.push(anyView.renderer);
-		if (scripts.length === 0) continue;
-		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`;
-}
-/**
-* Initiate a hub instance — the whole multi-devframe devtools surface
+* 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,9 +93,14 @@ 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");
+			const { getPort } = await import("../dist-BP3CGpgZ.mjs");
 			return getPort({
 				port: 9777,
 				portRange: [9777, 9877],
@@ -140,54 +111,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 !== false);
 			await ctx.services.ready();
 			for (const run of setups) await run();
 			await options.configure?.(ctx);
@@ -198,14 +129,21 @@ 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 mcpSetting = options.mcp ?? "auto";
+			let mcpModule;
+			let mcpConfig;
+			if (mcpSetting === "auto") {
+				mcpModule = await loadAutoMcpAdapter(ctx.agent);
+				if (mcpModule) mcpConfig = { authorization: false };
+			} else mcpConfig = resolveMcpConfig(mcpSetting);
 			if (!mcpConfig) return { context: ctx };
 			const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? DEVFRAME_MCP_ROUTE);
-			const { mountMcpHttp } = await importRuntimeModule("devframe/adapters/mcp");
-			const mounted = mountMcpHttp(app, ctx, joinURL(base, mcpRoute), {
+			mcpModule ??= await importRuntimeModule("devframe/adapters/mcp");
+			const mounted = mcpModule.mountMcpHttp(app, ctx, joinURL(base, mcpRoute), {
 				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