devframe 0.9.8 → 0.9.10

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-CLF4-8Pp.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 { Q as DevframeServiceMeta, Vt as EventEmitter, b as StreamSink, ct as DevframeSettings, d as RpcSharedStateHost, et as DevframeServiceScopeOf, gt as SettingsForNamespace, ht as ScopedSharedStates, it as DevframeServicesState, k as SharedState, mt as ScopedServerFunctions, pt as ScopedRpcFn, t as ConnectionMeta, u as RpcSharedStateGetOptions, vt as DevframeRpcClientFunctions, y as StreamReader, yt as DevframeRpcServerFunctions } from "../context-CHW4BZOj.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.

package/dist/client/index.mjs

@@ -1,8 +1,8 @@
-import { t as DEVFRAME_EVENTS } from "../events-4daw0uK9.mjs";
+import { t as DEVFRAME_EVENTS } from "../events-BV4Dj59a.mjs";
 import { t as hash } from "../hash-DdPnc4k3.mjs";
 import { colors } from "../utils/colors.mjs";
 import { createEventEmitter } from "../utils/events.mjs";
-import { t as createSharedState } from "../shared-state--sduc6Xi.mjs";
+import { t as createSharedState } from "../shared-state-CaxB1q0h.mjs";
 import { i as structuredCloneStringify, n as structuredCloneParse, t as structuredCloneDeserialize } from "../structured-clone-CgtQ61SA.mjs";
 import { createStreamReader, createStreamSink } from "../utils/streaming-channel.mjs";
 import { defineDiagnostics } from "nostics";
@@ -10,6 +10,7 @@ import { ansiFormatter } from "nostics/formatters/ansi";
 import { withBase, withProtocol } from "ufo";
 import { createBirpc } from "birpc";
 //#region src/constants.ts
+/** Devframe runtime routes and static output conventions. */
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
 * Global key holding the serializable connection prepared by
