devframe 0.6.2 → 0.7.2

package/dist/adapters/build.d.mts

@@ -1,5 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
-
+import { r as DevframeDefinition } from "../devframe-CnTVuGw9.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */

package/dist/adapters/build.mjs

@@ -1,4 +1,4 @@
-import { t as collectStaticRpcDump } from "../dump-D09PZb7T.mjs";
+import { t as collectStaticRpcDump } from "../dump-CocOVBVz.mjs";
 import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
 import { n as strictJsonStringify } from "../serialization-DpLXCy13.mjs";

package/dist/adapters/cac.d.mts

@@ -0,0 +1,40 @@
+import { Dt as defineCliFlags, Et as InferCliFlags, Ot as parseCliFlags, Tt as CliFlagsSchema, r as DevframeDefinition } from "../devframe-CnTVuGw9.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-BFCgKymz.mjs";
+export { createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/cli.d.mts

@@ -1,35 +1,11 @@
-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-CnTVuGw9.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-BFCgKymz.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,7 +1,6 @@
-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-CnTVuGw9.mjs";
+import { n as StartedServer } from "../server-4QH37sb-.mjs";
 import { H3 } from "h3";
-
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {
   /** Bind host. Default: `def.cli?.host ?? 'localhost'`. */
@@ -98,7 +97,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-Bs4oRVnI.mjs";
 export { createDevServer, resolveDevServerPort };

package/dist/adapters/embedded.d.mts

@@ -1,5 +1,4 @@
-import { h as DevframeNodeContext, r as DevframeDefinition } from "../devframe-CpXy1ZlO.mjs";
-
+import { g as DevframeNodeContext, r as DevframeDefinition } from "../devframe-CnTVuGw9.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */

package/dist/adapters/mcp.d.mts

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

package/dist/adapters/mcp.mjs

@@ -1,2 +1,2 @@
-import { n as createMcpServer } from "../build-server-0jWgMrz-.mjs";
+import { n as createMcpServer } from "../build-server-Bo0G5XcS.mjs";
 export { createMcpServer };

package/dist/{build-server-0jWgMrz-.mjs → build-server-Bo0G5XcS.mjs}

@@ -229,10 +229,16 @@ function registerToolHandlers(server, ctx) {
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: args } = request.params;
 		try {
-			return { content: [{
-				type: "text",
-				text: stringifyForMcp(await ctx.agent.invoke(name, args ?? {}))
-			}] };
+			const tool = ctx.agent.getTool(name);
+			const outputSchema = tool ? tool.outputSchema ?? computeOutputSchema(tool, ctx) : void 0;
+			const result = await ctx.agent.invoke(name, args ?? {});
+			return {
+				content: [{
+					type: "text",
+					text: stringifyForMcp(result)
+				}],
+				...outputSchema ? { structuredContent: result } : {}
+			};
 		} catch (error) {
 			return {
 				isError: true,

package/dist/cac-BFCgKymz.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-Bs4oRVnI.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,57 @@
-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 { _ 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 { 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-CnTVuGw9.mjs";
+import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-CrzNxXKq.mjs";
+import { C as RpcCacheManager, w as RpcCacheOptions } from "../index-DgsLFhZg.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-DSXiI2h7.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 +167,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 +201,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 +222,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 +307,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 +360,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 };