@ekrooh/bare 0.4.0 → 0.5.0

package/dist/messages-BbpF3wNH.mjs

@@ -0,0 +1,849 @@
+import { TextDecoder as TextDecoder$1, TextEncoder as TextEncoder$1 } from "bare-encoding";
+// core/messages/constants.ts
+const VERSION = 1;
+const MessageType = { ENVELOPE: 1 };
+/** Canonical error codes. Everything the framework throws uses these; peers
+* may carry arbitrary codes over the wire, and consumers may return app-scoped
+* codes (e.g. `app.photos/not-found`) which are preserved verbatim. Keep
+* `android/src/main/.../ErrorCodes.kt` in sync with the canonical union. */
+const ErrorCode = {
+	UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY",
+	UNSUPPORTED_EVENT: "UNSUPPORTED_EVENT",
+	HOST_ERROR: "HOST_ERROR",
+	TRANSPORT_ERROR: "TRANSPORT_ERROR",
+	PLUGIN_ERROR: "PLUGIN_ERROR",
+	INVALID_RESPONSE: "INVALID_RESPONSE",
+	FRAME_TOO_LARGE: "FRAME_TOO_LARGE",
+	FRAME_INVALID: "FRAME_INVALID",
+	TIMEOUT: "TIMEOUT"
+};
+/** A JSON header must fit a 16-bit big-endian length field. */
+const MAX_HEADER_BYTES = 65535;
+/** Upper bound on one encoded frame. Large binary transfers are a plugin-level
+* concern (out-of-band handles), not an in-band payload. */
+const MAX_FRAME_BYTES = 16777216;
+// core/messages/types.ts
+var CoreError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "CoreError";
+		this.code = code;
+	}
+};
+// core/messages/errors.ts
+/** Success half of an `Either` tuple. */
+function ok(result) {
+	return [null, result];
+}
+/** Failure half of an `Either` tuple. Accepts a canonical error code or any
+* app-scoped code (`app.photos/not-found`) — the code is preserved verbatim. */
+function err(code, message) {
+	return [new CoreError(code, message), null];
+}
+/** Convenience for constructing a `CoreError` from a possibly-non-canonical
+* wire code: preserves known codes, maps anything else to `PLUGIN_ERROR`.
+* Framework callers that want app codes preserved construct the error
+* directly instead. */
+function coerceErrorCode(code) {
+	if (code && code in ErrorCode) return code;
+	return ErrorCode.PLUGIN_ERROR;
+}
+// core/messages/plugin-kernel.ts
+function createPluginRegistry() {
+	const plugins = /* @__PURE__ */ new Map();
+	return {
+		register(plugin) {
+			if (!plugin.id.includes(".")) throw new Error(`plugin id must be namespaced (example: "vendor.plugin"), got "${plugin.id}"`);
+			if (plugins.has(plugin.id)) throw new Error(`plugin id "${plugin.id}" is already registered`);
+			plugins.set(plugin.id, plugin);
+		},
+		resolve(pluginId, runtime) {
+			return plugins.get(pluginId)?.runtimes[runtime];
+		},
+		get(pluginId) {
+			return plugins.get(pluginId);
+		},
+		listCapabilities(runtime) {
+			const rows = [];
+			for (const plugin of plugins.values()) {
+				const runtimes = Object.keys(plugin.runtimes);
+				if (runtime && !runtimes.includes(runtime)) continue;
+				rows.push({
+					pluginId: plugin.id,
+					capabilities: plugin.capabilities ?? [],
+					events: plugin.events ?? [],
+					runtimes
+				});
+			}
+			return rows;
+		}
+	};
+}
+const DEFAULT_MAX_INFLIGHT = 64;
+const DEFAULT_HOST_CAPABILITIES_TTL_MS = 3e4;
+/** An event the cached snapshot does not list triggers a fresh query only once
+* the snapshot is at least this old, so a host that announces a capability
+* late is honored quickly while a stream of calls to an unsupported event
+* cannot turn into a stream of capability queries. */
+const NEGATIVE_REFRESH_MS = 2e3;
+/** Whether the router may synthesize an UNSUPPORTED_EVENT response. Events are
+* only gated when the manifest declares them; a plugin with no manifest/owner
+* declares nothing and is rejected. */
+function declaresEvent(plugin, event) {
+	if (!plugin) return false;
+	if (!plugin.events) return false;
+	return plugin.events.includes(event);
+}
+function createPluginRouter(registry, runtime, options) {
+	const logger = options?.logger ?? console;
+	const maxInflight = options?.maxInflight ?? DEFAULT_MAX_INFLIGHT;
+	const serialPlugins = new Set(options?.serialPlugins);
+	const serialTails = /* @__PURE__ */ new Map();
+	let inflight = 0;
+	const capsTtlMs = options?.hostCapabilitiesTtlMs ?? DEFAULT_HOST_CAPABILITIES_TTL_MS;
+	let capsCache = null;
+	let capsInflight = null;
+	/** Asks the host for its capabilities. Concurrent callers share one query
+	* (calls now overlap, so each would otherwise send its own). A failed query
+	* rejects every waiter and is not cached. */
+	function queryHostCapabilities() {
+		if (capsInflight) return capsInflight;
+		const query = (async () => await options?.getHostCapabilities?.() ?? [])().then((caps) => {
+			capsCache = {
+				caps,
+				at: Date.now()
+			};
+			return caps;
+		}).finally(() => {
+			if (capsInflight === query) capsInflight = null;
+		});
+		capsInflight = query;
+		return query;
+	}
+	/** Whether the host currently announces `pluginId.event`. Served from the
+	* cached snapshot while it is fresh; re-queried when it has expired, or when
+	* it does not list the event and is old enough to have changed. */
+	async function hostAnnounces(pluginId, event) {
+		if (capsTtlMs > 0 && capsCache) {
+			const age = Date.now() - capsCache.at;
+			if (age < capsTtlMs) {
+				if (isHostRegistered(pluginId, event, capsCache.caps)) return true;
+				if (age < NEGATIVE_REFRESH_MS) return false;
+			}
+		}
+		return isHostRegistered(pluginId, event, await queryHostCapabilities());
+	}
+	/** Deny-by-default host-delegation allowlist: an event can only be delegated
+	* once the host has announced it via `HOST_CAPABILITIES_RESPONSE`. */
+	function isHostRegistered(pluginId, event, caps) {
+		const row = caps.find((c) => c.pluginId === pluginId);
+		return row ? row.events.includes(event) : false;
+	}
+	/** Runs `task` after the previous call to the same serial plugin settles, so
+	* a failing call never wedges the queue behind it. */
+	function runSerial(pluginId, task) {
+		const run = (serialTails.get(pluginId) ?? Promise.resolve()).then(task, task);
+		const next = run.catch(() => void 0);
+		serialTails.set(pluginId, next);
+		next.then(() => {
+			if (serialTails.get(pluginId) === next) serialTails.delete(pluginId);
+		});
+		return run;
+	}
+	async function routeNow(header, payload) {
+		const plugin = isPluginEnvelopeHeader(header) ? registry.get(header.pluginId) : void 0;
+		if (isPluginEnvelopeHeader(header)) {
+			if (!declaresEvent(plugin, header.event)) {
+				const error = new CoreError(ErrorCode.UNSUPPORTED_EVENT, `Unsupported event ${header.pluginId}.${header.event} on ${runtime}`);
+				if (isPluginDispatchHeader(header)) logger.warn(error.message);
+				return invokeErrorResponse(header, error);
+			}
+		}
+		if (isPluginDispatchHeader(header)) {
+			const runtimeAdapter = registry.resolve(header.pluginId, runtime);
+			if (!runtimeAdapter?.dispatch) {
+				const error = new CoreError(ErrorCode.UNSUPPORTED_CAPABILITY, `Unsupported capability ${header.pluginId}.${header.event} on ${runtime}`);
+				logger.warn(error.message);
+				return invokeErrorResponse(header, error);
+			}
+			try {
+				await runtimeAdapter.dispatch(header.event, header.args, {
+					runtime,
+					payload,
+					sender: { pluginId: header.pluginId }
+				});
+				return null;
+			} catch (e) {
+				const error = new CoreError(ErrorCode.PLUGIN_ERROR, e instanceof Error ? e.message : String(e));
+				logger.error(`dispatch ${header.pluginId}.${header.event} failed: ${error.message}`);
+				return invokeErrorResponse(header, error);
+			}
+		}
+		if (isPluginInvokeRequestHeader(header)) {
+			const runtimeAdapter = registry.resolve(header.pluginId, runtime);
+			if (runtimeAdapter?.invoke) try {
+				const [error, okResult] = await runtimeAdapter.invoke(header.event, header.args, {
+					runtime,
+					payload,
+					sender: { pluginId: header.pluginId }
+				});
+				return {
+					type: "INVOKE_RESPONSE",
+					pluginId: header.pluginId,
+					event: header.event,
+					requestId: header.requestId,
+					result: okResult ?? void 0,
+					error: error ? {
+						code: error.code,
+						message: error.message
+					} : void 0
+				};
+			} catch (e) {
+				const error = new CoreError(ErrorCode.PLUGIN_ERROR, e instanceof Error ? e.message : String(e));
+				logger.error(`invoke ${header.pluginId}.${header.event} failed: ${error.message}`);
+				return invokeErrorResponse(header, error);
+			}
+			if (header.requestId && options?.delegateToHost) {
+				if (await hostAnnounces(header.pluginId, header.event)) try {
+					const delegated = await options.delegateToHost(header, payload);
+					if (delegated) {
+						const code = delegated.error?.code;
+						if (code === ErrorCode.UNSUPPORTED_CAPABILITY || code === ErrorCode.UNSUPPORTED_EVENT) capsCache = null;
+						return delegated;
+					}
+					capsCache = null;
+				} catch (e) {
+					capsCache = null;
+					return invokeErrorResponse(header, new CoreError(ErrorCode.HOST_ERROR, e instanceof Error ? e.message : String(e)));
+				}
+			}
+			return invokeErrorResponse(header, new CoreError(ErrorCode.UNSUPPORTED_CAPABILITY, `Unsupported capability ${header.pluginId}.${header.event} on ${runtime}`));
+		}
+		return null;
+	}
+	return { async route(header, payload) {
+		if (!isPluginEnvelopeHeader(header)) return routeNow(header, payload);
+		if (inflight >= maxInflight) {
+			const error = new CoreError(ErrorCode.TRANSPORT_ERROR, `too many calls in flight (limit ${maxInflight}); retry later`);
+			logger.warn(`${header.pluginId}.${header.event}: ${error.message}`);
+			return invokeErrorResponse(header, error);
+		}
+		inflight++;
+		try {
+			return serialPlugins.has(header.pluginId) ? await runSerial(header.pluginId, () => routeNow(header, payload)) : await routeNow(header, payload);
+		} finally {
+			inflight--;
+		}
+	} };
+}
+function createPluginBus(messenger) {
+	return {
+		dispatch(envelope) {
+			return messenger.dispatch({
+				type: "DISPATCH",
+				pluginId: envelope.pluginId,
+				event: envelope.event,
+				args: envelope.args
+			});
+		},
+		async invoke(envelope) {
+			let response;
+			try {
+				response = await messenger.invoke({
+					type: "INVOKE_REQUEST",
+					pluginId: envelope.pluginId,
+					event: envelope.event,
+					args: envelope.args
+				}, envelope.payload ?? null, envelope.timeoutMs);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return [new CoreError(message.startsWith("invoke timeout") ? ErrorCode.TIMEOUT : ErrorCode.INVALID_RESPONSE, message), null];
+			}
+			if (isPluginInvokeResponseHeader(response)) {
+				if (response.error) return [new CoreError(response.error.code, String(response.error.message ?? "Plugin invoke failed")), null];
+				return [null, response.result];
+			}
+			return [new CoreError(ErrorCode.INVALID_RESPONSE, `Unexpected response type ${response.type}`), null];
+		}
+	};
+}
+function invokeErrorResponse(header, error) {
+	return {
+		type: "INVOKE_RESPONSE",
+		pluginId: header.pluginId,
+		event: header.event,
+		requestId: header.requestId,
+		error: {
+			code: error.code,
+			message: error.message
+		}
+	};
+}
+function isPluginDispatchHeader(header) {
+	return header.type === "DISPATCH" && typeof header.pluginId === "string" && typeof header.event === "string";
+}
+function isPluginEnvelopeHeader(header) {
+	return isPluginDispatchHeader(header) || isPluginInvokeRequestHeader(header);
+}
+function isPluginInvokeRequestHeader(header) {
+	return header.type === "INVOKE_REQUEST" && typeof header.pluginId === "string" && typeof header.event === "string";
+}
+function isPluginInvokeResponseHeader(header) {
+	return header.type === "INVOKE_RESPONSE" && typeof header.pluginId === "string" && typeof header.event === "string";
+}
+// core/messages/request-id.ts
+/**
+* CSPRNG-backed correlation id for RPC requests.
+*
+* Shared by the production messenger (`rpc-messenger.ts`) and the mantaq
+* prototype (`rpc-messenger.mantaq.ts`) so the unguessable,
+* collision-resistant guarantee can never regress in a single copy. Request
+* IDs must never be derived from `Math.random()` — a guessable id lets a peer
+* spoof or collide with an in-flight request and corrupt correlation. See
+* ekrooh#141.
+*/
+function createRequestId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	globalThis.crypto.getRandomValues(bytes);
+	const rand = bytes.reduce((acc, b) => acc + b.toString(36), "").slice(0, 22);
+	return `${Date.now().toString(36)}-${rand}`;
+}
+// core/messages/rpc-messenger.ts
+/** Hard ceiling on concurrently in-flight invokes. Above this, the oldest call
+* is dropped (its timer cleared and promise rejected) so a flood of requests
+* cannot grow the pending map without bound. */
+const MAX_CONCURRENT_INVOKES = 1024;
+function createProtocolMessenger(send) {
+	const pending = /* @__PURE__ */ new Map();
+	const sharedLogTail = createSharedLogTail();
+	return {
+		dispatch(request, payload) {
+			const requestWithId = withRequestId(request);
+			send(requestWithId, payload);
+			return requestWithId.requestId;
+		},
+		invoke(request, payload, timeoutMs = 5e3) {
+			const requestWithId = withRequestId(request);
+			const { requestId, pluginId, event } = requestWithId;
+			return new Promise((resolvePromise, rejectPromise) => {
+				const fail = async (reason) => {
+					console.error(`[invoke] ${reason}`);
+					const tail = await sharedLogTail();
+					rejectPromise(new Error(tail ? `${reason}; recent logs: ${tail}` : reason));
+				};
+				const timer = setTimeout(() => {
+					pending.delete(requestId);
+					fail(`invoke timeout for ${request.type} (${requestId})`);
+				}, timeoutMs);
+				if (pending.size >= MAX_CONCURRENT_INVOKES) {
+					const oldest = pending.keys().next().value;
+					if (oldest !== void 0) {
+						const dropped = pending.get(oldest);
+						if (dropped) {
+							clearTimeout(dropped.timer);
+							dropped.reject(/* @__PURE__ */ new Error(`invoke dropped: too many concurrent invokes (${requestId})`));
+						}
+						pending.delete(oldest);
+					}
+				}
+				pending.set(requestId, {
+					pluginId,
+					event,
+					resolve: resolvePromise,
+					reject: rejectPromise,
+					timer
+				});
+				send(requestWithId, payload);
+			});
+		},
+		handleIncoming(header) {
+			if (!header.requestId) {
+				try {
+					console.debug(`[rpc] incoming ${header.type} without a requestId; uncorrelatable, dropping`);
+				} catch {}
+				return;
+			}
+			const pendingCall = pending.get(header.requestId);
+			if (!pendingCall) {
+				try {
+					console.debug(`[rpc] ${header.type} for unknown/stale requestId (${header.requestId}); dropping`);
+				} catch {}
+				return;
+			}
+			if (header.type === "INVOKE_RESPONSE" && (header.pluginId !== pendingCall.pluginId || header.event !== pendingCall.event)) {
+				try {
+					console.debug(`[rpc] RESPONSE for ${header.requestId} mismatches pending ${pendingCall.pluginId}.${pendingCall.event} (got ${header.pluginId}.${header.event}); dropping`);
+				} catch {}
+				return;
+			}
+			clearTimeout(pendingCall.timer);
+			pending.delete(header.requestId);
+			pendingCall.resolve(header);
+		}
+	};
+}
+function withRequestId(request) {
+	return {
+		...request,
+		requestId: createRequestId()
+	};
+}
+const INVOKE_TAIL_TIMEOUT_MS = 2e3;
+/** A tail fetched within this window is reused for later timeouts instead of
+* fetching again. Timeouts cluster (a stalled peer times out every pending
+* call at once), so without this each one would add its own `/logs` request to
+* the server that is already struggling. */
+const INVOKE_TAIL_MIN_INTERVAL_MS = 5e3;
+/**
+* Wraps {@link serverLogTail} so concurrent timeouts share one request and
+* timeouts shortly after a fetch reuse its result. State is per messenger, so
+* nothing leaks between instances.
+*/
+function createSharedLogTail() {
+	let inflight = null;
+	let last = null;
+	return () => {
+		if (inflight) return inflight;
+		if (last && Date.now() - last.at < INVOKE_TAIL_MIN_INTERVAL_MS) return Promise.resolve(last.tail);
+		inflight = serverLogTail().then((tail) => {
+			last = {
+				at: Date.now(),
+				tail
+			};
+			return tail;
+		}).finally(() => {
+			inflight = null;
+		});
+		return inflight;
+	};
+}
+/**
+* Fetches a short tail of the loopback server's log (worklet + webview console)
+* to enrich an invoke timeout with whatever the peer just saw. Best-effort:
+* only attempted in a browser/webview context where `fetch` and a same-origin
+* `/logs` route exist; never throws into the caller. Returns null when nothing
+* can be learned.
+*/
+async function serverLogTail() {
+	if (typeof fetch !== "function" || typeof window === "undefined") return null;
+	try {
+		const response = await Promise.race([fetch("/logs?tail=50&format=text"), new Promise((resolve) => setTimeout(() => resolve(null), INVOKE_TAIL_TIMEOUT_MS))]);
+		if (response === null || !response.ok) return null;
+		const lines = (await response.text()).split("\n").map((line) => line.trim()).filter((line) => line.length > 0).slice(-20);
+		return lines.length > 0 ? lines.join(" | ") : null;
+	} catch {
+		return null;
+	}
+}
+// core/messages/wire-codec.ts
+/** Smallest frame that can legally carry a maximum-size header. Below this the
+* decoder could never extract a header, so it is the effective floor for the
+* frame cap. The frame prefix is `[version][type][headerLenHi][headerLenLo]
+* [payloadLenHi][payloadLenMid][payloadLenLo]`, so the floor is
+* 7 + MAX_HEADER_BYTES. */
+const MIN_FRAME_BYTES = 65542;
+function clampFrameBytes(value) {
+	return Math.min(Math.max(Number.isFinite(value) ? Math.floor(value) : MAX_FRAME_BYTES, MIN_FRAME_BYTES), MAX_FRAME_BYTES);
+}
+let sharedEncoder;
+let sharedDecoder;
+function defaultEncode(str) {
+	sharedEncoder ??= new TextEncoder();
+	return sharedEncoder.encode(str);
+}
+function defaultDecode(bytes) {
+	sharedDecoder ??= new TextDecoder(void 0, { fatal: true });
+	return sharedDecoder.decode(bytes);
+}
+var MessageProtocol = class {
+	encodeStr;
+	decodeStr;
+	allowUnknownTypes;
+	/** Resolved, clamped frame cap. Public so callers/tests can inspect the
+	* effective limit after clamping. */
+	maxFrameBytes;
+	constructor(options) {
+		this.encodeStr = options?.encode || defaultEncode;
+		this.decodeStr = options?.decode || defaultDecode;
+		this.allowUnknownTypes = options?.allowUnknownTypes ?? false;
+		this.maxFrameBytes = clampFrameBytes(options?.maxFrameBytes ?? 16777216);
+	}
+	encode(type, header, payload) {
+		let payloadBytes;
+		if (payload == null) payloadBytes = /* @__PURE__ */ new Uint8Array(0);
+		else if (typeof payload === "string") payloadBytes = this.encodeStr(payload);
+		else if (payload instanceof ArrayBuffer) payloadBytes = new Uint8Array(payload);
+		else payloadBytes = payload;
+		const pLen = payloadBytes.byteLength;
+		const headerObj = { ...header };
+		if (pLen > 0) headerObj.payloadLength = pLen;
+		const headerJson = JSON.stringify(headerObj);
+		const headerBytes = this.encodeStr(headerJson);
+		if (headerBytes.byteLength > 65535) throw new Error(`Header too large: ${headerBytes.byteLength} bytes, maximum is ${MAX_HEADER_BYTES}`);
+		const hLen = headerBytes.byteLength;
+		const totalLength = 7 + hLen + pLen;
+		if (totalLength > this.maxFrameBytes) throw new Error(`Frame too large: ${totalLength} bytes, maximum is ${this.maxFrameBytes}`);
+		let buffer;
+		if (typeof Buffer !== "undefined" && typeof Buffer.allocUnsafe === "function") buffer = Buffer.allocUnsafe(totalLength);
+		else buffer = new Uint8Array(totalLength);
+		buffer[0] = 1;
+		buffer[1] = type;
+		buffer[2] = hLen >> 8 & 255;
+		buffer[3] = hLen & 255;
+		buffer[4] = pLen >> 16 & 255;
+		buffer[5] = pLen >> 8 & 255;
+		buffer[6] = pLen & 255;
+		buffer.set(headerBytes, 7);
+		if (pLen > 0) buffer.set(payloadBytes, 7 + hLen);
+		return buffer;
+	}
+	decode(data) {
+		const view = data instanceof Uint8Array ? data : new Uint8Array(data);
+		const byteLength = view.byteLength;
+		if (byteLength < 7) throw new Error(`Message too short: ${byteLength} bytes`);
+		if (byteLength > this.maxFrameBytes) throw new Error(`Frame too large: ${byteLength} bytes, maximum is ${this.maxFrameBytes}`);
+		const version = view[0];
+		if (version !== 1) throw new Error(`Unsupported version: ${version}. Expected 1`);
+		const type = view[1];
+		if (!this.allowUnknownTypes && !isKnownMessageType(type)) throw new Error(`Unsupported message type: ${type}`);
+		const headerLen = view[2] << 8 | view[3];
+		const payloadLen = view[4] << 16 | view[5] << 8 | view[6];
+		if (headerLen > 65535) throw new Error(`Header too large: ${headerLen} bytes, maximum is ${MAX_HEADER_BYTES}`);
+		if (7 + headerLen + payloadLen > this.maxFrameBytes) throw new Error(`Frame too large: 7 + ${headerLen} + ${payloadLen} bytes, maximum is ${this.maxFrameBytes}`);
+		if (byteLength < 7 + headerLen + payloadLen) throw new Error(`Message too short for frame: ${byteLength} bytes, expected at least ${7 + headerLen + payloadLen}`);
+		let headerStr;
+		try {
+			headerStr = this.decodeStr(view.subarray(7, 7 + headerLen));
+		} catch {
+			try {
+				console.debug("[wire] header frame is not valid UTF-8");
+			} catch {}
+			throw new CoreError(ErrorCode.FRAME_INVALID, "FRAME_INVALID: header frame is not valid UTF-8");
+		}
+		return {
+			type,
+			header: parseAndValidateHeader(headerStr),
+			payload: view.subarray(7 + headerLen, 7 + headerLen + payloadLen)
+		};
+	}
+};
+const KNOWN_MESSAGE_TYPES = new Set(Object.values(MessageType));
+function isKnownMessageType(type) {
+	return KNOWN_MESSAGE_TYPES.has(type);
+}
+function parseAndValidateHeader(headerJson) {
+	const parsed = JSON.parse(headerJson);
+	if (!parsed || typeof parsed !== "object") throw new Error("Invalid header: expected object");
+	const header = parsed;
+	switch (header.type) {
+		case "DISPATCH":
+			if (isValidPluginHeaderFields(header)) return mergeHeader(header, {
+				type: "DISPATCH",
+				pluginId: header.pluginId,
+				event: header.event,
+				requestId: asOptionalString(header.requestId),
+				args: asOptionalRecord(header.args)
+			});
+			break;
+		case "INVOKE_REQUEST":
+			if (isValidPluginHeaderFields(header)) return mergeHeader(header, {
+				type: "INVOKE_REQUEST",
+				pluginId: header.pluginId,
+				event: header.event,
+				requestId: asOptionalString(header.requestId),
+				args: asOptionalRecord(header.args)
+			});
+			break;
+		case "INVOKE_RESPONSE":
+			if (isValidPluginHeaderFields(header)) return mergeHeader(header, {
+				type: "INVOKE_RESPONSE",
+				pluginId: header.pluginId,
+				event: header.event,
+				requestId: asOptionalString(header.requestId),
+				result: sanitizeValue(header.result, 0),
+				error: parseCoreErrorWire(header.error)
+			});
+			break;
+		case "HOST_CAPABILITIES_QUERY":
+			if (typeof header.requestId === "string") return mergeHeader(header, {
+				type: "HOST_CAPABILITIES_QUERY",
+				requestId: header.requestId
+			});
+			break;
+		case "HOST_CAPABILITIES_RESPONSE":
+			if (typeof header.requestId === "string") return mergeHeader(header, {
+				type: "HOST_CAPABILITIES_RESPONSE",
+				requestId: header.requestId,
+				capabilities: parseCapabilityDescriptors(header.capabilities)
+			});
+			break;
+		case "HOST_INVOKE_REQUEST":
+			if (typeof header.requestId === "string" && typeof header.pluginId === "string" && typeof header.event === "string") return mergeHeader(header, {
+				type: "HOST_INVOKE_REQUEST",
+				requestId: header.requestId,
+				pluginId: header.pluginId,
+				event: header.event,
+				args: asOptionalRecord(header.args)
+			});
+			break;
+		case "HOST_INVOKE_RESPONSE": if (typeof header.requestId === "string" && typeof header.pluginId === "string" && typeof header.event === "string") return mergeHeader(header, {
+			type: "HOST_INVOKE_RESPONSE",
+			requestId: header.requestId,
+			pluginId: header.pluginId,
+			event: header.event,
+			result: sanitizeValue(header.result, 0),
+			error: parseCoreErrorWire(header.error)
+		});
+	}
+	throw new Error(`Unsupported header type: ${String(header.type)}`);
+}
+/** Only allowlisted, schema-known fields are carried forward. Unknown wire
+* fields are dropped so attacker-controlled keys (e.g. `__proto__` or an
+* arbitrary `args` key) never ride into plugin args/result objects. */
+function mergeHeader(parsed, known) {
+	return known;
+}
+function isValidPluginHeaderFields(header) {
+	return typeof header.pluginId === "string" && typeof header.event === "string";
+}
+function asOptionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function asOptionalRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	return sanitizeValue(value, 0);
+}
+/** Recursively copy an attacker-controlled value onto a `null`-prototype object,
+* dropping prototype-polluting keys (`__proto__`/`constructor`/`prototype`) and
+* rejecting excessive nesting or breadth (depth/array bombs carried inside the
+* 64KB header budget). Throws {@link ErrorCode.FRAME_INVALID} on over-deep
+* structures. */
+const MAX_VALUE_DEPTH = 16;
+/** Ceiling on array elements / object keys at any one level of a sanitized
+* value. Together with {@link MAX_VALUE_DEPTH} and the 64KB header budget this
+* bounds total allocation: a wide-but-shallow structure can still be
+* serialized into a legal header, so it must be rejected, not materialized. */
+const MAX_VALUE_CARDINALITY = 16384;
+function sanitizeValue(value, depth) {
+	if (depth > MAX_VALUE_DEPTH) throw new CoreError(ErrorCode.FRAME_INVALID, `FRAME_INVALID: value nested deeper than ${MAX_VALUE_DEPTH} levels`);
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) {
+		if (value.length > MAX_VALUE_CARDINALITY) throw new CoreError(ErrorCode.FRAME_INVALID, `FRAME_INVALID: array longer than ${MAX_VALUE_CARDINALITY} elements`);
+		return value.map((item) => sanitizeValue(item, depth + 1));
+	}
+	const keys = Object.keys(value);
+	if (keys.length > MAX_VALUE_CARDINALITY) throw new CoreError(ErrorCode.FRAME_INVALID, `FRAME_INVALID: object with more than ${MAX_VALUE_CARDINALITY} keys`);
+	const out = Object.create(null);
+	for (const key of keys) {
+		if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+		out[key] = sanitizeValue(value[key], depth + 1);
+	}
+	return out;
+}
+function parseCoreErrorWire(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const candidate = value;
+	if (typeof candidate.code !== "string" || typeof candidate.message !== "string") return void 0;
+	return {
+		code: candidate.code,
+		message: candidate.message
+	};
+}
+const RUNTIME_TARGETS = /* @__PURE__ */ new Set([
+	"web",
+	"android",
+	"ios",
+	"bare"
+]);
+function parseRuntimeTarget(value) {
+	if (typeof value !== "string") return null;
+	return RUNTIME_TARGETS.has(value) ? value : null;
+}
+function parseCapabilityDescriptors(value) {
+	if (!Array.isArray(value)) return [];
+	const out = [];
+	for (const row of value) {
+		if (!row || typeof row !== "object") continue;
+		const r = row;
+		if (typeof r.pluginId !== "string") continue;
+		const events = Array.isArray(r.events) ? r.events.filter((e) => typeof e === "string") : [];
+		const caps = Array.isArray(r.capabilities) ? r.capabilities.filter((c) => typeof c === "string") : [];
+		const runtimes = [];
+		if (Array.isArray(r.runtimes)) for (const rt of r.runtimes) {
+			const parsed = parseRuntimeTarget(rt);
+			if (parsed) runtimes.push(parsed);
+		}
+		out.push({
+			pluginId: r.pluginId,
+			capabilities: caps,
+			events,
+			runtimes
+		});
+	}
+	return out;
+}
+// core/messages/define-plugin.ts
+/**
+* Builds a {@link PluginManifest} from an event spec table. The `events` list
+* is derived from the specs and handlers are dispatched by event name — no
+* hand-written if-chains. Handlers receive typed args. Plugins with no local
+* handlers (host-delegated, e.g. `core.permissions`) pass no `invoke`/`dispatch`.
+*/
+function definePlugin(id, specs, options = {}) {
+	const invokeByEvent = /* @__PURE__ */ new Map();
+	const dispatchByEvent = /* @__PURE__ */ new Map();
+	const events = [];
+	for (const key of Object.keys(specs)) {
+		const spec = specs[key];
+		if (spec.pluginId !== id) throw new Error(`event spec ${spec.name} belongs to ${spec.pluginId}, not ${id}`);
+		events.push(spec.name);
+		const invoker = options.invoke?.[key];
+		if (invoker) invokeByEvent.set(spec.name, invoker);
+		const dispatcher = options.dispatch?.[key];
+		if (dispatcher) dispatchByEvent.set(spec.name, dispatcher);
+	}
+	const adapter = {};
+	if (invokeByEvent.size > 0) adapter.invoke = (event, args, context) => {
+		const handler = invokeByEvent.get(event);
+		if (!handler) throw new Error(`Unhandled invoke event ${event}`);
+		return handler(args, context);
+	};
+	if (dispatchByEvent.size > 0) adapter.dispatch = (event, args, context) => {
+		const handler = dispatchByEvent.get(event);
+		if (!handler) throw new Error(`Unhandled dispatch event ${event}`);
+		return handler(args, context);
+	};
+	const runtimes = {};
+	if (invokeByEvent.size > 0 || dispatchByEvent.size > 0) runtimes.bare = adapter;
+	return {
+		id,
+		capabilities: options.capabilities,
+		events,
+		runtimes
+	};
+}
+/** Typed builder: an invoke envelope for a spec's event. */
+function invokeEvent(spec, args, payload, timeoutMs) {
+	return {
+		kind: "invoke",
+		pluginId: spec.pluginId,
+		event: spec.name,
+		args,
+		payload,
+		timeoutMs
+	};
+}
+/** Typed builder: a dispatch envelope for a spec's event. */
+function dispatchEvent(spec, args, payload) {
+	return {
+		kind: "dispatch",
+		pluginId: spec.pluginId,
+		event: spec.name,
+		args,
+		payload
+	};
+}
+// core/messages/create-bare-runtime-context.ts
+function createBareRuntimeContext(plugins = [], routerOptions) {
+	const runtime = "bare";
+	const protocol = new MessageProtocol({
+		encode: (str) => new TextEncoder$1().encode(str),
+		decode: (bytes) => new TextDecoder$1().decode(bytes)
+	});
+	const pluginRegistry = createPluginRegistry();
+	for (const plugin of plugins) pluginRegistry.register(plugin);
+	return {
+		protocol,
+		pluginRegistry,
+		pluginRouter: createPluginRouter(pluginRegistry, runtime, routerOptions)
+	};
+}
+// core/logs/capture-web.ts
+function safeStringify(value) {
+	if (typeof value === "string") return value;
+	if (value instanceof Error) return value.stack ?? value.message;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+function formatArgs(args) {
+	if (args.length === 0) return "";
+	return args.map((a) => safeStringify(a)).join(" ");
+}
+function isFetchAvailable() {
+	return typeof fetch === "function";
+}
+/**
+* Web-side console capture: wraps the console methods, buffers formatted
+* entries, and flushes them as a batch to the loopback `POST /logs` ingest
+* route with `source: 'web'` (same-origin fetch). Every step is try/catch-
+* wrapped so the seam can never break the app. Skip installing in mock mode,
+* where there is no loopback backend to ingest into.
+*/
+function installWebConsoleCapture(options = {}) {
+	const { endpoint = "/logs", flushThreshold = 25, flushIntervalMs = 1e3, ingest } = options;
+	const original = {
+		debug: console.debug,
+		log: console.log,
+		info: console.info,
+		warn: console.warn,
+		error: console.error
+	};
+	const pending = [];
+	function flush() {
+		if (pending.length === 0) return;
+		const batch = pending.splice(0, pending.length);
+		let flushed;
+		try {
+			flushed = ingest ? ingest({
+				source: "web",
+				entries: batch
+			}) : isFetchAvailable() ? fetch(endpoint, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					source: "web",
+					entries: batch
+				})
+			}).catch(() => void 0) : void 0;
+		} catch {
+			return;
+		}
+		if (flushed) Promise.resolve(flushed).catch(() => void 0);
+	}
+	const wrap = (method, level) => {
+		return (...args) => {
+			try {
+				pending.push({
+					level,
+					message: formatArgs(args)
+				});
+				if (pending.length >= flushThreshold) flush();
+			} catch {}
+			try {
+				original[method].apply(console, args);
+			} catch {}
+		};
+	};
+	console.debug = wrap("debug", "debug");
+	console.log = wrap("log", "info");
+	console.info = wrap("info", "info");
+	console.warn = wrap("warn", "warn");
+	console.error = wrap("error", "error");
+	const timer = flushIntervalMs > 0 ? setInterval(flush, flushIntervalMs) : void 0;
+	return {
+		flush,
+		restore() {
+			if (timer !== void 0) clearInterval(timer);
+			console.debug = original.debug;
+			console.log = original.log;
+			console.info = original.info;
+			console.warn = original.warn;
+			console.error = original.error;
+		}
+	};
+}
+export { MAX_FRAME_BYTES as _, invokeEvent as a, VERSION as b, createRequestId as c, createPluginRouter as d, coerceErrorCode as f, ErrorCode as g, CoreError as h, dispatchEvent as i, createPluginBus as l, ok as m, createBareRuntimeContext as n, MessageProtocol as o, err as p, definePlugin as r, createProtocolMessenger as s, installWebConsoleCapture as t, createPluginRegistry as u, MAX_HEADER_BYTES as v, MessageType as y };