devframe 0.9.8 → 0.9.9

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)
 		};
@@ -605,7 +612,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 +770,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 +798,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 +831,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 +882,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 +978,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 +1007,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 +1076,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 +1203,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 +1246,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 +1331,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 +1458,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 +1520,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 +1675,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 +1695,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`).

package/dist/constants.mjs

@@ -1,5 +1,6 @@
-import { t as DEVFRAME_EVENTS } from "./events-4daw0uK9.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-BV4Dj59a.mjs";
 //#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
@@ -10,7 +11,7 @@ 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).
 */
@@ -20,7 +21,7 @@ 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.
 */
 const DEVFRAME_SSE_ROUTE = "__sse";
@@ -34,7 +35,7 @@ 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`.
 */
 const DEVFRAME_MCP_ROUTE = "__mcp";
@@ -79,7 +80,7 @@ const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
 /**
 * `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`).
@@ -87,7 +88,7 @@ const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
 const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = DEVFRAME_EVENTS.postMessage.remoteAssetsError;
 /**
 * 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`).