@devframes/hub 0.9.8 → 0.9.10

package/dist/{context-BJFGlcf8.d.mts → context-Di-fhMKP.d.mts}

@@ -1,4 +1,4 @@
-import { A as DevframeViewIframe, T as DevframeDocksHost, b as DevframeDockEntryIcon, l as DevframeCommandsHost, m as DevframeDockActivation } from "./settings-DwxCyeI6.mjs";
+import { A as DevframeViewIframe, T as DevframeDocksHost, b as DevframeDockEntryIcon, l as DevframeCommandsHost, m as DevframeDockActivation } from "./settings-CWHPzCWS.mjs";
 import { CreateHostContextOptions } from "devframe/node";
 import { DevframeDefinition, DevframeHost, DevframeNodeContext, EventEmitter } from "devframe/types";
 import { ChildProcess } from "node:child_process";
@@ -154,13 +154,13 @@ interface DevframeMessageHandle {
   dismiss: () => Promise<void>;
 }
 /**
- * Extra fields accepted by the per-level message shortcuts —
+ * Extra fields accepted by the per-level message shortcuts:
  * everything on {@link DevframeMessageEntryInput} except the
  * `message` and `level` the shortcut itself provides.
  */
 type DevframeMessageShortcutInput = Omit<DevframeMessageEntryInput, 'message' | 'level'>;
 /**
- * Per-level shortcuts shared by the client and the node host —
+ * Per-level shortcuts shared by the client and the node host:
  * `messages.info('...')` is `messages.add({ message: '...', level: 'info' })`.
  */
 interface DevframeMessagesLevelShortcuts {
@@ -197,7 +197,7 @@ interface DevframeMessagesListDelta {
   entries: DevframeMessageEntry[];
   /** Ids removed since the cursor (empty when `full`) */
   removedIds: string[];
-  /** The version cursor — pass back as `since` on the next call */
+  /** The version cursor; pass back as `since` on the next call */
   version: number;
   /**
    * When `true`, `entries` is the complete snapshot and any locally cached
@@ -262,7 +262,7 @@ interface DevframeTerminalsHost {
    * {@link DevframePtyTerminalSession.resize}, TUI-capable. The session is
    * marked `interactive`, so a hub-aware terminal UI (e.g. the terminals
    * plugin) surfaces it as writable rather than read-only. Powered by
-   * `zigpty` — where its native bindings can't load, it degrades to
+   * `zigpty`; where its native bindings can't load, it degrades to
    * pipe-based terminal emulation.
    */
   startPtySession: (executeOptions: DevframePtyExecuteOptions, terminal: Omit<DevframeTerminalSessionBase, 'status'>) => Promise<DevframePtyTerminalSession>;
@@ -284,7 +284,7 @@ interface DevframeTerminalSessionBase {
   /**
    * Whether the session may be restarted in place (re-running its command).
    * Defaults to `true`. Set `false` for sessions whose lifecycle is owned
-   * elsewhere — e.g. a one-shot build, or a server (like code-server) that
+   * elsewhere, e.g. a one-shot build, or a server (like code-server) that
    * should be restarted through its own controls rather than by re-spawning
    * the raw process. A hub-aware terminal UI hides its restart affordance for
    * these, and `hub:terminals:restart` rejects them.
@@ -302,7 +302,7 @@ interface DevframeChildProcessExecuteOptions {
   env?: Record<string, string>;
 }
 /**
- * The settled outcome of a {@link DevframeChildProcessTerminalSession} run —
+ * The settled outcome of a {@link DevframeChildProcessTerminalSession} run:
  * stdout/stderr captured separately (unlike the session's merged display
  * `stream`), plus the process's exit code (`undefined` if it was killed by a
  * signal before exiting).
@@ -313,7 +313,7 @@ interface DevframeChildProcessOutput {
   exitCode: number | undefined;
 }
 /**
- * A live handle on a child process's outcome — mirrors the ergonomics of
+ * A live handle on a child process's outcome, mirroring the ergonomics of
  * `tinyexec`'s `Result` (a promise-like paired with synchronous accessors) so
  * callers migrating from a `tinyexec`/`execa`-based subprocess API (e.g.
  * Nuxt DevTools' `startSubprocess().getResult()`) can adopt
@@ -334,11 +334,11 @@ interface DevframeChildProcessTerminalSession extends DevframeTerminalSession {
   getChildProcess: () => ChildProcess | undefined;
   /**
    * Get a live handle on the current run's outcome. Reflects the most recent
-   * `restart()` — call it again after restarting to track the new run.
+   * `restart()`; call it again after restarting to track the new run.
    */
   getResult: () => DevframeChildProcessResult;
   terminate: () => Promise<void>;
-  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`) — drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
+  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`); drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
   restart: () => Promise<void>;
 }
 interface DevframePtyExecuteOptions {
@@ -384,7 +384,7 @@ interface DevframePtyTerminalSession extends DevframeTerminalSession {
    */
   getResult: () => DevframePtyResult;
   terminate: () => Promise<void>;
-  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`) — drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
+  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`); drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
   restart: () => Promise<void>;
 }
 //#endregion
@@ -399,7 +399,7 @@ interface InstallDevframeOptions {
    * this to customize the entry's `category`, override the icon, hide it
    * via `when` (or only its dock-bar button via `visibility`), etc. Takes
    * precedence over the definition's own {@link DevframeDefinition.dock}
-   * defaults. Cannot change `id`, `type`, or `url` — those are derived from
+   * defaults. Cannot change `id`, `type`, or `url`, which are derived from
    * the devframe definition.
    */
   dock?: Partial<Omit<DevframeViewIframe, 'id' | 'type' | 'url'>>;
@@ -441,7 +441,7 @@ declare module 'devframe/types' {
      * 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). Any connected client may call
-     * it — a mounted devframe in its own iframe steers the host shell's dock
+     * it, so a mounted devframe in its own iframe steers the host shell's dock
      * selection. Handled by {@link import('./rpc-builtins').hubDocksActivate}.
      */
     'hub:docks:activate': (input: {
@@ -477,7 +477,7 @@ declare module 'devframe/types' {
   }
 }
 /**
- * Hub-augmented node context — extends devframe's framework-neutral
+ * Hub-augmented node context that extends devframe's framework-neutral
  * `DevframeNodeContext` with the hub-level subsystems (`docks`,
  * `terminals`, `messages`, `commands`).
  *
@@ -486,7 +486,7 @@ declare module 'devframe/types' {
  * filesystem reveal, etc.) ship as kit-registered RPC functions rather
  * than as part of this surface. JSON-render is an opt-in integration
  * (`@devframes/json-render`) that augments any devframe context and
- * contributes its own dock type — use `createJsonRenderView` from
+ * contributes its own dock type; use `createJsonRenderView` from
  * `@devframes/json-render/node`.
  */
 interface DevframeHubContext extends DevframeNodeContext {
@@ -499,13 +499,13 @@ interface DevframeHubContext extends DevframeNodeContext {
    * Install a {@link DevframeDefinition} into this hub: serve its SPA at the
    * resolved base, synthesize an iframe dock from its metadata, and run its
    * `setup(ctx)`. The imperative counterpart to `initHub`'s declarative
-   * `devframes` list — call it from a hub host's `configure(ctx)`, or wherever
+   * `devframes` list. Call it from a hub host's `configure(ctx)`, or wherever
    * you hold the context, to plug an extra devframe in.
    */
   install: (devframe: DevframeDefinition, options?: InstallDevframeOptions) => Promise<void>;
 }
 /**
- * Options for {@link createHubContext} — devframe's
+ * Options for {@link createHubContext}: devframe's
  * {@link CreateHostContextOptions} plus any hub-level additions kits layer on
  * through declaration merging.
  */

package/dist/{index-OpSX0dK5.d.mts → index-faD2d5iX.d.mts}

@@ -1,5 +1,5 @@
-import "./context-BJFGlcf8.mjs";
-import "./settings-DwxCyeI6.mjs";
+import "./context-Di-fhMKP.mjs";
+import "./settings-CWHPzCWS.mjs";
 import { RpcDefinitionsFilter, RpcDefinitionsToFunctions } from "devframe/rpc";
 import { ConnectionMeta as ConnectionMeta$1, DevframeCapabilities, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeHost as DevframeHost$1, DevframeNodeRpcSession, DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeViewHost, EventEmitter as EventEmitter$1, EventUnsubscribe, EventsMap, RpcBroadcastOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost } from "devframe/types";
 export { RpcStreamingHost as S, RpcFunctionsHost as _, DevframeHost$1 as a, RpcStreamingChannel as b, DevframeRpcServerFunctions as c, EventEmitter$1 as d, EventUnsubscribe as f, RpcDefinitionsToFunctions as g, RpcDefinitionsFilter as h, DevframeDiagnosticsLogger as i, DevframeRpcSharedStates as l, RpcBroadcastOptions as m, DevframeCapabilities as n, DevframeNodeRpcSession as o, EventsMap as p, DevframeDiagnosticsHost as r, DevframeRpcClientFunctions as s, ConnectionMeta$1 as t, DevframeViewHost as u, RpcSharedStateGetOptions as v, RpcStreamingChannelOptions as x, RpcSharedStateHost as y };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { A as DevframeMessagesLevelShortcuts, C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, E as DevframeMessageLevel, O as DevframeMessagesClient, S as DevframeMessageEntryFrom, T as DevframeMessageHandle, _ as DevframeMessageAction, a as DevframeChildProcessExecuteOptions, b as DevframeMessageElementPosition, c as DevframeChildProcessTerminalSession, d as DevframePtyResult, f as DevframePtyTerminalSession, g as DevframeTerminalsHost, h as DevframeTerminalStatus, j as DevframeMessagesListDelta, k as DevframeMessagesHost, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, o as DevframeChildProcessOutput, p as DevframeTerminalSession, s as DevframeChildProcessResult, t as CreateHubContextOptions, u as DevframePtyOutput, v as DevframeMessageActivateAction, w as DevframeMessageFilePosition, x as DevframeMessageEntry, y as DevframeMessageCommandAction } from "./context-BJFGlcf8.mjs";
-import { A as DevframeViewIframe, C as DevframeDockUserEntry, D as DevframeViewBuiltin, E as DevframeViewAction, F as RemoteConnectionInfo, I as RemoteDockOptions, M as DevframeViewLauncherStatus, N as FrameSubTabsConfig, O as DevframeViewCustomRender, P as NavTarget, S as DevframeDockPanelState, T as DevframeDocksHost, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncher, k as DevframeViewGroup, l as DevframeCommandsHost, m as DevframeDockActivation, n as DevframeClientCommand, o as DevframeCommandHandle, p as ClientScriptEntry, r as DevframeCommandAgentOptions, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, u as DevframeCommandsHostEvents, v as DevframeDockEntryBase, w as DevframeDocksActiveState, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "./settings-DwxCyeI6.mjs";
-import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "./index-OpSX0dK5.mjs";
+import { A as DevframeMessagesLevelShortcuts, C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, E as DevframeMessageLevel, O as DevframeMessagesClient, S as DevframeMessageEntryFrom, T as DevframeMessageHandle, _ as DevframeMessageAction, a as DevframeChildProcessExecuteOptions, b as DevframeMessageElementPosition, c as DevframeChildProcessTerminalSession, d as DevframePtyResult, f as DevframePtyTerminalSession, g as DevframeTerminalsHost, h as DevframeTerminalStatus, j as DevframeMessagesListDelta, k as DevframeMessagesHost, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, o as DevframeChildProcessOutput, p as DevframeTerminalSession, s as DevframeChildProcessResult, t as CreateHubContextOptions, u as DevframePtyOutput, v as DevframeMessageActivateAction, w as DevframeMessageFilePosition, x as DevframeMessageEntry, y as DevframeMessageCommandAction } from "./context-Di-fhMKP.mjs";
+import { A as DevframeViewIframe, C as DevframeDockUserEntry, D as DevframeViewBuiltin, E as DevframeViewAction, F as RemoteConnectionInfo, I as RemoteDockOptions, M as DevframeViewLauncherStatus, N as FrameSubTabsConfig, O as DevframeViewCustomRender, P as NavTarget, S as DevframeDockPanelState, T as DevframeDocksHost, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, c as DevframeCommandShortcutOverrides, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, g as DevframeDockEntriesGrouped, h as DevframeDockBadgeVariant, i as DevframeCommandBase, j as DevframeViewLauncher, k as DevframeViewGroup, l as DevframeCommandsHost, m as DevframeDockActivation, n as DevframeClientCommand, o as DevframeCommandHandle, p as ClientScriptEntry, r as DevframeCommandAgentOptions, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, u as DevframeCommandsHostEvents, v as DevframeDockEntryBase, w as DevframeDocksActiveState, x as DevframeDockEntryRegistry, y as DevframeDockEntryCategory } from "./settings-CWHPzCWS.mjs";
+import { S as RpcStreamingHost, _ as RpcFunctionsHost, a as DevframeHost, b as RpcStreamingChannel, c as DevframeRpcServerFunctions, d as EventEmitter, f as EventUnsubscribe, g as RpcDefinitionsToFunctions, h as RpcDefinitionsFilter, i as DevframeDiagnosticsLogger, l as DevframeRpcSharedStates, m as RpcBroadcastOptions, n as DevframeCapabilities, o as DevframeNodeRpcSession, p as EventsMap, r as DevframeDiagnosticsHost, s as DevframeRpcClientFunctions, t as ConnectionMeta, u as DevframeViewHost, v as RpcSharedStateGetOptions, x as RpcStreamingChannelOptions, y as RpcSharedStateHost } from "./index-faD2d5iX.mjs";
 import { WhenContext, WhenExpression } from "devframe/utils/when";
 //#region src/define.d.ts
 declare const defineHubRpcFunction: <NAME extends string, TYPE extends import("devframe/rpc").RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends import("devframe/rpc").RpcArgsSchema | undefined = undefined, const RS extends import("devframe/rpc").RpcReturnSchema | undefined = undefined>(definition: import("devframe/rpc").RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeHubContext>) => import("devframe/rpc").RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeHubContext>;

package/dist/node/build.d.mts

@@ -0,0 +1,74 @@
+import { n as DevframeHubContext, t as CreateHubContextOptions } from "../context-Di-fhMKP.mjs";
+import { DevframeHubUi, DevframesInput, DockRendererRegistration } from "./initiate.mjs";
+import { DevframeServiceInput, DevframeStorageScope } from "devframe/types";
+//#region src/node/build.d.ts
+interface BuildHubOptions {
+  /**
+   * Output directory the hub subtree is written into. It corresponds to the
+   * hub {@link BuildHubOptions.base} at serve time: building with
+   * `base: '/__devframes/'` into `dist/__devframes` makes the deployed app's
+   * `dist/` servable as-is by any static file server.
+   */
+  outDir: string;
+  /**
+   * Mount base the deployed hub answers under (baked into every absolute URL
+   * the build emits: page-script rewrites, renderer modules, per-frame meta
+   * pointers). Default: `/__devframes/`.
+   */
+  base?: string;
+  /** Devframes to bake as docks, same input as `initHub({ devframes })`. */
+  devframes?: DevframesInput;
+  /** Host-level wire services, same contract as `initHub({ services })`. */
+  services?: DevframeServiceInput[];
+  /** Extra RPC declarations registered at context creation. */
+  rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations'];
+  /**
+   * Runs once the context exists and every `devframes` entry is mounted;
+   * register docks, commands, and messages surfaces here, exactly like
+   * `initHub({ configure })`. Everything it registers is baked into the
+   * static shared-state snapshot.
+   */
+  configure?: (ctx: DevframeHubContext) => void | Promise<void>;
+  /**
+   * The hub's UI slot: the viewer SPA is copied to the hub base, the
+   * `embedded.js` bootstrap next to it, and `setup(ctx)` runs so its static
+   * config (branding, dock preferences) is baked into the connection meta.
+   */
+  ui?: DevframeHubUi;
+  /** Prebuilt dock-renderer modules, copied to `<base>__renderers/<type>.mjs`. */
+  renderers?: readonly DockRendererRegistration[];
+  /** Name written into `<base>__index.json`. */
+  name?: string;
+  /** Version written into `<base>__index.json`. */
+  version?: string;
+  /** Working directory for the hub context. Default: `process.cwd()`. */
+  cwd?: string;
+  /** Override where persisted devframe state lives during the build. */
+  getStorageDir?: (scope: DevframeStorageScope) => string;
+  /** Pretty-print RPC dump JSON files. Default: `false` (minified shards). */
+  pretty?: boolean;
+}
+/**
+ * Produce a self-contained static deploy of a whole hub, the multi-devframe
+ * counterpart of devframe's `createBuild`:
+ *
+ *   - Build a `mode: 'build'` hub context and mount every devframe: each
+ *     SPA is copied to `<outDir>/<id>/`, an absolute-path page script to
+ *     `<outDir>/<id>/__page-script/`, and its `setup(ctx)` runs.
+ *   - Copy the UI slot's viewer SPA, `embedded.js`, and the renderer
+ *     modules, and write the discovery documents (`__index.json`,
+ *     `__client-imports.js`).
+ *   - Write `__connection.json` (`{ backend: 'static' }`, carrying
+ *     `ctx.staticConfig` as `configs`) at the hub base and at every frame
+ *     base (each pointing back at the hub's own meta via `baseUrl`).
+ *   - Bake the shared RPC dump under `<outDir>/__rpc-dump/`: every
+ *     `static`/`snapshot` RPC plus a snapshot of each shared-state key
+ *     (docks, commands, renderer manifest), so `createDevframeClientRuntime`
+ *     and every frame SPA boot from the dump with no live server.
+ *
+ * Reads work from the baked dump; live writes (messages, terminals,
+ * commands execution) have no server and degrade to no-ops in the clients.
+ */
+declare function buildHub(options: BuildHubOptions): Promise<void>;
+//#endregion
+export { BuildHubOptions, buildHub };

package/dist/node/build.mjs

@@ -0,0 +1,167 @@
+import { a as normalizeHubBase, i as DOCK_RENDERERS_STATE_KEY } from "../constants-Da23JxCZ.mjs";
+import { b as diagnostics, t as createHubContext } from "../context-BWaW6N53.mjs";
+import { i as resolveRendererRegistrations, n as renderClientImportsModule, r as resolveDevframesInput, t as mountDevframes } from "../assemble-Hj36CCzH.mjs";
+import { joinURL } from "ufo";
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME } from "devframe/constants";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import process from "node:process";
+import { createH3DevframeHost } from "devframe/internal";
+import { collectStaticRpcDump, writeStaticRpcDump } from "devframe/rpc/dump";
+import { colors } from "devframe/utils/colors";
+import { dirname, resolve } from "pathe";
+//#region src/node/build.ts
+/**
+* Produce a self-contained static deploy of a whole hub, the multi-devframe
+* counterpart of devframe's `createBuild`:
+*
+*   - Build a `mode: 'build'` hub context and mount every devframe: each
+*     SPA is copied to `<outDir>/<id>/`, an absolute-path page script to
+*     `<outDir>/<id>/__page-script/`, and its `setup(ctx)` runs.
+*   - Copy the UI slot's viewer SPA, `embedded.js`, and the renderer
+*     modules, and write the discovery documents (`__index.json`,
+*     `__client-imports.js`).
+*   - Write `__connection.json` (`{ backend: 'static' }`, carrying
+*     `ctx.staticConfig` as `configs`) at the hub base and at every frame
+*     base (each pointing back at the hub's own meta via `baseUrl`).
+*   - Bake the shared RPC dump under `<outDir>/__rpc-dump/`: every
+*     `static`/`snapshot` RPC plus a snapshot of each shared-state key
+*     (docks, commands, renderer manifest), so `createDevframeClientRuntime`
+*     and every frame SPA boot from the dump with no live server.
+*
+* Reads work from the baked dump; live writes (messages, terminals,
+* commands execution) have no server and degrade to no-ops in the clients.
+*/
+async function buildHub(options) {
+	const base = normalizeHubBase(options.base ?? "/__devframes/");
+	const cwd = options.cwd ?? process.cwd();
+	const outDir = resolve(cwd, options.outDir);
+	const rendererRegistrations = resolveRendererRegistrations(options.renderers ?? []);
+	if (existsSync(outDir)) await fs.rm(outDir, { recursive: true });
+	await fs.mkdir(outDir, { recursive: true });
+	/** Map a hub-base-relative URL base to its on-disk location under `outDir`. */
+	function resolveOutPath(urlBase) {
+		if (!urlBase.startsWith(base)) throw diagnostics.DF8006({
+			urlBase,
+			base
+		});
+		return resolve(outDir, urlBase.slice(base.length));
+	}
+	const frameMetaBases = [];
+	const host = {
+		...createH3DevframeHost({
+			origin: "http://localhost",
+			appName: "devframes",
+			workspaceRoot: cwd,
+			/**
+			* A static build "serves" by copying: a local dist verbatim, a remote
+			* assets source by materializing every listed file.
+			*/
+			mount: async (mountBase, source) => {
+				const target = resolveOutPath(mountBase);
+				await fs.mkdir(dirname(target), { recursive: true });
+				if (typeof source === "string") await fs.cp(source, target, { recursive: true });
+				else await source.materialize(target);
+			}
+		}),
+		...options.getStorageDir ? { getStorageDir: options.getStorageDir } : {},
+		mountConnectionMeta: (frameBase) => {
+			resolveOutPath(frameBase);
+			frameMetaBases.push(frameBase);
+		}
+	};
+	const ctx = await createHubContext({
+		cwd,
+		workspaceRoot: cwd,
+		mode: "build",
+		host,
+		...options.rpcDeclarations ? { builtinRpcDeclarations: options.rpcDeclarations } : {}
+	});
+	const devframes = await resolveDevframesInput(options.devframes ?? []);
+	for (const input of options.services ?? []) ctx.services.install(input);
+	const frames = [];
+	const setups = await mountDevframes(ctx, devframes, base, frames, false);
+	await ctx.services.ready();
+	for (const run of setups) await run();
+	await options.configure?.(ctx);
+	await options.ui?.setup?.(ctx);
+	await publishRendererManifest(ctx, rendererRegistrations, base, outDir);
+	await writeUiArtifacts(options.ui, outDir);
+	await fs.writeFile(resolve(outDir, DEVFRAME_DOCK_IMPORTS_FILENAME), renderClientImportsModule(ctx), "utf-8");
+	await fs.writeFile(resolve(outDir, "__index.json"), `${JSON.stringify({
+		name: options.name,
+		version: options.version,
+		base,
+		frames,
+		endpoints: {
+			connection: DEVFRAME_CONNECTION_META_FILENAME,
+			clientImports: DEVFRAME_DOCK_IMPORTS_FILENAME,
+			index: "__index.json",
+			...options.ui?.embedded ? { embedded: "embedded.js" } : {}
+		}
+	}, null, 2)}\n`, "utf-8");
+	await writeConnectionMetas(ctx, base, outDir, frameMetaBases.map(resolveOutPath));
+	console.log(colors.cyan`[devframes-hub] writing RPC dump to ${resolve(outDir, "__rpc-dump")}`);
+	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
+	await writeStaticRpcDump(dump, outDir, { pretty: options.pretty });
+	console.log(colors.green`[devframes-hub] built ${frames.length} devframe${frames.length === 1 ? "" : "s"} -> ${outDir}`);
+}
+/**
+* Publish the renderer manifest exactly like `initHub` does, so it is baked
+* into the shared-state snapshot, and copy each prebuilt module to the URL
+* the manifest advertises.
+*/
+async function publishRendererManifest(ctx, registrations, base, outDir) {
+	const manifest = {};
+	for (const registration of registrations) {
+		manifest[registration.type] = {
+			importFrom: joinURL(base, "__renderers", `${registration.type}.mjs`),
+			...registration.importName ? { importName: registration.importName } : {}
+		};
+		await fs.mkdir(resolve(outDir, "__renderers"), { recursive: true });
+		await fs.copyFile(registration.file, resolve(outDir, "__renderers", `${registration.type}.mjs`));
+	}
+	(await ctx.rpc.sharedState.get(DOCK_RENDERERS_STATE_KEY, { initialValue: {} })).mutate(() => manifest);
+}
+/**
+* Copy the UI slot's artifacts: the viewer SPA owns the hub base (copied
+* before the discovery documents, so those win over same-named files it
+* ships), `embedded.js` next to it, plus any produced assets.
+*/
+async function writeUiArtifacts(ui, outDir) {
+	if (ui?.viewer) await fs.cp(resolve(ui.viewer.distDir), outDir, { recursive: true });
+	if (ui?.embedded) await fs.copyFile(resolve(ui.embedded.entry), resolve(outDir, "embedded.js"));
+	for (const [key, produce] of Object.entries(ui?.assets ?? {})) {
+		const target = resolve(outDir, key);
+		await fs.mkdir(dirname(target), { recursive: true });
+		await fs.writeFile(target, produce());
+	}
+}
+/**
+* Write the `backend: 'static'` connection meta at the hub base, and a copy
+* at every frame base whose `baseUrl` points relative resolution (the RPC
+* dump) back at the hub's own meta, so a frame SPA that fetched its
+* per-frame copy (instead of inheriting the host page's connection) still
+* finds the shared dump.
+*/
+async function writeConnectionMetas(ctx, base, outDir, frameDirs) {
+	const jsonSerializableMethods = [];
+	for (const def of ctx.rpc.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);
+	const meta = {
+		backend: "static",
+		jsonSerializableMethods,
+		...Object.keys(ctx.staticConfig).length > 0 ? { configs: ctx.staticConfig } : {}
+	};
+	await fs.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify(meta, null, 2), "utf-8");
+	const frameMeta = {
+		...meta,
+		baseUrl: joinURL(base, DEVFRAME_CONNECTION_META_FILENAME)
+	};
+	for (const frameDir of frameDirs) {
+		const target = resolve(frameDir, DEVFRAME_CONNECTION_META_FILENAME);
+		await fs.mkdir(dirname(target), { recursive: true });
+		await fs.writeFile(target, JSON.stringify(frameMeta, null, 2), "utf-8");
+	}
+}
+//#endregion
+export { buildHub };

package/dist/node/index.d.mts

@@ -1,5 +1,5 @@
-import { C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, T as DevframeMessageHandle, a as DevframeChildProcessExecuteOptions, c as DevframeChildProcessTerminalSession, f as DevframePtyTerminalSession, g as DevframeTerminalsHost$1, i as InstallDevframeOptions, j as DevframeMessagesListDelta, k as DevframeMessagesHost$1, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, p as DevframeTerminalSession, r as createHubContext, t as CreateHubContextOptions, x as DevframeMessageEntry } from "../context-BJFGlcf8.mjs";
-import { C as DevframeDockUserEntry, T as DevframeDocksHost$1, _ as DevframeDockEntry, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, l as DevframeCommandsHost$1, o as DevframeCommandHandle, p as ClientScriptEntry, t as DevframeDocksUserSettings } from "../settings-DwxCyeI6.mjs";
+import { C as DevframeMessageEntryInput, D as DevframeMessageShortcutInput, T as DevframeMessageHandle, a as DevframeChildProcessExecuteOptions, c as DevframeChildProcessTerminalSession, f as DevframePtyTerminalSession, g as DevframeTerminalsHost$1, i as InstallDevframeOptions, j as DevframeMessagesListDelta, k as DevframeMessagesHost$1, l as DevframePtyExecuteOptions, m as DevframeTerminalSessionBase, n as DevframeHubContext, p as DevframeTerminalSession, r as createHubContext, t as CreateHubContextOptions, x as DevframeMessageEntry } from "../context-Di-fhMKP.mjs";
+import { C as DevframeDockUserEntry, T as DevframeDocksHost$1, _ as DevframeDockEntry, d as DevframeServerCommandEntry, f as DevframeServerCommandInput, l as DevframeCommandsHost$1, o as DevframeCommandHandle, p as ClientScriptEntry, t as DevframeDocksUserSettings } from "../settings-CWHPzCWS.mjs";
 import { RpcFunctionDefinitionAny } from "devframe/rpc";
 import { SharedState } from "devframe/utils/shared-state";
 //#region src/node/host-commands.d.ts
@@ -9,7 +9,7 @@ declare class DevframeCommandsHost implements DevframeCommandsHost$1 {
   readonly events: DevframeCommandsHost$1['events'];
   /**
    * 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.
    */
   private readonly agentProvider;
@@ -27,7 +27,7 @@ declare class DevframeCommandsHost implements DevframeCommandsHost$1 {
    * 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`).
    */
   private collectAgentTools;
@@ -52,7 +52,7 @@ declare class DevframeDocksHost implements DevframeDocksHost$1 {
   update(view: DevframeDockUserEntry): void;
   activate(dockId: string, params?: Record<string, unknown>): void;
   /**
-   * 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
@@ -79,7 +79,7 @@ declare class DevframeMessagesHost implements DevframeMessagesHost$1 {
   private _clock;
   /**
    * 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}.
    */
   private _removalsTrimmedAt;
@@ -113,14 +113,23 @@ declare class DevframeTerminalsHost implements DevframeTerminalsHost$1 {
   private _channel?;
   constructor(context: DevframeHubContext);
   /**
-   * 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.
    */
   private getStreamingChannel;
+  /**
+   * 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).
+   */
+  private createStreamLifecycle;
   register(session: DevframeTerminalSession): DevframeTerminalSession;
   update(patch: PartialWithoutId<DevframeTerminalSession>): void;
   remove(session: DevframeTerminalSession): void;
+  /** Drain a session's output stream into its scrollback buffer and streaming sink. */
+  private pumpStream;
   private bindStream;
   startChildProcess(executeOptions: DevframeChildProcessExecuteOptions, terminal: Omit<DevframeTerminalSessionBase, 'status'>): Promise<DevframeChildProcessTerminalSession>;
   startPtySession(executeOptions: DevframePtyExecuteOptions, terminal: Omit<DevframeTerminalSessionBase, 'status'>): Promise<DevframePtyTerminalSession>;
@@ -128,7 +137,7 @@ declare class DevframeTerminalsHost implements DevframeTerminalsHost$1 {
 //#endregion
 //#region src/node/rpc-builtins.d.ts
 /**
- * `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.
  *
@@ -151,7 +160,7 @@ declare const hubCommandsExecute: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, ...args: any[]], Promise<unknown>>> | undefined;
 };
 /**
- * `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).
  *
@@ -174,7 +183,7 @@ declare const hubMessagesAdd: {
   __cache?: WeakMap<object, import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[input: DevframeMessageEntryInput], Promise<DevframeMessageEntry>>>> | undefined;
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[input: DevframeMessageEntryInput], Promise<DevframeMessageEntry>>> | undefined;
 };
-/** `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`). */
 declare const hubMessagesUpdate: {
   name: "hub:messages:update";
   type?: "action" | undefined;
@@ -190,7 +199,7 @@ declare const hubMessagesUpdate: {
   __cache?: WeakMap<object, import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, patch: Partial<DevframeMessageEntryInput>], Promise<DevframeMessageEntry | undefined>>>> | undefined;
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, patch: Partial<DevframeMessageEntryInput>], Promise<DevframeMessageEntry | undefined>>> | undefined;
 };
-/** `hub:messages:remove` — Remove a message by id. */
+/** `hub:messages:remove`: Remove a message by id. */
 declare const hubMessagesRemove: {
   name: "hub:messages:remove";
   type?: "action" | undefined;
@@ -206,7 +215,7 @@ declare const hubMessagesRemove: {
   __cache?: WeakMap<object, import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string], Promise<void>>>> | undefined;
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string], Promise<void>>> | undefined;
 };
-/** `hub:messages:clear` — Remove every message. */
+/** `hub:messages:clear`: Remove every message. */
 declare const hubMessagesClear: {
   name: "hub:messages:clear";
   type?: "action" | undefined;
@@ -223,7 +232,7 @@ declare const hubMessagesClear: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[], Promise<void>>> | undefined;
 };
 /**
- * `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.
  */
@@ -242,7 +251,7 @@ declare const hubTerminalsWrite: {
   __cache?: WeakMap<object, import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, data: string], Promise<void>>>> | undefined;
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, data: string], Promise<void>>> | undefined;
 };
