devframe 0.6.2 → 0.7.0

package/dist/adapters/build.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
+import { r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
 
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {

package/dist/adapters/cac.d.mts

@@ -0,0 +1,41 @@
+import { Dt as defineCliFlags, Et as InferCliFlags, Ot as parseCliFlags, Tt as CliFlagsSchema, r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
+import { CAC } from "cac";
+import { H3 } from "h3";
+
+//#region src/adapters/cac.d.ts
+interface CreateCacOptions {
+  /** Default port for `dev` (default: 9999). */
+  defaultPort?: number;
+  /**
+   * Final CAC hook invoked after devframe's built-in subcommands and
+   * after the definition's `cli.configure`. Use this to add app-level
+   * flags and commands at the assembly stage.
+   */
+  configureCli?: (cli: CAC) => void;
+  /**
+   * Called once the dev server is listening. Use this to print a
+   * startup banner or trigger side-effects that depend on the live URL.
+   */
+  onReady?: (info: {
+    origin: string;
+    port: number;
+    app: H3;
+  }) => void | Promise<void>;
+}
+interface CacHandle {
+  /**
+   * Raw CAC instance. Mutate before calling `parse()` for last-mile
+   * flag or command additions that don't fit `configureCli`.
+   */
+  cli: CAC;
+  parse: (argv?: string[]) => Promise<void>;
+}
+/**
+ * Wrap a {@link DevframeDefinition} in a `cac`-powered command-line
+ * interface exposing `dev` / `build` / `mcp` subcommands.
+ *
+ * Requires the optional `cac` peer dependency.
+ */
+declare function createCac(d: DevframeDefinition, options?: CreateCacOptions): CacHandle;
+//#endregion
+export { CacHandle, type CliFlagsSchema, CreateCacOptions, type InferCliFlags, createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/cac.mjs

@@ -0,0 +1,2 @@
+import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-DCBSjlzl.mjs";
+export { createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/cli.d.mts

@@ -1,35 +1,12 @@
-import { Dt as parseCliFlags, Et as defineCliFlags, Tt as InferCliFlags, r as DevframeDefinition, wt as CliFlagsSchema } from "../devframe-CpXy1ZlO.mjs";
-import { CAC } from "cac";
-import { H3 } from "h3";
+import { Dt as defineCliFlags, Et as InferCliFlags, Ot as parseCliFlags, Tt as CliFlagsSchema } from "../devframe-Dma0XG3U.mjs";
+import { CacHandle, CreateCacOptions, createCac } from "./cac.mjs";
 
 //#region src/adapters/cli.d.ts
-interface CreateCliOptions {
-  /** Default port for `dev` (default: 9999). */
-  defaultPort?: number;
-  /**
-   * Final CAC hook invoked after devframe's built-in subcommands and
-   * after the definition's `cli.configure`. Use this to add app-level
-   * flags and commands at the assembly stage.
-   */
-  configureCli?: (cli: CAC) => void;
-  /**
-   * Called once the dev server is listening. Use this to print a
-   * startup banner or trigger side-effects that depend on the live URL.
-   */
-  onReady?: (info: {
-    origin: string;
-    port: number;
-    app: H3;
-  }) => void | Promise<void>;
-}
-interface CliHandle {
-  /**
-   * Raw CAC instance. Mutate before calling `parse()` for last-mile
-   * flag or command additions that don't fit `configureCli`.
-   */
-  cli: CAC;
-  parse: (argv?: string[]) => Promise<void>;
-}
-declare function createCli(d: DevframeDefinition, options?: CreateCliOptions): CliHandle;
+/** @deprecated Use `createCac` from `devframe/adapters/cac` instead. */
+declare const createCli: typeof createCac;
+/** @deprecated Use `CreateCacOptions` from `devframe/adapters/cac` instead. */
+type CreateCliOptions = CreateCacOptions;
+/** @deprecated Use `CacHandle` from `devframe/adapters/cac` instead. */
+type CliHandle = CacHandle;
 //#endregion
 export { type CliFlagsSchema, CliHandle, CreateCliOptions, type InferCliFlags, createCli, defineCliFlags, parseCliFlags };

package/dist/adapters/cli.mjs

@@ -1,146 +1,6 @@
-import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
-import { createBuild } from "./build.mjs";
-import { n as resolveDevServerPort, t as createDevServer } from "../dev-DE51PeJc.mjs";
-import process from "node:process";
-import cac from "cac";
-import { safeParse } from "valibot";
-//#region src/adapters/flags.ts
-/**
-* Identity helper that preserves the literal schema-map type — use this
-* so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
-*
-* ```ts
-* const appFlags = defineCliFlags({
-*   depth: v.pipe(v.number(), v.integer()),
-*   config: v.optional(v.string()),
-* })
-*
-* defineDevframe({
-*   cli: { flags: appFlags },
-*   setup(ctx, info) {
-*     const flags = info.flags as InferCliFlags<typeof appFlags>
-*     flags.depth // number
-*     flags.config // string | undefined
-*   },
-* })
-* ```
-*/
-function defineCliFlags(flags) {
-	return flags;
-}
-/**
-* Best-effort probe of a valibot schema to decide whether the
-* corresponding CAC option takes a value. Unwraps `optional` / `nullable`
-* / `nullish` / `default` / `pipe` wrappers then matches on the inner
-* type's kind.
-*/
-function getSchemaKind(schema) {
-	let current = schema;
-	while (current) {
-		const kind = current.type;
-		if (kind === "optional" || kind === "nullable" || kind === "nullish" || kind === "undefined") {
-			current = current.wrapped ?? current.inner;
-			continue;
-		}
-		if (kind === "pipe" && Array.isArray(current.pipe) && current.pipe.length > 0) {
-			current = current.pipe[0];
-			continue;
-		}
-		return kind;
-	}
-	return "unknown";
-}
-/** Whether the CAC option for this schema should be a boolean flag. */
-function isBooleanFlag(schema) {
-	return getSchemaKind(schema) === "boolean";
-}
-/** Validate and coerce the raw cac-parsed bag against a {@link CliFlagsSchema}. */
-function parseCliFlags(schema, raw) {
-	const flags = {};
-	const issues = [];
-	for (const [key, fieldSchema] of Object.entries(schema)) {
-		const result = safeParse(fieldSchema, raw[key]);
-		if (result.success) flags[key] = result.output;
-		else issues.push(`--${toKebab(key)}: ${result.issues.map((i) => i.message).join(", ")}`);
-	}
-	for (const [key, value] of Object.entries(raw)) if (!(key in schema) && !(key in flags)) flags[key] = value;
-	return issues.length ? {
-		flags,
-		issues
-	} : { flags };
-}
-function toKebab(camel) {
-	return camel.replaceAll(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
-}
-/** Kebab-case a schema key for CAC option registration. */
-function flagKeyToOption(camel) {
-	return toKebab(camel);
-}
-//#endregion
+import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-DCBSjlzl.mjs";
 //#region src/adapters/cli.ts
-function createCli(d, options = {}) {
-	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
-	const defaultHost = d.cli?.host ?? "localhost";
-	const cli = cac(d.cli?.command ?? d.id);
-	const devCommand = cli.command("[...args]", "Start a local dev server").option("--port <port>", "Port to listen on").option("--host <host>", "Host to bind to", { default: defaultHost }).option("--open", "Open the browser on start").option("--no-open", "Do not open the browser").option("--mcp", "Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable) [experimental]");
-	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
-		const optionName = flagKeyToOption(key);
-		const description = schema.description ?? "";
-		if (isBooleanFlag(schema)) devCommand.option(`--${optionName}`, description);
-		else devCommand.option(`--${optionName} <value>`, description);
-	}
-	devCommand.action(async (_args, rawFlags) => {
-		const flags = resolveTypedFlags(d, rawFlags);
-		const host = flags.host ?? defaultHost;
-		const port = flags.port ?? await resolveDevServerPort(d, {
-			host,
-			defaultPort
-		});
-		const mcp = flags.mcp;
-		await createDevServer(d, {
-			host,
-			port,
-			flags,
-			mcp,
-			onReady: options.onReady
-		});
-	});
-	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,
-			pretty: flags.pretty
-		});
-	});
-	cli.command("mcp", "Start an MCP server exposing agent-facing tools (stdio) [experimental]").action(async () => {
-		const { createMcpServer } = await import("./mcp.mjs");
-		await createMcpServer(d, {
-			transport: "stdio",
-			onReady: ({ transport }) => {
-				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
-			}
-		});
-	});
-	d.cli?.configure?.(cli);
-	options.configureCli?.(cli);
-	cli.help();
-	cli.version("0.0.0");
-	return {
-		cli,
-		async parse(argv = process.argv) {
-			cli.parse(argv, { run: false });
-			await cli.runMatchedCommand();
-		}
-	};
-}
-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(colors.red`[devframe] invalid flag — ${issue}`);
-		process.exit(1);
-	}
-	return flags;
-}
+/** @deprecated Use `createCac` from `devframe/adapters/cac` instead. */
+const createCli = createCac;
 //#endregion
 export { createCli, defineCliFlags, parseCliFlags };

