@devframes/hub 0.9.8 → 0.9.9

package/dist/{constants-DJrPlLi0.d.mts → constants-Coo1p3ja.d.mts}

@@ -1,8 +1,8 @@
-import { t as DevframeDocksUserSettings } from "./settings-DwxCyeI6.mjs";
+import { t as DevframeDocksUserSettings } from "./settings-CWHPzCWS.mjs";
 //#region src/events.d.ts
 /**
  * Centralized registry of every event, broadcast, RPC method, shared-state
- * key, and channel name the hub uses — the single source of truth that keeps
+ * key, and channel name the hub uses: the single source of truth that keeps
  * these names out of scattered string literals.
  *
  * **Keep this in sync with [`docs/content/8.references/3.events.md`](../../../docs/content/8.references/3.events.md)**
@@ -75,7 +75,7 @@ declare const HUB_EVENTS: {
 };
 //#endregion
 //#region src/constants.d.ts
-/** Default mount base for a hub instance — one namespace, one catch-all. */
+/** Default mount base for a hub instance: one namespace, one catch-all. */
 declare const DEVFRAMES_HUB_BASE = "/__devframes/";
 /**
  * Normalize a hub mount base to an absolute path with leading and trailing
@@ -86,7 +86,7 @@ declare const DEVFRAMES_HUB_BASE = "/__devframes/";
  */
 declare function normalizeHubBase(base: string): string;
 /**
- * The default ordering weight for each known dock category — lower sorts
+ * The default ordering weight for each known dock category, where lower sorts
  * earlier. Downstream viewers (e.g. `@vitejs/devtools-kit`) import this as the
  * single source of truth so the hub and its viewers agree on category order.
  * `framework` sorts first; `~builtin` (the viewer's own built-in views) last.
@@ -97,7 +97,7 @@ declare function normalizeHubBase(base: string): string;
  */
 declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
 /**
- * Shared-state slot carrying the hub's renderer manifest — one
+ * Shared-state slot carrying the hub's renderer manifest: one
  * {@link import('./client/renderers').DockRendererManifest} entry per dock
  * `type`, published by `initHub({ renderers })` and consumed by every
  * hub-aware client (the headless client host and viewers alike).

package/dist/constants.d.mts

@@ -1,3 +1,3 @@
-import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-DJrPlLi0.mjs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-Coo1p3ja.mjs";
 export * from "devframe/constants";
 export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS, normalizeHubBase };

package/dist/constants.mjs

@@ -1,3 +1,3 @@
-import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-D1zicoJ4.mjs";
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY, n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS, r as DEVFRAMES_HUB_BASE, t as DEFAULT_CATEGORIES_ORDER } from "./constants-BUd6oMci.mjs";
 export * from "devframe/constants";
 export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS, normalizeHubBase };

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

@@ -1,6 +1,6 @@
 import { r as defineHubRpcFunction } from "./define-Ceekw2EO.mjs";
-import { n as DEFAULT_STATE_USER_SETTINGS, o as HUB_EVENTS } from "./constants-D1zicoJ4.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";
@@ -13,24 +13,39 @@ import { nanoid } from "devframe/utils/nanoid";
 import process from "node:process";
 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`,
@@ -57,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}"`,
@@ -73,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` },
@@ -89,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` },
@@ -145,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;
@@ -223,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() {
@@ -236,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);
@@ -266,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()
 		}) });
@@ -326,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
@@ -380,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;
@@ -561,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.
 	*/
@@ -571,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);
@@ -592,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();
@@ -602,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;
@@ -634,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();
@@ -701,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;
@@ -739,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");
@@ -750,7 +785,7 @@ var DevframeTerminalsHost = class {
 			closeStream();
 			markStatus("stopped");
 		};
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			stream,
@@ -761,6 +796,7 @@ var DevframeTerminalsHost = class {
 			terminate,
 			restart
 		};
+		state.session = session;
 		this.register(session);
 		return Promise.resolve(session);
 	}
@@ -769,35 +805,14 @@ 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() {
 				killCurrentRun?.();
@@ -842,7 +857,7 @@ var DevframeTerminalsHost = class {
 			ptyProcess.onData((data) => {
 				const text = typeof data === "string" ? data : data.toString("utf8");
 				outputChunks.push(text);
-				if (!streamClosed && currentRun === runId) controller?.enqueue(text);
+				if (!state.streamClosed && currentRun === runId) state.controller?.enqueue(text);
 			});
 			ptyProcess.onExit(({ exitCode, signal }) => {
 				settle(exitCode, signal);
@@ -882,7 +897,7 @@ var DevframeTerminalsHost = class {
 				reason: error instanceof Error ? error.message : String(error)
 			});
 		}
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			interactive: true,
@@ -915,7 +930,7 @@ var DevframeTerminalsHost = class {
 				markStatus("stopped");
 			},
 			restart: async () => {
-				if (streamClosed) throw diagnostics.DF8206({ id: terminal.id });
+				if (state.streamClosed) throw diagnostics.DF8206({ id: terminal.id });
 				killCurrentRun?.();
 				killCurrentRun = void 0;
 				pty = void 0;
@@ -931,6 +946,7 @@ var DevframeTerminalsHost = class {
 				markStatus("running");
 			}
 		};
+		state.session = session;
 		this.register(session);
 		return session;
 	}
@@ -966,7 +982,7 @@ async function resolvePageScriptClientScript(ctx, clientScript, base) {
 	};
 }
 /**
-* Framework-neutral primitive backing {@link DevframeHubContext.install} —
+* 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
@@ -974,20 +990,35 @@ async function resolvePageScriptClientScript(ctx, clientScript, base) {
 * 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);
@@ -1014,17 +1045,7 @@ async function prepareDevframe(ctx, d, options = {}) {
 	};
 	const clientScript = await resolvePageScriptClientScript(ctx, dockDefaults.clientScript, base);
 	if (clientScript) dockDefaults.clientScript = clientScript;
-	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);
-	}
+	await serveDevframeAssets(ctx, d, id, base);
 	ctx.docks.register({
 		id,
 		title: d.name,
@@ -1037,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
@@ -1073,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.
 *
@@ -1088,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).
 *
@@ -1107,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",
@@ -1116,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",
@@ -1124,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",
@@ -1133,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.
 */
@@ -1144,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",
@@ -1153,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.
@@ -1166,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.
 */
@@ -1180,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.
 */
@@ -1196,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).