devframe 0.1.21 → 0.1.22

package/README.md

@@ -1,6 +1,8 @@
 # devframe
 
-Framework-neutral foundation for building generic DevTools — RPC layer (birpc + valibot + WS presets), six hosts (RPC / docks / views / terminals / logs / commands / agent), and adapters under `devframe/adapters/*` (cli / build / spa / vite / kit / embedded / mcp). Part of the [Vite DevTools](https://devtools.vite.dev) monorepo.
+Framework-neutral foundation for building generic DevTools. Describe one devframe — its RPC, its data, its SPA, its CLI shape — and deploy the same definition through any of seven adapters.
+
+Part of the [Vite DevTools](https://devtools.vite.dev) monorepo. Full documentation: [https://devfra.me/](https://devfra.me/).
 
 ## Install
 
@@ -8,18 +10,48 @@ Framework-neutral foundation for building generic DevTools — RPC layer (birpc
 pnpm add devframe
 ```
 
-## Docs
+## Hello, Devframe
+
+```ts
+import { defineDevframe, defineRpcFunction } from 'devframe'
+import { createCli } from 'devframe/adapters/cli'
+
+const devframe = defineDevframe({
+  id: 'my-devframe',
+  name: 'My Devframe',
+  setup(ctx) {
+    ctx.rpc.register(defineRpcFunction({
+      name: 'my-devframe:hello',
+      type: 'static',
+      jsonSerializable: true,
+      handler: () => ({ message: 'hello' }),
+    }))
+  },
+})
 
-See the [DevFrame documentation](https://devfra.me/) for the full guide and API reference.
+await createCli(devframe).parse()
+```
+
+## Adapters
+
+| Adapter | Use case |
+|---------|----------|
+| `cli` | Standalone CLI tool with `dev` / `build` / `mcp` subcommands. |
+| `build` | Generates a static, self-contained SPA snapshot. |
+| `vite` | Runs as a Vite plugin alongside the host app's dev server. |
+| `kit` | Mounts into the DevTools Kit aggregator. |
+| `embedded` | Overlays inside another devtool's UI. |
+| `mcp` | Surfaces the devframe's RPC to coding agents over MCP. |
 
 ## Agent-Native (experimental)
 
-> ⚠️ **Experimental.** The agent-native surface — the `agent` field on `defineRpcFunction`, `DevToolsAgentHost`, and the `devframe/adapters/mcp` adapter — is experimental and may change without a major version bump until it stabilizes.
+> [!WARNING]
+> The agent-native surface — the `agent` field on `defineRpcFunction`, `DevToolsAgentHost`, and the `devframe/adapters/mcp` adapter — may change without a major version bump until it stabilizes.
 
-DevFrame can expose a devtool's RPC functions, tools, and resources to coding agents over [MCP](https://modelcontextprotocol.io). Flag an RPC function with `agent: { description }` to surface it, then spin up an MCP server:
+Devframe surfaces a devframe's RPC functions, tools, and resources to coding agents over [MCP](https://modelcontextprotocol.io). Flag an RPC function with `agent: { description }` to expose it, then spin up an MCP server:
 
 ```ts
-import { defineDevtool, defineRpcFunction } from 'devframe'
+import { defineDevframe, defineRpcFunction } from 'devframe'
 import { createMcpServer } from 'devframe/adapters/mcp'
 
 const getSummary = defineRpcFunction({
@@ -31,11 +63,10 @@ const getSummary = defineRpcFunction({
   setup: ctx => ({ handler: async () => buildSummary() }),
 })
 
-const devtool = defineDevtool({
+const devframe = defineDevframe({
   id: 'my-plugin',
   setup(ctx) {
     ctx.rpc.register(getSummary)
-    // Optional: register tools or resources directly.
     ctx.agent.registerResource({
       id: 'latest-build',
       name: 'Latest build',
@@ -44,18 +75,10 @@ const devtool = defineDevtool({
   },
 })
 
-await createMcpServer(devtool, { transport: 'stdio' })
+await createMcpServer(devframe, { transport: 'stdio' })
 ```
 
-Or via the CLI:
-
-```sh
-devframe mcp
-```
-
-`@modelcontextprotocol/sdk` is a peer dependency — add it to your package when you want to ship MCP support.
-
-See the [Agent-Native guide](https://devfra.me/agent-native) for the full API, safety model, and Claude Desktop integration example.
+Or via the CLI: `devframe mcp`. `@modelcontextprotocol/sdk` is a peer dependency — add it when you want MCP support. See the [Agent-Native guide](https://devfra.me/guide/agent-native) for the full API and Claude Desktop integration example.
 
 ## License
 

package/dist/{_shared-iZy45oG3.mjs → _shared-DcJX9-Az.mjs}

@@ -1,11 +1,11 @@
 //#region src/adapters/_shared.ts
 /**
-* Resolve the mount base path for a devtool's SPA. Hosted adapters
+* Resolve the mount base path for a devframe's SPA. Hosted adapters
 * (`vite`, `kit`, `embedded`) default to `/__<id>/` so they don't
 * collide with the host app; standalone adapters (`cli`, `spa`,
 * `build`) default to `/` because they own the origin.
 *
-* The devtool author can override with `basePath` on the definition.
+* The devframe author can override with `basePath` on the definition.
 */
 function resolveBasePath(def, kind) {
 	if (def.basePath) return normalizeBasePath(def.basePath);

package/dist/adapters/build.d.mts

@@ -1,4 +1,4 @@
-import { r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
+import { r as DevframeDefinition } from "../devframe-DulcIxwu.mjs";
 
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
@@ -8,7 +8,7 @@ interface CreateBuildOptions {
   base?: string;
   /**
    * Override the SPA dist directory to copy into `outDir`. When omitted
-   * the adapter reads `devtool.cli?.distDir` — authors typically set this
+   * the adapter reads `devframe.cli?.distDir` — authors typically set this
    * once on the definition itself.
    */
   distDir?: string;
@@ -20,9 +20,9 @@ interface CreateBuildOptions {
   pretty?: boolean;
 }
 /**
- * Produce a self-contained static deploy of a devtool:
+ * Produce a self-contained static deploy of a devframe:
  *
- *   - Build a `mode: 'build'` context and run `devtool.setup(ctx)`.
+ *   - Build a `mode: 'build'` context and run `devframe.setup(ctx)`.
  *   - Copy the author's SPA dist into `<outDir>/`.
  *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
  *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
@@ -32,6 +32,6 @@ interface CreateBuildOptions {
  *     `'none'`). The output is mount-path agnostic — the same bundle
  *     works at `/`, `/devtools/`, or any base, no rewriting required.
  */
-declare function createBuild(d: DevtoolDefinition, options?: CreateBuildOptions): Promise<void>;
+declare function createBuild(d: DevframeDefinition, options?: CreateBuildOptions): Promise<void>;
 //#endregion
 export { CreateBuildOptions, createBuild };

package/dist/adapters/build.mjs

@@ -1,19 +1,20 @@
-import { n as strictJsonStringify, o as structuredCloneStringify } from "../serialization-DwKi05Pn.mjs";
-import { t as createHostContext } from "../context-BJ4r2SmR.mjs";
-import { t as createH3DevToolsHost } from "../host-h3-9jeHcltx.mjs";
+import { n as strictJsonStringify } from "../serialization-CwO31axa.mjs";
+import { i as structuredCloneStringify } from "../structured-clone-DcDc2Dds.mjs";
+import { t as colors } from "../colors-Bl4W18Mh.mjs";
+import { t as createHostContext } from "../context-DUibxhrR.mjs";
+import { t as createH3DevToolsHost } from "../host-h3-Dz8YnFgu.mjs";
 import { DEVTOOLS_CONNECTION_META_FILENAME, DEVTOOLS_RPC_DUMP_DIRNAME, DEVTOOLS_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { t as collectStaticRpcDump } from "../static-dump-D5VH8Iqk.mjs";
-import { n as resolveBasePath } from "../_shared-iZy45oG3.mjs";
-import c from "ansis";
+import { t as collectStaticRpcDump } from "../static-dump-D7AvjrgL.mjs";
+import { n as resolveBasePath } from "../_shared-DcJX9-Az.mjs";
 import { existsSync } from "node:fs";
-import { dirname, resolve } from "pathe";
 import process from "node:process";
+import { dirname, resolve } from "pathe";
 import fs$1 from "node:fs/promises";
 //#region src/adapters/build.ts
 /**
-* Produce a self-contained static deploy of a devtool:
+* Produce a self-contained static deploy of a devframe:
 *
-*   - Build a `mode: 'build'` context and run `devtool.setup(ctx)`.
+*   - Build a `mode: 'build'` context and run `devframe.setup(ctx)`.
 *   - Copy the author's SPA dist into `<outDir>/`.
 *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
 *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
@@ -29,7 +30,7 @@ async function createBuild(d, options = {}) {
 	if (!distDir) throw new Error(`[devframe] createBuild: no distDir for "${d.id}". Set \`cli.distDir\` on the definition or pass it as an option.`);
 	if (existsSync(outDir)) await fs$1.rm(outDir, { recursive: true });
 	await fs$1.mkdir(outDir, { recursive: true });
-	console.log(c.cyan`[devframe] copying SPA from ${distDir} -> ${outDir}`);
+	console.log(colors.cyan`[devframe] copying SPA from ${distDir} -> ${outDir}`);
 	await fs$1.cp(distDir, outDir, { recursive: true });
 	const ctx = await createHostContext({
 		cwd: process.cwd(),
@@ -47,7 +48,7 @@ async function createBuild(d, options = {}) {
 		backend: "static",
 		jsonSerializableMethods
 	}, null, 2), "utf-8");
-	console.log(c.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVTOOLS_RPC_DUMP_MANIFEST_FILENAME)}`);
+	console.log(colors.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVTOOLS_RPC_DUMP_MANIFEST_FILENAME)}`);
 	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
 	const indent = options.pretty ? 2 : void 0;
 	for (const [filepath, file] of Object.entries(dump.files)) {
@@ -66,7 +67,7 @@ async function createBuild(d, options = {}) {
 		};
 		await fs$1.writeFile(resolve(outDir, "spa-loader.json"), JSON.stringify(spaLoader, null, 2), "utf-8");
 	}
-	console.log(c.green`[devframe] built "${d.id}" -> ${outDir}`);
+	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
 }
 //#endregion
 export { createBuild };

package/dist/adapters/cli.d.mts

@@ -1,4 +1,4 @@
-import { dt as CliFlagsSchema, ft as InferCliFlags, mt as parseCliFlags, pt as defineCliFlags, r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
+import { _t as InferCliFlags, gt as CliFlagsSchema, r as DevframeDefinition, vt as defineCliFlags, yt as parseCliFlags } from "../devframe-DulcIxwu.mjs";
 import { App } from "h3";
 import { CAC } from "cac";
 
@@ -30,6 +30,6 @@ interface CliHandle {
   cli: CAC;
   parse: (argv?: string[]) => Promise<void>;
 }
-declare function createCli(d: DevtoolDefinition, options?: CreateCliOptions): CliHandle;
+declare function createCli(d: DevframeDefinition, options?: CreateCliOptions): CliHandle;
 //#endregion
 export { type CliFlagsSchema, CliHandle, CreateCliOptions, type InferCliFlags, createCli, defineCliFlags, parseCliFlags };

package/dist/adapters/cli.mjs

@@ -1,6 +1,6 @@
+import { t as colors } from "../colors-Bl4W18Mh.mjs";
 import { createBuild } from "./build.mjs";
-import { n as resolveDevServerPort, t as createDevServer } from "../dev-CdAy400a.mjs";
-import c from "ansis";
+import { n as resolveDevServerPort, t as createDevServer } from "../dev-BGpTpYiR.mjs";
 import process from "node:process";
 import cac from "cac";
 import { safeParse } from "valibot";
@@ -15,7 +15,7 @@ import { safeParse } from "valibot";
 *   config: v.optional(v.string()),
 * })
 *
-* defineDevtool({
+* defineDevframe({
 *   cli: { flags: appFlags },
 *   setup(ctx, info) {
 *     const flags = info.flags as InferCliFlags<typeof appFlags>
@@ -102,7 +102,7 @@ function createCli(d, options = {}) {
 			onReady: options.onReady
 		});
 	});
-	cli.command("build", "Build a self-contained static deploy of the devtool").option("--out-dir <outDir>", "Output directory", { default: "dist-static" }).option("--base <base>", "URL base", { default: "/" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
+	cli.command("build", "Build a self-contained static deploy of the devframe").option("--out-dir <outDir>", "Output directory", { default: "dist-static" }).option("--base <base>", "URL base", { default: "/" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
 		await createBuild(d, {
 			outDir: flags.outDir,
 			base: flags.base,
@@ -134,7 +134,7 @@ function resolveTypedFlags(d, raw) {
 	if (!d.cli?.flags) return raw;
 	const { flags, issues } = parseCliFlags(d.cli.flags, raw);
 	if (issues?.length) {
-		for (const issue of issues) console.error(c.red`[devframe] invalid flag — ${issue}`);
+		for (const issue of issues) console.error(colors.red`[devframe] invalid flag — ${issue}`);
 		process.exit(1);
 	}
 	return flags;

package/dist/adapters/dev.d.mts

@@ -1,5 +1,5 @@
-import { r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
-import { n as StartedServer } from "../server-BAqOajx_.mjs";
+import { r as DevframeDefinition } from "../devframe-DulcIxwu.mjs";
+import { n as StartedServer } from "../server-zKEDxgqD.mjs";
 import { App } from "h3";
 
 //#region src/adapters/dev.d.ts
@@ -19,8 +19,11 @@ interface CreateDevServerOptions {
    */
   flags?: Record<string, unknown>;
   /**
-   * Override `def.cli?.distDir`. Throws when neither is set — the dev
-   * server has nothing to mount otherwise.
+   * Override `def.cli?.distDir`. When neither this option nor
+   * `def.cli?.distDir` is set, the dev server runs in **bridge mode** —
+   * only `__connection.json` and the WS endpoint are mounted; the SPA
+   * is expected to be hosted elsewhere (e.g. by a parent Vite/Nuxt
+   * dev server via `createVitePlugin({ devMiddleware })`).
    */
   distDir?: string;
   /**
@@ -65,11 +68,17 @@ interface ResolveDevServerPortOptions {
  * resolve a port up-front (to print it, log it, etc.) before starting
  * the server.
  */
-declare function resolveDevServerPort(def: DevtoolDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
+declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
 /**
- * Start a devframe dev server for a {@link DevtoolDefinition} —
- * h3 + WebSocket RPC + the author's SPA mounted at the resolved base
- * path.
+ * Start a devframe dev server for a {@link DevframeDefinition} —
+ * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
+ * resolved base path.
+ *
+ * When `distDir` is omitted (and `def.cli?.distDir` is unset) the
+ * server runs in **bridge mode**: only `__connection.json` and the WS
+ * endpoint are mounted, with no SPA mount. The SPA is expected to be
+ * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server) — see
+ * `createVitePlugin({ devMiddleware })`.
  *
  * Returns the underlying {@link StartedServer} handle so callers can
  * close it gracefully (SIGINT, hot-reload, test teardown).
@@ -78,6 +87,6 @@ declare function resolveDevServerPort(def: DevtoolDefinition, options?: ResolveD
  * framework (commander, yargs, hand-rolled CAC). For the all-in-one
  * `dev` / `build` / `mcp` shell, reach for {@link createCli} instead.
  */
-declare function createDevServer(def: DevtoolDefinition, options?: CreateDevServerOptions): Promise<StartedServer>;
+declare function createDevServer(def: DevframeDefinition, options?: CreateDevServerOptions): Promise<StartedServer>;
 //#endregion
 export { CreateDevServerOptions, ResolveDevServerPortOptions, createDevServer, resolveDevServerPort };

package/dist/adapters/dev.mjs

@@ -1,2 +1,2 @@
-import { n as resolveDevServerPort, t as createDevServer } from "../dev-CdAy400a.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "../dev-BGpTpYiR.mjs";
 export { createDevServer, resolveDevServerPort };

package/dist/adapters/embedded.d.mts

@@ -1,19 +1,19 @@
-import { d as DevToolsNodeContext, r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
+import { r as DevframeDefinition, y as DevToolsNodeContext } from "../devframe-DulcIxwu.mjs";
 
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
-  /** Target context the devtool is registered into. Required. */
+  /** Target context the devframe is registered into. Required. */
   ctx: DevToolsNodeContext;
 }
 /**
- * Register a devtool into an already-running devframe/Kit context at
- * runtime. Mirrors what the Vite plugin scan does for devtools passed
+ * Register a devframe into an already-running devframe/Kit context at
+ * runtime. Mirrors what the Vite plugin scan does for devframes passed
  * as plugin options, but exposes the same flow to callers that need
  * dynamic, post-startup registration.
  *
  * The host owns the mount path; when a hosted mount is needed the
  * effective default follows the hosted rule of `def.basePath ?? '/__<id>/'`.
  */
-declare function createEmbedded(d: DevtoolDefinition, options: CreateEmbeddedOptions): Promise<void>;
+declare function createEmbedded(d: DevframeDefinition, options: CreateEmbeddedOptions): Promise<void>;
 //#endregion
 export { CreateEmbeddedOptions, createEmbedded };

package/dist/adapters/embedded.mjs

@@ -1,7 +1,7 @@
 //#region src/adapters/embedded.ts
 /**
-* Register a devtool into an already-running devframe/Kit context at
-* runtime. Mirrors what the Vite plugin scan does for devtools passed
+* Register a devframe into an already-running devframe/Kit context at
+* runtime. Mirrors what the Vite plugin scan does for devframes passed
 * as plugin options, but exposes the same flow to callers that need
 * dynamic, post-startup registration.
 *

package/dist/adapters/mcp.d.mts

@@ -1,4 +1,4 @@
-import { r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
+import { r as DevframeDefinition } from "../devframe-DulcIxwu.mjs";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 
 //#region src/node/mcp/build-server.d.ts
@@ -28,12 +28,12 @@ interface McpServerHandle {
   stop: () => Promise<void>;
 }
 /**
- * Build an MCP server over the agent surface of a devtool definition.
+ * Build an MCP server over the agent surface of a devframe definition.
  * Currently supports `stdio` transport only.
  *
  * @experimental The agent-native surface is experimental and may change
  * without a major version bump until it stabilizes.
  */
-declare function createMcpServer(definition: DevtoolDefinition, options?: CreateMcpServerOptions): Promise<McpServerHandle>;
+declare function createMcpServer(definition: DevframeDefinition, options?: CreateMcpServerOptions): Promise<McpServerHandle>;
 //#endregion
 export { type CreateMcpServerOptions, type McpServerHandle, createMcpServer };

package/dist/adapters/mcp.mjs

@@ -1,8 +1,8 @@
-import { n as logger } from "../diagnostics-DxPnRoXO.mjs";
-import { t as createHostContext } from "../context-BJ4r2SmR.mjs";
-import { join } from "pathe";
+import { n as logger } from "../diagnostics-BFhNNmST.mjs";
+import { t as createHostContext } from "../context-DUibxhrR.mjs";
 import { homedir } from "node:os";
 import process from "node:process";
+import { join } from "pathe";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { toJsonSchema } from "@valibot/to-json-schema";
@@ -113,7 +113,7 @@ function buildMcpServerFromContext(ctx, options) {
 	};
 }
 /**
-* Build an MCP server over the agent surface of a devtool definition.
+* Build an MCP server over the agent surface of a devframe definition.
 * Currently supports `stdio` transport only.
 *
 * @experimental The agent-native surface is experimental and may change
@@ -140,7 +140,7 @@ async function createMcpServer(definition, options = {}) {
 		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
 		exposeSharedState: options.exposeSharedState ?? true
 	});
-	const { startStdioTransport } = await import("../transports-DSV5_5QM.mjs");
+	const { startStdioTransport } = await import("../transports-BnCs4rj9.mjs");
 	let stop;
 	try {
 		stop = await startStdioTransport(server);

package/dist/adapters/vite.d.mts

@@ -1,12 +1,33 @@
-import { r as DevtoolDefinition } from "../devtool-CNvLs2_Y.mjs";
+import { r as DevframeDefinition } from "../devframe-DulcIxwu.mjs";
 
 //#region src/adapters/vite.d.ts
 interface CreateVitePluginOptions {
   /**
    * Mount base. Defaults to `def.basePath ?? '/__<id>/'` for this hosted
-   * adapter — the devtool shares the origin with the host Vite app.
+   * adapter — 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
+   * router.
    */
   base?: string;
+  /**
+   * Dev-time middleware mode. When set, the host app owns the SPA and
+   * devframe spins up a separate RPC + WS server on a resolved port,
+   * registering Vite middleware at `<base>__connection.json` so the
+   * host-served SPA can discover the WS endpoint.
+   *
+   *  - `false` (default) — static-mount the SPA at `base` with SPA
+   *    fallback. No RPC server is started.
+   *  - `true` — bridge mode with all defaults (port from
+   *    {@link resolveDevServerPort}, host from `def.cli?.host`).
+   *  - object — bridge mode with explicit overrides.
+   */
+  devMiddleware?: boolean | {
+    /** Override the bridge port. Default: {@link resolveDevServerPort}. */port?: number; /** Override the bridge bind host. Default: `def.cli?.host ?? 'localhost'`. */
+    host?: string; /** Flag bag forwarded to `def.setup(ctx, { flags })`. */
+    flags?: Record<string, unknown>;
+  };
 }
 interface DevframeVitePlugin {
   name: string;
@@ -15,19 +36,31 @@ interface DevframeVitePlugin {
     middlewares: {
       use: (path: string, handler: any) => void;
     };
-  }) => void;
+    httpServer?: {
+      once: (event: 'close', cb: () => void) => void;
+    } | null;
+  }) => void | Promise<void>;
+  closeBundle?: () => void | Promise<void>;
 }
 /**
- * Plain Vite plugin — mounts a devframe devtool's SPA into a user's
- * Vite dev server at `options.base` (default: `def.basePath ?? '/__<id>/'`).
- * Use this for tools that want the Vite dev experience without
- * pulling the full Vite DevTools Kit.
+ * Vite plugin for hosting a devframe inside a Vite dev server.
+ *
+ * Two modes, picked via `options.devMiddleware`:
+ *
+ *   - **static-mount mode** (default) — mounts `def.cli.distDir` at
+ *     `options.base` with SPA fallback enabled. No RPC server is started.
+ *
+ *   - **bridge mode** (`devMiddleware: true | {…}`) — skips the static
+ *     mount; the host app owns the SPA. Devframe starts a separate
+ *     RPC + WS dev server (via {@link createDevServer} in bridge mode)
+ *     and registers Vite middleware at `<base>__connection.json` so the
+ *     host-served SPA can discover the WS endpoint via
+ *     {@link connectDevframe}.
  *
- * Note: this does not yet spin up the RPC WS server — for the full
- * RPC path, use `createPluginFromDevframe` from
- * `@vitejs/devtools-kit/node` alongside `@vitejs/devtools`, or the
- * standalone `createCli`.
+ * Use bridge mode when integrating with frameworks that own the SPA
+ * (Nuxt, Astro, SolidStart, plain Vite apps). For the all-in-one
+ * `dev` / `build` / `mcp` shell, reach for {@link createCli} instead.
  */
-declare function createVitePlugin(d: DevtoolDefinition, options?: CreateVitePluginOptions): DevframeVitePlugin;
+declare function createVitePlugin(d: DevframeDefinition, options?: CreateVitePluginOptions): DevframeVitePlugin;
 //#endregion
 export { CreateVitePluginOptions, DevframeVitePlugin, createVitePlugin };

package/dist/adapters/vite.mjs

@@ -1,32 +1,95 @@
-import { n as resolveBasePath } from "../_shared-iZy45oG3.mjs";
+import { n as logger } from "../diagnostics-BFhNNmST.mjs";
+import { DEVTOOLS_CONNECTION_META_FILENAME } from "../constants.mjs";
+import { n as resolveBasePath } from "../_shared-DcJX9-Az.mjs";
+import { serveStaticNodeMiddleware } from "../utils/serve-static.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "../dev-BGpTpYiR.mjs";
 import { resolve } from "pathe";
-import sirv from "sirv";
 //#region src/adapters/vite.ts
 /**
-* Plain Vite plugin — mounts a devframe devtool's SPA into a user's
-* Vite dev server at `options.base` (default: `def.basePath ?? '/__<id>/'`).
-* Use this for tools that want the Vite dev experience without
-* pulling the full Vite DevTools Kit.
+* Vite plugin for hosting a devframe inside a Vite dev server.
 *
-* Note: this does not yet spin up the RPC WS server — for the full
-* RPC path, use `createPluginFromDevframe` from
-* `@vitejs/devtools-kit/node` alongside `@vitejs/devtools`, or the
-* standalone `createCli`.
+* Two modes, picked via `options.devMiddleware`:
+*
+*   - **static-mount mode** (default) — mounts `def.cli.distDir` at
+*     `options.base` with SPA fallback enabled. No RPC server is started.
+*
+*   - **bridge mode** (`devMiddleware: true | {…}`) — skips the static
+*     mount; the host app owns the SPA. Devframe starts a separate
+*     RPC + WS dev server (via {@link createDevServer} in bridge mode)
+*     and registers Vite middleware at `<base>__connection.json` so the
+*     host-served SPA can discover the WS endpoint via
+*     {@link connectDevframe}.
+*
+* Use bridge mode when integrating with frameworks that own the SPA
+* (Nuxt, Astro, SolidStart, plain Vite apps). For the all-in-one
+* `dev` / `build` / `mcp` shell, reach for {@link createCli} instead.
 */
 function createVitePlugin(d, options = {}) {
-	const base = options.base ?? resolveBasePath(d, "hosted");
-	const distDir = d.cli?.distDir;
+	const base = normalizeMountBase(options.base ?? resolveBasePath(d, "hosted"));
+	if (!options.devMiddleware) {
+		const distDir = d.cli?.distDir;
+		return {
+			name: `devframe:${d.id}`,
+			apply: "serve",
+			configureServer(server) {
+				if (!distDir) return;
+				server.middlewares.use(base, serveStaticNodeMiddleware(resolve(distDir)));
+			}
+		};
+	}
+	const mw = options.devMiddleware === true ? {} : options.devMiddleware;
+	let started;
 	return {
 		name: `devframe:${d.id}`,
 		apply: "serve",
-		configureServer(server) {
-			if (!distDir) return;
-			server.middlewares.use(base, sirv(resolve(distDir), {
-				dev: true,
-				single: true
-			}));
+		async configureServer(server) {
+			await started?.close().catch(() => {});
+			started = void 0;
+			let port;
+			try {
+				port = mw.port ?? await resolveDevServerPort(d, { host: mw.host });
+				started = await createDevServer(d, {
+					host: mw.host,
+					port,
+					flags: mw.flags,
+					openBrowser: false
+				});
+			} catch (e) {
+				logger.DF0033({
+					id: d.id,
+					reason: String(e)
+				}, { cause: e }).log();
+				return;
+			}
+			const metaPath = `${base}${DEVTOOLS_CONNECTION_META_FILENAME}`;
+			server.middlewares.use(metaPath, (_req, res) => {
+				res.setHeader("Content-Type", "application/json");
+				res.end(JSON.stringify({
+					backend: "websocket",
+					websocket: port
+				}));
+			});
+			server.httpServer?.once("close", () => {
+				started?.close().catch(() => {});
+			});
+		},
+		async closeBundle() {
+			await started?.close().catch(() => {});
+			started = void 0;
 		}
 	};
 }
+/**
+* Make `base` safe for `server.middlewares.use(path, …)`. Vite's connect
+* router matches by absolute URL prefix, so relative spellings like
+* `'./'` (commonly used for base-agnostic Nuxt builds) need to be
+* converted to `/` first.
+*/
+function normalizeMountBase(base) {
+	let out = base.replace(/^\.\/?/, "/");
+	if (!out.startsWith("/")) out = `/${out}`;
+	if (!out.endsWith("/")) out = `${out}/`;
+	return out.replace(/\/+/g, "/");
+}
 //#endregion
 export { createVitePlugin };

package/dist/chunk-e9Ob2GDo.mjs

@@ -0,0 +1,26 @@
+import { createRequire } from "node:module";
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+export { __require as n, __toESM as r, __commonJSMin as t };

package/dist/client/index.d.mts

@@ -1,7 +1,7 @@
-import { T as StreamSink, U as DevToolsRpcClientFunctions, W as DevToolsRpcServerFunctions, ct as EventEmitter, g as RpcSharedStateHost, l as ConnectionMeta, w as StreamReader } from "../devtool-CNvLs2_Y.mjs";
-import { _ as RpcCacheManager, v as RpcCacheOptions } from "../index-CuLRIMto.mjs";
-import { S as RpcFunctionsCollector } from "../types-C5OVe4AC.mjs";
-import { t as WsRpcChannelOptions } from "../ws-client-CjPuPFbA.mjs";
+import { M as StreamReader, N as StreamSink, Q as DevToolsRpcServerFunctions, Z as DevToolsRpcClientFunctions, _ as ConnectionMeta, pt as EventEmitter, w as RpcSharedStateHost } from "../devframe-DulcIxwu.mjs";
+import { m as RpcCacheOptions, p as RpcCacheManager } from "../index-DB2Ie0Or.mjs";
+import { S as RpcFunctionsCollector } from "../types-4rdUEi2R.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-Bavoya6-.mjs";
 import { BirpcOptions, BirpcReturn } from "birpc";
 
 //#region src/client/rpc-streaming.d.ts
@@ -131,4 +131,9 @@ interface DevToolsRpcClientMode {
 }
 declare function getDevToolsRpcClient(options?: DevToolsRpcClientOptions): Promise<DevToolsRpcClient>;
 //#endregion
-export { DevToolsClientRpcHost, DevToolsRpcClient, DevToolsRpcClientCall, DevToolsRpcClientCallEvent, DevToolsRpcClientCallOptional, DevToolsRpcClientMode, DevToolsRpcClientOptions, DevToolsRpcContext, RpcClientEvents, RpcStreamingClientHost, StreamingSubscribeOptions, getDevToolsRpcClient as connectDevtool, getDevToolsRpcClient, createRpcStreamingClientHost };
+//#region src/client/index.d.ts
+declare const connectDevframe: typeof getDevToolsRpcClient;
+/** @deprecated Use `connectDevframe`. */
+declare function connectDevtool(...args: Parameters<typeof getDevToolsRpcClient>): ReturnType<typeof getDevToolsRpcClient>;
+//#endregion
+export { DevToolsClientRpcHost, DevToolsRpcClient, DevToolsRpcClientCall, DevToolsRpcClientCallEvent, DevToolsRpcClientCallOptional, DevToolsRpcClientMode, DevToolsRpcClientOptions, DevToolsRpcContext, RpcClientEvents, RpcStreamingClientHost, StreamingSubscribeOptions, connectDevframe, connectDevtool, createRpcStreamingClientHost, getDevToolsRpcClient };