@devframes/hub 0.9.8 → 0.9.10

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

@@ -1,36 +1,55 @@
 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-Da23JxCZ.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 { existsSync } from "node:fs";
+import process from "node:process";
 import { coerceAgentPositionalArgs, resolveClientAssets } from "devframe/internal";
-import { defineDiagnostics } from "devframe/utils/nostics";
 import { basename, dirname, isAbsolute, join, resolve } from "pathe";
+import { defineDiagnostics } from "devframe/utils/nostics";
+import { getInternalContext, resolveBasePath } from "devframe/node/hub-internals";
+import { createHostContext, createStorage } from "devframe/node";
+import { debounce } from "perfect-debounce";
 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 (\`mcp: false\`), 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. Drop `mcp: false` from `initHub` (the `'auto'` default mounts the aggregate route once agent tools exist) to surface this devframe's tools, or drop `mcp` from the devframe to silence this warning."
+		},
+		DF8006: {
+			why: (p) => `A static hub build can only write mounts under its own base: "${p.urlBase}" escapes "${p.base}".`,
+			fix: "buildHub maps each mount base to a directory under its `outDir`, so every mount must live under the hub base. Drop the `basePath` override (or the `ctx.install` base) that points outside it, or move the hub `base` up so it contains the mount."
 		},
 		DF8100: {
 			why: (p) => `Dock with id "${p.id}" is already registered`,
@@ -57,12 +76,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 +92,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 +108,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` },
@@ -113,6 +132,134 @@ const diagnostics = defineDiagnostics({
 	}
 });
 //#endregion
+//#region src/node/install-devframe.ts
+/**
+* Find the next free dock id derived from `baseId`. Returns `baseId`
+* when it is unused, otherwise appends `-2`, `-3`, … until a free slot
+* is found. Used by the `'duplicate'` strategy so co-existing instances
+* never collide in the dock registry.
+*/
+function nextAvailableDockId(views, baseId) {
+	if (!views.has(baseId)) return baseId;
+	let n = 2;
+	while (views.has(`${baseId}-${n}`)) n++;
+	return `${baseId}-${n}`;
+}
+/**
+* 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
+* `setup(ctx)`. Reach for it through `ctx.install(devframe)` rather than
+* calling it directly.
+*
+* Framework kits wrap `ctx.install` with their own plugin/middleware
+* 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
+* 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,
+* 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);
+}
+/**
+* Whether a devframe stays out of a static hub build: `capabilities.build:
+* false` declares its value inherently live (a terminal, a process proxy),
+* so `buildHub` never mounts it, registers its dock, or bakes its RPCs.
+*/
+function skippedInStaticBuild(ctx, d) {
+	return ctx.mode === "build" && d.capabilities?.build === false;
+}
+async function prepareDevframe(ctx, d, options = {}) {
+	if (skippedInStaticBuild(ctx, d)) return null;
+	const strategy = d.duplicationStrategy ?? "warn";
+	const isDuplicate = ctx.docks.views.has(d.id);
+	if (isDuplicate && strategy !== "duplicate") {
+		if (strategy === "throw") throw diagnostics.DF8105({
+			id: d.id,
+			name: d.name
+		});
+		if (strategy === "warn") diagnostics.DF8105({
+			id: d.id,
+			name: d.name
+		});
+		return null;
+	}
+	const id = isDuplicate ? nextAvailableDockId(ctx.docks.views, d.id) : d.id;
+	const base = options.base ?? (id === d.id ? resolveBasePath(d, "hosted") : resolveBasePath({
+		...d,
+		id,
+		basePath: void 0
+	}, "hosted"));
+	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,
+		...dockDefaults,
+		type: "iframe",
+		url: base
+	});
+	for (const input of d.services ?? []) ctx.services.install(input, { resolveFrom: d.importMetaUrl });
+	return () => Promise.resolve(d.setup(ctx));
+}
+/**
+* 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
+* wherever you hold the context to plug in an extra devframe after startup.
+*/
+async function installDevframe(ctx, d, options = {}) {
+	const run = await prepareDevframe(ctx, d, options);
+	if (!run) return;
+	await ctx.services.ready();
+	await run();
+}
+//#endregion
 //#region src/node/host-commands.ts
 function findChildCommand(command, id) {
 	for (const child of command.children ?? []) {
@@ -145,7 +292,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 +370,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 +383,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 +418,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 +479,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 +533,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 +714,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 +724,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 +780,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 +809,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 +822,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 +868,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 +906,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 +917,7 @@ var DevframeTerminalsHost = class {
 			closeStream();
 			markStatus("stopped");
 		};
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			stream,
@@ -761,6 +928,7 @@ var DevframeTerminalsHost = class {
 			terminate,
 			restart
 		};
+		state.session = session;
 		this.register(session);
 		return Promise.resolve(session);
 	}
@@ -769,35 +937,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 +989,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 +1029,7 @@ var DevframeTerminalsHost = class {
 				reason: error instanceof Error ? error.message : String(error)
 			});
 		}