-/** `hub:terminals:resize` — Resize an interactive PTY session by id. */
+/** `hub:terminals:resize`: Resize an interactive PTY session by id. */
 declare const hubTerminalsResize: {
   name: "hub:terminals:resize";
   type?: "action" | undefined;
@@ -259,7 +268,7 @@ declare const hubTerminalsResize: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string, cols: number, rows: number], Promise<void>>> | undefined;
 };
 /**
- * `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.
@@ -280,7 +289,7 @@ declare const hubTerminalsTerminate: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string], Promise<void>>> | undefined;
 };
 /**
- * `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.
  */
@@ -300,7 +309,7 @@ declare const hubTerminalsRestart: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string], Promise<void>>> | undefined;
 };
 /**
- * `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.
  */
@@ -320,13 +329,13 @@ declare const hubTerminalsRemove: {
   __promise?: import("devframe/rpc").Thenable<import("devframe/rpc").RpcFunctionSetupResult<[id: string], Promise<void>>> | undefined;
 };
 /**
- * `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).

package/dist/node/index.mjs

@@ -1,8 +1,8 @@
-import { _ as DevframeDocksHost, a as hubMessagesAdd, c as hubMessagesUpdate, d as hubTerminalsRestart, f as hubTerminalsTerminate, g as DevframeMessagesHost, h as DevframeTerminalsHost, i as hubDocksActivate, l as hubTerminalsRemove, n as builtinHubRpcDeclarations, o as hubMessagesClear, p as hubTerminalsWrite, r as hubCommandsExecute, s as hubMessagesRemove, t as createHubContext, u as hubTerminalsResize, v as DevframeCommandsHost } from "../context-DYUkd3il.mjs";
+import { _ as DevframeCommandsHost, a as hubMessagesAdd, c as hubMessagesUpdate, d as hubTerminalsRestart, f as hubTerminalsTerminate, g as DevframeDocksHost, h as DevframeMessagesHost, i as hubDocksActivate, l as hubTerminalsRemove, m as DevframeTerminalsHost, n as builtinHubRpcDeclarations, o as hubMessagesClear, p as hubTerminalsWrite, r as hubCommandsExecute, s as hubMessagesRemove, t as createHubContext, u as hubTerminalsResize } from "../context-BWaW6N53.mjs";
 import "ufo";
-import "pathe";
-import "node:process";
 import "node:fs";
+import "node:process";
+import "pathe";
 import { builtinModules } from "node:module";
 import "node:url";
 import assert from "node:assert";