devframe 0.9.7 → 0.9.9

package/dist/adapters/mcp.mjs

@@ -1,9 +1,10 @@
-import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
-import { t as DEVFRAME_EVENTS } from "../events-4daw0uK9.mjs";
-import { i as isAllowedOrigin } from "../ws-server-BdSLrhxE.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "../context-omlma_1n.mjs";
-import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
+import { t as Diagnostic } from "../nostics-D0PvLZsn.mjs";
+import { t as DEVFRAME_EVENTS } from "../events-BV4Dj59a.mjs";
+import { t as isAllowedOrigin } from "../origin-DZit9g29.mjs";
+import { r as timingSafeEqual } from "../crypto-token-TVbGGFuj.mjs";
+import { t as diagnostics } from "../diagnostics-BMfN8mb1.mjs";
+import { t as createHostContext } from "../context-CwPUinjn.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-DGzeuWcO.mjs";
 import process from "node:process";
 import { join } from "pathe";
 import { homedir } from "node:os";
@@ -65,7 +66,7 @@ function stringifyForMcp(value) {
 * Format a thrown value for an MCP `isError` text payload.
 *
 * A nostics `Diagnostic` (every coded devframe error) becomes structured
-* JSON — `{ error: { code, message, fix?, docs? } }` — so an agent receives
+* JSON (`{ error: { code, message, fix?, docs? } }`), so an agent receives
 * the actionable next step (`fix`) and the docs URL instead of a bare
 * message string. Other errors surface `Error.name`/`message`, plus one
 * level of `cause.message` so context isn't dropped silently.
@@ -93,7 +94,7 @@ const FALLBACK_OBJECT_SCHEMA = Object.freeze({
 *
 * Devframe stays validator-neutral, so conversion uses the schema's own
 * [Standard JSON Schema](https://standardschema.dev/) converter
-* (`~standard.jsonSchema`) when the validator provides one — zod 4 does,
+* (`~standard.jsonSchema`) when the validator provides one; zod 4 does,
 * for example. Validators without a native converter (e.g. valibot) degrade
 * to a permissive object schema rather than pulling in a converter library.
 */
@@ -116,7 +117,7 @@ function returnToJsonSchema(schema) {
 }
 /**
 * JSON Schema for an RPC function's positional args on the agent/MCP
-* surface. Each positional arg is advertised under `arg0` / `arg1` / … —
+* surface. Each positional arg is advertised under `arg0` / `arg1` / …,
 * matching how the agent bridge coerces the incoming object payload back
 * into positional arguments.
 *
@@ -152,7 +153,7 @@ function argsToJsonSchema(args) {
 //#region src/adapters/mcp/build-server.ts
 /**
 * Build a fresh MCP {@link Server} over a devframe context, registering its
-* tool and resource handlers. This is a pure factory — it sets up no
+* tool and resource handlers. This is a pure factory: it sets up no
 * long-lived subscriptions and holds no per-connection state, so it is safe
 * to call once per request under `createMcpHandler` or once per connection
 * under `serveStdio`. Change notifications are published separately: over
@@ -265,9 +266,9 @@ async function createMcpServer(definition, options = {}) {
 	} };
 }
 /**
-* Id of the built-in shared-state read tool — namespaced like every other
+* Id of the built-in shared-state read tool, namespaced like every other
 * built-in (`devframe:<area>:<fn>`). Tool-shaped access matters because many
-* MCP clients only consume tools — the parallel `devframe://state/<key>`
+* MCP clients only consume tools; the parallel `devframe://state/<key>`
 * resource projection stays for the clients that do read resources.
 */
 const READ_STATE_TOOL = "devframe:state:read";
@@ -310,8 +311,8 @@ function registerToolHandlers(server, ctx, exposeSharedState) {
 	const warnedCollisions = /* @__PURE__ */ new Set();
 	/**
 	* Resolve a wire tool name back to the registered {@link AgentTool}.
-	* Wire-name matching runs first, in manifest order — the same tool the
-	* list projection advertises under that name — with a raw-id fallback so
+	* Wire-name matching runs first, in manifest order (the same tool the
+	* list projection advertises under that name), with a raw-id fallback so
 	* a colon-namespaced id keeps working as a call name.
 	*/
 	const resolveTool = (name) => {
@@ -375,6 +376,7 @@ function registerToolHandlers(server, ctx, exposeSharedState) {
 	});
 }
 function registerResourceHandlers(server, ctx, exposeSharedState) {
+	const stateFilter = sharedStateFilter(exposeSharedState);
 	server.setRequestHandler("resources/list", async () => {
 		const resources = ctx.agent.list().resources.map((resource) => ({
 			uri: resource.uri,
@@ -382,17 +384,14 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 			description: resource.description,
 			mimeType: resource.mimeType
 		}));
-		if (exposeSharedState !== false) {
-			const filter = typeof exposeSharedState === "function" ? exposeSharedState : () => true;
-			for (const key of ctx.rpc.sharedState.keys()) {
-				if (!filter(key)) continue;
-				resources.push({
-					uri: `devframe://state/${encodeURIComponent(key)}`,
-					name: key,
-					description: `Shared state: ${key}`,
-					mimeType: "application/json"
-				});
-			}
+		if (stateFilter) for (const key of ctx.rpc.sharedState.keys()) {
+			if (!stateFilter(key)) continue;
+			resources.push({
+				uri: `devframe://state/${encodeURIComponent(key)}`,
+				name: key,
+				description: `Shared state: ${key}`,
+				mimeType: "application/json"
+			});
 		}
 		return { resources };
 	});
@@ -407,17 +406,20 @@ function registerResourceHandlers(server, ctx, exposeSharedState) {
 				text: content.text ?? stringifyForMcp(content.json)
 			}] };
 		}
-		if (parsed.kind === "state") return { contents: [{
-			uri,
-			mimeType: "application/json",
-			text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
-		}] };
+		if (parsed.kind === "state") {
+			if (!stateFilter || !stateFilter(parsed.key)) throw diagnostics.DF0048({ key: parsed.key });
+			return { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
+			}] };
+		}
 		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
 	});
 }
 /**
 * MCP constrains a tool's `outputSchema` to a JSON Schema of `type:
-* "object"` — clients (the SDK included) reject anything else. Non-object
+* "object"`; clients (the SDK included) reject anything else. Non-object
 * return schemas (e.g. a schema for `void` / a bare string) simply project
 * no output schema; the text content still carries the result.
 */
