@devframes/next 0.9.8 → 0.9.10

package/dist/client.d.mts

@@ -5,7 +5,7 @@ import { ConnectionMeta } from "devframe";
 interface DevframeRpcState {
   /** The connected client, or `null` while the initial connect is in flight. */
   rpc: DevframeRpcClient | null;
-  /** Live connection status — `'connecting'` until the client resolves. */
+  /** Live connection status, `'connecting'` until the client resolves. */
   status: DevframeConnectionStatus;
   /** The latest connection error, or `null`. */
   error: Error | null;
@@ -25,8 +25,8 @@ interface RpcProviderProps {
   connectionMeta?: ConnectionMeta;
 }
 /**
- * Connect to the devframe RPC backend once and provide the client — plus live
- * connection status — to the tree. The React counterpart to `@devframes/nuxt`'s
+ * Connect to the devframe RPC backend once and provide the client, plus live
+ * connection status, to the tree. The React counterpart to `@devframes/nuxt`'s
  * client plugin.
  *
  * Children render immediately (before the connection resolves), so your shell

package/dist/client.mjs

@@ -10,8 +10,8 @@ const INITIAL = {
 	error: null
 };
 /**
-* Connect to the devframe RPC backend once and provide the client — plus live
-* connection status — to the tree. The React counterpart to `@devframes/nuxt`'s
+* Connect to the devframe RPC backend once and provide the client, plus live
+* connection status, to the tree. The React counterpart to `@devframes/nuxt`'s
 * client plugin.
 *
 * Children render immediately (before the connection resolves), so your shell

package/dist/hub-client.d.mts

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

package/dist/hub-client.mjs

@@ -4,7 +4,7 @@ import { createDevframeClientRuntime } from "@devframes/hub/client";
 import { DEVFRAMES_HUB_BASE } from "@devframes/hub/constants";
 //#region src/hub-client.tsx
 /**
-* Boot the devframes-hub **client runtime** inside a React (Next.js) page —
+* Boot the devframes-hub **client runtime** inside a React (Next.js) page:
 * the browser half of {@link import('./hub').nextDevframeHub}. Connects RPC to
 * the hub (defaulting `base` to `/__devframes/`), assembles the shared
 * `DevframeClientContext`, imports each dock's client script into the page,

package/dist/hub.d.mts

@@ -1,5 +1,5 @@
 import { DevframeHubUi, HubInstance, InitHubOptions } from "@devframes/hub/initiate";
-import { ConnectionMeta, DevframeHost, DevframeNodeContext, DevframeStorageScope } from "devframe";
+import { ConnectionMeta, DevframeHost, DevframeNodeContext, DevframeStorageScope, McpAuthorization } from "devframe";
 //#region src/host.d.ts
 interface CreateDevframeNextHostOptions {
   /**
@@ -16,12 +16,21 @@ interface CreateDevframeNextHostOptions {
   /**
    * Initial connection meta served at every base registered via
    * {@link DevframeHost.mountConnectionMeta}. Usually unknown until the
-   * side-car RPC/WS server has started — publish it later with
+   * side-car RPC/WS server has started, so publish it later with
    * {@link DevframeNextHost.setConnectionMeta}.
    */
   connectionMeta?: ConnectionMeta;
 }
 interface DevframeNextHostMcpOptions {
+  /**
+   * Optional identity check layered on the origin gate. Defaults to
+   * origin-only (`false`), trusting same-machine callers. A bearer token
+   * string (matched in constant time) or a `(request) => boolean` callback
+   * hardens the route when a same-machine process is not your trust boundary;
+   * see {@link McpAuthorization}. Back a bearer with an environment variable,
+   * never a literal.
+   */
+  authorization?: McpAuthorization;
   /** Name reported in the MCP handshake. Default: `'devframe (next)'`. */
   serverName?: string;
   /** Version reported in the MCP handshake. Default: `'0.0.0'`. */
@@ -31,7 +40,8 @@ interface DevframeNextHostMcpOptions {
   /**
    * Origin allow-list beyond the loopback default. `false` disables the
    * origin gate entirely. Note the MCP route rejects `Origin`-less requests
-   * (see `createMcpFetchHandler`).
+   * (see `createMcpFetchHandler`). This hardens the request; `authorization`
+   * proves identity.
    */
   allowedOrigins?: readonly string[] | false;
 }
@@ -44,7 +54,7 @@ interface DevframeNextHost {
   host: DevframeHost;
   /**
    * A WHATWG-`fetch` handler that serves every mounted SPA (with SPA
-   * fallback, correct content types, and path-traversal guarding — all from
+   * fallback, correct content types, and path-traversal guarding, all from
    * devframe's own `serveStaticHandler`) and answers `<base>/__connection.json`
    * for each base registered via `mountConnectionMeta`. Delegate a Next App
    * Router route handler straight to it:
@@ -63,12 +73,12 @@ interface DevframeNextHost {
    */
   setConnectionMeta: (meta: ConnectionMeta) => void;
   /**
-   * Serve an MCP Streamable-HTTP endpoint at `path` **in-process** — on the
+   * Serve an MCP Streamable-HTTP endpoint at `path` **in-process**, on the
    * Next app's own origin, through the same catch-all route as the SPAs (the
    * `/_next/mcp` shape). Built on `createMcpFetchHandler` from
-   * `devframe/adapters/mcp` (imported lazily: `@modelcontextprotocol/server`
-   * stays an optional peer). Advertise the path in the connection meta
-   * (`mcp: { path }` — same origin, no port) and register the instance via
+   * `devframe/adapters/mcp` (imported lazily, so the MCP SDK stays out of
+   * the app's bundle graph). Advertise the path in the connection meta
+   * (`mcp: { path }`, same origin, no port) and register the instance via
    * `registerDevframeInstance` so `devframe connect` can discover it.
    */
   mountMcp: (ctx: DevframeNodeContext, path: string, options?: DevframeNextHostMcpOptions) => Promise<{
@@ -81,7 +91,7 @@ interface DevframeNextHost {
  * route delegates to.
  *
  * This is the hosted-adapter counterpart to `devframeViteBridge` for the Next
- * runtime, which — being webpack/Turbopack rather than Vite — can't reuse the
+ * runtime, which (being webpack/Turbopack rather than Vite) can't reuse the
  * Vite middleware path. Instead of hand-rolling static serving in a route
  * handler, static mounts are registered on an internal h3 app and served
  * through devframe's shared `serveStaticHandler` (`app.fetch` makes h3 a
@@ -95,7 +105,7 @@ declare function createDevframeNextHost(options: CreateDevframeNextHostOptions):
 //#region src/hub.d.ts
 interface NextDevframeHubOptions {
   /**
-   * Mount base the hub answers under — every frame lives at `<base><id>/`,
+   * Mount base the hub answers under; every frame lives at `<base><id>/`,
    * so the App Router needs one catch-all route under it. Default:
    * `/__devframes/`.
    */
@@ -113,7 +123,7 @@ interface NextDevframeHubOptions {
   /**
    * Devframes to mount. Load built-in plugin packages through a
    * bundler-ignored dynamic `import()` (their node code + `import.meta.url`
-   * dist lookups don't survive static Next bundling) and pass them here —
+   * dist lookups don't survive static Next bundling) and pass them here, where
    * `initHub` resolves async/factory entries.
    */
   devframes?: InitHubOptions['devframes'];
@@ -133,8 +143,11 @@ interface NextDevframeHubOptions {
   /** The hub's single auth gate. Gates by default; `false` opts out. */
   auth?: InitHubOptions['auth'];
   /**
-   * Expose the aggregate MCP endpoint at `<base>__mcp`. Default: `true`
-   * (the Next hub's agent surface rides the same catch-all route).
+   * Expose the aggregate MCP endpoint at `<base>__mcp`. Defaults to `'auto'`
+   * (mount once any mounted devframe exposes an agent surface); `true`
+   * mounts it unconditionally with the
+   * loopback origin gate (trusting same-machine callers), an object opts
+   * into an `authorization` identity check, `false` keeps it off.
    */
   mcp?: InitHubOptions['mcp'];
   /** Public origin the Next app is reachable at. Default: derived from `PORT`. */
@@ -152,12 +165,13 @@ interface NextDevframeHubOptions {
  * Build a devframes-hub for a Next.js App Router app: one `initHub()` call
  * mounting every devframe under `<base><id>/` behind one web-standard
  * `handler`, with the RPC socket on a side-car (Next routes can't accept WS
- * upgrades) and the aggregate MCP route on by default. The UI defaults to
+ * upgrades) and the aggregate MCP route mounted on demand (the `'auto'`
+ * default; pass `mcp` to force or disable it). The UI defaults to
  * `@devframes/hub-ui`'s `createUi()`, loaded lazily via a bundler-ignored
  * dynamic `import()` so its asset lookups resolve at request time; pass `ui`
  * to swap it or `ui: false` for a headless hub.
  *
- * Prefer {@link nextDevframeHub} at a route module — it memoizes this on
+ * Prefer {@link nextDevframeHub} at a route module: it memoizes this on
  * `globalThis` so Next's dev-time route re-evaluation reuses one instance
  * instead of leaking a side-car per reload.
  */

package/dist/hub.mjs

@@ -16,7 +16,7 @@ function stripTrailingSlash(base) {
 * route delegates to.
 *
 * This is the hosted-adapter counterpart to `devframeViteBridge` for the Next
-* runtime, which — being webpack/Turbopack rather than Vite — can't reuse the
+* runtime, which (being webpack/Turbopack rather than Vite) can't reuse the
 * Vite middleware path. Instead of hand-rolling static serving in a route
 * handler, static mounts are registered on an internal h3 app and served
 * through devframe's shared `serveStaticHandler` (`app.fetch` makes h3 a
@@ -66,6 +66,7 @@ function createDevframeNextHost(options) {
 				serverName: mcpOptions.serverName ?? "devframe (next)",
 				serverVersion: mcpOptions.serverVersion ?? "0.0.0",
 				exposeSharedState: mcpOptions.exposeSharedState ?? true,
+				authorization: mcpOptions.authorization,
 				allowedOrigins: mcpOptions.allowedOrigins
 			});
 			const key = stripTrailingSlash(path);
@@ -83,12 +84,13 @@ function createDevframeNextHost(options) {
 * Build a devframes-hub for a Next.js App Router app: one `initHub()` call
 * mounting every devframe under `<base><id>/` behind one web-standard
 * `handler`, with the RPC socket on a side-car (Next routes can't accept WS
-* upgrades) and the aggregate MCP route on by default. The UI defaults to
+* upgrades) and the aggregate MCP route mounted on demand (the `'auto'`
+* default; pass `mcp` to force or disable it). The UI defaults to
 * `@devframes/hub-ui`'s `createUi()`, loaded lazily via a bundler-ignored
 * dynamic `import()` so its asset lookups resolve at request time; pass `ui`
 * to swap it or `ui: false` for a headless hub.
 *
-* Prefer {@link nextDevframeHub} at a route module — it memoizes this on
+* Prefer {@link nextDevframeHub} at a route module: it memoizes this on
 * `globalThis` so Next's dev-time route re-evaluation reuses one instance
 * instead of leaking a side-car per reload.
 */
@@ -101,8 +103,9 @@ async function createNextDevframeHub(options = {}) {
 		...options.host != null ? { host: options.host } : {},
 		...options.origin != null ? { origin: options.origin } : {},
 		auth: options.auth,
+		/** Next route handlers can't accept WS upgrades, so always a side-car socket. */
 		ws: options.port != null ? { port: options.port } : { sidecar: true },
-		mcp: options.mcp ?? true,
+		...options.mcp !== void 0 ? { mcp: options.mcp } : {},
 		...ui ? { ui } : {},
 		...options.renderers ? { renderers: options.renderers } : {},
 		...options.rpcDeclarations ? { rpcDeclarations: options.rpcDeclarations } : {},
@@ -170,7 +173,7 @@ function nextDevframeHub(options = {}) {
 * Load `@devframes/hub-ui`'s default UI through a bundler-ignored dynamic
 * `import()`: `createUi()` resolves its prebuilt assets via `import.meta.url`,
 * which only points at the published `dist` when Node loads the package at
-* request time — a static import would be rewritten into a Next server chunk.
+* request time, since a static import would be rewritten into a Next server chunk.
 */
 async function loadDefaultUi() {
 	return (await import(

package/dist/index.mjs

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

package/dist/single.d.mts

@@ -33,7 +33,7 @@ declare function withDevframe<T extends DevframeNextConfig>(nextConfig?: T): T;
 //#region src/handler.d.ts
 interface CreateDevframeNextHandlerOptions {
   /**
-   * Mount base for the SPA. Defaults to `def.basePath ?? '/__<id>/'` — the
+   * Mount base for the SPA. Defaults to `def.basePath ?? '/__<id>/'`, the
    * hosted-adapter default, so the devframe shares the Next app's origin
    * without colliding with its routes.
    */
@@ -57,11 +57,12 @@ interface CreateDevframeNextHandlerOptions {
   /** Override where persisted devframe state lives (defaults under the cwd / home). */
   getStorageDir?: (scope: DevframeStorageScope) => string;
   /**
-   * Expose the route-based MCP server (Streamable-HTTP) at `<base>__mcp` —
+   * Expose the route-based MCP server (Streamable-HTTP) at `<base>__mcp`,
    * on the Next app's own origin, through the same catch-all route as the
-   * SPA — and advertise it in the handler's `__connection.json`. Overrides
-   * `def.cli?.mcp`, `undefined` falls through to it, `false` disables the
-   * route regardless.
+   * SPA, and advertise it in the handler's `__connection.json`. Overrides
+   * `def.cli?.mcp`, `undefined` falls through to it, then to the `'auto'`
+   * default (mount once the agent surface is non-empty); `false` disables
+   * the route regardless.
    */
   mcp?: InitDevframeOptions['mcp'];
   /**
@@ -85,7 +86,7 @@ interface DevframeNextHandler {
   close: () => Promise<void>;
 }
 /**
- * Host a **single** devframe from a Next.js App Router app — the Next
+ * Host a **single** devframe from a Next.js App Router app: the Next
  * counterpart to `devframeViteBridge`, reduced to memoization + defaults over
  * `initDevframe` (Next's route handlers can't accept WS upgrades, so the
  * RPC socket lives on the instance's side-car port, advertised at

package/dist/single.mjs

@@ -52,7 +52,7 @@ function defaultGetStorageDir(scope) {
 	return join(homedir(), ".devframe");
 }
 /**
-* Host a **single** devframe from a Next.js App Router app — the Next
+* Host a **single** devframe from a Next.js App Router app: the Next
 * counterpart to `devframeViteBridge`, reduced to memoization + defaults over
 * `initDevframe` (Next's route handlers can't accept WS upgrades, so the
 * RPC socket lives on the instance's side-car port, advertised at
@@ -85,8 +85,17 @@ function createDevframeNextHandler(def, options = {}) {
 		distDir,
 		host: options.host,
 		flags: options.flags,
+		/**
+		* Gate by default: an unset `auth` defers to the instance (devframe's
+		* interactive OTP unless `cli.auth` opts out). `false` opts out.
+		*/
 		auth: options.auth,
 		mcp: options.mcp,
+		/**
+		* Next's route handlers never see WebSocket upgrades, so the RPC socket
+		* lives on a side-car server (on `options.port` when pinned, otherwise
+		* a free port), advertised via `<base>__connection.json`.
+		*/
 		ws: options.port != null ? { port: options.port } : { sidecar: true },
 		...options.resolveOrigin ? { origin: options.resolveOrigin } : {},
 		getStorageDir: options.getStorageDir ?? defaultGetStorageDir

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/next",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Next.js host integration that serves mounted devframes from an App Router route.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -47,9 +47,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",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -71,11 +71,11 @@
     "h3": "^2.0.1-rc.29"
   },
   "devDependencies": {
-    "@devframes/hub": "0.9.8",
-    "@devframes/hub-ui": "0.9.8",
+    "@devframes/hub": "0.9.10",
+    "@devframes/hub-ui": "0.9.10",
     "@types/node": "^26.4.0",
     "@types/react": "^19.2.18",
-    "devframe": "0.9.8",
+    "devframe": "0.9.10",
     "react": "^19.2.8",
     "tsdown": "^0.22.14"
   },