devframe 0.5.3 → 0.6.0-beta.1

package/dist/client/index.mjs

@@ -1,17 +1,26 @@
-import { t as hash } from "../hash-bwOD8RgU.mjs";
+import { t as hash } from "../hash-DFc5WwhO.mjs";
 import { colors } from "../utils/colors.mjs";
 import { createEventEmitter } from "../utils/events.mjs";
-import { humanId } from "../utils/human-id.mjs";
-import { t as createSharedState } from "../shared-state-u0y123fi.mjs";
-import { i as structuredCloneStringify, n as structuredCloneParse, t as structuredCloneDeserialize } from "../structured-clone-PdCZwt7F.mjs";
+import { t as createSharedState } from "../shared-state-D4PPieA0.mjs";
+import { i as structuredCloneStringify, n as structuredCloneParse, t as structuredCloneDeserialize } from "../structured-clone-CeZOHvkd.mjs";
 import { createStreamReader, createStreamSink } from "../utils/streaming-channel.mjs";
 import { promiseWithResolver } from "../utils/promise.mjs";
+import { isQualifiedName, qualifyName } from "../utils/scope.mjs";
 import { defineDiagnostics } from "nostics";
 import { ansiFormatter } from "nostics/formatters/ansi";
+import { withBase, withProtocol } from "ufo";
 import { createBirpc } from "birpc";
 //#region src/constants.ts
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
+/**
+* Page-URL query parameter carrying a one-time authentication code (OTP) for
+* "magic link" auth. A host can print a link like `<origin>/?devframe_otp=<code>`;
+* the client reads the code, exchanges it for a token, and strips the parameter
+* from the URL. See `buildOtpAuthUrl` (node) and the `authenticateWithUrlOtp` /
+* `consumeOtpFromUrl` client utilities (or `connectDevframe`'s `otpParam`).
+*/
+const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
 //#endregion
 //#region src/utils/diagnostics-reporter.ts
 const formatAnsi = ansiFormatter(colors);
@@ -259,6 +268,54 @@ function formatPath(parent, key) {
 	return key;
 }
 //#endregion
