@devframes/hub 0.9.7 → 0.9.9

package/dist/{context-C3hUUCC1.mjs → context-D4L966cN.mjs}

@@ -1,35 +1,51 @@
 import { r as defineHubRpcFunction } from "./define-Ceekw2EO.mjs";
-import { n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS } from "./constants-DrF61GFx.mjs";
-import { i as isBareModuleSpecifier, t as buildRemoteConnectionUrl } from "./remote-url-Bgc7gtsP.mjs";
+import { n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS } from "./constants-BUd6oMci.mjs";
+import { i as isBareModuleSpecifier, t as buildRemoteConnectionUrl } from "./remote-url-UClKLQ5_.mjs";
+import { joinURL, withTrailingSlash } from "ufo";
 import { createEventEmitter } from "devframe/utils/events";
 import { createHostContext, createStorage } from "devframe/node";
 import { getInternalContext, resolveBasePath } from "devframe/node/hub-internals";
 import { debounce } from "perfect-debounce";
-import { coerceAgentPositionalArgs } from "devframe/internal";
+import { coerceAgentPositionalArgs, resolveClientAssets } from "devframe/internal";
 import { defineDiagnostics } from "devframe/utils/nostics";
-import { join, resolve } from "pathe";
+import { basename, dirname, isAbsolute, join, resolve } from "pathe";
 import { nanoid } from "devframe/utils/nanoid";
 import process from "node:process";
-import { resolveClientAssets } from "devframe";
+import { existsSync } from "node:fs";
 //#region src/node/diagnostics.ts