@@ -110,7 +111,7 @@ function devframeReporter(d, { method = "warn" } = {}) {
 * ANSI console reporter pre-wired ahead of any `reporters` passed in. Every
 * `diagnostics.ts` in devframe core, `@devframes/hub`, `@devframes/json-render`,
 * and the built-in plugins defines its codes through this instead of
-* `nostics`'s own `defineDiagnostics` — the reporter registration lives
+* `nostics`'s own `defineDiagnostics`; the reporter registration lives
 * here, once, so none of them need to build their own reporter (`colors`,
 * `ansiFormatter`) or take a direct dependency on `nostics` themselves.
 */
@@ -126,7 +127,7 @@ const diagnostics = defineDiagnostics$1({
 	docsBase: "https://devfra.me/errors",
 	codes: {
 		DF0019: {
-			why: (p) => `RPC function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\` — MCP requires JSON-serializable data.`,
+			why: (p) => `RPC function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\`; MCP requires JSON-serializable data.`,
 			fix: "Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it RPC-only."
 		},
 		DF0020: {
@@ -207,7 +208,7 @@ async function validateRpcArgs(name, argsSchema, args) {
 /**
 * Validate a handler's resolved return value against its declared schema.
 * Throws `DF0039` when the value fails the schema, otherwise returns the
-* original value unchanged (guard-only, never rewriting the payload — see
+* original value unchanged (guard-only, never rewriting the payload; see
 * {@link validateRpcArgs}). Passes through when no return schema is set.
 *
 * @internal
@@ -350,16 +351,16 @@ function assertAgentJsonSerializable(fn) {
 * instances, or `undefined` inside an array (silently becomes `null`).
 *
 * Native pass-throughs (no extra work needed):
-*   - circular references — `JSON.stringify` raises `TypeError`.
-*   - `BigInt` at top level — caught here for a friendlier error path.
+*   - circular references: `JSON.stringify` raises `TypeError`.
+*   - `BigInt` at top level: caught here for a friendlier error path.
 *
 * Lenient cases (allowed without throwing):
-*   - `undefined` as an object property — legitimate optional field;
+*   - `undefined` as an object property: legitimate optional field;
 *     JSON.stringify just omits it.
-*   - `undefined` at the root — legitimate "action returned nothing".
-*   - `Symbol` / `Function` values — semantically "drop me" in JSON.
+*   - `undefined` at the root: legitimate "action returned nothing".
+*   - `Symbol` / `Function` values: semantically "drop me" in JSON.
 *
-* `fnName` is used only for the diagnostic message — pass the RPC
+* `fnName` is used only for the diagnostic message; pass the RPC
 * function name when calling from a wire serializer / dump writer so
 * the error points at the offending function.
 */
@@ -371,19 +372,21 @@ function strictJsonStringify(value, fnName = "") {
 			if (Array.isArray(holder)) throw nonJsonAt(fnName, "undefined", holder, key);
 			return val;
 		}
-		if (original === null) return val;
-		if (typeof original === "bigint") throw nonJsonAt(fnName, "BigInt", holder, key);
-		if (typeof original === "object") {
-			if (original instanceof Map) throw nonJsonAt(fnName, "Map", holder, key);
-			if (original instanceof Set) throw nonJsonAt(fnName, "Set", holder, key);
-			if (original instanceof Date) throw nonJsonAt(fnName, "Date", holder, key);
-			if (Array.isArray(original)) return val;
-			const proto = Object.getPrototypeOf(original);
-			if (proto !== null && proto !== Object.prototype) throw nonJsonAt(fnName, original.constructor?.name ?? "class instance", holder, key);
-		}
+		if (original !== null) assertJsonSafe(original, holder, key, fnName);
 		return val;
 	});
 }
+/** Throw `DF0020` when `original` is a type JSON can't round-trip losslessly. */
+function assertJsonSafe(original, holder, key, fnName) {
+	if (typeof original === "bigint") throw nonJsonAt(fnName, "BigInt", holder, key);
+	if (typeof original !== "object") return;
+	if (original instanceof Map) throw nonJsonAt(fnName, "Map", holder, key);
+	if (original instanceof Set) throw nonJsonAt(fnName, "Set", holder, key);
+	if (original instanceof Date) throw nonJsonAt(fnName, "Date", holder, key);
+	if (Array.isArray(original)) return;
+	const proto = Object.getPrototypeOf(original);
+	if (proto !== null && proto !== Object.prototype) throw nonJsonAt(fnName, original.constructor?.name ?? "class instance", holder, key);
+}
 function nonJsonAt(fnName, type, parent, key) {
 	const path = formatPath(parent, key);
 	return diagnostics.DF0020({
@@ -506,6 +509,10 @@ async function setupDevframeConnection(options = {}) {
 	if (options.connectionMeta) {
 		const connection = {
 			connectionMeta: options.connectionMeta,
+			/**
+			* Preserve the established connectionMeta behavior: an explicitly
+			* supplied descriptor resolves from the caller's explicit base.
+			*/
 			metaBaseUrl: resolveMetaBaseUrl(bases[0] ?? "./"),
 			authToken: readStoredAuthToken(options.authToken ?? options.connectionMeta.authToken)
 		};
@@ -526,9 +533,15 @@ async function setupDevframeConnection(options = {}) {
 			const response = await fetch(metaPath);
 			if (!response.ok) throw new Error(`Failed to fetch connection meta from ${metaUrl}: ${response.status}`);
 			const connectionMeta = await response.json();
+			const loadedFrom = response.url || metaUrl;
 			const connection = {
 				connectionMeta,
-				metaBaseUrl: response.url || metaUrl,
+				/**
+				* A served `baseUrl` re-points relative resolution (RPC dump shards,
+				* transport paths) at the meta that owns them: a static hub build's
+				* per-frame meta directs each frame SPA at the hub's own dump.
+				*/
+				metaBaseUrl: connectionMeta.baseUrl ? new URL(connectionMeta.baseUrl, loadedFrom).href : loadedFrom,
 				authToken: readStoredAuthToken(options.authToken ?? connectionMeta.authToken)
 			};
 			storeConnection(connection);
@@ -605,7 +618,7 @@ function consumeOtpFromUrl(param = DEVFRAME_OTP_URL_PARAM) {
 *
 * 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.
 */
 async function authenticateWithUrlOtp(rpc, options = {}) {
 	const code = consumeOtpFromUrl(options.param ?? "devframe_otp");
@@ -763,7 +776,7 @@ const EMPTY_WIRE_DEFS = /* @__PURE__ */ new Map();
 * JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
 * structured-clone (everything else, including all error envelopes), with a
 * request-id → method map so a response independently picks the same
-* encoder as its request. One codec per connection — request-id spaces
+* encoder as its request. One codec per connection; request-id spaces
 * don't collide across connections.
 *
 * @internal
@@ -791,9 +804,32 @@ function createRpcWireCodec(definitions = EMPTY_WIRE_DEFS) {
 //#endregion
 //#region src/rpc/transports/sse-client.ts
 function NOOP$1() {}
+/** Split the next complete SSE frame (up to a blank line) off the buffer. */
+function takeFrame(buffer) {
+	const boundary = buffer.search(/\n\n|\r\n\r\n/);
+	if (boundary < 0) return void 0;
+	return {
+		frame: buffer.slice(0, boundary),
+		rest: buffer.slice(boundary + (buffer[boundary] === "\r" ? 4 : 2))
+	};
+}
+/** Parse one SSE frame's lines into its event name and data lines. */
+function parseFrame(frame) {
+	let event = "message";
+	const data = [];
+	for (const rawLine of frame.split(/\r?\n/)) {
+		if (rawLine.startsWith(":")) continue;
+		if (rawLine.startsWith("event:")) event = rawLine.slice(6).trimStart();
+		else if (rawLine.startsWith("data:")) data.push(rawLine.slice(5).replace(/^ /, ""));
+	}
+	return {
+		event,
+		data
+	};
+}
 /**
 * Build a birpc `ChannelOptions` object backed by an SSE stream (server →
-* client) and HTTP `POST` (client → server) — the WebSocket-free counterpart
+* client) and HTTP `POST` (client → server): the WebSocket-free counterpart
 * to `createWsRpcChannel`, wire-compatible with `attachSseRpcTransport`.
 *
 * The stream is consumed via `fetch` streaming (not `EventSource`), so it
@@ -801,7 +837,7 @@ function NOOP$1() {}
 * (`event: session`) carries the session id; every `POST` echoes it in the
 * `x-birpc-session` header. A response to a client-initiated request comes
 * back in the `POST`'s own body and is re-injected into the channel; a
-* dropped stream terminates the channel — there is no reconnect, matching
+* dropped stream terminates the channel; there is no reconnect, matching
 * the WS channel's closed-is-done semantics.
 */
 function createSseRpcChannel(options) {
@@ -852,17 +888,10 @@ function createSseRpcChannel(options) {
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
 			for (;;) {
-				const boundary = buffer.search(/\n\n|\r\n\r\n/);
-				if (boundary < 0) break;
-				const frame = buffer.slice(0, boundary);
-				buffer = buffer.slice(boundary + (buffer[boundary] === "\r" ? 4 : 2));
-				let event = "message";
-				const data = [];
-				for (const rawLine of frame.split(/\r?\n/)) {
-					if (rawLine.startsWith(":")) continue;
-					if (rawLine.startsWith("event:")) event = rawLine.slice(6).trimStart();
-					else if (rawLine.startsWith("data:")) data.push(rawLine.slice(5).replace(/^ /, ""));
-				}
+				const taken = takeFrame(buffer);
+				if (!taken) break;
+				buffer = taken.rest;
+				const { event, data } = parseFrame(taken.frame);
 				if (data.length > 0) dispatch(event, data.join("\n"));
 			}
 		}
@@ -955,8 +984,8 @@ function promiseWithResolver() {
 //#endregion
 //#region src/client/rpc-live.ts
 /**
-* The transport-independent half of a live RPC client mode — connection
-* status, pending-call guarding, and the trust handshake — shared by the
+* The transport-independent half of a live RPC client mode (connection
+* status, pending-call guarding, and the trust handshake), shared by the
 * WebSocket and SSE modes. Each transport supplies only its channel.
 */
 function createLiveRpcClientMode(options) {
@@ -984,7 +1013,7 @@ function createLiveRpcClientMode(options) {
 	}
 	/**
 	* 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.
+	* optional wall-clock timeout, or when the connection drops, so it never hangs.
 	*/
 	function guardCall(promise, method) {
 		return new Promise((resolve, reject) => {
@@ -1053,6 +1082,11 @@ function createLiveRpcClientMode(options) {
 		currentAuthToken = token;
 		const result = await serverRpc.$call("anonymous:devframe:auth", {
 			authToken: token,
+			/**
+			* Sent raw; the server parses it into a display label (see
+			* `describeUA` in `node/auth/state.ts`) so `ua-parser-modern` stays
+			* out of the browser bundle.
+			*/
 			ua: navigator.userAgent,
 			origin: location.origin
 		});
@@ -1175,7 +1209,7 @@ function resolveSseUrl(sse, metaBaseUrl, loc) {
 	return new URL(str, base).href;
 }
 /**
-* The SSE-backed live client mode — picked by `connectDevframe` when the
+* The SSE-backed live client mode, picked by `connectDevframe` when the
 * server advertises SSE as its primary transport (`backend: 'sse'`) or when
 * the caller pins `transport: 'sse'`. Same status machine, call guarding,
 * and trust handshake as the WebSocket mode, over `createSseRpcChannel`.
@@ -1218,13 +1252,11 @@ function createSseRpcClientMode(options) {
 * the original `name`, and re-attaches any custom own properties.
 */
 function reviveDumpError(stored) {
-	const cause = stored.cause instanceof Error ? stored.cause : isPlainErrorShape(stored.cause) ? reviveDumpError(stored.cause) : stored.cause;
-	const error = cause !== void 0 ? new Error(stored.message, { cause }) : new Error(stored.message);
-	error.name = stored.name;
-	for (const key of Object.keys(stored)) {
-		if (key === "name" || key === "message" || key === "cause") continue;
-		error[key] = stored[key];
-	}
+	const { name, message, cause: rawCause, ...extras } = stored;
+	const cause = rawCause instanceof Error ? rawCause : isPlainErrorShape(rawCause) ? reviveDumpError(rawCause) : rawCause;
+	const error = cause !== void 0 ? new Error(message, { cause }) : new Error(message);
+	error.name = name;
+	Object.assign(error, extras);
 	return error;
 }
 function isPlainErrorShape(value) {
@@ -1305,15 +1337,21 @@ async function createStaticRpcClientMode(options) {
 	return {
 		transport: "static",
 		isTrusted: true,
+		/**
+		* A static backend has no live socket; every call is a local fetch, so it
+		* is "connected" for its whole life.
+		*/
 		status: "connected",
 		connectionError: null,
 		requestTrust: async () => true,
 		requestTrustWithToken: async () => true,
+		/** Static backends are always trusted, so there's nothing to exchange. */
 		requestTrustWithCode: async () => null,
 		ensureTrusted: async () => true,
 		call: (...args) => staticCaller.call(args[0], args.slice(1)),
 		callEvent: (...args) => staticCaller.callEvent(args[0], args.slice(1)),
 		callOptional: (...args) => staticCaller.callOptional(args[0], args.slice(1)),
+		/** No live socket to close; every call is a local fetch. */
 		close: () => {}
 	};
 }
@@ -1426,7 +1464,7 @@ const EMPTY_DEFS = /* @__PURE__ */ new Map();
 * Build a birpc `ChannelOptions` object backed by a browser `WebSocket`.
 * Pass the result straight to `createRpcClient`'s `channel` option.
 *
-* Also returns `close()`, closing the underlying socket — mirroring the server transport's
+* Also returns `close()`, closing the underlying socket, mirroring the server transport's
 * existing `WsRpcTransport.close()`. `birpc`'s own `ChannelOptions` has no teardown of its own.
 */
 function createWsRpcChannel(options) {
@@ -1488,7 +1526,7 @@ function createWsRpcChannel(options) {
 * 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.
@@ -1643,7 +1681,7 @@ function createScopedClientContext(rpc, namespace) {
 //#region src/client/rpc.ts
 /**
 * 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.
@@ -1663,7 +1701,7 @@ function resolveClientTransport(requested, meta) {
 	if (meta.backend === "sse" && hasSse) return "sse";
 	if (hasWebsocket) return "websocket";
 	if (hasSse) return "sse";
-	throw new Error("[devframe] This server advertises no RPC transport (backend \"none\") — nothing to connect to. Enable the WebSocket or SSE endpoint on the server, or use its static/MCP surfaces instead.");
+	throw new Error("[devframe] This server advertises no RPC transport (backend \"none\"), so there is nothing to connect to. Enable the WebSocket or SSE endpoint on the server, or use its static/MCP surfaces instead.");
 }
 async function getDevframeRpcClient(options = {}) {
 	const { baseURL = "./", rpcOptions = {}, cacheOptions = false } = options;

package/dist/{client-assets-C7SXgTWY.mjs → client-assets-DNdhagGm.mjs}

@@ -1,9 +1,9 @@
 //#region src/client-assets.ts
 /**
-* Resolve a definition's client assets source — the built SPA served as its
+* Resolve a definition's client assets source: the built SPA served as its
 * UI. Prefers the top-level {@link DevframeDefinition.clientAssets} and falls
 * back to the deprecated `cli.distDir`, so both the new and legacy shapes
-* resolve. Returns `undefined` when neither is set (bridge mode — the SPA is
+* resolve. Returns `undefined` when neither is set (bridge mode, where the SPA is
 * hosted elsewhere).
 *
 * Internal: exposed to first-party integrations via `devframe/internal`, not

package/dist/constants.d.mts

@@ -1,8 +1,8 @@
 //#region src/events.d.ts
 /**
- * Centralized registry of the core devframe event names — the node-side host
+ * Centralized registry of the core devframe event names: the node-side host
  * bus events, the client RPC connection events, and the server→client
- * broadcast notifications — so these names live in one place instead of
+ * broadcast notifications, so these names live in one place instead of
  * scattered string literals.
  *
  * **Keep this in sync with [`docs/content/8.references/3.events.md`](../../../docs/content/8.references/3.events.md)**
@@ -77,6 +77,7 @@ declare const DEVFRAME_EVENTS: {
 };
 //#endregion
 //#region src/constants.d.ts
+/** Devframe runtime routes and static output conventions. */
 declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
  * Global key holding the serializable connection prepared by
@@ -87,7 +88,7 @@ declare const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
 /**
  * Route the WebSocket RPC endpoint is bound to, relative to a devframe's
  * base path. Sits next to `__connection.json` so the deployed SPA can reach
- * it on the same origin it loaded from — the dev server shares one port for
+ * it on the same origin it loaded from: the dev server shares one port for
  * both HTTP and WS, and a host server (Vite, etc.) can mount the WS upgrade
  * handler here without colliding with its own routes (HMR, asset serving).
  */
@@ -97,7 +98,7 @@ declare const DEVFRAME_WS_ROUTE = "__ws";
  * path. A single method-dispatched route: `GET` opens the event stream
  * (server→client), `POST` carries RPC frames (client→server). Sits next to
  * `__connection.json` so the deployed SPA reaches it on the same origin it
- * loaded from — the transport for hosts and proxies where the WebSocket
+ * loaded from; the transport for hosts and proxies where the WebSocket
  * upgrade isn't available.
  */
 declare const DEVFRAME_SSE_ROUTE = "__sse";
@@ -111,7 +112,7 @@ declare const DEVFRAME_SSE_SESSION_HEADER = "x-birpc-session";
 /**
  * Route the Streamable-HTTP MCP endpoint is bound to, relative to a
  * devframe's base path. Sits next to `__connection.json` and the WS route
- * so an MCP client reaches it on the same origin the SPA loaded from — the
+ * so an MCP client reaches it on the same origin the SPA loaded from; the
  * dev server shares one port for HTTP, WS, and MCP. Opt-in via `cli.mcp`.
  */
 declare const DEVFRAME_MCP_ROUTE = "__mcp";
@@ -156,7 +157,7 @@ declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin
 /**
  * `postMessage` type the remote-assets fallback page posts to `window.parent`
  * on load. That page is what a devframe serves (with a 502) when its client
- * assets can be reached neither locally nor through their CDN provider — the
+ * assets can be reached neither locally nor through their CDN provider; the
  * message lets an embedding viewer replace the bare page with its own UI
  * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
  * `RemoteAssetsErrorMessage` (`devframe/types`).
@@ -164,7 +165,7 @@ declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin
 declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string;
 /**
  * Prefix that marks an RPC method as callable before a connection is
- * trusted. This is the *only* rule the pre-trust gate applies — there is no
+ * trusted. This is the *only* rule the pre-trust gate applies; there is no
  * per-method allowlist. Any handshake method a host adapter needs to reach
  * before authentication must be named `anonymous:<rest>` (e.g.
  * `anonymous:devframe:auth`).