@@ -477,26 +479,56 @@ function parseResourceUri(uri) {
 //#endregion
 //#region src/adapters/mcp/fetch.ts
 /**
+* Parse exactly one `Authorization: Bearer <token>` credential, returning the
+* token or `undefined` for a missing, malformed, empty, or multi-credential
+* header. The token itself is never logged. `\S+` rejects the whitespace that
+* a second credential (fetch merges duplicate headers as `a, b`) or an empty
+* value would introduce.
+*/
+function parseBearerToken(header) {
+	if (!header) return void 0;
+	const match = /^Bearer (\S+)$/i.exec(header.trim());
+	return match ? match[1] : void 0;
+}
+/**
+* Resolve the identity gate for one request. `false` is the origin-only
+* opt-out; a callback delegates identity; a string requires a constant-time
+* bearer match. Never reveals whether a supplied token was close to correct.
+*/
+async function isAuthorized(req, authorization) {
+	if (authorization === false) return true;
+	if (typeof authorization === "function") return await authorization(req) === true;
+	const token = parseBearerToken(req.headers.get("authorization"));
+	if (token === void 0) return false;
+	return timingSafeEqual(token, authorization);
+}
+/**
 * Build a framework-agnostic MCP endpoint over a devframe context: a
-* web-standard `Request → Response` handler any host can mount — h3 (see
+* web-standard `Request → Response` handler any host can mount: h3 (see
 * `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
 * server.
 *
 * The endpoint is **stateless**: it serves the 2026-07-28 revision per request
 * through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
 * (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
-* request — no `Mcp-Session-Id` registry, no session-local routing, no
+* request: no `Mcp-Session-Id` registry, no session-local routing, no
 * GET/DELETE teardown protocol. 2025-era clients are still served through the
 * SDK's default stateless legacy path. `list_changed` events reach modern
 * `subscriptions/listen` streams through the handler's `notify` bus.
 *
 * The origin gate guards every request: loopback-default DNS-rebinding
-* protection that — unlike the WS upgrade's `isAllowedOrigin` — also rejects
-* `Origin`-less requests, so a route-based endpoint isn't reachable by an
-* arbitrary local process.
+* protection that (unlike the WS upgrade's `isAllowedOrigin`) also rejects
+* `Origin`-less requests, so a route-based endpoint isn't reachable by a
+* browser or a remote host (a disallowed origin gets `403`). It trusts
+* same-machine callers by default. When that isn't your trust boundary, add
+* an optional identity gate ({@link CreateMcpFetchHandlerOptions.authorization}),
+* checked after the origin gate: a bearer/callback check that proves *who* is
+* calling (a missing/invalid credential gets `401` with a
+* `WWW-Authenticate: Bearer` challenge).
 */
 function createMcpFetchHandler(ctx, options) {
 	const allowedOrigins = options.allowedOrigins;
+	const authorization = options.authorization ?? false;
 	const handler = createMcpHandler(() => buildMcpServerFromContext(ctx, {
 		serverName: options.serverName,
 		serverVersion: options.serverVersion,
@@ -512,7 +544,11 @@ function createMcpFetchHandler(ctx, options) {
 	});
 	async function handle(req) {
 		const origin = req.headers.get("origin") ?? void 0;
-		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden: origin required", { status: 403 });
+		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden", { status: 403 });
+		if (!await isAuthorized(req, authorization)) return new Response("Unauthorized", {
+			status: 401,
+			headers: { "WWW-Authenticate": "Bearer" }
+		});
 		return handler.fetch(req);
 	}
 	return {
@@ -526,11 +562,11 @@ function createMcpFetchHandler(ctx, options) {
 //#endregion
 //#region src/adapters/mcp/http.ts
 /**
-* Mount a stateless MCP endpoint on an h3 app at `path` — the h3 binding over
+* Mount a stateless MCP endpoint on an h3 app at `path`: the h3 binding over
 * {@link createMcpFetchHandler}, which owns the per-request serving, the
 * origin gate, and the transport plumbing.
 *
-* The handler is web-standard — it takes the h3 event's web `Request` and
+* The handler is web-standard: it takes the h3 event's web `Request` and
 * returns a web `Response` (an SSE `ReadableStream` body for a
 * `subscriptions/listen` stream). We copy that response onto `event.res` and
 * return its body rather than returning the `Response` object directly, so an

package/dist/{agent-tool-name-EgfoFO8C.mjs → agent-tool-name-DGzeuWcO.mjs}

@@ -7,13 +7,13 @@ const MAX_TOOL_NAME_LENGTH = 128;
 /**
 * Derive the wire-safe agent tool name for an internal tool id.
 *
-* Devframe tool ids are colon-namespaced — `devframe:<area>:<fn>` for
+* Devframe tool ids are colon-namespaced: `devframe:<area>:<fn>` for
 * built-ins, `devframes:plugin:<slug>:<fn>` for plugin RPCs, and hub
 * command ids for command-derived tools. MCP clients constrain tool names
 * to `^[a-zA-Z0-9_-]{1,128}$`, so the agent/MCP boundary derives the wire
 * name automatically: every run of characters outside `[a-zA-Z0-9_-]`
 * becomes a single `_`, truncated to 128 characters. Internal ids never
-* change — resolution back to the id happens at the boundary.
+* change; resolution back to the id happens at the boundary.
 *
 * ```
 * devframe:state:read          → devframe_state_read

package/dist/cli/main.d.mts

@@ -1,6 +1,6 @@
 //#region src/cli/main.d.ts
 /**
- * The `devframe` bin — the framework's own CLI, distinct from the per-app
+ * The `devframe` bin is the framework's own CLI, distinct from the per-app
  * CLI shells authors build with `createCac(definition)`. It hosts the
  * app-independent commands; today that is `connect`, the MCP connector.
  */

package/dist/cli/main.mjs

@@ -1,18 +1,37 @@
-import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-BjlMQbFB.mjs";
-import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
+import { t as Diagnostic } from "../nostics-D0PvLZsn.mjs";
+import { t as diagnostics } from "../diagnostics-BMfN8mb1.mjs";
+import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-C7-41RSp.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-DGzeuWcO.mjs";
 import process from "node:process";
 import { joinURL } from "ufo";
 import { cac } from "cac";
 //#region src/cli/connect.ts
+/**
+* Resolve the per-record bearer from the {@link ConnectServerOptions.authToken}
+* option. Exported for focused tests of the credential resolution.
+*/
+function resolveAuthToken(authToken, record) {
+	return typeof authToken === "function" ? authToken(record) : authToken;
+}
+/**
+* Build the request headers the connector sends to one instance's MCP route:
+* the instance's own (loopback) `origin` so the route's origin gate accepts
+* this native client, plus `Authorization: Bearer <token>` when a bearer is
+* configured. The bearer appears **only** here, never in the connection URL,
+* the registry records, or the indexed results. Exported for focused tests.
+*/
+function buildInstanceRequestHeaders(url, token) {
+	const headers = { origin: new URL(url).origin };
+	if (token) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
 const INDEX_TOOL = toAgentToolName("devframe:connect:list-instances");
 const CALL_TOOL = toAgentToolName("devframe:connect:call-tool");
 const MCP_DISABLED_HINT = "This instance runs without an MCP route. Restart it with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.";
 const GATEWAY_TOOLS = [{
 	name: INDEX_TOOL,
 	title: "Discover running devframes",
-	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available — the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
+	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
 	inputSchema: {
 		type: "object",
 		properties: {}
@@ -48,12 +67,12 @@ const GATEWAY_TOOLS = [{
 /**
 * Start the devframe MCP connector on stdio: a thin discovery + proxy server
 * in the shape Vercel's next-devtools-mcp (https://github.com/vercel/next-devtools-mcp)
-* validated — credit due there for the architecture this connector follows.
-* It exposes two gateway tools —
+* validated; credit is due there for the architecture this connector follows.
+* It exposes two gateway tools:
 * `devframe_connect_list-instances` (discover running devframe instances via
 * the instance registry and list each one's MCP tools) and
 * `devframe_connect_call-tool` (invoke one tool on one instance over its
-* Streamable-HTTP endpoint) — and holds no domain knowledge of its own.
+* Streamable-HTTP endpoint), and holds no domain knowledge of its own.
 */
 async function startConnectServer(options = {}) {
 	const sdk = await importSdk();
@@ -128,7 +147,7 @@ async function index(sdk, options) {
 		try {
 			entry.mcp = {
 				url,
-				tools: await listInstanceTools(sdk, url)
+				tools: await listInstanceTools(sdk, url, resolveAuthToken(options.authToken, record))
 			};
 		} catch (error) {
 			entry.mcp = {
@@ -163,8 +182,8 @@ async function probePort(port, timeoutMs) {
 		startedAt: 0
 	};
 }
-async function listInstanceTools(sdk, url) {
-	return withInstanceClient(sdk, url, async (client) => {
+async function listInstanceTools(sdk, url, token) {
+	return withInstanceClient(sdk, url, token, async (client) => {
 		return (await client.listTools()).tools.map((tool) => ({
 			name: tool.name,
 			description: tool.description
@@ -180,7 +199,7 @@ async function call(sdk, options, args) {
 	const record = live.find((r) => r.port === args.port) ?? await probePort(args.port, options.timeoutMs);
 	if (!record) throw diagnostics.DF0050({ port: args.port });
 	if (!record.mcp) throw diagnostics.DF0051({ port: args.port });
-	return withInstanceClient(sdk, `${record.origin}${record.mcp.path}`, async (client) => {
+	return withInstanceClient(sdk, `${record.origin}${record.mcp.path}`, resolveAuthToken(options.authToken, record), async (client) => {
 		const result = await client.callTool({
 			name: args.tool,
 			arguments: args.args ?? {}
@@ -197,9 +216,8 @@ async function call(sdk, options, args) {
 		};
 	});
 }
-async function withInstanceClient(sdk, url, fn) {
-	const origin = new URL(url).origin;
-	const transport = new sdk.StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: { origin } } });
+async function withInstanceClient(sdk, url, token, fn) {
+	const transport = new sdk.StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: buildInstanceRequestHeaders(url, token) } });
 	const client = new sdk.Client({
 		name: "devframe-connect",
 		version: "0.0.0"
@@ -254,7 +272,7 @@ function keepAlive() {
 //#endregion
 //#region src/cli/main.ts
 /**
-* The `devframe` bin — the framework's own CLI, distinct from the per-app
+* The `devframe` bin is the framework's own CLI, distinct from the per-app
 * CLI shells authors build with `createCac(definition)`. It hosts the
 * app-independent commands; today that is `connect`, the MCP connector.
 */
@@ -264,7 +282,13 @@ async function runDevframeCli(argv = process.argv) {
 		await startConnectServer({
 			ports: parsePortsFlag(options.port),
 			instancesDir: options.instancesDir,
-			timeoutMs: options.timeout
+			timeoutMs: options.timeout,
+			/**
+			* The bearer for authenticated instance MCP routes comes from the
+			* environment, never a CLI flag: command-line arguments are visible to
+			* any process on the machine (`ps`, `/proc`), which would defeat it.
+			*/
+			authToken: process.env.DEVFRAME_MCP_AUTH_TOKEN
 		});
 		keepAlive();
 	});

package/dist/client/index.d.mts

@@ -1,8 +1,8 @@
-import { f as RpcCacheManager, p as RpcCacheOptions } from "../index-BzyopqxV.mjs";
-import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-CMdPYhOx.mjs";
-import { Q as DevframeServiceScopeOf, X as DevframeServiceMeta, _t as DevframeRpcServerFunctions, b as StreamSink, d as RpcSharedStateHost, dt as ScopedRpcFn, ft as ScopedServerFunctions, gt as DevframeRpcClientFunctions, k as SharedState, mt as SettingsForNamespace, nt as DevframeServicesState, ot as DevframeSettings, pt as ScopedSharedStates, t as ConnectionMeta, u as RpcSharedStateGetOptions, y as StreamReader, zt as EventEmitter } from "../context-BhBzOXVa.mjs";
-import { t as SseRpcChannelOptions } from "../sse-client-DwX021ST.mjs";
-import { t as WsRpcChannelOptions } from "../ws-client-7_lZi-B9.mjs";
+import { f as RpcCacheManager, p as RpcCacheOptions } from "../index-pIVt92jP.mjs";
+import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-Dq4i156u.mjs";
+import { $ as DevframeServiceScopeOf, Bt as EventEmitter, Z as DevframeServiceMeta, _t as DevframeRpcClientFunctions, b as StreamSink, d as RpcSharedStateHost, ft as ScopedRpcFn, ht as SettingsForNamespace, k as SharedState, mt as ScopedSharedStates, pt as ScopedServerFunctions, rt as DevframeServicesState, st as DevframeSettings, t as ConnectionMeta, u as RpcSharedStateGetOptions, vt as DevframeRpcServerFunctions, y as StreamReader } from "../context-4AIVRLYF.mjs";
+import { t as SseRpcChannelOptions } from "../sse-client-BQ4jS3eO.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-Xpxt0oPA.mjs";
 import { BirpcOptions, BirpcReturn } from "birpc";
 //#region src/client/connection.d.ts
 interface DevframeConnection {
@@ -50,15 +50,15 @@ declare function setupDevframeConnection(options?: SetupDevframeConnectionOption
  * trust handshake, so a viewer never has to reason about the two dimensions
  * separately.
  *
- * - `connecting` — establishing the WebSocket / running the initial trust
+ * - `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,
+ * - `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).
+ * - `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
+ * - `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
@@ -67,9 +67,9 @@ declare function setupDevframeConnection(options?: SetupDevframeConnectionOption
 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}.
+ * - `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';
 /**
@@ -199,7 +199,7 @@ declare function createScopedClientContext<NS extends string = string>(rpc: Devf
 //#endregion
 //#region src/client/rpc-services.d.ts
 /**
- * A typed handle on one advertised wire service — the service's
+ * A typed handle on one advertised wire service: the service's
  * advertisement meta plus an RPC surface scoped to its namespace, so
  * `handle.rpc.call('fn-name', …)` targets `<scope>:fn-name`. Service
  * packages type the calls by augmenting `DevframeRpcServerFunctions` with
@@ -214,7 +214,7 @@ interface DevframeServiceClientHandle<NS extends string = string> extends Devfra
 /**
  * Client-side view of the server's wire-service registry, mirrored through
  * the reactive `devframe:services` shared state. The accessors are
- * synchronous snapshots — before the first sync lands (or on a server with
+ * synchronous snapshots; before the first sync lands (or on a server with
  * no services) they read as empty. For reactive UI (e.g. hiding an
  * "open in editor" button until the service appears), subscribe to the
  * shared state itself via {@link DevframeServicesClient.state}.
@@ -223,14 +223,14 @@ interface DevframeServicesClient {
   /** Whether the service package is advertised as installed. */
   has: (pkg: string) => boolean;
   /**
-   * A typed handle on an advertised service — its meta plus a scoped RPC
-   * surface — or `undefined` while it isn't available (never throws).
+   * A typed handle on an advertised service (its meta plus a scoped RPC
+   * surface), or `undefined` while it isn't available (never throws).
    */
   get: <PKG extends string>(pkg: PKG) => DevframeServiceClientHandle<DevframeServiceScopeOf<PKG>> | undefined;
   /** Package names of every advertised service. */
   keys: () => string[];
   /**
-   * The mirrored `devframe:services` shared state — subscribe to its
+   * The mirrored `devframe:services` shared state; subscribe to its
    * `updated` event for reactivity.
    */
   state: () => Promise<SharedState<DevframeServicesState>>;
@@ -257,7 +257,7 @@ interface RpcClientEvents {
    */
   'connection:error': (error: Error) => void;
   /**
-   * An RPC call rejected — either from the server, or because the connection
+   * 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;
@@ -271,7 +271,7 @@ interface DevframeRpcClientOptions extends SetupDevframeConnectionOptions {
    * Query-param name on the page URL carrying a one-time authentication code
    * (OTP) for "magic link" auth (e.g. a link the dev server prints). When
    * present, the client exchanges the code for a token and removes the parameter
-   * from the URL. Set `false` to disable — e.g. integrations that drive their
+   * from the URL. Set `false` to disable, e.g. integrations that drive their
    * own authentication via `authenticateWithUrlOtp`.
    *
    * @default 'devframe_otp'
@@ -281,7 +281,7 @@ interface DevframeRpcClientOptions extends SetupDevframeConnectionOptions {
    * Fall back to a native browser `prompt()` for the one-time authentication
    * code when the server refuses trust and no other credential succeeds (a
    * stored token, an injected token, or a magic-link OTP). The prompt fires
-   * only on a **top-level, unframed** page — a framed plugin (e.g. mounted in
+   * only on a **top-level, unframed** page; a framed plugin (e.g. mounted in
    * a hub dock) never prompts, since a hub pre-authorizes it and browsers
    * block `prompt()` in cross-origin frames anyway.
    *
@@ -294,20 +294,20 @@ interface DevframeRpcClientOptions extends SetupDevframeConnectionOptions {
   /**
    * Which live transport to connect over:
    *
-   *  - `'auto'` (default) — trust the server's advertisement: its declared
+   *  - `'auto'` (default) trusts the server's advertisement: its declared
    *    primary (`backend`), preferring the WebSocket when both endpoints are
    *    present. A server that couldn't bind a socket advertises SSE as its
    *    primary, so no client-side fallback probing is needed.
-   *  - `'websocket'` / `'sse'` — pin one transport; connecting fails with a
+   *  - `'websocket'` / `'sse'` pins one transport; connecting fails with a
    *    clear error when the server doesn't advertise it. Reach for
-   *    `transport: 'sse'` when an intermediary silently strips WS upgrades —
+   *    `transport: 'sse'` when an intermediary silently strips WS upgrades,
    *    something the server cannot detect.
    *
    * A `static` backend ignores this option (there is no live transport).
    */
   transport?: 'auto' | 'websocket' | 'sse';
   wsOptions?: Partial<WsRpcChannelOptions>;
-  /** Channel overrides for the SSE transport — the `wsOptions` counterpart. */
+  /** Channel overrides for the SSE transport, the `wsOptions` counterpart. */
   sseOptions?: Partial<SseRpcChannelOptions>;
   rpcOptions?: Partial<BirpcOptions<DevframeRpcServerFunctions, DevframeRpcClientFunctions, boolean>>;
   cacheOptions?: boolean | Partial<RpcCacheOptions>;
@@ -315,8 +315,8 @@ interface DevframeRpcClientOptions extends SetupDevframeConnectionOptions {
    * 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.
+   * Omit (or `0`) to wait indefinitely. Calls always fail fast, regardless of
+   * this option, once the socket closes or trust is refused.
    */
   callTimeout?: number;
 }
@@ -344,7 +344,7 @@ interface DevframeRpcClient {
    */
   readonly connectionError: Error | null;
   /**
-   * The transport this client is actually connected over — `'websocket'`,
+   * The transport this client is actually connected over: `'websocket'`,
    * `'sse'`, or `'static'`. Reflects the resolution of the `transport`
    * option against the server's advertisement.
    */
@@ -404,7 +404,7 @@ interface DevframeRpcClient {
   sharedState: RpcSharedStateHost;
   /**
    * The server's advertised wire services (mirrored `devframe:services`
-   * shared state) — feature-detect a capability with
+   * shared state); feature-detect a capability with
    * `rpc.services.has('@devframes/service-x')` and get a scoped, typed RPC
    * handle with `rpc.services.get(...)`. See {@link DevframeServicesClient}.
    */
@@ -437,11 +437,11 @@ interface DevframeRpcClient {
    * a `websocket` backend closes the underlying `WebSocket`, which the server observes as a
    * normal disconnect. Mirrors {@link WsRpcTransport.close} on the server side.
    *
-   * There is no corresponding "reconnect" — a closed client is done. Discard it and call
+   * There is no corresponding "reconnect"; a closed client is done. Discard it and call
    * {@link getDevframeRpcClient} again to reconnect.
    *
-   * Optional so a `DevframeRpcClientMode` implemented before this method existed — a custom
-   * transport, a hand-typed mock — still satisfies the interface; an absent `close` is treated
+   * Optional so a `DevframeRpcClientMode` implemented before this method existed (a custom
+   * transport, a hand-typed mock) still satisfies the interface; an absent `close` is treated
    * as nothing to close.
    */
   close?: () => void;
@@ -449,7 +449,7 @@ interface DevframeRpcClient {
 interface DevframeRpcClientMode {
   /**
    * The transport this mode speaks. Optional so a mode implemented before
-   * this field existed — a custom transport, a hand-typed mock — still
+   * this field existed (a custom transport, a hand-typed mock) still
    * satisfies the interface; an absent value reads as `'websocket'`.
    */
   readonly transport?: 'websocket' | 'sse' | 'static';
@@ -472,7 +472,7 @@ interface DevframeRpcClientMode {
 }
 /**
  * Resolve the requested `transport` option against what the server
- * advertises. `'auto'` trusts the advertisement — the server's declared
+ * advertises. `'auto'` trusts the advertisement: the server's declared
  * primary (`backend`), preferring the WebSocket when both endpoints are
  * present; an explicit `'websocket'` / `'sse'` pins that transport and
  * throws when the server doesn't advertise it.
@@ -502,7 +502,7 @@ declare function consumeOtpFromUrl(param?: string): string | undefined;
  *
  * Higher-level integrations (e.g. Vite DevTools) that want to drive their own
  * authentication UI can disable `connectDevframe`'s built-in handling with
- * `otpParam: false` and call this — or {@link consumeOtpFromUrl} — themselves.
+ * `otpParam: false` and call this (or {@link consumeOtpFromUrl}) themselves.
  */
 declare function authenticateWithUrlOtp(rpc: Pick<DevframeRpcClient, 'isTrusted' | 'requestTrustWithCode'>, options?: {
   param?: string;
@@ -523,7 +523,7 @@ interface WsUrlLocation {
  * The object / relative-path forms connect to the page's own origin (only the
  * `http`→`ws` protocol swap is applied), resolving the path against where
  * `__connection.json` was loaded. This is deliberately host-agnostic so the
- * connection survives a reverse proxy that changes the domain or port — the
+ * connection survives a reverse proxy that changes the domain or port, since the
  * client trusts its own location, never a server-baked hostname. An explicit
  * `port`/`host` (or a full `ws(s)://` URL string) opts into a cross-origin
  * endpoint, e.g. a side-car server on its own port.