package/dist/adapters/dev.d.mts

@@ -1,5 +1,5 @@
-import { l as DevframeWsOptions, r as DevframeDefinition, u as McpRouteOptions } from "../devframe-CpXy1ZlO.mjs";
-import { n as StartedServer } from "../server-C83NJvZp.mjs";
+import { d as McpRouteOptions, r as DevframeDefinition, u as DevframeWsOptions } from "../devframe-Dma0XG3U.mjs";
+import { n as StartedServer } from "../server-BD-tKDVf.mjs";
 import { H3 } from "h3";
 
 //#region src/adapters/dev.d.ts
@@ -98,7 +98,7 @@ declare function resolveDevServerPort(def: DevframeDefinition, options?: Resolve
  *
  * Use this directly when integrating devframe into an existing CLI
  * framework (commander, yargs, hand-rolled CAC). For the all-in-one
- * `dev` / `build` / `mcp` shell, reach for {@link createCli} instead.
+ * `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
  */
 declare function createDevServer(def: DevframeDefinition, options?: CreateDevServerOptions): Promise<StartedServer>;
 //#endregion

package/dist/adapters/dev.mjs

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

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { h as DevframeNodeContext, r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
+import { g as DevframeNodeContext, r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
 
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {

package/dist/adapters/mcp.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
+import { r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
 //#region src/adapters/mcp/build-server.d.ts
 interface CreateMcpServerOptions {
   /**

package/dist/cac-DCBSjlzl.mjs

@@ -0,0 +1,152 @@
+import { n as colors } from "./diagnostics-reporter-CsIG85Q5.mjs";
+import { createBuild } from "./adapters/build.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "./dev-YeAm6GL0.mjs";
+import process from "node:process";
+import cac from "cac";
+import { safeParse } from "valibot";
+//#region src/adapters/flags.ts
+/**
+* Identity helper that preserves the literal schema-map type — use this
+* so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
+*
+* ```ts
+* const appFlags = defineCliFlags({
+*   depth: v.pipe(v.number(), v.integer()),
+*   config: v.optional(v.string()),
+* })
+*
+* defineDevframe({
+*   cli: { flags: appFlags },
+*   setup(ctx, info) {
+*     const flags = info.flags as InferCliFlags<typeof appFlags>
+*     flags.depth // number
+*     flags.config // string | undefined
+*   },
+* })
+* ```
+*/
+function defineCliFlags(flags) {
+	return flags;
+}
+/**
+* Best-effort probe of a valibot schema to decide whether the
+* corresponding CAC option takes a value. Unwraps `optional` / `nullable`
+* / `nullish` / `default` / `pipe` wrappers then matches on the inner
+* type's kind.
+*/
+function getSchemaKind(schema) {
+	let current = schema;
+	while (current) {
+		const kind = current.type;
+		if (kind === "optional" || kind === "nullable" || kind === "nullish" || kind === "undefined") {
+			current = current.wrapped ?? current.inner;
+			continue;
+		}
+		if (kind === "pipe" && Array.isArray(current.pipe) && current.pipe.length > 0) {
+			current = current.pipe[0];
+			continue;
+		}
+		return kind;
+	}
+	return "unknown";
+}
+/** Whether the CAC option for this schema should be a boolean flag. */
+function isBooleanFlag(schema) {
+	return getSchemaKind(schema) === "boolean";
+}
+/** Validate and coerce the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+function parseCliFlags(schema, raw) {
+	const flags = {};
+	const issues = [];
+	for (const [key, fieldSchema] of Object.entries(schema)) {
+		const result = safeParse(fieldSchema, raw[key]);
+		if (result.success) flags[key] = result.output;
+		else issues.push(`--${toKebab(key)}: ${result.issues.map((i) => i.message).join(", ")}`);
+	}
+	for (const [key, value] of Object.entries(raw)) if (!(key in schema) && !(key in flags)) flags[key] = value;
+	return issues.length ? {
+		flags,
+		issues
+	} : { flags };
+}
+function toKebab(camel) {
+	return camel.replaceAll(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Kebab-case a schema key for CAC option registration. */
+function flagKeyToOption(camel) {
+	return toKebab(camel);
+}
+//#endregion
+//#region src/adapters/cac.ts
+/**
+* Wrap a {@link DevframeDefinition} in a `cac`-powered command-line
+* interface exposing `dev` / `build` / `mcp` subcommands.
+*
+* Requires the optional `cac` peer dependency.
+*/
+function createCac(d, options = {}) {
+	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
+	const defaultHost = d.cli?.host ?? "localhost";
+	const cli = cac(d.cli?.command ?? d.id);
+	const devCommand = cli.command("[...args]", "Start a local dev server").option("--port <port>", "Port to listen on").option("--host <host>", "Host to bind to", { default: defaultHost }).option("--open", "Open the browser on start").option("--no-open", "Do not open the browser").option("--mcp", "Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable) [experimental]");
+	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
+		const optionName = flagKeyToOption(key);
+		const description = schema.description ?? "";
+		if (isBooleanFlag(schema)) devCommand.option(`--${optionName}`, description);
+		else devCommand.option(`--${optionName} <value>`, description);
+	}
+	devCommand.action(async (_args, rawFlags) => {
+		const flags = resolveTypedFlags(d, rawFlags);
+		const host = flags.host ?? defaultHost;
+		const port = flags.port ?? await resolveDevServerPort(d, {
+			host,
+			defaultPort
+		});
+		const mcp = flags.mcp;
+		await createDevServer(d, {
+			host,
+			port,
+			flags,
+			mcp,
+			onReady: options.onReady
+		});
+	});
+	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,
+			pretty: flags.pretty
+		});
+	});
+	cli.command("mcp", "Start an MCP server exposing agent-facing tools (stdio) [experimental]").action(async () => {
+		const { createMcpServer } = await import("./adapters/mcp.mjs");
+		await createMcpServer(d, {
+			transport: "stdio",
+			onReady: ({ transport }) => {
+				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
+			}
+		});
+	});
+	d.cli?.configure?.(cli);
+	options.configureCli?.(cli);
+	cli.help();
+	cli.version("0.0.0");
+	return {
+		cli,
+		async parse(argv = process.argv) {
+			cli.parse(argv, { run: false });
+			await cli.runMatchedCommand();
+		}
+	};
+}
+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(colors.red`[devframe] invalid flag — ${issue}`);
+		process.exit(1);
+	}
+	return flags;
+}
+//#endregion
+export { defineCliFlags as n, parseCliFlags as r, createCac as t };

package/dist/client/index.d.mts

@@ -1,9 +1,58 @@
-import { O as StreamReader, R as SharedState, Y as DevframeSettings, at as DevframeRpcServerFunctions, b as RpcSharedStateHost, et as ScopedServerFunctions, f as ConnectionMeta, it as DevframeRpcClientFunctions, k as StreamSink, nt as SettingsForNamespace, tt as ScopedSharedStates, xt as EventEmitter, y as RpcSharedStateGetOptions } from "../devframe-CpXy1ZlO.mjs";
+import { A as StreamSink, St as EventEmitter, X as DevframeSettings, at as DevframeRpcClientFunctions, b as RpcSharedStateGetOptions, k as StreamReader, nt as ScopedSharedStates, ot as DevframeRpcServerFunctions, p as ConnectionMeta, rt as SettingsForNamespace, tt as ScopedServerFunctions, x as RpcSharedStateHost, z as SharedState } from "../devframe-Dma0XG3U.mjs";
 import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-oEqKqUC9.mjs";
 import { C as RpcCacheManager, w as RpcCacheOptions } from "../index-DI_TMGjv.mjs";
 import { t as WsRpcChannelOptions } from "../ws-client-nBjpin71.mjs";
 import { BirpcOptions, BirpcReturn } from "birpc";
 
+//#region src/client/connection.d.ts
+/**
+ * The connection lifecycle of a devframe client, as a single value a UI can
+ * render from. Derived from the transport (WebSocket open/close/error) and the
+ * trust handshake, so a viewer never has to reason about the two dimensions
+ * separately.
+ *
+ * - `connecting` — establishing the WebSocket / running the initial trust
+ *   handshake. Calls issued here queue until the socket opens.
+ * - `connected` — socket open and trusted; RPC calls will be served.
+ * - `unauthorized` — socket open but the server rejected trust (no valid token,
+ *   or an auth-enforcing host refused it). Calls fail fast with an auth error;
+ *   the UI should prompt for re-authentication or a reload.
+ * - `disconnected` — the socket closed (dropped mid-session, or never opened).
+ *   Pending and new calls fail fast until the page reconnects.
+ * - `error` — a fatal connection error (e.g. the WebSocket errored, or the
+ *   connection meta could not be loaded).
+ *
+ * A `static` backend has no live socket, so it reports `connected` for its
+ * whole life.
+ */
+type DevframeConnectionStatus = 'connecting' | 'connected' | 'unauthorized' | 'disconnected' | 'error';
+/**
+ * What kind of failure a {@link DevframeConnectionError} describes:
+ * - `connection` — the transport dropped, errored, or never opened.
+ * - `auth` — the server rejected trust for this client.
+ * - `timeout` — a call exceeded its {@link DevframeRpcClientOptions.callTimeout}.
+ */
+type DevframeConnectionErrorKind = 'connection' | 'auth' | 'timeout';
+/**
+ * The error rejected from `rpc.call(...)` (and carried on
+ * `rpc.connectionError`) when a call cannot be served because the connection is
+ * down, the client is unauthorized, or a call timed out. Its `kind` lets a UI
+ * tailor its message and recovery affordance without string-matching.
+ */
+declare class DevframeConnectionError extends Error {
+  name: string;
+  readonly kind: DevframeConnectionErrorKind;
+  constructor(kind: DevframeConnectionErrorKind, message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Whether a status means calls can be attempted. `connecting` counts because
+ * the transport queues outgoing calls until the socket opens; the terminal
+ * failure states short-circuit calls so a stuck socket never hangs the UI.
+ */
+declare function isCallableStatus(status: DevframeConnectionStatus): boolean;
+//#endregion
 //#region src/client/rpc-streaming.d.ts
 interface StreamingSubscribeOptions {
   /** Maximum buffered chunks before the oldest is dropped. Default 256. */
@@ -119,6 +168,21 @@ interface DevframeRpcContext {
 type DevframeClientRpcHost = RpcFunctionsCollector<DevframeRpcClientFunctions, DevframeRpcContext>;
 interface RpcClientEvents {
   'rpc:is-trusted:updated': (isTrusted: boolean) => void;
+  /**
+   * The connection status changed. Carries the new status and the previous one
+   * so a UI can react to specific transitions (e.g. `connected` → `disconnected`).
+   */
+  'connection:status': (status: DevframeConnectionStatus, previous: DevframeConnectionStatus) => void;
+  /**
+   * A connection-level error occurred (the WebSocket errored, or trust was
+   * refused). The status typically moves to `error`/`unauthorized` alongside it.
+   */
+  'connection:error': (error: Error) => void;
+  /**
+   * An RPC call rejected — either from the server, or because the connection
+   * was down / timed out. Useful for a global error feed or toast surface.
+   */
+  'rpc:error': (error: Error, method: string) => void;
 }
 interface DevframeRpcClientOptions {
   connectionMeta?: ConnectionMeta;
@@ -138,6 +202,14 @@ interface DevframeRpcClientOptions {
   wsOptions?: Partial<WsRpcChannelOptions>;
   rpcOptions?: Partial<BirpcOptions<DevframeRpcServerFunctions, DevframeRpcClientFunctions, boolean>>;
   cacheOptions?: boolean | Partial<RpcCacheOptions>;
+  /**
+   * Reject a pending `rpc.call(...)` if the server hasn't answered within this
+   * many milliseconds, with a {@link DevframeConnectionError} of kind
+   * `'timeout'`. Guards against a live-but-unresponsive server hanging the UI.
+   * Omit (or `0`) to wait indefinitely. Calls always fail fast — regardless of
+   * this option — once the socket closes or trust is refused.
+   */
+  callTimeout?: number;
 }
 type DevframeRpcClientCall = BirpcReturn<DevframeRpcServerFunctions, DevframeRpcClientFunctions>['$call'];
 type DevframeRpcClientCallEvent = BirpcReturn<DevframeRpcServerFunctions, DevframeRpcClientFunctions>['$callEvent'];
@@ -151,6 +223,17 @@ interface DevframeRpcClient {
    * Whether the client is trusted
    */
   readonly isTrusted: boolean | null;
+  /**
+   * The current connection status. Drives connection/auth/error UI without the
+   * consumer having to track the transport and trust handshake separately.
+   * Subscribe to `events.on('connection:status', …)` to react to changes.
+   */
+  readonly status: DevframeConnectionStatus;
+  /**
+   * The most recent connection-level error (WebSocket error, refused trust, or
+   * failed connection-meta load), or `null` when the connection is healthy.
+   */
+  readonly connectionError: Error | null;
   /**
    * The connection meta
    */
@@ -225,6 +308,8 @@ interface DevframeRpcClient {
 }
 interface DevframeRpcClientMode {
   readonly isTrusted: boolean;
+  readonly status: DevframeConnectionStatus;
+  readonly connectionError: Error | null;
   ensureTrusted: DevframeRpcClient['ensureTrusted'];
   requestTrust: DevframeRpcClient['requestTrust'];
   requestTrustWithToken: DevframeRpcClient['requestTrustWithToken'];
@@ -276,4 +361,4 @@ declare function createClientSettings<T extends Record<string, any> = Record<str
 //#region src/client/index.d.ts
 declare const connectDevframe: typeof getDevframeRpcClient;
 //#endregion
-export { DevframeClientRpcHost, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, RpcClientEvents, RpcStreamingClientHost, StreamingSubscribeOptions, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, readOtpFromUrl };
+export { DevframeClientRpcHost, DevframeConnectionError, DevframeConnectionErrorKind, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, RpcClientEvents, RpcStreamingClientHost, StreamingSubscribeOptions, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, isCallableStatus, readOtpFromUrl };

package/dist/client/index.mjs

@@ -505,6 +505,8 @@ async function createStaticRpcClientMode(options) {
 	const staticCaller = createStaticRpcCaller(await options.fetchJsonFromBases(DEVFRAME_RPC_DUMP_MANIFEST_FILENAME), options.fetchJsonFromBases);
 	return {
 		isTrusted: true,
+		status: "connected",
+		connectionError: null,
 		requestTrust: async () => true,
 		requestTrustWithToken: async () => true,
 		requestTrustWithCode: async () => null,
@@ -1857,6 +1859,30 @@ function parseUA(uastringOrExtensions, extensions) {
 	};
 }
 //#endregion
+//#region src/client/connection.ts
+/**
+* The error rejected from `rpc.call(...)` (and carried on
+* `rpc.connectionError`) when a call cannot be served because the connection is
+* down, the client is unauthorized, or a call timed out. Its `kind` lets a UI
+* tailor its message and recovery affordance without string-matching.
+*/
+var DevframeConnectionError = class extends Error {
+	name = "DevframeConnectionError";
+	kind;
+	constructor(kind, message, options) {
+		super(message, options);
+		this.kind = kind;
+	}
+};
+/**
+* Whether a status means calls can be attempted. `connecting` counts because
+* the transport queues outgoing calls until the socket opens; the terminal
+* failure states short-circuit calls so a stuck socket never hangs the UI.
+*/
+function isCallableStatus(status) {
+	return status === "connected" || status === "connecting";
+}
+//#endregion
 //#region src/client/rpc-ws.ts
 /**
 * Resolve a {@link ConnectionMeta.websocket} descriptor into a concrete
@@ -1899,10 +1925,65 @@ function resolveWsUrl(websocket, metaBaseUrl, loc) {
 	return target.href;
 }
 function createWsRpcClientMode(options) {
-	const { authToken, connectionMeta, metaBaseUrl, events, clientRpc, rpcOptions = {}, wsOptions = {} } = options;
+	const { authToken, connectionMeta, metaBaseUrl, events, clientRpc, rpcOptions = {}, wsOptions = {}, callTimeout = 0 } = options;
 	let isTrusted = false;
+	let status = "connecting";
+	let connectionError = null;
 	const trustedPromise = promiseWithResolver();
 	const url = resolveWsUrl(connectionMeta.websocket, metaBaseUrl ?? "./", location);
+	function setStatus(next, error = null) {
+		if (error) connectionError = error;
+		else if (next === "connected") connectionError = null;
+		if (next === status) return;
+		const previous = status;
+		status = next;
+		events.emit("connection:status", next, previous);
+	}
+	const pending = /* @__PURE__ */ new Set();
+	function rejectAllPending(error) {
+		for (const entry of [...pending]) entry.reject(error);
+	}
+	function terminalError() {
+		if (status === "disconnected" || status === "error") return new DevframeConnectionError("connection", "[devframe] Not connected to the devframe server", { cause: connectionError ?? void 0 });
+		if (status === "unauthorized") return new DevframeConnectionError("auth", "[devframe] Not authorized by the devframe server", { cause: connectionError ?? void 0 });
+		return null;
+	}
+	/**
+	* Wrap an in-flight call promise so it settles on server response, on an
+	* optional wall-clock timeout, or when the connection drops — never hangs.
+	*/
+	function guardCall(promise, method) {
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let timer;
+			const entry = { reject(error) {
+				if (settled) return;
+				finish();
+				events.emit("rpc:error", error, method);
+				reject(error);
+			} };
+			function finish() {
+				settled = true;
+				pending.delete(entry);
+				if (timer) clearTimeout(timer);
+			}
+			pending.add(entry);
+			if (callTimeout > 0) timer = setTimeout(() => {
+				entry.reject(new DevframeConnectionError("timeout", `[devframe] RPC call "${method}" timed out after ${callTimeout}ms`));
+			}, callTimeout);
+			promise.then((value) => {
+				if (settled) return;
+				finish();
+				resolve(value);
+			}, (error) => {
+				if (settled) return;
+				finish();
+				const err = error instanceof Error ? error : new Error(String(error));
+				events.emit("rpc:error", err, method);
+				reject(err);
+			});
+		});
+	}
 	const definitions = /* @__PURE__ */ new Map();
 	for (const name of connectionMeta.jsonSerializableMethods ?? []) definitions.set(name, { jsonSerializable: true });
 	const serverRpc = createRpcClient(clientRpc.functions, {
@@ -1910,7 +1991,21 @@ function createWsRpcClientMode(options) {
 			url,
 			authToken,
 			definitions,
-			...wsOptions
+			...wsOptions,
+			onConnected(event) {
+				wsOptions.onConnected?.(event);
+			},
+			onError(error) {
+				setStatus("error", error);
+				events.emit("connection:error", error);
+				rejectAllPending(new DevframeConnectionError("connection", "[devframe] Connection to the devframe server failed", { cause: error }));
+				wsOptions.onError?.(error);
+			},
+			onDisconnected(event) {
+				if (status !== "error") setStatus("disconnected");
+				rejectAllPending(new DevframeConnectionError("connection", "[devframe] Disconnected from the devframe server", { cause: connectionError ?? void 0 }));
+				wsOptions.onDisconnected?.(event);
+			}
 		}),
 		rpcOptions
 	});
@@ -1919,6 +2014,10 @@ function createWsRpcClientMode(options) {
 		type: "event",
 		handler: () => {
 			isTrusted = false;
+			const authError = new DevframeConnectionError("auth", "[devframe] The devframe server revoked this client's trust");
+			setStatus("unauthorized", authError);
+			events.emit("connection:error", authError);
+			rejectAllPending(authError);
 			events.emit("rpc:is-trusted:updated", false);
 		}
 	});
@@ -1942,7 +2041,14 @@ function createWsRpcClientMode(options) {
 			origin: location.origin
 		});
 		isTrusted = result.isTrusted;
-		if (isTrusted) trustedPromise.resolve(true);
+		if (isTrusted) {
+			trustedPromise.resolve(true);
+			setStatus("connected");
+		} else {
+			const authError = new DevframeConnectionError("auth", "[devframe] The devframe server refused this client's credentials");
+			setStatus("unauthorized", authError);
+			events.emit("connection:error", authError);
+		}
 		events.emit("rpc:is-trusted:updated", isTrusted);
 		return result.isTrusted;
 	}
@@ -1956,6 +2062,7 @@ function createWsRpcClientMode(options) {
 			currentAuthToken = token;
 			isTrusted = true;
 			trustedPromise.resolve(true);
+			setStatus("connected");
 			events.emit("rpc:is-trusted:updated", true);
 		}
 		return token;
@@ -1980,18 +2087,41 @@ function createWsRpcClientMode(options) {
 		get isTrusted() {
 			return isTrusted;
 		},
+		get status() {
+			return status;
+		},
+		get connectionError() {
+			return connectionError;
+		},
 		requestTrust,
 		requestTrustWithToken,
 		requestTrustWithCode,
 		ensureTrusted,
 		call: (...args) => {
-			return serverRpc.$call(...args);
+			const method = String(args[0]);
+			const failFast = terminalError();
+			if (failFast) {
+				events.emit("rpc:error", failFast, method);
+				return Promise.reject(failFast);
+			}
+			return guardCall(serverRpc.$call(...args), method);
 		},
 		callEvent: (...args) => {
+			const failFast = terminalError();
+			if (failFast) {
+				events.emit("rpc:error", failFast, String(args[0]));
+				return;
+			}
 			return serverRpc.$callEvent(...args);
 		},
 		callOptional: (...args) => {
-			return serverRpc.$callOptional(...args);
+			const method = String(args[0]);
+			const failFast = terminalError();
+			if (failFast) {
+				events.emit("rpc:error", failFast, method);
+				return Promise.reject(failFast);
+			}
+			return guardCall(serverRpc.$callOptional(...args), method);
 		}
 	};
 }
@@ -2156,6 +2286,7 @@ async function getDevframeRpcClient(options = {}) {
 		metaBaseUrl: resolveMetaBaseUrl(),
 		events,
 		clientRpc,
+		callTimeout: options.callTimeout,
 		rpcOptions: {
 			...rpcOptions,
 			async onRequest(req, next, resolve) {
@@ -2178,6 +2309,12 @@ async function getDevframeRpcClient(options = {}) {
 		get isTrusted() {
 			return mode.isTrusted;
 		},
+		get status() {
+			return mode.status;
+		},
+		get connectionError() {
+			return mode.connectionError;
+		},
 		connectionMeta,
 		ensureTrusted: mode.ensureTrusted,
 		requestTrust: mode.requestTrust,
@@ -2231,4 +2368,4 @@ async function getDevframeRpcClient(options = {}) {
 //#region src/client/index.ts
 const connectDevframe = getDevframeRpcClient;
 //#endregion
-export { authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, readOtpFromUrl };
+export { DevframeConnectionError, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, isCallableStatus, readOtpFromUrl };

package/dist/{context-DgkYTlXx.d.mts → context-BsiCAEC4.d.mts}

@@ -1,4 +1,4 @@
-import { R as SharedState, h as DevframeNodeContext } from "./devframe-CpXy1ZlO.mjs";
+import { g as DevframeNodeContext, z as SharedState } from "./devframe-Dma0XG3U.mjs";
 
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {

package/dist/{dev-DE51PeJc.mjs → dev-YeAm6GL0.mjs}

@@ -262,7 +262,7 @@ async function resolveDevServerPort(def, options = {}) {
 *
 * Use this directly when integrating devframe into an existing CLI
 * framework (commander, yargs, hand-rolled CAC). For the all-in-one
-* `dev` / `build` / `mcp` shell, reach for {@link createCli} instead.
+* `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
 */
 async function createDevServer(def, options = {}) {
 	const distDir = options.distDir ?? def.cli?.distDir;

package/dist/{devframe-CpXy1ZlO.d.mts → devframe-Dma0XG3U.d.mts}

@@ -1378,7 +1378,7 @@ interface DevframeCliOptions {
   /**
    * Capability-side CAC hook. Called with the CAC instance after the
    * adapter registers its built-in commands (`build` / `spa` / `mcp`)
-   * but before `createCli`'s own `configureCli` caller. Use this to
+   * but before `createCac`'s own `configureCli` caller. Use this to
    * contribute tool-specific flags and subcommands from the definition
    * itself.
    */
@@ -1409,6 +1409,44 @@ interface DevframeCliOptions {
    */
   flags?: CliFlagsSchema;
 }
+/**
+ * Default dock attributes for the iframe entry a hub synthesizes when it
+ * mounts this devframe. Framework-neutral metadata only — the hub layer
+ * (`mountDevframe`) merges these beneath its per-mount `dock` overrides,
+ * which in turn sit beneath the locked, derived `id` / `type` / `url`.
+ *
+ * Every field is optional. `title` / `icon` default to the definition's
+ * `name` / `icon` when omitted here; the rest are unset by default.
+ * Standalone adapters (`cli` / `spa` / `build`) ignore this entirely.
+ */
+interface DevframeDockDefaults {
+  /** Dock entry title. Defaults to the definition's `name`. */
+  title?: string;
+  /** Dock entry icon. Defaults to the definition's `icon`. */
+  icon?: string | {
+    light: string;
+    dark: string;
+  };
+  /**
+   * Sort weight within the dock; higher sorts earlier.
+   * @default 0
+   */
+  defaultOrder?: number;
+  /**
+   * Category the entry groups under in the dock.
+   * @default 'default'
+   */
+  category?: string;
+  /**
+   * Conditional-visibility expression (same syntax as command `when`
+   * clauses). Set to `'false'` to hide the entry unconditionally.
+   */
+  when?: string;
+  /** Badge text rendered on the dock icon (e.g. an unread count). */
+  badge?: string;
+  /** Id of the dock group this entry collapses under, if any. */
+  groupId?: string;
+}
 interface DevframeSpaOptions {
   base?: string;
   /**
@@ -1428,7 +1466,7 @@ interface DevframeBrowserContext {
 /**
  * Runtime information threaded into `setup(ctx, info)`. Adapters
  * populate the fields that make sense for their deployment. In
- * particular, `createCli` fills `flags` with the parsed CAC bag.
+ * particular, `createCac` fills `flags` with the parsed CAC bag.
  */
 interface DevframeSetupInfo {
   /** Parsed CLI flags, populated by the CLI adapter. */
@@ -1449,6 +1487,15 @@ interface DevframeDefinition {
     light: string;
     dark: string;
   };
+  /**
+   * Default dock attributes applied when a hub mounts this devframe as an
+   * iframe dock entry. Consulted only by hub adapters (`mountDevframe`),
+   * which merge these beneath the per-mount `dock` overrides; standalone
+   * adapters (`cli` / `spa` / `build`) ignore it.
+   *
+   * @see {@link DevframeDockDefaults}
+   */
+  dock?: DevframeDockDefaults;
   /**
    * Mount path override. Defaults depend on the adapter:
    * `/` for standalone (`cli` / `spa` / `build`), `/__<id>/` for hosted
@@ -1478,4 +1525,4 @@ interface DevframeDefinition {
 }
 declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { ScopedClientFunctions as $, StreamSinkEvents as A, SharedStateOptions as B, RpcStreamingHost as C, EventsMap as Ct, StreamErrorPayload as D, parseCliFlags as Dt, CreateStreamSinkOptions as E, defineCliFlags as Et, ImmutableMap as F, Thenable as G, createSharedState as H, ImmutableObject as I, DevframeScopedStreamingHost as J, DevframeScopedNodeContext as K, ImmutableSet as L, createStreamSink as M, Immutable as N, StreamReader as O, ImmutableArray as P, ScopedBroadcastOptions as Q, SharedState as R, RpcStreamingChannelOptions as S, EventUnsubscribe as St, CreateStreamReaderOptions as T, InferCliFlags as Tt, EntriesToObject as U, SharedStatePatch as V, PartialWithoutId as W, DevframeSettingsRegistry as X, DevframeSettings as Y, DevframeSettingsStore as Z, RpcBroadcastOptions as _, AgentTool as _t, DevframeDuplicationStrategy as a, DevframeRpcServerFunctions as at, RpcSharedStateHost as b, DevframeAgentHostEvents as bt, DevframeSpaOptions as c, DevframeDefineDiagnosticsOptions as ct, defineDevframe as d, DevframeDiagnosticsLogger as dt, ScopedServerFunctions as et, ConnectionMeta as f, AgentHandle as ft, DevframeNodeRpcSession as g, AgentResourceInput as gt, DevframeNodeContext as h, AgentResourceContent as ht, DevframeDeploymentKind as i, DevframeRpcClientFunctions as it, createStreamReader as j, StreamSink as k, DevframeWsOptions as l, DevframeDiagnosticsDefinition as lt, DevframeCapabilities as m, AgentResource as mt, DevframeCliOptions as n, SettingsForNamespace as nt, DevframeRuntime as o, DevframeRpcSharedStates as ot, ConnectionMetaWebsocket as p, AgentManifest as pt, DevframeScopedNodeRpc as q, DevframeDefinition as r, DevframeViewHost as rt, DevframeSetupInfo as s, DevframeHost as st, DevframeBrowserContext as t, ScopedSharedStates as tt, McpRouteOptions as u, DevframeDiagnosticsHost as ut, RpcFunctionsHost as v, AgentToolInput as vt, BufferedChunk as w, CliFlagsSchema as wt, RpcStreamingChannel as x, EventEmitter as xt, RpcSharedStateGetOptions as y, DevframeAgentHost as yt, SharedStateEvents as z };
+export { ScopedBroadcastOptions as $, StreamSink as A, SharedStateEvents as B, RpcStreamingChannelOptions as C, EventUnsubscribe as Ct, CreateStreamSinkOptions as D, defineCliFlags as Dt, CreateStreamReaderOptions as E, InferCliFlags as Et, ImmutableArray as F, PartialWithoutId as G, SharedStatePatch as H, ImmutableMap as I, DevframeScopedNodeRpc as J, Thenable as K, ImmutableObject as L, createStreamReader as M, createStreamSink as N, StreamErrorPayload as O, parseCliFlags as Ot, Immutable as P, DevframeSettingsStore as Q, ImmutableSet as R, RpcStreamingChannel as S, EventEmitter as St, BufferedChunk as T, CliFlagsSchema as Tt, createSharedState as U, SharedStateOptions as V, EntriesToObject as W, DevframeSettings as X, DevframeScopedStreamingHost as Y, DevframeSettingsRegistry as Z, DevframeNodeRpcSession as _, AgentResourceInput as _t, DevframeDockDefaults as a, DevframeRpcClientFunctions as at, RpcSharedStateGetOptions as b, DevframeAgentHost as bt, DevframeSetupInfo as c, DevframeHost as ct, McpRouteOptions as d, DevframeDiagnosticsHost as dt, ScopedClientFunctions as et, defineDevframe as f, DevframeDiagnosticsLogger as ft, DevframeNodeContext as g, AgentResourceContent as gt, DevframeCapabilities as h, AgentResource as ht, DevframeDeploymentKind as i, DevframeViewHost as it, StreamSinkEvents as j, StreamReader as k, DevframeSpaOptions as l, DevframeDefineDiagnosticsOptions as lt, ConnectionMetaWebsocket as m, AgentManifest as mt, DevframeCliOptions as n, ScopedSharedStates as nt, DevframeDuplicationStrategy as o, DevframeRpcServerFunctions as ot, ConnectionMeta as p, AgentHandle as pt, DevframeScopedNodeContext as q, DevframeDefinition as r, SettingsForNamespace as rt, DevframeRuntime as s, DevframeRpcSharedStates as st, DevframeBrowserContext as t, ScopedServerFunctions as tt, DevframeWsOptions as u, DevframeDiagnosticsDefinition as ut, RpcBroadcastOptions as v, AgentTool as vt, RpcStreamingHost as w, EventsMap as wt, RpcSharedStateHost as x, DevframeAgentHostEvents as xt, RpcFunctionsHost as y, AgentToolInput as yt, SharedState as z };

package/dist/helpers/vite.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
+import { r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
 
 //#region src/helpers/vite.d.ts
 interface ViteDevBridgeOptions {
@@ -58,7 +58,7 @@ interface DevframeVitePlugin {
  *
  * 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.
+ * `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
  */
 declare function viteDevBridge(d: DevframeDefinition, options?: ViteDevBridgeOptions): DevframeVitePlugin;
 //#endregion

package/dist/helpers/vite.mjs

@@ -2,7 +2,7 @@ import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_WS_ROUTE } from "../constan
 import { a as diagnostics } from "../storage-yrUZaiib.mjs";
 import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-bWRzeSa0.mjs";
 import { serveStaticNodeMiddleware } from "../utils/serve-static.mjs";
-import { n as resolveDevServerPort, t as createDevServer } from "../dev-DE51PeJc.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "../dev-YeAm6GL0.mjs";
 import { resolve } from "pathe";
 //#region src/helpers/vite.ts
 /**
@@ -21,7 +21,7 @@ import { resolve } from "pathe";
 *
 * 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.
+* `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
 */
 function viteDevBridge(d, options = {}) {
 	const base = normalizeMountBase(options.base ?? resolveBasePath(d, "hosted"));

package/dist/{index-DzeFcwMM.d.mts → index-d40ZLcYw.d.mts}

@@ -1,6 +1,6 @@
-import { R as SharedState, g as DevframeNodeRpcSession, h as DevframeNodeContext } from "./devframe-CpXy1ZlO.mjs";
+import { _ as DevframeNodeRpcSession, g as DevframeNodeContext, z as SharedState } from "./devframe-Dma0XG3U.mjs";
 import { v as RpcFunctionDefinitionAny } from "./types-oEqKqUC9.mjs";
-import { n as InternalAnonymousAuthStorage } from "./context-DgkYTlXx.mjs";
+import { n as InternalAnonymousAuthStorage } from "./context-BsiCAEC4.mjs";
 import { Peer } from "crossws";
 
 //#region src/node/auth/handler.d.ts

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as ScopedClientFunctions, C as RpcStreamingHost, Ct as EventsMap, G as Thenable, J as DevframeScopedStreamingHost, K as DevframeScopedNodeContext, Q as ScopedBroadcastOptions, S as RpcStreamingChannelOptions, St as EventUnsubscribe, U as EntriesToObject, W as PartialWithoutId, X as DevframeSettingsRegistry, Y as DevframeSettings, Z as DevframeSettingsStore, _ as RpcBroadcastOptions, _t as AgentTool, a as DevframeDuplicationStrategy, at as DevframeRpcServerFunctions, b as RpcSharedStateHost, bt as DevframeAgentHostEvents, c as DevframeSpaOptions, ct as DevframeDefineDiagnosticsOptions, d as defineDevframe, dt as DevframeDiagnosticsLogger, et as ScopedServerFunctions, f as ConnectionMeta, ft as AgentHandle, g as DevframeNodeRpcSession, gt as AgentResourceInput, h as DevframeNodeContext, ht as AgentResourceContent, i as DevframeDeploymentKind, it as DevframeRpcClientFunctions, l as DevframeWsOptions, lt as DevframeDiagnosticsDefinition, m as DevframeCapabilities, mt as AgentResource, n as DevframeCliOptions, nt as SettingsForNamespace, o as DevframeRuntime, ot as DevframeRpcSharedStates, p as ConnectionMetaWebsocket, pt as AgentManifest, q as DevframeScopedNodeRpc, r as DevframeDefinition, rt as DevframeViewHost, s as DevframeSetupInfo, st as DevframeHost, t as DevframeBrowserContext, tt as ScopedSharedStates, u as McpRouteOptions, ut as DevframeDiagnosticsHost, v as RpcFunctionsHost, vt as AgentToolInput, x as RpcStreamingChannel, xt as EventEmitter, y as RpcSharedStateGetOptions, yt as DevframeAgentHost } from "./devframe-CpXy1ZlO.mjs";
+import { $ as ScopedBroadcastOptions, C as RpcStreamingChannelOptions, Ct as EventUnsubscribe, G as PartialWithoutId, J as DevframeScopedNodeRpc, K as Thenable, Q as DevframeSettingsStore, S as RpcStreamingChannel, St as EventEmitter, W as EntriesToObject, X as DevframeSettings, Y as DevframeScopedStreamingHost, Z as DevframeSettingsRegistry, _ as DevframeNodeRpcSession, _t as AgentResourceInput, a as DevframeDockDefaults, at as DevframeRpcClientFunctions, b as RpcSharedStateGetOptions, bt as DevframeAgentHost, c as DevframeSetupInfo, ct as DevframeHost, d as McpRouteOptions, dt as DevframeDiagnosticsHost, et as ScopedClientFunctions, f as defineDevframe, ft as DevframeDiagnosticsLogger, g as DevframeNodeContext, gt as AgentResourceContent, h as DevframeCapabilities, ht as AgentResource, i as DevframeDeploymentKind, it as DevframeViewHost, l as DevframeSpaOptions, lt as DevframeDefineDiagnosticsOptions, m as ConnectionMetaWebsocket, mt as AgentManifest, n as DevframeCliOptions, nt as ScopedSharedStates, o as DevframeDuplicationStrategy, ot as DevframeRpcServerFunctions, p as ConnectionMeta, pt as AgentHandle, q as DevframeScopedNodeContext, r as DevframeDefinition, rt as SettingsForNamespace, s as DevframeRuntime, st as DevframeRpcSharedStates, t as DevframeBrowserContext, tt as ScopedServerFunctions, u as DevframeWsOptions, ut as DevframeDiagnosticsDefinition, v as RpcBroadcastOptions, vt as AgentTool, w as RpcStreamingHost, wt as EventsMap, x as RpcSharedStateHost, xt as DevframeAgentHostEvents, y as RpcFunctionsHost, yt as AgentToolInput } from "./devframe-Dma0XG3U.mjs";
 import { C as RpcFunctionType, T as RpcReturnSchema, _ as RpcFunctionDefinition, g as RpcFunctionAgentOptions, i as RpcArgsSchema } from "./types-oEqKqUC9.mjs";
 import { t as DevframeNodeRpcSessionMeta } from "./ws-server-BUgJpdX4.mjs";
 
 //#region src/define.d.ts
 declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>;
 //#endregion
-export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type ConnectionMeta, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeBrowserContext, type DevframeCapabilities, type DevframeCliOptions, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRuntime, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSpaOptions, type DevframeViewHost, type DevframeWsOptions, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type PartialWithoutId, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type Thenable, type defineDevframe, defineRpcFunction };
+export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type ConnectionMeta, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeBrowserContext, type DevframeCapabilities, type DevframeCliOptions, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRuntime, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSpaOptions, type DevframeViewHost, type DevframeWsOptions, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type PartialWithoutId, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type Thenable, type defineDevframe, defineRpcFunction };

package/dist/node/auth.d.mts

@@ -1,2 +1,2 @@
-import { a as verifyAuthToken, c as DevframeAuthHandler, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-DzeFcwMM.mjs";
+import { a as verifyAuthToken, c as DevframeAuthHandler, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-d40ZLcYw.mjs";
 export { DevframeAuthHandler, buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, refreshTempAuthCode, revokeActiveConnectionsForToken, revokeAuthToken, verifyAuthToken };

package/dist/node/hub-internals.d.mts

@@ -1,5 +1,5 @@
-import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
-import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-DgkYTlXx.mjs";
+import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-Dma0XG3U.mjs";
+import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-BsiCAEC4.mjs";
 
 //#region src/adapters/_shared.d.ts
 /**

package/dist/node/index.d.mts

@@ -1,8 +1,8 @@
-import { C as RpcStreamingHost, K as DevframeScopedNodeContext, R as SharedState, Y as DevframeSettings, _ as RpcBroadcastOptions, _t as AgentTool, at as DevframeRpcServerFunctions, b as RpcSharedStateHost, bt as DevframeAgentHostEvents, dt as DevframeDiagnosticsLogger, ft as AgentHandle, g as DevframeNodeRpcSession, gt as AgentResourceInput, h as DevframeNodeContext, ht as AgentResourceContent, it as DevframeRpcClientFunctions, mt as AgentResource, pt as AgentManifest, rt as DevframeViewHost$1, st as DevframeHost, ut as DevframeDiagnosticsHost$1, v as RpcFunctionsHost$1, vt as AgentToolInput, xt as EventEmitter, yt as DevframeAgentHost$1 } from "../devframe-CpXy1ZlO.mjs";
+import { St as EventEmitter, X as DevframeSettings, _ as DevframeNodeRpcSession, _t as AgentResourceInput, at as DevframeRpcClientFunctions, bt as DevframeAgentHost$1, ct as DevframeHost, dt as DevframeDiagnosticsHost$1, ft as DevframeDiagnosticsLogger, g as DevframeNodeContext, gt as AgentResourceContent, ht as AgentResource, it as DevframeViewHost$1, mt as AgentManifest, ot as DevframeRpcServerFunctions, pt as AgentHandle, q as DevframeScopedNodeContext, v as RpcBroadcastOptions, vt as AgentTool, w as RpcStreamingHost, x as RpcSharedStateHost, xt as DevframeAgentHostEvents, y as RpcFunctionsHost$1, yt as AgentToolInput, z as SharedState } from "../devframe-Dma0XG3U.mjs";
 import { v as RpcFunctionDefinitionAny } from "../types-oEqKqUC9.mjs";
 import { S as RpcFunctionsCollectorBase } from "../index-DI_TMGjv.mjs";
 import { t as DevframeNodeRpcSessionMeta } from "../ws-server-BUgJpdX4.mjs";
-import { n as StartedServer, r as startHttpAndWs, t as StartHttpAndWsOptions } from "../server-C83NJvZp.mjs";
+import { n as StartedServer, r as startHttpAndWs, t as StartHttpAndWsOptions } from "../server-BD-tKDVf.mjs";
 import { BirpcGroup } from "birpc";
 import { AsyncLocalStorage } from "node:async_hooks";
 

package/dist/recipes/interactive-auth.d.mts

@@ -1,5 +1,5 @@
-import { h as DevframeNodeContext } from "../devframe-CpXy1ZlO.mjs";
-import { c as DevframeAuthHandler } from "../index-DzeFcwMM.mjs";
+import { g as DevframeNodeContext } from "../devframe-Dma0XG3U.mjs";
+import { c as DevframeAuthHandler } from "../index-d40ZLcYw.mjs";
 
 //#region src/recipes/interactive-auth.d.ts
 interface CreateInteractiveAuthOptions {

package/dist/{server-C83NJvZp.d.mts → server-BD-tKDVf.d.mts}

@@ -1,5 +1,5 @@
-import { at as DevframeRpcServerFunctions, f as ConnectionMeta, g as DevframeNodeRpcSession, h as DevframeNodeContext, it as DevframeRpcClientFunctions } from "./devframe-CpXy1ZlO.mjs";
-import { c as DevframeAuthHandler } from "./index-DzeFcwMM.mjs";
+import { _ as DevframeNodeRpcSession, at as DevframeRpcClientFunctions, g as DevframeNodeContext, ot as DevframeRpcServerFunctions, p as ConnectionMeta } from "./devframe-Dma0XG3U.mjs";
+import { c as DevframeAuthHandler } from "./index-d40ZLcYw.mjs";
 import { BirpcGroup, EventOptions } from "birpc";
 import { Peer } from "crossws";
 import { NodeAdapter } from "crossws/adapters/node";

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as ScopedClientFunctions, C as RpcStreamingHost, Ct as EventsMap, G as Thenable, J as DevframeScopedStreamingHost, K as DevframeScopedNodeContext, Q as ScopedBroadcastOptions, S as RpcStreamingChannelOptions, St as EventUnsubscribe, U as EntriesToObject, W as PartialWithoutId, X as DevframeSettingsRegistry, Y as DevframeSettings, Z as DevframeSettingsStore, _ as RpcBroadcastOptions, _t as AgentTool, a as DevframeDuplicationStrategy, at as DevframeRpcServerFunctions, b as RpcSharedStateHost, bt as DevframeAgentHostEvents, c as DevframeSpaOptions, ct as DevframeDefineDiagnosticsOptions, d as defineDevframe, dt as DevframeDiagnosticsLogger, et as ScopedServerFunctions, f as ConnectionMeta, ft as AgentHandle, g as DevframeNodeRpcSession, gt as AgentResourceInput, h as DevframeNodeContext, ht as AgentResourceContent, i as DevframeDeploymentKind, it as DevframeRpcClientFunctions, l as DevframeWsOptions, lt as DevframeDiagnosticsDefinition, m as DevframeCapabilities, mt as AgentResource, n as DevframeCliOptions, nt as SettingsForNamespace, o as DevframeRuntime, ot as DevframeRpcSharedStates, p as ConnectionMetaWebsocket, pt as AgentManifest, q as DevframeScopedNodeRpc, r as DevframeDefinition, rt as DevframeViewHost, s as DevframeSetupInfo, st as DevframeHost, t as DevframeBrowserContext, tt as ScopedSharedStates, u as McpRouteOptions, ut as DevframeDiagnosticsHost, v as RpcFunctionsHost, vt as AgentToolInput, x as RpcStreamingChannel, xt as EventEmitter, y as RpcSharedStateGetOptions, yt as DevframeAgentHost } from "../devframe-CpXy1ZlO.mjs";
+import { $ as ScopedBroadcastOptions, C as RpcStreamingChannelOptions, Ct as EventUnsubscribe, G as PartialWithoutId, J as DevframeScopedNodeRpc, K as Thenable, Q as DevframeSettingsStore, S as RpcStreamingChannel, St as EventEmitter, W as EntriesToObject, X as DevframeSettings, Y as DevframeScopedStreamingHost, Z as DevframeSettingsRegistry, _ as DevframeNodeRpcSession, _t as AgentResourceInput, a as DevframeDockDefaults, at as DevframeRpcClientFunctions, b as RpcSharedStateGetOptions, bt as DevframeAgentHost, c as DevframeSetupInfo, ct as DevframeHost, d as McpRouteOptions, dt as DevframeDiagnosticsHost, et as ScopedClientFunctions, f as defineDevframe, ft as DevframeDiagnosticsLogger, g as DevframeNodeContext, gt as AgentResourceContent, h as DevframeCapabilities, ht as AgentResource, i as DevframeDeploymentKind, it as DevframeViewHost, l as DevframeSpaOptions, lt as DevframeDefineDiagnosticsOptions, m as ConnectionMetaWebsocket, mt as AgentManifest, n as DevframeCliOptions, nt as ScopedSharedStates, o as DevframeDuplicationStrategy, ot as DevframeRpcServerFunctions, p as ConnectionMeta, pt as AgentHandle, q as DevframeScopedNodeContext, r as DevframeDefinition, rt as SettingsForNamespace, s as DevframeRuntime, st as DevframeRpcSharedStates, t as DevframeBrowserContext, tt as ScopedServerFunctions, u as DevframeWsOptions, ut as DevframeDiagnosticsDefinition, v as RpcBroadcastOptions, vt as AgentTool, w as RpcStreamingHost, wt as EventsMap, x as RpcSharedStateHost, xt as DevframeAgentHostEvents, y as RpcFunctionsHost, yt as AgentToolInput } from "../devframe-Dma0XG3U.mjs";
 import { g as RpcFunctionAgentOptions } from "../types-oEqKqUC9.mjs";
 import { t as DevframeNodeRpcSessionMeta } from "../ws-server-BUgJpdX4.mjs";
-export { AgentHandle, AgentManifest, AgentResource, AgentResourceContent, AgentResourceInput, AgentTool, AgentToolInput, ConnectionMeta, ConnectionMetaWebsocket, DevframeAgentHost, DevframeAgentHostEvents, DevframeBrowserContext, DevframeCapabilities, DevframeCliOptions, DevframeDefineDiagnosticsOptions, DevframeDefinition, DevframeDeploymentKind, DevframeDiagnosticsDefinition, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeDuplicationStrategy, DevframeHost, DevframeNodeContext, DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeRuntime, DevframeScopedNodeContext, DevframeScopedNodeRpc, DevframeScopedStreamingHost, DevframeSettings, DevframeSettingsRegistry, DevframeSettingsStore, DevframeSetupInfo, DevframeSpaOptions, DevframeViewHost, DevframeWsOptions, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, McpRouteOptions, PartialWithoutId, RpcBroadcastOptions, type RpcFunctionAgentOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, ScopedBroadcastOptions, ScopedClientFunctions, ScopedServerFunctions, ScopedSharedStates, SettingsForNamespace, Thenable, defineDevframe };
+export { AgentHandle, AgentManifest, AgentResource, AgentResourceContent, AgentResourceInput, AgentTool, AgentToolInput, ConnectionMeta, ConnectionMetaWebsocket, DevframeAgentHost, DevframeAgentHostEvents, DevframeBrowserContext, DevframeCapabilities, DevframeCliOptions, DevframeDefineDiagnosticsOptions, DevframeDefinition, DevframeDeploymentKind, DevframeDiagnosticsDefinition, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeDockDefaults, DevframeDuplicationStrategy, DevframeHost, DevframeNodeContext, DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeRuntime, DevframeScopedNodeContext, DevframeScopedNodeRpc, DevframeScopedStreamingHost, DevframeSettings, DevframeSettingsRegistry, DevframeSettingsStore, DevframeSetupInfo, DevframeSpaOptions, DevframeViewHost, DevframeWsOptions, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, McpRouteOptions, PartialWithoutId, RpcBroadcastOptions, type RpcFunctionAgentOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, ScopedBroadcastOptions, ScopedClientFunctions, ScopedServerFunctions, ScopedSharedStates, SettingsForNamespace, Thenable, defineDevframe };

package/dist/utils/events.d.mts

@@ -1,4 +1,4 @@
-import { Ct as EventsMap, xt as EventEmitter } from "../devframe-CpXy1ZlO.mjs";
+import { St as EventEmitter, wt as EventsMap } from "../devframe-Dma0XG3U.mjs";
 
 //#region src/utils/events.d.ts
 /**

package/dist/utils/shared-state.d.mts

@@ -1,2 +1,2 @@
-import { B as SharedStateOptions, F as ImmutableMap, H as createSharedState, I as ImmutableObject, L as ImmutableSet, N as Immutable, P as ImmutableArray, R as SharedState, V as SharedStatePatch, z as SharedStateEvents } from "../devframe-CpXy1ZlO.mjs";
+import { B as SharedStateEvents, F as ImmutableArray, H as SharedStatePatch, I as ImmutableMap, L as ImmutableObject, P as Immutable, R as ImmutableSet, U as createSharedState, V as SharedStateOptions, z as SharedState } from "../devframe-Dma0XG3U.mjs";
 export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, SharedStatePatch, createSharedState };

package/dist/utils/streaming-channel.d.mts

@@ -1,2 +1,2 @@
-import { A as StreamSinkEvents, D as StreamErrorPayload, E as CreateStreamSinkOptions, M as createStreamSink, O as StreamReader, T as CreateStreamReaderOptions, j as createStreamReader, k as StreamSink, w as BufferedChunk } from "../devframe-CpXy1ZlO.mjs";
+import { A as StreamSink, D as CreateStreamSinkOptions, E as CreateStreamReaderOptions, M as createStreamReader, N as createStreamSink, O as StreamErrorPayload, T as BufferedChunk, j as StreamSinkEvents, k as StreamReader } from "../devframe-Dma0XG3U.mjs";
 export { BufferedChunk, CreateStreamReaderOptions, CreateStreamSinkOptions, StreamErrorPayload, StreamReader, StreamSink, StreamSinkEvents, createStreamReader, createStreamSink };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -21,6 +21,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./adapters/build": "./dist/adapters/build.mjs",
+    "./adapters/cac": "./dist/adapters/cac.mjs",
     "./adapters/cli": "./dist/adapters/cli.mjs",
     "./adapters/dev": "./dist/adapters/dev.mjs",
     "./adapters/embedded": "./dist/adapters/embedded.mjs",
@@ -62,17 +63,20 @@
     "skills"
   ],
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "cac": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "cac": {
+      "optional": true
     }
   },
   "dependencies": {
     "@valibot/to-json-schema": "^1.7.1",
     "birpc": "^4.0.0",
-    "cac": "^7.0.0",
     "crossws": "^0.4.9",
     "destr": "^2.0.5",
     "h3": "2.0.1-rc.22",
@@ -84,6 +88,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "cac": "^7.0.0",
     "get-port-please": "^3.2.0",
     "immer": "^11.1.11",
     "launch-editor": "^2.14.1",

package/skills/devframe/SKILL.md

@@ -11,7 +11,7 @@ description: >
   terminals, palette, etc.), the devframe can be mounted into a
   host that provides them — Vite DevTools is one supported target,
   reached via the `vite` adapter. Triggers on `devframe` imports,
-  `defineDevframe`, `createCli`, `createMcpServer`,
+  `defineDevframe`, `createCac`, `createMcpServer`,
   `connectDevframe`, and on migrations of existing inspectors
   (eslint-config-inspector, unocss-inspector,
   node-modules-inspector-style tools) to devframe.
@@ -31,7 +31,7 @@ All adapter factories share the shape `createXxx(devframeDef, options?)`.
 
 | Author goal | Factory | Entry |
 |-------------|---------|-------|
-| Standalone CLI for local use | `createCli(def, options?)` | `devframe/adapters/cli` |
+| Standalone CLI for local use | `createCac(def, options?)` | `devframe/adapters/cac` |
 | Run the dev server programmatically (any CLI framework) | `createDevServer(def, options?)` | `devframe/adapters/dev` |
 | Self-contained static deploy with baked data | `createBuild(def, options?)` | `devframe/adapters/build` |
 | Mount into a host (Vite DevTools or any compatible host) | `createPluginFromDevframe(def, options?)` | `@vitejs/devtools-kit/node` |
@@ -530,7 +530,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 ## CLI adapter subcommands
 
-`createCli(devframe).parse()` gives the tool four subcommands out of the box:
+`createCac(devframe).parse()` gives the tool four subcommands out of the box:
 
 | Subcommand | Action |
 |------------|--------|
@@ -539,7 +539,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 | `spa` | Deployable SPA → `./dist-spa/` |
 | `mcp` | stdio MCP server (experimental) |
 
-**Bring your own CLI framework?** `createCli` is just a cac wrapper around three peer factories — `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCli`'s baked-in command structure doesn't fit. `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cli`) validate an arbitrary flag bag against a `CliFlagsSchema` — typed flags aren't tied to cac.
+**Bring your own CLI framework?** `createCac` (`devframe/adapters/cac`) is just a cac wrapper around three peer factories — `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCac`'s baked-in command structure doesn't fit. `cac` is an optional peer dependency pulled in only through `devframe/adapters/cac`, so bring-your-own-CLI tools run without installing it. (The legacy `devframe/adapters/cli` entry / `createCli` remains as a deprecated alias.) `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cac`) validate an arbitrary flag bag against a `CliFlagsSchema` — the helpers are framework-agnostic.
 
 ## Bundled utilities