+//#region src/client/otp.ts
+/**
+* Read a one-time authentication code (OTP) from the current page URL's query
+* string, without side effects. Returns `undefined` when the parameter is absent.
+*/
+function readOtpFromUrl(param = DEVFRAME_OTP_URL_PARAM) {
+	try {
+		return new URLSearchParams(globalThis.location?.search).get(param) || void 0;
+	} catch {
+		return;
+	}
+}
+function stripParamFromUrl(param) {
+	try {
+		const url = new URL(globalThis.location.href);
+		if (!url.searchParams.has(param)) return;
+		url.searchParams.delete(param);
+		globalThis.history?.replaceState(globalThis.history.state, "", url.href);
+	} catch {}
+}
+/**
+* Read the one-time code from the page URL and remove it from the address bar
+* (and the current history entry), so the single-use code isn't left in the
+* URL, browser history, or a `Referer`. Returns the code, or `undefined` when
+* absent.
+*/
+function consumeOtpFromUrl(param = DEVFRAME_OTP_URL_PARAM) {
+	const code = readOtpFromUrl(param);
+	if (code) stripParamFromUrl(param);
+	return code;
+}
+/**
+* Consume a one-time code from the page URL (see {@link consumeOtpFromUrl}) and
+* exchange it for a token via the client. Resolves `true` when the client is
+* authenticated (already trusted, or the exchange succeeded), and `false` when
+* no code is present or the exchange failed.
+*
+* 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.
+*/
+async function authenticateWithUrlOtp(rpc, options = {}) {
+	const code = consumeOtpFromUrl(options.param ?? "devframe_otp");
+	if (!code) return false;
+	if (rpc.isTrusted) return true;
+	return rpc.requestTrustWithCode(code);
+}
+//#endregion
 //#region src/client/rpc-shared-state.ts
 function createRpcSharedStateClientHost(rpc) {
 	const sharedState = /* @__PURE__ */ new Map();
@@ -364,28 +421,38 @@ function resolveRecordOutput(record) {
 	if (record.error) throw reviveDumpError(record.error);
 	return record.output;
 }
+function hasMeaningfulArgs(args) {
+	return args.some((arg) => arg !== null && arg !== void 0);
+}
+function unwrapEnvelope(raw) {
+	if (raw !== null && typeof raw === "object" && "serialization" in raw && "data" in raw) return raw.data;
+	return raw;
+}
 function createStaticRpcCaller(manifest, fetchJson) {
 	const staticCache = /* @__PURE__ */ new Map();
 	const queryRecordCache = /* @__PURE__ */ new Map();
 	function reviveIfStructuredClone(value, serialization) {
-		if (serialization === "structured-clone") return structuredCloneDeserialize(value);
+		if (serialization === "structured-clone" && Array.isArray(value)) return structuredCloneDeserialize(value);
 		return value;
 	}
+	function decode(raw, serialization) {
+		return reviveIfStructuredClone(unwrapEnvelope(raw), serialization);
+	}
 	async function loadStatic(entry) {
-		if (!staticCache.has(entry.path)) staticCache.set(entry.path, fetchJson(entry.path).then((raw) => reviveIfStructuredClone(raw, entry.serialization)));
+		if (!staticCache.has(entry.path)) staticCache.set(entry.path, fetchJson(entry.path).then((raw) => decode(raw, entry.serialization)));
 		const data = await staticCache.get(entry.path);
 		if (isRecord(data)) return resolveRecordOutput(data);
 		return data;
 	}
 	async function loadQueryRecord(path, serialization) {
-		if (!queryRecordCache.has(path)) queryRecordCache.set(path, fetchJson(path).then((raw) => reviveIfStructuredClone(raw, serialization)));
+		if (!queryRecordCache.has(path)) queryRecordCache.set(path, fetchJson(path).then((raw) => decode(raw, serialization)));
 		return await queryRecordCache.get(path);
 	}
 	async function call(functionName, args) {
 		if (!(functionName in manifest)) throw new Error(`[devframe-rpc] Function "${functionName}" not found in dump store`);
 		const entry = manifest[functionName];
 		if (isStaticEntry(entry)) {
-			if (args.length > 0) throw new Error(`[devframe-rpc] No dump match for "${functionName}" with args: ${JSON.stringify(args)}`);
+			if (hasMeaningfulArgs(args)) throw new Error(`[devframe-rpc] No dump match for "${functionName}" with args: ${JSON.stringify(args)}`);
 			return await loadStatic(entry);
 		}
 		if (isQueryEntry(entry)) {
@@ -395,7 +462,7 @@ function createStaticRpcCaller(manifest, fetchJson) {
 			if (entry.fallback) return resolveRecordOutput(await loadQueryRecord(entry.fallback, entry.serialization));
 			throw new Error(`[devframe-rpc] No dump match for "${functionName}" with args: ${JSON.stringify(args)}`);
 		}
-		if (args.length === 0) return entry;
+		if (!hasMeaningfulArgs(args)) return entry;
 		throw new Error(`[devframe-rpc] No dump match for "${functionName}" with args: ${JSON.stringify(args)}`);
 	}
 	return {
@@ -415,6 +482,7 @@ async function createStaticRpcClientMode(options) {
 		isTrusted: true,
 		requestTrust: async () => true,
 		requestTrustWithToken: async () => true,
+		requestTrustWithCode: async () => null,
 		ensureTrusted: async () => true,
 		call: (...args) => staticCaller.call(args[0], args.slice(1)),
 		callEvent: (...args) => staticCaller.callEvent(args[0], args.slice(1)),
@@ -1753,15 +1821,51 @@ function parseUA(uastringOrExtensions, extensions) {
 }
 //#endregion
 //#region src/client/rpc-ws.ts
-function isNumeric(str) {
-	if (str == null) return false;
-	return `${+str}` === `${str}`;
+/**
+* Resolve a {@link ConnectionMeta.websocket} descriptor into a concrete
+* `ws(s)://` URL.
+*
+* 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
+* 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.
+*/
+function resolveWsUrl(websocket, metaBaseUrl, loc) {
+	const wsProtocol = loc.protocol === "https:" ? "wss:" : "ws:";
+	const base = (() => {
+		try {
+			return new URL(metaBaseUrl, loc.href);
+		} catch {
+			return new URL(loc.href);
+		}
+	})();
+	if (websocket && typeof websocket === "object") {
+		if (websocket.host != null || websocket.port != null) {
+			const host = websocket.host ?? `${loc.hostname}:${websocket.port}`;
+			const target = new URL(websocket.path ?? "/", `${wsProtocol}//${host}`);
+			target.protocol = wsProtocol;
+			return target.href;
+		}
+		const target = new URL(websocket.path ?? "", base);
+		target.protocol = wsProtocol;
+		return target.href;
+	}
+	if (typeof websocket === "number") return `${wsProtocol}//${loc.hostname}:${websocket}`;
+	const str = websocket ?? "";
+	if (/^wss?:\/\//i.test(str)) return str;
+	if (/^https?:\/\//i.test(str)) return withProtocol(str, /^https/i.test(str) ? "wss://" : "ws://");
+	const target = new URL(str, base);
+	target.protocol = wsProtocol;
+	return target.href;
 }
 function createWsRpcClientMode(options) {
-	const { authToken, connectionMeta, events, clientRpc, rpcOptions = {}, wsOptions = {} } = options;
+	const { authToken, connectionMeta, metaBaseUrl, events, clientRpc, rpcOptions = {}, wsOptions = {} } = options;
 	let isTrusted = false;
 	const trustedPromise = promiseWithResolver();
-	const url = isNumeric(connectionMeta.websocket) ? `${location.protocol.replace("http", "ws")}//${location.hostname}:${connectionMeta.websocket}` : connectionMeta.websocket;
+	const url = resolveWsUrl(connectionMeta.websocket, metaBaseUrl ?? "./", location);
 	const definitions = /* @__PURE__ */ new Map();
 	for (const name of connectionMeta.jsonSerializableMethods ?? []) definitions.set(name, { jsonSerializable: true });
 	const serverRpc = createRpcClient(clientRpc.functions, {
@@ -1782,10 +1886,9 @@ function createWsRpcClientMode(options) {
 		}
 	});
 	let currentAuthToken = authToken;
-	async function requestTrustWithToken(token) {
-		currentAuthToken = token;
+	function describeUA() {
 		const info = parseUA(navigator.userAgent);
-		const ua = [
+		return [
 			info.browser.name,
 			info.browser.version,
 			"|",
@@ -1793,19 +1896,36 @@ function createWsRpcClientMode(options) {
 			info.os.version,
 			info.device.type
 		].filter((i) => i).join(" ");
+	}
+	async function requestTrustWithToken(token) {
+		currentAuthToken = token;
 		const result = await serverRpc.$call("devframe:anonymous:auth", {
 			authToken: token,
-			ua,
+			ua: describeUA(),
 			origin: location.origin
 		});
 		isTrusted = result.isTrusted;
-		trustedPromise.resolve(isTrusted);
+		if (isTrusted) trustedPromise.resolve(true);
 		events.emit("rpc:is-trusted:updated", isTrusted);
 		return result.isTrusted;
 	}
+	async function requestTrustWithCode(code) {
+		const token = (await serverRpc.$call("devframe:auth:exchange", {
+			code,
+			ua: describeUA(),
+			origin: location.origin
+		}))?.authToken ?? null;
+		if (token) {
+			currentAuthToken = token;
+			isTrusted = true;
+			trustedPromise.resolve(true);
+			events.emit("rpc:is-trusted:updated", true);
+		}
+		return token;
+	}
 	async function requestTrust() {
 		if (isTrusted) return true;
-		return requestTrustWithToken(currentAuthToken);
+		return requestTrustWithToken(currentAuthToken ?? "");
 	}
 	async function ensureTrusted(timeout = 6e4) {
 		if (isTrusted) trustedPromise.resolve(true);
@@ -1825,6 +1945,7 @@ function createWsRpcClientMode(options) {
 		},
 		requestTrust,
 		requestTrustWithToken,
+		requestTrustWithCode,
 		ensureTrusted,
 		call: (...args) => {
 			return serverRpc.$call(...args);
@@ -1838,26 +1959,101 @@ function createWsRpcClientMode(options) {
 	};
 }
 //#endregion
+//#region src/client/settings.ts
+function createClientSettingsStore(rpc, namespace, scope) {
+	const stateKey = `devframe:settings:${scope}:${namespace}`;
+	let statePromise;
+	function store() {
+		if (!statePromise) statePromise = rpc.sharedState.get(stateKey, { initialValue: {} });
+		return statePromise;
+	}
+	return {
+		async get(key) {
+			return (await store()).value()[key];
+		},
+		async set(key, value) {
+			(await store()).mutate((draft) => {
+				draft[key] = value;
+			});
+		},
+		async delete(key) {
+			(await store()).mutate((draft) => {
+				delete draft[key];
+			});
+		},
+		async all() {
+			return (await store()).value();
+		},
+		async onChange(fn) {
+			return (await store()).on("updated", (full) => fn(full));
+		}
+	};
+}
+/**
+* Build the client-side `settings` surface for a scope namespace. Mirrors
+* the node-side stores over the shared-state sync protocol.
+*/
+function createClientSettings(rpc, namespace) {
+	return {
+		global: createClientSettingsStore(rpc, namespace, "global"),
+		project: createClientSettingsStore(rpc, namespace, "project")
+	};
+}
+//#endregion
+//#region src/client/scope.ts
+/**
+* Build a namespace-scoped view of a {@link DevframeRpcClient}. Every RPC
+* id, shared-state key, and streaming channel passed through the returned
+* `rpc` surface is auto-namespaced with `<namespace>:`.
+*/
+function createScopedClientContext(rpc, namespace) {
+	return {
+		namespace,
+		base: rpc,
+		rpc: {
+			namespace,
+			register(fn) {
+				if (isQualifiedName(fn.name)) throw new Error(`[devframe] Scoped client RPC registration for namespace "${namespace}" received an already-namespaced function name "${fn.name}". Pass a bare name without a ":" separator.`);
+				rpc.client.register({
+					...fn,
+					name: `${namespace}:${fn.name}`
+				});
+			},
+			call: ((method, ...args) => rpc.call(qualifyName(namespace, method), ...args)),
+			callEvent: ((method, ...args) => rpc.callEvent(qualifyName(namespace, method), ...args)),
+			callOptional: ((method, ...args) => rpc.callOptional(qualifyName(namespace, method), ...args)),
+			sharedState: ((key, options) => rpc.sharedState.get(qualifyName(namespace, key), options)),
+			streaming: {
+				subscribe: (channel, id, options) => rpc.streaming.subscribe(qualifyName(namespace, channel), id, options),
+				upload: (channel, id) => rpc.streaming.upload(qualifyName(namespace, channel), id)
+			}
+		},
+		settings: createClientSettings(rpc, namespace),
+		scope: rpc.scope
+	};
+}
+//#endregion
 //#region src/client/rpc.ts
 const CONNECTION_META_KEY = "__DEVFRAME_CONNECTION_META__";
 const CONNECTION_AUTH_TOKEN_KEY = "__DEVFRAME_CONNECTION_AUTH_TOKEN__";
-function getConnectionAuthTokenFromWindows(userAuthToken) {
+function getStoredAuthToken(userAuthToken) {
 	const getters = [
 		() => userAuthToken,
-		() => localStorage.getItem(CONNECTION_AUTH_TOKEN_KEY),
+		() => localStorage.getItem(CONNECTION_AUTH_TOKEN_KEY) ?? void 0,
 		() => window?.[CONNECTION_AUTH_TOKEN_KEY],
 		() => globalThis?.[CONNECTION_AUTH_TOKEN_KEY],
 		() => parent.window?.[CONNECTION_AUTH_TOKEN_KEY]
 	];
-	let value;
 	for (const getter of getters) try {
-		value = getter();
-		if (value) break;
+		const value = getter();
+		if (value) return value;
 	} catch {}
-	if (!value) value = humanId();
-	localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, value);
-	globalThis[CONNECTION_AUTH_TOKEN_KEY] = value;
-	return value;
+}
+function persistAuthToken(token) {
+	try {
+		localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, token);
+	} catch {}
+	globalThis[CONNECTION_AUTH_TOKEN_KEY] = token;
 }
 function findConnectionMetaFromWindows() {
 	const getters = [
@@ -1876,18 +2072,18 @@ async function getDevframeRpcClient(options = {}) {
 	const bases = Array.isArray(baseURL) ? baseURL : [baseURL];
 	let connectionMeta = options.connectionMeta || findConnectionMetaFromWindows();
 	let resolvedBaseURL = bases[0] ?? "./";
-	function normalizeBase(base) {
-		return base.endsWith("/") ? base : `${base}/`;
-	}
-	function resolveBasePath(base, path) {
-		if (/^https?:\/\//.test(path)) return path;
-		if (path.startsWith("/")) return path;
-		return `${normalizeBase(base)}${path}`;
+	function resolveMetaBaseUrl() {
+		const metaPath = withBase(DEVFRAME_CONNECTION_META_FILENAME, resolvedBaseURL);
+		try {
+			return new URL(metaPath, globalThis.location?.href).href;
+		} catch {
+			return metaPath;
+		}
 	}
 	if (!connectionMeta) {
 		const errors = [];
 		for (const base of bases) try {
-			connectionMeta = await fetch(resolveBasePath(base, DEVFRAME_CONNECTION_META_FILENAME)).then((r) => r.json());
+			connectionMeta = await fetch(withBase(DEVFRAME_CONNECTION_META_FILENAME, base)).then((r) => r.json());
 			resolvedBaseURL = base;
 			globalThis[CONNECTION_META_KEY] = connectionMeta;
 			break;
@@ -1901,13 +2097,14 @@ async function getDevframeRpcClient(options = {}) {
 		...typeof options.cacheOptions === "object" ? options.cacheOptions : {}
 	});
 	const context = { rpc: void 0 };
-	const authToken = getConnectionAuthTokenFromWindows(options.authToken);
+	const authToken = getStoredAuthToken(options.authToken);
+	if (authToken) persistAuthToken(authToken);
 	const clientRpc = new RpcFunctionsCollectorBase(context);
 	async function fetchJsonFromBases(path) {
 		const candidates = [resolvedBaseURL, ...bases.filter((base) => base !== resolvedBaseURL)].filter((x) => x != null);
 		const errors = [];
 		for (const base of candidates) try {
-			return await fetch(resolveBasePath(base, path)).then((r) => {
+			return await fetch(withBase(path, base)).then((r) => {
 				if (!r.ok) throw new Error(`Failed to fetch ${path} from ${base}: ${r.status}`);
 				return r.json();
 			});
@@ -1919,6 +2116,7 @@ async function getDevframeRpcClient(options = {}) {
 	const mode = connectionMeta.backend === "static" ? await createStaticRpcClientMode({ fetchJsonFromBases }) : createWsRpcClientMode({
 		authToken,
 		connectionMeta,
+		metaBaseUrl: resolveMetaBaseUrl(),
 		events,
 		clientRpc,
 		rpcOptions: {
@@ -1937,6 +2135,10 @@ async function getDevframeRpcClient(options = {}) {
 		},
 		wsOptions: options.wsOptions
 	});
+	let authChannel;
+	try {
+		authChannel = new BroadcastChannel("devframe-auth");
+	} catch {}
 	const rpc = {
 		events,
 		get isTrusted() {
@@ -1946,32 +2148,53 @@ async function getDevframeRpcClient(options = {}) {
 		ensureTrusted: mode.ensureTrusted,
 		requestTrust: mode.requestTrust,
 		requestTrustWithToken: async (token) => {
-			localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, token);
-			globalThis[CONNECTION_AUTH_TOKEN_KEY] = token;
+			persistAuthToken(token);
 			return mode.requestTrustWithToken(token);
 		},
+		requestTrustWithCode: async (code) => {
+			const token = await mode.requestTrustWithCode(code);
+			if (!token) return false;
+			persistAuthToken(token);
+			try {
+				authChannel?.postMessage({
+					type: "auth-update",
+					authToken: token
+				});
+			} catch {}
+			return true;
+		},
 		call: mode.call,
 		callEvent: mode.callEvent,
 		callOptional: mode.callOptional,
 		client: clientRpc,
 		sharedState: void 0,
 		streaming: void 0,
-		cacheManager
+		cacheManager,
+		scope: void 0
 	};
 	rpc.sharedState = createRpcSharedStateClientHost(rpc);
 	rpc.streaming = createRpcStreamingClientHost(rpc);
+	const scopedCache = /* @__PURE__ */ new Map();
+	rpc.scope = ((namespace) => {
+		if (!namespace) return rpc;
+		let scoped = scopedCache.get(namespace);
+		if (!scoped) {
+			scoped = createScopedClientContext(rpc, namespace);
+			scopedCache.set(namespace, scoped);
+		}
+		return scoped;
+	});
 	context.rpc = rpc;
 	mode.requestTrust();
-	try {
-		const bc = new BroadcastChannel("devframe-auth");
-		bc.onmessage = (event) => {
-			if (event.data?.type === "auth-update" && event.data.authToken) rpc.requestTrustWithToken(event.data.authToken);
-		};
-	} catch {}
+	const otpParam = options.otpParam ?? "devframe_otp";
+	if (otpParam) authenticateWithUrlOtp(rpc, { param: otpParam });
+	if (authChannel) authChannel.onmessage = (event) => {
+		if (event.data?.type === "auth-update" && event.data.authToken) rpc.requestTrustWithToken(event.data.authToken);
+	};
 	return rpc;
 }
 //#endregion
 //#region src/client/index.ts
 const connectDevframe = getDevframeRpcClient;
 //#endregion
-export { connectDevframe, createRpcStreamingClientHost, getDevframeRpcClient };
+export { authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, readOtpFromUrl };

package/dist/constants.d.mts

@@ -3,6 +3,14 @@ declare const DEVFRAME_MOUNT_PATH = "/__devframe/";
 declare const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH = "/__devframe";
 declare const DEVFRAME_DIRNAME = "__devframe";
 declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
+/**
+ * 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
+ * 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).
+ */
+declare const DEVFRAME_WS_ROUTE = "__devframe_ws";
 declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 declare const DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID = "/__devframe-client-imports.js";
@@ -13,5 +21,13 @@ declare const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
  * `@vitejs/devtools-kit`) injected into remote-UI iframe dock URLs.
  */
 declare const REMOTE_CONNECTION_KEY = "devframe-remote-connection";
+/**
+ * Page-URL query parameter carrying a one-time authentication code (OTP) for
+ * "magic link" auth. A host can print a link like `<origin>/?devframe_otp=<code>`;
+ * the client reads the code, exchanges it for a token, and strips the parameter
+ * from the URL. See `buildOtpAuthUrl` (node) and the `authenticateWithUrlOtp` /
+ * `consumeOtpFromUrl` client utilities (or `connectDevframe`'s `otpParam`).
+ */
+declare const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
 //#endregion
-export { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, REMOTE_CONNECTION_KEY };
+export { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY };

package/dist/constants.mjs

@@ -3,6 +3,14 @@ const DEVFRAME_MOUNT_PATH = "/__devframe/";
 const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH = "/__devframe";
 const DEVFRAME_DIRNAME = "__devframe";
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
+/**
+* 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
+* 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).
+*/
+const DEVFRAME_WS_ROUTE = "__devframe_ws";
 const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 const DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID = "/__devframe-client-imports.js";
@@ -13,5 +21,13 @@ const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
 * `@vitejs/devtools-kit`) injected into remote-UI iframe dock URLs.
 */
 const REMOTE_CONNECTION_KEY = "devframe-remote-connection";
+/**
+* Page-URL query parameter carrying a one-time authentication code (OTP) for
+* "magic link" auth. A host can print a link like `<origin>/?devframe_otp=<code>`;
+* the client reads the code, exchanges it for a token, and strips the parameter
+* from the URL. See `buildOtpAuthUrl` (node) and the `authenticateWithUrlOtp` /
+* `consumeOtpFromUrl` client utilities (or `connectDevframe`'s `otpParam`).
+*/
+const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
 //#endregion
-export { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, REMOTE_CONNECTION_KEY };
+export { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY };

package/dist/context-3x_bgBgZ.mjs

@@ -0,0 +1,48 @@
+import { t as createStorage } from "./storage-l2ezeend.mjs";
+import { i as randomToken, n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-ENfxWkFK.mjs";
+import { join } from "pathe";
+//#region src/node/hub-internals/context.ts
+const internalContextMap = /* @__PURE__ */ new WeakMap();
+function getInternalContext(context) {
+	if (!internalContextMap.has(context)) {
+		const storage = createStorage({
+			filepath: join(context.host.getStorageDir("global"), "auth.json"),
+			initialValue: { trusted: {} }
+		});
+		const remoteTokens = /* @__PURE__ */ new Map();
+		function revokeRemoteToken(token) {
+			if (!remoteTokens.delete(token)) return;
+			revokeActiveConnectionsForToken(context, token);
+		}
+		const internalContext = {
+			storage: { auth: storage },
+			revokeAuthToken: (token) => revokeAuthToken(context, storage, token),
+			remoteTokens,
+			allocateRemoteToken(dockId, origin, originLock) {
+				const token = randomToken();
+				remoteTokens.set(token, {
+					dockId,
+					origin,
+					originLock
+				});
+				return token;
+			},
+			revokeRemoteToken,
+			revokeRemoteTokensForDock(dockId) {
+				const tokensToRevoke = [];
+				for (const [token, record] of remoteTokens) if (record.dockId === dockId) tokensToRevoke.push(token);
+				for (const token of tokensToRevoke) revokeRemoteToken(token);
+			},
+			isRemoteTokenTrusted(token, requestOrigin) {
+				const record = remoteTokens.get(token);
+				if (!record) return false;
+				if (!record.originLock) return true;
+				return !!requestOrigin && record.origin === requestOrigin;
+			}
+		};
+		internalContextMap.set(context, internalContext);
+	}
+	return internalContextMap.get(context);
+}
+//#endregion
+export { internalContextMap as n, getInternalContext as t };

package/dist/{context-DTRcO_UH.d.mts → context-o-TwncyP.d.mts}

@@ -1,4 +1,4 @@
-import { P as SharedState, d as DevframeNodeContext } from "./devframe-BuR6n9ZD.mjs";
+import { L as SharedState, m as DevframeNodeContext } from "./devframe-BwfavB78.mjs";
 
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {