@devframes/vite 0.9.8 → 0.9.10

package/dist/hub-client.d.mts

@@ -10,7 +10,7 @@ interface MountDevframeHubClientOptions extends DevframeClientRuntimeOptions$1 {
   base?: string;
 }
 /**
- * Boot the devframes-hub **client runtime** in the host page — the browser
+ * Boot the devframes-hub **client runtime** in the host page: the browser
  * half of {@link import('./hub').viteDevframeHub}. Connects RPC to the hub
  * (defaulting `base` to `/__devframes/`), assembles the shared
  * `DevframeClientContext`, and imports each dock's client script into the

package/dist/hub-client.mjs

@@ -2,7 +2,7 @@ import { createDevframeClientRuntime } from "@devframes/hub/client";
 import { DEVFRAMES_HUB_BASE } from "@devframes/hub/constants";
 //#region src/hub-client.ts
 /**
-* Boot the devframes-hub **client runtime** in the host page — the browser
+* Boot the devframes-hub **client runtime** in the host page: the browser
 * half of {@link import('./hub').viteDevframeHub}. Connects RPC to the hub
 * (defaulting `base` to `/__devframes/`), assembles the shared
 * `DevframeClientContext`, and imports each dock's client script into the

package/dist/hub.d.mts

@@ -5,7 +5,7 @@ import { Plugin } from "vite";
 //#region src/hub.d.ts
 interface ViteDevframeHubOptions {
   /**
-   * Mount base the hub answers under — every frame lives at `<base><id>/`.
+   * Mount base the hub answers under; every frame lives at `<base><id>/`.
    * Default: `/__devframes/`.
    */
   base?: string;
@@ -28,7 +28,7 @@ interface ViteDevframeHubOptions {
    */
   clientScripts?: Record<string, ClientScriptEntry>;
   /**
-   * Prebuilt dock-renderer modules forwarded to `initHub({ renderers })` —
+   * Prebuilt dock-renderer modules forwarded to `initHub({ renderers })`,
    * each served at `<base>__renderers/<type>.mjs` and published in the
    * renderer manifest (e.g. `jsonRenderUiRenderer()` from
    * `@devframes/json-render-ui/hub`).
@@ -40,13 +40,13 @@ interface ViteDevframeHubOptions {
    */
   rpcDeclarations?: InitHubOptions['rpcDeclarations'];
   /**
-   * Runs once the context exists and every `devframes` entry is mounted —
+   * Runs once the context exists and every `devframes` entry is mounted;
    * register docks, commands, terminals, and messages surfaces here.
    */
   configure?: (ctx: DevframeHubContext) => void | Promise<void>;
   /**
    * The hub's UI slot. Defaults to `@devframes/hub-ui`'s `createUi()` (the
-   * reference floating dock + standalone viewer) when omitted — install
+   * reference floating dock + standalone viewer) when omitted, so install
    * `@devframes/hub-ui` for that default. Pass your own {@link DevframeHubUi}
    * to swap the hub UI provider, or `false` for a headless hub (serve your own UI
    * against `@devframes/hub/client`).
@@ -58,7 +58,9 @@ interface ViteDevframeHubOptions {
    */
   auth?: InitHubOptions['auth'];
   /**
-   * Expose the aggregate MCP endpoint at `<base>__mcp`.
+   * Expose the aggregate MCP endpoint at `<base>__mcp`. Defaults to `'auto'`
+   * (mount once any mounted devframe exposes an agent surface); `true`
+   * forces it on, `false` off.
    */
   mcp?: InitHubOptions['mcp'];
   /** Publish this hub in the global instance registry. Default: off. */
@@ -79,10 +81,21 @@ interface ViteDevframeHubOptions {
    * @default false
    */
   quiet?: boolean;
+  /**
+   * Also bake the hub into `vite build` output: `buildHub` writes the whole
+   * static hub subtree (each devframe's SPA, the RPC dump, `embedded.js`, …)
+   * into `<outDir><base>`, and the UI's `embedded.js` script tag is injected
+   * into the built HTML, so the deployed app ships working devtools against
+   * a `static` backend (baked reads, no live server). Off by default: a
+   * production bundle only carries devtools when the host opts in.
+   *
+   * @default false
+   */
+  build?: boolean;
 }
 /**
- * Mount a whole **devframes-hub** — many integrations under one namespace,
- * one merged RPC registry, one WebSocket — inside an existing Vite dev
+ * Mount a whole **devframes-hub** (many integrations under one namespace,
+ * one merged RPC registry, one WebSocket) inside an existing Vite dev
  * server. One `initHub()` call, mounted as connect middleware; the WebSocket
  * shares Vite's own HTTP server (upgrading at `<base>__ws`) unless a `port`
  * pins a side-car. The UI defaults to `@devframes/hub-ui` (its `embedded.js`

package/dist/hub.mjs

@@ -1,4 +1,5 @@
 import process from "node:process";
+import { resolve } from "pathe";
 import { Server } from "node:http";
 import { DEVFRAMES_HUB_BASE, normalizeHubBase } from "@devframes/hub/constants";
 import { initHub } from "@devframes/hub/initiate";
@@ -7,11 +8,11 @@ let recommendedViteDevtools = false;
 function recommendViteDevtools() {
 	if (recommendedViteDevtools) return;
 	recommendedViteDevtools = true;
-	console.warn("[@devframes/vite/hub] Serving a devframes-hub directly inside Vite works, but Vite DevTools (`@vitejs/devtools-kit`) integrates the hub protocol natively — prefer it for a first-class, multi-integration experience. Pass `{ quiet: true }` to silence this notice.");
+	console.warn("[@devframes/vite/hub] Serving a devframes-hub directly inside Vite works, but Vite DevTools (`@vitejs/devtools-kit`) integrates the hub protocol natively, so prefer it for a first-class, multi-integration experience. Pass `{ quiet: true }` to silence this notice.");
 }
 /**
-* Mount a whole **devframes-hub** — many integrations under one namespace,
-* one merged RPC registry, one WebSocket — inside an existing Vite dev
+* Mount a whole **devframes-hub** (many integrations under one namespace,
+* one merged RPC registry, one WebSocket) inside an existing Vite dev
 * server. One `initHub()` call, mounted as connect middleware; the WebSocket
 * shares Vite's own HTTP server (upgrading at `<base>__ws`) unless a `port`
 * pins a side-car. The UI defaults to `@devframes/hub-ui` (its `embedded.js`
@@ -29,14 +30,20 @@ function viteDevframeHub(options = {}) {
 	let viteConfig;
 	let instance;
 	let embeddedSrc;
+	let buildUi;
 	const teardown = async () => {
 		const previous = instance;
 		instance = void 0;
 		await previous?.close().catch(() => {});
 	};
+	const resolveUi = async () => options.ui === false ? void 0 : options.ui ?? await loadDefaultUi();
 	return {
 		name: "devframes:hub",
-		apply: "serve",
+		/**
+		* Dev middleware by default; a production bundle only carries the hub
+		* when the host opts into the static build.
+		*/
+		apply: (_, env) => env.command === "serve" || options.build === true,
 		configResolved(config) {
 			viteConfig = config;
 		},
@@ -44,31 +51,44 @@ function viteDevframeHub(options = {}) {
 			if (!options.quiet) recommendViteDevtools();
 			await teardown();
 			const cwd = options.cwd ?? viteConfig?.root ?? process.cwd();
-			const ui = options.ui === false ? void 0 : options.ui ?? await loadDefaultUi();
+			const ui = await resolveUi();
 			const devframes = attachClientScripts(options.devframes, options.clientScripts);
 			const httpServer = server.httpServer instanceof Server ? server.httpServer : void 0;
 			const hub = initHub({
 				base,
 				cwd,
+				/**
+				* Bare-specifier client scripts resolve through Vite's own module
+				* graph: `/@id/<specifier>` routes the import (and its transitive
+				* bare imports) through Vite's resolution and import-analysis.
+				*/
 				clientModuleResolution: "/@id/{specifier}",
 				origin: options.origin ?? (() => {
 					const resolved = server.resolvedUrls?.local?.[0];
 					return resolved ? new URL(resolved).origin : "";
 				}),
 				auth: options.auth,
+				/**
+				* Share Vite's own HTTP server for the WS upgrade at `<base>__ws`, with no
+				* side-car port to discover. A pinned `port` uses a side-car instead;
+				* an https/http2 dev server (non-`node:http`) asks for an auto-port
+				* side-car. Clients discover either via `__connection.json`.
+				*/
 				server: httpServer,
-				...options.port != null ? { ws: { port: options.port } } : httpServer ? {} : { ws: { sidecar: true } },
-				...options.host != null ? { host: options.host } : {},
+				...resolveWsBinding(options.port, httpServer),
 				...ui ? { ui } : {},
-				...options.renderers ? { renderers: options.renderers } : {},
-				...options.rpcDeclarations ? { rpcDeclarations: options.rpcDeclarations } : {},
-				...options.mcp != null ? { mcp: options.mcp } : {},
-				...options.register != null ? { register: options.register } : {},
-				...options.getStorageDir ? { getStorageDir: options.getStorageDir } : {},
-				...options.name != null ? { name: options.name } : {},
-				...options.version != null ? { version: options.version } : {},
 				devframes,
-				...options.configure ? { configure: options.configure } : {}
+				...pickDefined(options, [
+					"host",
+					"renderers",
+					"rpcDeclarations",
+					"mcp",
+					"register",
+					"getStorageDir",
+					"name",
+					"version",
+					"configure"
+				])
 			});
 			instance = hub;
 			embeddedSrc = ui?.embedded ? `${base}embedded.js` : void 0;
@@ -78,6 +98,11 @@ function viteDevframeHub(options = {}) {
 				teardown();
 			});
 		},