-		session = {
+		const session = {
 			...terminal,
 			status: "running",
 			interactive: true,
@@ -915,7 +1062,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,125 +1078,12 @@ var DevframeTerminalsHost = class {
 				markStatus("running");
 			}
 		};
+		state.session = session;
 		this.register(session);
 		return session;
 	}
 };
 //#endregion
-//#region src/node/install-devframe.ts
-/**
-* Find the next free dock id derived from `baseId`. Returns `baseId`
-* when it is unused, otherwise appends `-2`, `-3`, … until a free slot
-* is found. Used by the `'duplicate'` strategy so co-existing instances
-* never collide in the dock registry.
-*/
-function nextAvailableDockId(views, baseId) {
-	if (!views.has(baseId)) return baseId;
-	let n = 2;
-	while (views.has(`${baseId}-${n}`)) n++;
-	return `${baseId}-${n}`;
-}
-/**
-* 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
-* `setup(ctx)`. Reach for it through `ctx.install(devframe)` rather than
-* calling it directly.
-*
-* Framework kits wrap `ctx.install` with their own plugin/middleware
-* 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
-* 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 —
-* so services are ready before any setup, and a plugin can consume a service
-* another plugin declared regardless of mount order.
-*/
-async function prepareDevframe(ctx, d, options = {}) {
-	const strategy = d.duplicationStrategy ?? "warn";
-	const isDuplicate = ctx.docks.views.has(d.id);
-	if (isDuplicate && strategy !== "duplicate") {
-		if (strategy === "throw") throw diagnostics.DF8105({
-			id: d.id,
-			name: d.name
-		});
-		if (strategy === "warn") diagnostics.DF8105({
-			id: d.id,
-			name: d.name
-		});
-		return null;
-	}
-	const id = isDuplicate ? nextAvailableDockId(ctx.docks.views, d.id) : d.id;
-	const base = options.base ?? (id === d.id ? resolveBasePath(d, "hosted") : resolveBasePath({
-		...d,
-		id,
-		basePath: void 0
-	}, "hosted"));
-	const dockDefaults = {
-		...d.dock,
-		...options.dock
-	};
-	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);
-	}
-	ctx.docks.register({
-		id,
-		title: d.name,
-		icon: d.icon,
-		...dockDefaults,
-		type: "iframe",
-		url: base
-	});
-	for (const input of d.services ?? []) ctx.services.install(input, { resolveFrom: d.importMetaUrl });
-	return () => Promise.resolve(d.setup(ctx));
-}
-/**
-* 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
-* wherever you hold the context to plug in an extra devframe after startup.
-*/
-async function installDevframe(ctx, d, options = {}) {
-	const run = await prepareDevframe(ctx, d, options);
-	if (!run) return;
-	await ctx.services.ready();
-	await run();
-}
-//#endregion
 //#region src/node/rpc-builtins.ts
 /**
 * Resolve an interactive (PTY) terminal session by id, or throw. Sessions
@@ -1073,7 +1107,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 +1122,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 +1141,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 +1150,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 +1158,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 +1167,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 +1178,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 +1187,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 +1200,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 +1214,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 +1230,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).
@@ -1303,4 +1337,4 @@ async function createHubContext(options) {
 	return context;
 }
 //#endregion
-export { DevframeDocksHost as _, hubMessagesAdd as a, hubMessagesUpdate as c, hubTerminalsRestart as d, hubTerminalsTerminate as f, DevframeMessagesHost as g, DevframeTerminalsHost as h, hubDocksActivate as i, hubTerminalsRemove as l, prepareDevframe as m, builtinHubRpcDeclarations as n, hubMessagesClear as o, hubTerminalsWrite as p, hubCommandsExecute as r, hubMessagesRemove as s, createHubContext as t, hubTerminalsResize as u, DevframeCommandsHost as v, diagnostics as y };
+export { DevframeCommandsHost as _, hubMessagesAdd as a, diagnostics as b, hubMessagesUpdate as c, hubTerminalsRestart as d, hubTerminalsTerminate as f, DevframeDocksHost as g, DevframeMessagesHost as h, hubDocksActivate as i, hubTerminalsRemove as l, DevframeTerminalsHost as m, builtinHubRpcDeclarations as n, hubMessagesClear as o, hubTerminalsWrite as p, hubCommandsExecute as r, hubMessagesRemove as s, createHubContext as t, hubTerminalsResize as u, prepareDevframe as v, skippedInStaticBuild as y };