+/**
+* Hub-side diagnostics for docks, terminals, messages, and commands.
+* Shares the `DF` prefix with devframe core; the hub reserves the
+* `DF8xxx` range so the unified surface stays collision-free.
+* Sub-ranges:
+* DF8000-DF8099: hub context / lifecycle
+* DF8100-DF8199: docks
+* DF8200-DF8299: terminals
+* DF8300-DF8399: messages
+* DF8400-DF8499: commands
+*/
 const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: {
 		DF8000: {
-			why: (p) => `Devframe id "${p.id}" collides with a reserved hub path — it cannot be mounted directly under the hub base.`,
+			why: (p) => `Devframe id "${p.id}" collides with a reserved hub path, so it cannot be mounted directly under the hub base.`,
 			fix: "The filenames directly under the hub base (`__connection.json`, `__ws`, `__index.json`, `__client-imports.js`, `__mcp`, `embedded.js`) are reserved for the hub protocol. Rename the devframe id, or override its mount with a non-colliding `basePath`."
 		},
 		DF8002: {
-			why: "initHub received both `devframes` and `context` — the two assembly modes are mutually exclusive.",
-			fix: "Pass `devframes` to let the instance create the hub context and mount each frame itself, or pass a pre-built `context` (your host already mounted the frames) — never both."
+			why: "initHub received both `devframes` and `context`; the two assembly modes are mutually exclusive.",
+			fix: "Pass `devframes` to let the instance create the hub context and mount each frame itself, or pass a pre-built `context` (your host already mounted the frames), but never both."
 		},
 		DF8003: {
 			why: "connectionMeta() was called before initHub finished initializing.",
-			fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes."
+			fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()`, since the WebSocket binding it describes is only known once initialization completes."
 		},
 		DF8004: {
-			why: (p) => `Devframe id "${p.id}" is not a mountable URL segment — the hub mounts each frame at \`<base><id>/\`.`,
-			fix: "Ids become route segments, so they may only contain letters, digits, `_`, `-`, and `.` — `:` and `*` are route-pattern markers to the underlying router, and `/` would escape the segment. Set a route-safe `id` on the definition (e.g. `my_plugin` instead of `my:plugin`)."
+			why: (p) => `Devframe id "${p.id}" is not a mountable URL segment, and the hub mounts each frame at \`<base><id>/\`.`,
+			fix: "Ids become route segments, so they may only contain letters, digits, `_`, `-`, and `.`; `:` and `*` are route-pattern markers to the underlying router, and `/` would escape the segment. Set a route-safe `id` on the definition (e.g. `my_plugin` instead of `my:plugin`)."
+		},
+		DF8005: {
+			why: (p) => `Devframe "${p.id}" requests an MCP route, but the hub's aggregate MCP is off, so its tools are not exposed over MCP.`,
+			fix: "A hub exposes one aggregate MCP endpoint over every mounted devframe, so per-devframe `mcp` settings are ignored. Enable the hub's own MCP (pass `mcp` to `initHub`) to surface this devframe's tools, or drop `mcp` from the devframe to silence this warning."
 		},
 		DF8100: {
 			why: (p) => `Dock with id "${p.id}" is already registered`,
@@ -56,12 +72,12 @@ const diagnostics = defineDiagnostics({
 			fix: "Each devframe is deduplicated by id. Set `duplicationStrategy: \"duplicate\"` on the definition to let instances coexist, `\"silent\"` to drop duplicates quietly, or `\"throw\"` to surface them as errors."
 		},
 		DF8106: {
-			why: (p) => `The host cannot serve the RPC connection meta for devframe "${p.name}" (id "${p.id}") at "${p.base}" — its \`DevframeHost\` does not implement \`mountConnectionMeta\`.`,
+			why: (p) => `The host cannot serve the RPC connection meta for devframe "${p.name}" (id "${p.id}") at "${p.base}"; its \`DevframeHost\` does not implement \`mountConnectionMeta\`.`,
 			fix: "Implement `mountConnectionMeta(base)` on your DevframeHost so it serves `__connection.json` at each mounted base. Without it, the devframe SPA connects only when it shares an origin with the hub UI (same-origin window inheritance); cross-origin, sandboxed, or directly-opened iframes stay disconnected. Static-snapshot hosts that bake the meta into the served files can implement it as a no-op to acknowledge this intentionally."
 		},
 		DF8107: {
 			why: (p) => `Dock activation requested for unknown dock id "${p.id}"`,
-			fix: "Pass a `dockId` that matches a registered dock entry. The activation is still broadcast, but no hub UI provider will switch to it. Ids are case-sensitive — check for typos, and ensure the target dock is registered before activating it."
+			fix: "Pass a `dockId` that matches a registered dock entry. The activation is still broadcast, but no hub UI provider will switch to it. Ids are case-sensitive, so check for typos, and ensure the target dock is registered before activating it."
 		},
 		DF8108: {
 			why: (p) => `A renderer module is already registered for dock type "${p.type}"`,
@@ -72,11 +88,11 @@ const diagnostics = defineDiagnostics({
 			fix: "Point the registration's `file` at the prebuilt browser ES module (build the renderer package first, or check the path). Registration helpers like `jsonRenderUiRenderer()` resolve the path for you."
 		},
 		DF8110: {
-			why: (p) => `Dock type "${p.type}" is not a servable renderer-module name — the hub serves each module at \`<base>__renderers/<type>.mjs\``,
+			why: (p) => `Dock type "${p.type}" is not a servable renderer-module name; the hub serves each module at \`<base>__renderers/<type>.mjs\``,
 			fix: "Renderer types become URL segments, so they may only contain letters, digits, `_`, `-`, and `.`. Use a route-safe dock type (e.g. `json-render`)."
 		},
 		DF8111: {
-			why: (p) => `Dock "${p.id}" declares the bare-specifier client script "${p.specifier}", but this host advertises no client-module resolution — the browser cannot resolve a bare npm specifier natively, so the script will fail to load.`,
+			why: (p) => `Dock "${p.id}" declares the bare-specifier client script "${p.specifier}", but this host advertises no client-module resolution, and the browser cannot resolve a bare npm specifier natively, so the script will fail to load.`,
 			fix: "Run under a host framework that declares `initHub({ clientModuleResolution })` (e.g. Vite's `'/@id/{specifier}'`), ship the script as a self-contained bundle served by URL, or resolve it in the hub UI provider via `createDevframeClientRuntime({ resolveClientModule })` (then disregard this warning)."
 		},
 		DF8200: { why: (p) => `Terminal session with id "${p.id}" already registered` },
@@ -88,14 +104,14 @@ const diagnostics = defineDiagnostics({
 		DF8203: { why: (p) => `Failed to spawn PTY session for "${p.command}": ${p.reason}` },
 		DF8204: {
 			why: (p) => `Terminal session "${p.id}" cannot be controlled (no lifecycle handle)`,
-			fix: "Spawn it via ctx.terminals.startChildProcess() or startPtySession() — sessions added with a bare register() expose no terminate/restart handle."
+			fix: "Spawn it via ctx.terminals.startChildProcess() or startPtySession(); sessions added with a bare register() expose no terminate/restart handle."
 		},
 		DF8205: {
 			why: (p) => `Terminal session "${p.id}" is not restartable`,
 			fix: "It was registered with `restartable: false`; restart it through its owner's controls, or spawn it with `restartable: true` (the default) to allow in-place restarts."
 		},
 		DF8206: {
-			why: (p) => `Terminal session "${p.id}" cannot be restarted — its output stream is already closed`,
+			why: (p) => `Terminal session "${p.id}" cannot be restarted because its output stream is already closed`,
 			fix: "The session already exited (or was terminated) and its stream is spent. Drop it with `ctx.terminals.remove(session)`, then spawn a replacement via `ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` with a fresh id."
 		},
 		DF8400: { why: (p) => `Command "${p.id}" is already registered` },
@@ -144,7 +160,7 @@ var DevframeCommandsHost = class {
 	events = createEventEmitter();
 	/**
 	* Lazy agent projection: `ctx.agent` queries this provider at list/invoke
-	* time, deriving tools from {@link commands} on demand — the commands map
+	* time, deriving tools from {@link commands} on demand, so the commands map
 	* stays the single source of truth, nothing is mirrored or kept in sync.
 	*/
 	agentProvider;
@@ -222,7 +238,7 @@ var DevframeCommandsHost = class {
 	* agent-flagged, handler-bearing command (children included) becomes a
 	* callable tool. Queried lazily by the provider registered in the
 	* constructor. `when` clauses evaluate client-side only and are not
-	* enforced here — opting in a `when`-gated command is a deliberate author
+	* enforced here; opting in a `when`-gated command is a deliberate author
 	* decision (documented on `DevframeCommandAgentOptions`).
 	*/
 	collectAgentTools() {
@@ -235,7 +251,12 @@ var DevframeCommandsHost = class {
 				description: agent.description,
 				safety: agent.safety ?? "action",
 				tags: agent.tags,
+				/** The agent host derives the tool's JSON-Schema input from these. */
 				args: agent.args,
+				/**
+				* A command handler's positional parameters come solely from its
+				* declared `agent.args` schemas; undeclared payload is dropped.
+				*/
 				handler: async (args) => this.execute(command.id, ...coerceAgentPositionalArgs(args, agent.args, "drop"))
 			});
 			for (const child of command.children ?? []) walk(child);
@@ -265,6 +286,7 @@ var DevframeDocksHost = class {
 	}
 	async init() {
 		this.userSettings = await this.context.rpc.sharedState.get(HUB_EVENTS.sharedState.userSettings, { sharedState: createStorage({
+			/** Personal dock layout/preferences: per-checkout private state. */
 			filepath: join(this.context.host.getStorageDir("project"), "settings.json"),
 			initialValue: DEFAULT_STATE_USER_SETTINGS()
 		}) });
@@ -325,7 +347,7 @@ var DevframeDocksHost = class {
 		});
 	}
 	/**
-	* Warn (don't throw — a client-runtime `resolveClientModule` override may still cover
+	* Warn (don't throw, since a client-runtime `resolveClientModule` override may still cover
 	* it) when a dock declares a **bare-specifier** client script on a host
 	* that advertises no `staticConfig.dock.clientModuleResolution`: the
 	* browser cannot resolve a bare npm specifier natively, so the script is
@@ -379,7 +401,7 @@ var DevframeMessagesHost = class {
 	_clock = 0;
 	/**
 	* The tick of the newest removal record dropped from the capped
-	* `removals` log — cursors older than this can't get a reliable delta
+	* `removals` log; cursors older than this can't get a reliable delta
 	* and fall back to a full snapshot in {@link listSince}.
 	*/
 	_removalsTrimmedAt = 0;
@@ -560,7 +582,7 @@ var DevframeTerminalsHost = class {
 		this.context = context;
 	}
 	/**
-	* Lazily acquire the streaming channel — `context.rpc` isn't assigned
+	* Lazily acquire the streaming channel, since `context.rpc` isn't assigned
 	* until after every host is constructed, so we can't grab it in the
 	* constructor.
 	*/
@@ -570,6 +592,41 @@ var DevframeTerminalsHost = class {
 		this._channel = this.context.rpc.streaming.create(TERMINAL_STREAM_CHANNEL, { replayWindow: TERMINAL_REPLAY_WINDOW });
 		return this._channel;
 	}
+	/**
+	* Per-run stream lifecycle shared by the child-process and PTY paths: guards
+	* the single-close/error transition and keeps the session's `status` in step
+	* with the process lifecycle (a hub-aware client sees `running` →
+	* `stopped`/`error` instead of a value frozen at spawn time).
+	*/
+	createStreamLifecycle() {
+		const state = { streamClosed: false };
+		const markStatus = (next) => {
+			const session = state.session;
+			if (session.status === next) return;
+			session.status = next;
+			this.events.emit(HUB_EVENTS.bus.terminalsSessionUpdated, session);
+		};
+		const closeStream = () => {
+			if (state.streamClosed) return;
+			state.streamClosed = true;
+			try {
+				state.controller?.close();
+			} catch {}
+		};
+		const errorStream = (error) => {
+			if (state.streamClosed) return;
+			state.streamClosed = true;
+			try {
+				state.controller?.error(error);
+			} catch {}
+		};
+		return {
+			state,
+			markStatus,
+			closeStream,
+			errorStream
+		};
+	}
 	register(session) {
 		if (this.sessions.has(session.id)) throw diagnostics.DF8200({ id: session.id });
 		this.sessions.set(session.id, session);
@@ -591,6 +648,25 @@ var DevframeTerminalsHost = class {
 		this.events.emit(HUB_EVENTS.bus.terminalsSessionUpdated, session);
 		this._boundStreams.delete(session.id);
 	}
+	/** Drain a session's output stream into its scrollback buffer and streaming sink. */
+	async pumpStream(reader, sessionBuffer, sink, isDisposed) {
+		try {
+			while (!isDisposed()) {
+				const result = await reader.read();
+				if (isDisposed() || result.done) break;
+				sessionBuffer.push(result.value);
+				if (sessionBuffer.length > TERMINAL_BUFFER_LIMIT) sessionBuffer.splice(0, sessionBuffer.length - TERMINAL_BUFFER_LIMIT);
+				sink?.write(result.value);
+			}
+			if (!isDisposed() && sink && !sink.closed) sink.close();
+		} catch (error) {
+			if (!isDisposed() && sink && !sink.closed) sink.error(error);
+		} finally {
+			try {
+				reader.releaseLock();
+			} catch {}
+		}
+	}
 	bindStream(session) {
 		if (this._boundStreams.has(session.id) && this._boundStreams.get(session.id)?.stream === session.stream) return;
 		this._boundStreams.get(session.id)?.dispose();
@@ -601,26 +677,7 @@ var DevframeTerminalsHost = class {
 		const sink = this.getStreamingChannel()?.start({ id: session.id });
 		const reader = session.stream.getReader();
 		let disposed = false;
-		(async () => {
-			try {
-				while (true) {
-					if (disposed) break;
-					const result = await reader.read();
-					if (disposed) break;
-					if (result.done) break;
-					sessionBuffer.push(result.value);
-					if (sessionBuffer.length > TERMINAL_BUFFER_LIMIT) sessionBuffer.splice(0, sessionBuffer.length - TERMINAL_BUFFER_LIMIT);
-					sink?.write(result.value);
-				}
-				if (!disposed && sink && !sink.closed) sink.close();
-			} catch (error) {
-				if (!disposed && sink && !sink.closed) sink.error(error);
-			} finally {
-				try {
-					reader.releaseLock();
-				} catch {}
-			}
-		})();
+		this.pumpStream(reader, sessionBuffer, sink, () => disposed);
 		this._boundStreams.set(session.id, {
 			dispose: () => {
 				disposed = true;
@@ -633,34 +690,13 @@ var DevframeTerminalsHost = class {
 	async startChildProcess(executeOptions, terminal) {
 		if (this.sessions.has(terminal.id)) throw diagnostics.DF8200({ id: terminal.id });
 		const { exec } = await import("tinyexec");
-		let controller;
+		const { state, markStatus, closeStream, errorStream } = this.createStreamLifecycle();
 		let cp;
 		let currentResult;
 		let runId = 0;
-		let streamClosed = false;
-		let session;
-		const markStatus = (next) => {
-			if (session.status === next) return;
-			session.status = next;
-			this.events.emit(HUB_EVENTS.bus.terminalsSessionUpdated, session);
-		};
-		const closeStream = () => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.close();
-			} catch {}
-		};
-		const errorStream = (error) => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.error(error);
-			} catch {}
-		};
 		const stream = new ReadableStream({
 			start(_controller) {
-				controller = _controller;
+				state.controller = _controller;
 			},
 			cancel() {
 				cp?.kill();
@@ -700,13 +736,13 @@ var DevframeTerminalsHost = class {
 				if (currentRun !== runId) return;
 				const text = chunk.toString();
 				stdoutChunks.push(text);
-				if (!streamClosed) controller?.enqueue(text);
+				if (!state.streamClosed) state.controller?.enqueue(text);
 			});
 			cp.process?.stderr?.on("data", (chunk) => {
 				if (currentRun !== runId) return;
 				const text = chunk.toString();
 				stderrChunks.push(text);
-				if (!streamClosed) controller?.enqueue(text);
+				if (!state.streamClosed) state.controller?.enqueue(text);
 			});
 			cp.process?.once("error", (error) => {
 				if (currentRun !== runId) return;
@@ -738,7 +774,7 @@ var DevframeTerminalsHost = class {
 		}
 		cp = createChildProcess();
 		const restart = async () => {
-			if (streamClosed) throw diagnostics.DF8206({ id: terminal.id });
+			if (state.streamClosed) throw diagnostics.DF8206({ id: terminal.id });
 			cp?.kill();
 			cp = createChildProcess();
 			markStatus("running");
@@ -749,7 +785,7 @@ var DevframeTerminalsHost = class {
 			closeStream();
 			markStatus("stopped");
 		};
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			stream,
@@ -760,6 +796,7 @@ var DevframeTerminalsHost = class {
 			terminate,
 			restart
 		};
+		state.session = session;
 		this.register(session);
 		return Promise.resolve(session);
 	}
@@ -768,43 +805,24 @@ var DevframeTerminalsHost = class {
 		const { spawn } = await import("zigpty");
 		const cols = executeOptions.cols ?? 80;
 		const rows = executeOptions.rows ?? 24;
-		let controller;
+		const { state, markStatus, closeStream, errorStream } = this.createStreamLifecycle();
 		let pty;
+		let currentResult;
+		let killCurrentRun;
 		let runId = 0;
-		let streamClosed = false;
-		let session;
-		const markStatus = (next) => {
-			if (session.status === next) return;
-			session.status = next;
-			this.events.emit(HUB_EVENTS.bus.terminalsSessionUpdated, session);
-		};
-		const closeStream = () => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.close();
-			} catch {}
-		};
-		const errorStream = (error) => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.error(error);
-			} catch {}
-		};
 		const stream = new ReadableStream({
 			start(_controller) {
-				controller = _controller;
+				state.controller = _controller;
 			},
 			cancel() {
-				pty?.kill();
+				killCurrentRun?.();
 				pty = void 0;
 				closeStream();
 			}
 		});
 		const spawnPty = () => {
 			const currentRun = ++runId;
-			const proc = spawn(executeOptions.command, executeOptions.args ?? [], {
+			const ptyProcess = spawn(executeOptions.command, executeOptions.args ?? [], {
 				name: PTY_TERM_NAME,
 				cols,
 				rows,
@@ -817,16 +835,58 @@ var DevframeTerminalsHost = class {
 					...executeOptions.env ?? {}
 				}
 			});
-			proc.onData((data) => {
-				if (streamClosed || currentRun !== runId) return;
-				controller?.enqueue(typeof data === "string" ? data : data.toString("utf8"));
+			const outputChunks = [];
+			let killed = false;
+			let settled = false;
+			let settledExitCode;
+			let resolveOutput;
+			const outputPromise = new Promise((resolve) => {
+				resolveOutput = resolve;
 			});
-			proc.onExit(({ exitCode, signal }) => {
+			const settle = (exitCode, signal) => {
+				if (settled) return;
+				settled = true;
+				killed ||= signal !== 0;
+				settledExitCode = killed ? void 0 : exitCode;
+				resolveOutput({
+					output: outputChunks.join(""),
+					exitCode: settledExitCode,
+					signal: signal === 0 ? void 0 : signal
+				});
+			};
+			ptyProcess.onData((data) => {
+				const text = typeof data === "string" ? data : data.toString("utf8");
+				outputChunks.push(text);
+				if (!state.streamClosed && currentRun === runId) state.controller?.enqueue(text);
+			});
+			ptyProcess.onExit(({ exitCode, signal }) => {
+				settle(exitCode, signal);
 				if (currentRun !== runId) return;
 				closeStream();
-				markStatus(signal === 0 && exitCode !== 0 ? "error" : "stopped");
+				/**
+				* Killed runs and clean exits are stopped. Only a non-killed non-zero exit
+				* code is a crash, matching the child-process path.
+				*/
+				markStatus(!killed && exitCode !== 0 ? "error" : "stopped");
 			});
-			return proc;
+			currentResult = {
+				get pid() {
+					return ptyProcess.pid;
+				},
+				get exitCode() {
+					return killed ? void 0 : ptyProcess.exitCode ?? settledExitCode;
+				},
+				get killed() {
+					return killed;
+				},
+				then: (onfulfilled, onrejected) => outputPromise.then(onfulfilled, onrejected)
+			};
+			killCurrentRun = () => {
+				if (ptyProcess.exitCode !== null) return;
+				killed = true;
+				ptyProcess.kill();
+			};
+			return ptyProcess;
 		};
 		try {
 			pty = spawnPty();
@@ -837,7 +897,7 @@ var DevframeTerminalsHost = class {
 				reason: error instanceof Error ? error.message : String(error)
 			});
 		}
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			interactive: true,
@@ -862,19 +922,31 @@ var DevframeTerminalsHost = class {
 					return;
 				}
 			},
+			getResult: () => currentResult,
 			terminate: async () => {
-				pty?.kill();
+				killCurrentRun?.();
 				pty = void 0;
 				closeStream();
 				markStatus("stopped");
 			},
 			restart: async () => {
-				if (streamClosed) throw diagnostics.DF8206({ id: terminal.id });
-				pty?.kill();
-				pty = spawnPty();
+				if (state.streamClosed) throw diagnostics.DF8206({ id: terminal.id });
+				killCurrentRun?.();
+				killCurrentRun = void 0;
+				pty = void 0;
+				try {
+					pty = spawnPty();
+				} catch (error) {
+					markStatus("error");
+					throw diagnostics.DF8203({
+						command: executeOptions.command,
+						reason: error instanceof Error ? error.message : String(error)
+					});
+				}
 				markStatus("running");
 			}
 		};
+		state.session = session;
 		this.register(session);
 		return session;
 	}
@@ -894,7 +966,23 @@ function nextAvailableDockId(views, baseId) {
 	return `${baseId}-${n}`;
 }
 /**
-* Framework-neutral primitive backing {@link DevframeHubContext.install} —
+* When a dock's `clientScript.importFrom` is an absolute filesystem path, serve
+* its directory under `<base>__page-script/` and rewrite `importFrom` to that
+* URL. A URL or bare specifier (not existing on disk) passes through untouched.
+*/
+async function resolvePageScriptClientScript(ctx, clientScript, base) {
+	if (!clientScript?.importFrom) return clientScript;
+	const { importFrom } = clientScript;
+	if (!isAbsolute(importFrom) || !existsSync(importFrom)) return clientScript;
+	const scriptBase = withTrailingSlash(joinURL(base, "__page-script"));
+	await ctx.host.mountStatic(scriptBase, dirname(importFrom));
+	return {
+		...clientScript,
+		importFrom: joinURL(scriptBase, basename(importFrom))
+	};
+}
+/**
+* Framework-neutral primitive backing {@link DevframeHubContext.install} -
 * installs a {@link DevframeDefinition} as a dock inside a hub-aware context:
 * serves the devframe's SPA at the resolved base path, synthesizes an iframe
 * dock entry from the definition's metadata, and runs the definition's
@@ -902,20 +990,35 @@ function nextAvailableDockId(views, baseId) {
 * calling it directly.
 *
 * Framework kits wrap `ctx.install` with their own plugin/middleware
-* machinery — e.g. `@vitejs/devtools-kit`'s `createPluginFromDevframe`
+* machinery, e.g. `@vitejs/devtools-kit`'s `createPluginFromDevframe`
 * returns a Vite `Plugin` whose `devtools.setup` ultimately delegates here.
 */
 /**
 * Phase one of an install: run the duplication guard, serve the SPA + meta,
 * register the iframe dock, and queue the definition's declarative wire
-* services — everything up to (but not including) `setup(ctx)`. Returns a
+* services, everything up to (but not including) `setup(ctx)`. Returns a
 * deferred setup thunk, or `null` when the devframe was deduplicated.
 *
 * The hub's initial batch uses this to collect every devframe's services
-* across the whole hub, `ready()` them once, and only then run the setups —
+* across the whole hub, `ready()` them once, and only then run the setups,
 * so services are ready before any setup, and a plugin can consume a service
 * another plugin declared regardless of mount order.
 */
+/**
+* Serve a devframe's SPA (and the hub's connection meta) under `base`, if the
+* definition ships client assets.
+*/
+async function serveDevframeAssets(ctx, d, id, base) {
+	const clientAssets = resolveClientAssets(d);
+	if (!clientAssets) return;
+	if (ctx.host.mountConnectionMeta) await ctx.host.mountConnectionMeta(base);
+	else diagnostics.DF8106({
+		id,
+		name: d.name,
+		base
+	});
+	ctx.views.hostStatic(base, typeof clientAssets === "string" ? resolve(clientAssets) : clientAssets, d.importMetaUrl);
+}
 async function prepareDevframe(ctx, d, options = {}) {
 	const strategy = d.duplicationStrategy ?? "warn";
 	const isDuplicate = ctx.docks.views.has(d.id);
@@ -936,23 +1039,18 @@ async function prepareDevframe(ctx, d, options = {}) {
 		id,
 		basePath: void 0
 	}, "hosted"));
-	const clientAssets = resolveClientAssets(d);
-	if (clientAssets) {
-		if (ctx.host.mountConnectionMeta) await ctx.host.mountConnectionMeta(base);
-		else diagnostics.DF8106({
-			id,
-			name: d.name,
-			base
-		});
-		const distSource = clientAssets;
-		ctx.views.hostStatic(base, typeof distSource === "string" ? resolve(distSource) : distSource, d.importMetaUrl);
-	}
+	const dockDefaults = {
+		...d.dock,
+		...options.dock
+	};
+	const clientScript = await resolvePageScriptClientScript(ctx, dockDefaults.clientScript, base);
+	if (clientScript) dockDefaults.clientScript = clientScript;
+	await serveDevframeAssets(ctx, d, id, base);
 	ctx.docks.register({
 		id,
 		title: d.name,
 		icon: d.icon,
-		...d.dock,
-		...options.dock,
+		...dockDefaults,
 		type: "iframe",
 		url: base
 	});
@@ -960,7 +1058,7 @@ async function prepareDevframe(ctx, d, options = {}) {
 	return () => Promise.resolve(d.setup(ctx));
 }
 /**
-* Install a {@link DevframeDefinition} into a hub in one call — serve its SPA,
+* Install a {@link DevframeDefinition} into a hub in one call: serve its SPA,
 * register its dock, ready its services, and run `setup(ctx)`. The imperative
 * counterpart to the hub's declarative `devframes` list (which batches the
 * phases via {@link prepareDevframe}); use it from `configure(ctx)` or
@@ -996,7 +1094,7 @@ function resolveControllableSession(sessions, id) {
 	return session;
 }
 /**
-* `hub:commands:execute` — Invoke a registered server command by id. The
+* `hub:commands:execute`: Invoke a registered server command by id. The
 * arguments after `id` are forwarded to the command's `handler(...)`.
 * Returns whatever the handler returns.
 *
@@ -1011,7 +1109,7 @@ const hubCommandsExecute = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:messages:add` — Add a message from a browser client into the hub's
+* `hub:messages:add`: Add a message from a browser client into the hub's
 * messages subsystem. Marked `from: 'browser'`. Returns the serializable
 * entry (the mutation handle stays server-side).
 *
@@ -1030,7 +1128,7 @@ const hubMessagesAdd = defineHubRpcFunction({
 		})).entry;
 	} })
 });
-/** `hub:messages:update` — Patch a message by id; returns the updated entry (or `undefined`). */
+/** `hub:messages:update`: Patch a message by id; returns the updated entry (or `undefined`). */
 const hubMessagesUpdate = defineHubRpcFunction({
 	name: HUB_EVENTS.rpc.messagesUpdate,
 	type: "action",
@@ -1039,7 +1137,7 @@ const hubMessagesUpdate = defineHubRpcFunction({
 		return context.messages.update(id, patch);
 	} })
 });
-/** `hub:messages:remove` — Remove a message by id. */
+/** `hub:messages:remove`: Remove a message by id. */
 const hubMessagesRemove = defineHubRpcFunction({
 	name: HUB_EVENTS.rpc.messagesRemove,
 	type: "action",
@@ -1047,7 +1145,7 @@ const hubMessagesRemove = defineHubRpcFunction({
 		await context.messages.remove(id);
 	} })
 });
-/** `hub:messages:clear` — Remove every message. */
+/** `hub:messages:clear`: Remove every message. */
 const hubMessagesClear = defineHubRpcFunction({
 	name: HUB_EVENTS.rpc.messagesClear,
 	type: "action",
@@ -1056,7 +1154,7 @@ const hubMessagesClear = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:terminals:write` — Send input to an interactive PTY session spawned
+* `hub:terminals:write`: Send input to an interactive PTY session spawned
 * via `ctx.terminals.startPtySession`. Lets a hub-aware terminal UI (e.g. the
 * terminals plugin) drive a session owned by another plugin.
 */
@@ -1067,7 +1165,7 @@ const hubTerminalsWrite = defineHubRpcFunction({
 		resolveInteractiveSession(context.terminals.sessions, id).write(data);
 	} })
 });
-/** `hub:terminals:resize` — Resize an interactive PTY session by id. */
+/** `hub:terminals:resize`: Resize an interactive PTY session by id. */
 const hubTerminalsResize = defineHubRpcFunction({
 	name: HUB_EVENTS.rpc.terminalsResize,
 	type: "action",
@@ -1076,7 +1174,7 @@ const hubTerminalsResize = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:terminals:terminate` — Kill a session's process while keeping the
+* `hub:terminals:terminate`: Kill a session's process while keeping the
 * session registered (its output/scrollback stays). Works for both read-only
 * child-process and interactive PTY sessions, letting a hub-aware terminal UI
 * force-kill a session owned by another plugin.
@@ -1089,7 +1187,7 @@ const hubTerminalsTerminate = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:terminals:restart` — Re-run a session's command in place. Rejected for
+* `hub:terminals:restart`: Re-run a session's command in place. Rejected for
 * sessions registered with `restartable: false`, whose lifecycle is owned
 * elsewhere.
 */
@@ -1103,7 +1201,7 @@ const hubTerminalsRestart = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:terminals:remove` — Kill a session's process (when it still owns one)
+* `hub:terminals:remove`: Kill a session's process (when it still owns one)
 * and drop it from the registry, disposing its output stream. Lets a hub-aware
 * terminal UI discard a stopped aggregated session.
 */
@@ -1119,13 +1217,13 @@ const hubTerminalsRemove = defineHubRpcFunction({
 	} })
 });
 /**
-* `hub:docks:activate` — Ask the active viewer to switch its focused dock to
+* `hub:docks:activate`: Ask the active viewer to switch its focused dock to
 * `dockId`, optionally carrying `params` for the target dock to interpret
 * (e.g. `{ sessionId }` for the terminals dock to focus a session).
 *
 * Any connected client may call it, which is the point: a mounted devframe
 * running in its own iframe (on its own RPC client) can steer the host shell's
-* dock selection — client-local state it otherwise can't reach. The hub
+* dock selection, client-local state it otherwise can't reach. The hub
 * broadcasts the request live to connected clients (the host shell switches)
 * and mirrors it into the `devframe:docks:active` shared state (a dock that
 * mounts in response still converges on it).