+		async buildStart() {
+			if (viteConfig?.command !== "build" || !options.build) return;
+			buildUi = await resolveUi();
+			embeddedSrc = buildUi?.embedded ? `${base}embedded.js` : void 0;
+		},
 		transformIndexHtml() {
 			if (!embeddedSrc) return;
 			return [{
@@ -91,9 +116,45 @@ function viteDevframeHub(options = {}) {
 		},
 		async closeBundle() {
 			await teardown();
+			if (viteConfig?.command !== "build" || !options.build) return;
+			const cwd = options.cwd ?? viteConfig.root;
+			const { buildHub } = await import("@devframes/hub/build");
+			await buildHub({
+				base,
+				cwd,
+				outDir: resolve(viteConfig.root, viteConfig.build.outDir, base.slice(1)),
+				devframes: attachClientScripts(options.devframes, options.clientScripts) ?? [],
+				...buildUi ? { ui: buildUi } : {},
+				...pickDefined(options, [
+					"renderers",
+					"rpcDeclarations",
+					"getStorageDir",
+					"name",
+					"version",
+					"configure"
+				])
+			});
 		}
 	};
 }
+/**
+* Share Vite's own HTTP server for the WS upgrade unless a `port` pins a
+* side-car, or the dev server isn't a plain `node:http` server (https/http2),
+* which needs an auto-port side-car.
+*/
+function resolveWsBinding(port, httpServer) {
+	if (port != null) return { ws: { port } };
+	return httpServer ? {} : { ws: { sidecar: true } };
+}
+/** Forward only the options a caller actually set. */
+function pickDefined(source, keys) {
+	const out = {};
+	for (const key of keys) {
+		const value = source[key];
+		if (value != null) out[key] = value;
+	}
+	return out;
+}
 /** Lazy-load `@devframes/hub-ui`'s default UI so it stays an optional dep. */
 async function loadDefaultUi() {
 	const { createUi } = await import("@devframes/hub-ui");

package/dist/index.mjs

@@ -1,4 +1,4 @@
 //#region src/index.ts
-throw new Error("[@devframes/vite] has no root export. Import from a scoped subpath instead:\n  • \"@devframes/vite/single\" — dev-serve one devframe's SPA with Vite\n  • \"@devframes/vite/hub\"    — mount a devframes-hub inside a Vite app\n");
+throw new Error("[@devframes/vite] has no root export. Import from a scoped subpath instead:\n  • \"@devframes/vite/single\": dev-serve one devframe's SPA with Vite\n  • \"@devframes/vite/hub\": mount a devframes-hub inside a Vite app\n");
 //#endregion
 export {};

package/dist/single.d.mts

@@ -1,10 +1,10 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import { Plugin } from "vite";
-import { DevframeDefinition, McpRouteOptions } from "devframe";
+import { DevframeDefinition, McpSetting } from "devframe";
 import { DevframeAuthHandler } from "devframe/node/auth";
 //#region src/single.d.ts
 /**
- * The slice of a Vite dev server these plugins touch — deliberately
+ * The slice of a Vite dev server these plugins touch, deliberately
  * narrower than Vite's real `ViteDevServer` (which carries the module
  * graph, watcher, transform pipeline, …) so a host can hand a plugin
  * anything shaped like this, and a test double only needs to fake two
@@ -18,7 +18,7 @@ interface DevframeViteDevServerLike {
   };
   /**
    * Deliberately structural (just the one event these plugins listen for)
-   * rather than `NodeHttpServer` — Vite's real `ViteDevServer.httpServer`
+   * rather than `NodeHttpServer`: Vite's real `ViteDevServer.httpServer`
    * is `http.Server | Http2SecureServer | null`, and `Http2SecureServer`
    * doesn't satisfy `http.Server`'s full shape.
    */
@@ -26,12 +26,12 @@ interface DevframeViteDevServerLike {
     once: (event: 'close', listener: () => void) => unknown;
   } | null;
 }
-/** A devframe Vite plugin — a real Vite `Plugin`, scoped to its `serve`-only hooks. */
+/** A devframe Vite plugin: a real Vite `Plugin`, scoped to its `serve`-only hooks. */
 type DevframeVitePlugin = Plugin;
 interface DevframeVitePluginOptions {
   /**
    * Mount base. Defaults to `def.basePath ?? '/__<id>/'` for this hosted
-   * adapter — the devframe shares the origin with the host Vite app.
+   * adapter, so the devframe shares the origin with the host Vite app.
    *
    * Relative spellings like `'./'` (common for base-agnostic Nuxt builds)
    * are normalized to absolute paths so they compose with Vite's connect
@@ -42,7 +42,7 @@ interface DevframeVitePluginOptions {
 /**
  * Statically mount a devframe's built SPA (`def.clientAssets`) at
  * `options.base` inside an existing Vite dev server. No RPC server is
- * started — reach for {@link devframeViteBridge} when the mounted UI
+ * started; reach for {@link devframeViteBridge} when the mounted UI
  * needs a live RPC/WebSocket connection back to the devframe.
  *
  * Use this when the devframe ships its own pre-built UI and the host
@@ -54,7 +54,7 @@ declare function devframeVitePlugin(d: DevframeDefinition, options?: DevframeVit
 interface DevframeViteBridgeOptions {
   /**
    * Mount base. Defaults to `def.basePath ?? '/__<id>/'` for this hosted
-   * adapter — the devframe shares the origin with the host Vite app.
+   * adapter, so the devframe shares the origin with the host Vite app.
    *
    * Relative spellings like `'./'` (common for base-agnostic Nuxt builds)
    * are normalized to absolute paths so they compose with Vite's connect
@@ -86,18 +86,19 @@ interface DevframeViteBridgeOptions {
   auth?: boolean | DevframeAuthHandler;
   /**
    * Expose the bridge's route-based MCP server (Streamable-HTTP) at
-   * `<base>__mcp` — on the Vite app's own origin — and advertise it in the
+   * `<base>__mcp` (on the Vite app's own origin) and advertise it in the
    * bridge's `__connection.json`. Overrides `def.cli?.mcp`, `undefined`
-   * falls through to it, `false` disables the route regardless.
+   * falls through to it, then to the `'auto'` default (mount once the agent
+   * surface is non-empty); `false` disables the route regardless.
    */
-  mcp?: boolean | McpRouteOptions;
+  mcp?: McpSetting;
 }
 /**
  * Bridge a devframe's RPC + WebSocket backend into an existing Vite dev
  * server: the host app owns the SPA (`clientAssets` is never mounted), and this
  * plugin serves discovery (`<base>__connection.json`), the WebSocket RPC
  * upgrade (`<base>__ws`, shared on Vite's own HTTP server), and the
- * optional MCP route through {@link initDevframe}'s node middleware — so
+ * optional MCP route through {@link initDevframe}'s node middleware, so
  * the host-served SPA can discover the endpoint via `connectDevframe`.
  *
  * The bridge **gates by default** (devframe's interactive OTP unless the

package/dist/single.mjs

@@ -8,7 +8,7 @@ import { join, resolve } from "pathe";
 /**
 * Statically mount a devframe's built SPA (`def.clientAssets`) at
 * `options.base` inside an existing Vite dev server. No RPC server is
-* started — reach for {@link devframeViteBridge} when the mounted UI
+* started; reach for {@link devframeViteBridge} when the mounted UI
 * needs a live RPC/WebSocket connection back to the devframe.
 *
 * Use this when the devframe ships its own pre-built UI and the host
@@ -34,7 +34,7 @@ function devframeVitePlugin(d, options = {}) {
 * server: the host app owns the SPA (`clientAssets` is never mounted), and this
 * plugin serves discovery (`<base>__connection.json`), the WebSocket RPC
 * upgrade (`<base>__ws`, shared on Vite's own HTTP server), and the
-* optional MCP route through {@link initDevframe}'s node middleware — so
+* optional MCP route through {@link initDevframe}'s node middleware, so
 * the host-served SPA can discover the endpoint via `connectDevframe`.
 *
 * The bridge **gates by default** (devframe's interactive OTP unless the
@@ -62,10 +62,19 @@ function devframeViteBridge(d, options = {}) {
 			try {
 				const created = initDevframe(d, {
 					base,
+					/**
+					* The host app owns the SPA in bridge mode, so never mount the
+					* definition's own client assets here.
+					*/
 					distDir: false,
 					flags: options.flags,
 					host: options.host,
 					...options.port != null ? { ws: { port: options.port } } : server.httpServer ? { server: server.httpServer } : { ws: { sidecar: true } },
+					/**
+					* Gate by default: an unset `auth` defers to the handler
+					* (devframe's interactive OTP unless `cli.auth` opts out) rather
+					* than leaving the socket ungated. `false` opts out explicitly.
+					*/
 					auth: options.auth,
 					mcp: options.mcp
 				});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/vite",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Vite plugin for mounting a devframe inside any Vite-based host (Astro, SolidStart, Nuxt, plain Vite apps).",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -30,9 +30,9 @@
     "dist"
   ],
   "peerDependencies": {
-    "@devframes/hub": "0.9.8",
-    "@devframes/hub-ui": "0.9.8",
-    "devframe": "0.9.8",
+    "@devframes/hub": "0.9.10",
+    "@devframes/hub-ui": "0.9.10",
+    "devframe": "0.9.10",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -50,11 +50,11 @@
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@devframes/hub": "0.9.8",
-    "@devframes/hub-ui": "0.9.8",
+    "@devframes/hub": "0.9.10",
+    "@devframes/hub-ui": "0.9.10",
     "@modelcontextprotocol/client": "^2.0.0",
     "@types/node": "^26.4.0",
-    "devframe": "0.9.8",
+    "devframe": "0.9.10",
     "get-port-please": "^3.2.0",
     "tsdown": "^0.22.14",
     "vite": "^8.2.2",