devframe 0.9.12 → 0.9.13

package/dist/client/index.mjs

@@ -1,12 +1,10 @@
-import { t as DEVFRAME_EVENTS } from "../events-BV4Dj59a.mjs";
+import { n as DEVFRAME_EVENTS, t as defineDiagnostics } from "../nostics-DD6gsDZA.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-CaxB1q0h.mjs";
+import { t as createSharedState } from "../shared-state-eQVYHNqA.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";
-import { ansiFormatter } from "nostics/formatters/ansi";
+import { toAgentToolName } from "../utils/agent-tool-name.mjs";
 import { withBase, withProtocol } from "ufo";
 import { createBirpc } from "birpc";
 //#region src/constants.ts
@@ -96,34 +94,8 @@ var RpcCacheManager = class {
 	}
 };
 //#endregion
-//#region src/utils/nostics.ts
-const formatAnsi = ansiFormatter(colors);
-/**
-* The reporter every {@link defineDiagnostics} call below wires in ahead of
-* any caller-supplied ones: prints the diagnostic through devframe's own
-* ANSI colors via `console[method]` (default `'warn'`).
-*/
-function devframeReporter(d, { method = "warn" } = {}) {
-	console[method](formatAnsi(d));
-}
-/**
-* Drop-in replacement for `nostics`'s `defineDiagnostics()` with devframe's
-* 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
-* here, once, so none of them need to build their own reporter (`colors`,
-* `ansiFormatter`) or take a direct dependency on `nostics` themselves.
-*/
-function defineDiagnostics$1(options) {
-	return defineDiagnostics({
-		...options,
-		reporters: [devframeReporter, ...options.reporters ?? []]
-	});
-}
-//#endregion
 //#region src/rpc/diagnostics.ts
-const diagnostics = defineDiagnostics$1({
+const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: {
 		DF0019: {
@@ -1675,6 +1647,207 @@ function createScopedClientContext(rpc, namespace) {
 	};
 }
 //#endregion
+//#region src/adapters/mcp/to-json-schema.ts
+const FALLBACK_OBJECT_SCHEMA = Object.freeze({
+	type: "object",
+	additionalProperties: true
+});
+/**
+* Convert a Standard Schema to JSON Schema for the agent/MCP surface.
+*
+* Devframe stays validator-neutral, so conversion uses the schema's own
+* [Standard JSON Schema](https://standardschema.dev/) converter
+* (`~standard.jsonSchema`) when the validator provides one; zod 4 does,
+* for example. Validators without a native converter (e.g. valibot) degrade
+* to a permissive object schema rather than pulling in a converter library.
+*/
+function safeToJsonSchema(schema) {
+	const standard = schema["~standard"];
+	if (standard.jsonSchema) try {
+		return standard.jsonSchema.input({ target: "draft-2020-12" });
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+	return FALLBACK_OBJECT_SCHEMA;
+}
+/**
+* JSON Schema for an RPC function's positional args on the agent/MCP
+* surface. Each positional arg is advertised under `arg0` / `arg1` / …,
+* matching how the agent bridge coerces the incoming object payload back
+* into positional arguments.
+*
+* Returns `{ type: 'object', properties: {} }` when there are no args.
+* @internal
+*/
+function argsToJsonSchema(args) {
+	if (!args || args.length === 0) return {
+		type: "object",
+		properties: {}
+	};
+	const properties = {};
+	const required = [];
+	for (let i = 0; i < args.length; i++) {
+		const key = `arg${i}`;
+		properties[key] = safeToJsonSchema(args[i]);
+		required.push(key);
+	}
+	return {
+		type: "object",
+		properties,
+		required,
+		additionalProperties: false
+	};
+}
+//#endregion
+//#region src/node/agent-args.ts
+/**
+* Map the args payload an agent surface receives (MCP sends an object
+* keyed `arg0`/`arg1`/…, matching the schema the adapter advertises) onto
+* a handler's positional parameters. Shared by the agent host's RPC
+* bridge and the hub's command-derived tools so the coercion cannot
+* drift between them.
+*
+* - an array passes through as-is
+* - `null`/`undefined` become a zero-argument call
+* - with declared schemas, each schema reads its own `argN` key, in order
+* - without schemas, `arg0`/`arg1`/… keys are collected when present
+* - an empty object becomes a zero-argument call
+* - anything else follows the {@link AgentArgsFallback}
+*/
+function coerceAgentPositionalArgs(args, schemas, fallback = "wrap") {
+	if (Array.isArray(args)) return args;
+	if (args === void 0 || args === null) return [];
+	if (typeof args === "object") {
+		const obj = args;
+		if (schemas && schemas.length) return schemas.map((_, i) => obj[`arg${i}`]);
+		if ("arg0" in obj) {
+			const out = [];
+			let i = 0;
+			while (`arg${i}` in obj) {
+				out.push(obj[`arg${i}`]);
+				i++;
+			}
+			return out;
+		}
+		if (Object.keys(obj).length === 0) return [];
+	}
+	return fallback === "drop" ? [] : [args];
+}
+//#endregion
+//#region src/client/webmcp.ts
+/**
+* The page's WebMCP model context, when the browser (or a polyfill)
+* provides one. Checks `document.modelContext` (current draft) first,
+* then `navigator.modelContext` (earlier drafts and polyfills).
+*/
+function resolveWebMcpModelContext() {
+	if (typeof document !== "undefined") {
+		const context = document.modelContext;
+		if (context) return context;
+	}
+	if (typeof navigator !== "undefined") {
+		const context = navigator.modelContext;
+		if (context) return context;
+	}
+}
+/**
+* Mirror the `agent`-flagged RPC functions of a browser-side collector
+* (`rpc.client`) onto the page's WebMCP model context as callable tools,
+* using the same `agent` signature, wire names, and `arg0`/`arg1`/… input
+* schema as the node-side MCP adapter. Functions without an `agent` field
+* stay unexposed (default-deny), and the tool set follows later
+* `register`/`update` calls. Returns a dispose that unregisters every tool.
+*/
+function registerWebMcpTools(clientRpc, options = {}) {
+	const resolved = options.modelContext ?? resolveWebMcpModelContext();
+	if (!resolved) return () => {};
+	const modelContext = resolved;
+	/** Unregister callbacks keyed by definition name. */
+	const registered = /* @__PURE__ */ new Map();
+	/** Wire name → definition name, to detect sanitization collisions. */
+	const wireNames = /* @__PURE__ */ new Map();
+	function register(def, agent) {
+		const name = toAgentToolName(def.name);
+		const owner = wireNames.get(name);
+		if (owner && owner !== def.name) {
+			console.warn(`[devframe] WebMCP tool name "${name}" (from "${def.name}") collides with "${owner}"; keeping the first registration.`);
+			return;
+		}
+		const controller = new AbortController();
+		const result = modelContext.registerTool({
+			name,
+			description: agent.description,
+			inputSchema: argsToJsonSchema(def.args),
+			annotations: {
+				title: agent.title ?? def.name,
+				readOnlyHint: resolveSafety(def, agent) === "read",
+				destructiveHint: resolveSafety(def, agent) === "destructive"
+			},
+			execute: (args) => executeRpcTool(def, clientRpc.context, args)
+		}, { signal: controller.signal });
+		if (result && "then" in result) result.then(() => {}, () => {});
+		wireNames.set(name, def.name);
+		registered.set(def.name, () => {
+			controller.abort();
+			if (result && "unregister" in result && typeof result.unregister === "function") result.unregister();
+			wireNames.delete(name);
+		});
+	}
+	function sync(id) {
+		const names = id ? [id] : [...clientRpc.definitions.keys()];
+		for (const name of names) {
+			registered.get(name)?.();
+			registered.delete(name);
+			const def = clientRpc.definitions.get(name);
+			const agent = def?.agent;
+			if (def && agent) register(def, agent);
+		}
+	}
+	sync();
+	const unsubscribe = clientRpc.onChanged((id) => sync(id));
+	return () => {
+		unsubscribe();
+		for (const unregister of registered.values()) unregister();
+		registered.clear();
+	};
+}
+function resolveSafety(def, agent) {
+	if (agent.safety) return agent.safety;
+	const type = def.type ?? "query";
+	return type === "static" || type === "query" ? "read" : "action";
+}
+async function executeRpcTool(def, context, args) {
+	try {
+		const positional = coerceAgentPositionalArgs(args, def.args, "wrap");
+		return { content: [{
+			type: "text",
+			text: stringifyResult(await (await getRpcHandler(def, context))(...positional))
+		}] };
+	} catch (error) {
+		return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: formatError(error)
+			}]
+		};
+	}
+}
+/**
+* Agent-exposed functions are strict-JSON by contract (`jsonSerializable:
+* true` is enforced at registration), so plain `JSON.stringify` suffices.
+*/
+function stringifyResult(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	return JSON.stringify(value, null, 2);
+}
+function formatError(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause instanceof Error ? ` (cause: ${error.cause.message})` : "";
+	return `${error.name}: ${error.message}${cause}`;
+}
+//#endregion
 //#region src/client/rpc.ts
 /**
 * Resolve the requested `transport` option against what the server
@@ -1716,6 +1889,7 @@ async function getDevframeRpcClient(options = {}) {
 	});
 	const context = { rpc: void 0 };
 	const clientRpc = new RpcFunctionsCollectorBase(context);
+	const disposeWebMcp = options.webmcp === false ? void 0 : registerWebMcpTools(clientRpc);
 	async function fetchJsonFromBases(path) {
 		const candidates = [resolvedBaseURL, ...bases.filter((base) => base !== resolvedBaseURL)].filter((x) => x != null);
 		const errors = [];
@@ -1821,7 +1995,10 @@ async function getDevframeRpcClient(options = {}) {
 		streaming: void 0,
 		cacheManager,
 		scope: void 0,
-		close: () => mode.close?.()
+		close: () => {
+			disposeWebMcp?.();
+			mode.close?.();
+		}
 	};
 	rpc.sharedState = createRpcSharedStateClientHost(rpc);
 	rpc.streaming = createRpcStreamingClientHost(rpc);
@@ -1876,4 +2053,4 @@ async function getDevframeRpcClient(options = {}) {
 //#region src/client/index.ts
 const connectDevframe = getDevframeRpcClient;
 //#endregion
-export { DevframeConnectionError, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeConnection, getDevframeRpcClient, isCallableStatus, readOtpFromUrl, registerDevframeViewerOrigin, resolveClientTransport, resolveSseUrl, resolveWsUrl, setupDevframeConnection };
+export { DevframeConnectionError, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeConnection, getDevframeRpcClient, isCallableStatus, readOtpFromUrl, registerDevframeViewerOrigin, registerWebMcpTools, resolveClientTransport, resolveSseUrl, resolveWebMcpModelContext, resolveWsUrl, setupDevframeConnection };

package/dist/constants.d.mts

@@ -22,7 +22,7 @@
  * keys (a literal is unavoidable in a type position); those declarations mirror
  * this map and move with it.
  */
-declare const DEVFRAME_EVENTS: {
+export declare const DEVFRAME_EVENTS: {
   /**
    * Node-side host `EventEmitter` events. The agent host (`ctx.agent.events`)
    * emits these as its tool/resource surface changes; protocol adapters (e.g.
@@ -78,13 +78,13 @@ 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";
+export declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
  * Global key holding the serializable connection prepared by
  * `setupDevframeConnection()`. External viewers can use this key to read the
  * connection from another JavaScript realm.
  */
-declare const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
+export 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
@@ -92,7 +92,7 @@ declare const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
  * 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 = "__ws";
+export declare const DEVFRAME_WS_ROUTE = "__ws";
 /**
  * Route the SSE RPC endpoint is bound to, relative to a devframe's base
  * path. A single method-dispatched route: `GET` opens the event stream
@@ -101,36 +101,36 @@ declare const DEVFRAME_WS_ROUTE = "__ws";
  * loaded from; the transport for hosts and proxies where the WebSocket
  * upgrade isn't available.
  */
-declare const DEVFRAME_SSE_ROUTE = "__sse";
+export declare const DEVFRAME_SSE_ROUTE = "__sse";
 /**
  * Request header carrying the SSE session id on every RPC `POST`. The
  * server mints the id as the stream's first event (`event: session`);
  * the client echoes it here so the POST joins that stream's birpc
  * channel. Mirrors birpc's own SSE helpers for wire compatibility.
  */
-declare const DEVFRAME_SSE_SESSION_HEADER = "x-birpc-session";
+export 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
  * dev server shares one port for HTTP, WS, and MCP. Opt-in via `cli.mcp`.
  */
-declare const DEVFRAME_MCP_ROUTE = "__mcp";
-declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
-declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
-declare const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
+export declare const DEVFRAME_MCP_ROUTE = "__mcp";
+export declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
+export declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
+export declare const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
 /**
  * Shared-state key carrying the wire-service advertisements (package name →
  * `DevframeServiceMeta`). Written by the node services host; mirrored to
  * clients for feature-detection via `client.services`.
  */
-declare const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
+export declare const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
 /**
  * URL fragment / query parameter name carrying the remote dock
  * connection descriptor (defined as `RemoteConnectionInfo` in
  * `@vitejs/devtools-kit`) injected into remote-UI iframe dock URLs.
  */
-declare const REMOTE_CONNECTION_KEY = "devframe-remote-connection";
+export declare const REMOTE_CONNECTION_KEY = "devframe-remote-connection";
 /**
  * Page-URL **fragment** parameter carrying a one-time authentication code (OTP)
  * for "magic link" auth. A host can print a link like
@@ -141,7 +141,7 @@ declare const REMOTE_CONNECTION_KEY = "devframe-remote-connection";
  * (node) and the `authenticateWithUrlOtp` / `consumeOtpFromUrl` client utilities
  * (or `connectDevframe`'s `otpParam`).
  */
-declare const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
+export declare const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
 /**
  * WS upgrade-URL query parameter carrying a previously-issued bearer token.
  * Set by `createWsRpcChannel` (browser transport) whenever `authToken` is
@@ -149,11 +149,11 @@ declare const DEVFRAME_OTP_URL_PARAM = "devframe_otp";
  * `recipes/interactive-auth`'s `onConnect`) so a returning client can be
  * trusted before its own `anonymous:devframe:auth` handshake call arrives.
  */
-declare const DEVFRAME_AUTH_TOKEN_QUERY_PARAM = "devframe_auth_token";
+export declare const DEVFRAME_AUTH_TOKEN_QUERY_PARAM = "devframe_auth_token";
 /** External viewer origin requested during connection bootstrap. */
-declare const DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM = "devframe_viewer_origin";
+export declare const DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM = "devframe_viewer_origin";
 /** Token that authorizes an external viewer origin registration. */
-declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
+export declare 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
@@ -162,7 +162,7 @@ declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin
  * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
  * `RemoteAssetsErrorMessage` (`devframe/types`).
  */
-declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string;
+export 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
@@ -170,13 +170,12 @@ declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string;
  * before authentication must be named `anonymous:<rest>` (e.g.
  * `anonymous:devframe:auth`).
  */
-declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
+export declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
 /**
  * Whether `name` is callable before a connection is trusted, i.e. it starts
  * with {@link ANONYMOUS_RPC_PREFIX}. Used by the resolver gate in
  * the RPC server binding (via an `authorize` function) and by host adapters that
  * implement their own transport.
  */
-declare function isAnonymousRpcMethod(name: string): boolean;
-//#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_EVENTS, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SERVICES_STATE_KEY, DEVFRAME_SSE_ROUTE, DEVFRAME_SSE_SESSION_HEADER, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export declare function isAnonymousRpcMethod(name: string): boolean;
+//#endregion

package/dist/{context-DwGevWqT.mjs → context-Cdj9z9m2.mjs}

@@ -143,7 +143,11 @@ function createRpcSharedStateServerHost(rpc) {
 		name: "devframe:rpc:server-state:set",
 		type: "query",
 		handler: async (key, value, syncId) => {
-			(await host.get(key, { initialValue: value })).mutate(() => value, syncId);
+			(await host.get(key, { initialValue: value })).patch([{
+				op: "replace",
+				path: [],
+				value
+			}], syncId);
 		}
 	});
 	rpc.register({
@@ -192,7 +196,10 @@ function createStreamSink(options = {}) {
 				seq: lastSeq,
 				chunk
 			});
-			if (buffer.length > replayWindow) buffer.splice(0, buffer.length - replayWindow);
+			if (buffer.length > replayWindow) {
+				if (buffer.length - replayWindow === 1) buffer.shift();
+				else buffer.splice(0, buffer.length - replayWindow);
+			}
 		}
 		events.emit("chunk", lastSeq, chunk);
 	}

package/dist/{dev-CZ1fu4J1.mjs → dev-SPZzBTrH.mjs}

@@ -1,7 +1,7 @@
 import { t as resolveClientAssets } from "./client-assets-DNdhagGm.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
 import { t as diagnostics } from "./diagnostics-DZA6KQ_Z.mjs";
-import { t as createHostContext } from "./context-DwGevWqT.mjs";
+import { t as createHostContext } from "./context-Cdj9z9m2.mjs";
 import { t as resolveStaticAssetsSource } from "./remote-assets-DMFzLSoH.mjs";
 import { a as resolveMcpConfig, i as resolveDevServerPort, n as normalizeBasePath, r as resolveBasePath, s as importRuntimeModule, t as loadAutoMcpAdapter } from "./_shared-U8D-xzrp.mjs";
 import { t as createH3DevframeHost } from "./host-h3-BROI6SQ4.mjs";

package/dist/in-page-channel/index.d.mts

@@ -9,9 +9,9 @@ import { BirpcReturn } from "birpc";
  * channel-name constant declared next to it.
  */
 interface InPageChannelProtocol {
-  /** Functions implemented by the page script, callable by panels. */
+  /** Functions and events received by the page script. */
   pageScript?: Record<string, (...args: any[]) => any>;
-  /** Functions implemented by panels, callable by the page script. */
+  /** Functions and events received by panels. */
   panel?: Record<string, (...args: any[]) => any>;
   /**
    * Shared-state slots. The page script is the authority: it owns the
@@ -26,6 +26,16 @@ type PanelFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable
 type SharedStates<P extends InPageChannelProtocol> = P['sharedStates'] extends Record<string, object> ? P['sharedStates'] : Record<string, never>;
 type FnArgs<F> = F extends ((...args: infer A) => any) ? A : never;
 type FnReturn<F> = F extends ((...args: any[]) => infer R) ? Awaited<R> : never;
+/**
+ * Page-script functions whose resolved return type marks an event.
+ * @internal
+ */
+type PageScriptFunctionsEvents<P extends InPageChannelProtocol> = { [K in keyof PageScriptFunctions<P> as FnReturn<PageScriptFunctions<P>[K]> extends void ? K : never]: PageScriptFunctions<P>[K]; };
+/**
+ * Panel functions whose resolved return type marks an event.
+ * @internal
+ */
+type PanelFunctionsEvents<P extends InPageChannelProtocol> = { [K in keyof PanelFunctions<P> as FnReturn<PanelFunctions<P>[K]> extends void ? K : never]: PanelFunctions<P>[K]; };
 /**
  * Converts a protocol function to its accepted endpoint handler.
  *
@@ -38,46 +48,69 @@ type ProtocolHandler<F> = F extends ((...args: any[]) => any) ? (...args: FnArgs
  * fan-out), `action` performs, `query` requests data (the default).
  */
 type InPageFunctionType = 'action' | 'event' | 'query';
-/**
- * An in-page channel function definition: the `defineRpcFunction` authoring
- * shape (`name`, `type`, Standard-Schema `args`/`returns`,
- * `jsonSerializable`, `handler`) narrowed to the browser: there is no
- * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
- * payloads are strictly validated at the receiving endpoint and misshapen
- * values reject the call with a descriptive `InPageChannelError` instead of
- * a cryptic `DataCloneError` in the port.
- */
-type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = [AS, RS] extends [undefined, undefined] ? {
+interface InPageFunctionDefinitionBase<NAME extends string> {
   name: NAME;
-  type?: TYPE;
+  jsonSerializable?: boolean;
+}
+interface InPageEventFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type: 'event';
+  handler?: HANDLER;
+}
+interface InPageQueryFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type?: 'query';
+  handler: HANDLER;
+}
+interface InPageActionFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type: 'action';
+  handler: HANDLER;
+}
+type InPageFunctionDefinitionForType<NAME extends string, TYPE extends InPageFunctionType, HANDLER> = TYPE extends 'event' ? InPageEventFunctionDefinition<NAME, HANDLER> : TYPE extends 'action' ? InPageActionFunctionDefinition<NAME, HANDLER> : InPageQueryFunctionDefinition<NAME, HANDLER>;
+type InPageFunctionDefinitionSchemas<AS extends RpcArgsSchema | undefined, RS extends RpcReturnSchema | undefined> = [AS, RS] extends [undefined, undefined] ? {
   args?: AS;
   returns?: RS;
-  jsonSerializable?: boolean;
-  handler: (...args: ARGS) => RETURN;
 } : {
-  name: NAME;
-  type?: TYPE;
   /** Standard Schema array validating (and typing) the arguments. */
   args: AS;
   /** Standard Schema typing the resolved return value. */
   returns: RS;
-  jsonSerializable?: boolean;
-  handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
 };
+type InPageFunctionDefinitionHandler<ARGS extends any[], RETURN, AS extends RpcArgsSchema | undefined, RS extends RpcReturnSchema | undefined> = [AS, RS] extends [undefined, undefined] ? (...args: ARGS) => RETURN : (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
+/**
+ * An in-page channel function definition: the `defineRpcFunction` authoring
+ * shape (`name`, `type`, Standard-Schema `args`/`returns`,
+ * `jsonSerializable`, `handler`) narrowed to the browser: there is no
+ * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
+ * payloads are strictly validated at the receiving endpoint and misshapen
+ * values reject the call with a descriptive `InPageChannelError` instead of
+ * a cryptic `DataCloneError` in the port. Event definitions may omit their
+ * handler when runtime listeners subscribe through `channel.on()`.
+ */
+type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = InPageFunctionDefinitionForType<NAME, TYPE, InPageFunctionDefinitionHandler<ARGS, RETURN, AS, RS>> & InPageFunctionDefinitionSchemas<AS, RS>;
 /**
  * Function metadata with its handler constrained by a protocol function.
  *
  * @internal
  */
-interface InPageFunctionOption<F> {
-  type?: InPageFunctionType;
+interface InPageFunctionOptionBase {
   /** Optional Standard Schema array validating the arguments. */
   args?: RpcArgsSchema;
   /** Optional Standard Schema validating the resolved return value. */
   returns?: RpcReturnSchema;
   jsonSerializable?: boolean;
+}
+interface InPageEventFunctionOption<F> extends InPageFunctionOptionBase {
+  type: 'event';
+  handler?: ProtocolHandler<F>;
+}
+interface InPageQueryFunctionOption<F> extends InPageFunctionOptionBase {
+  type?: 'query';
   handler: ProtocolHandler<F>;
 }
+interface InPageActionFunctionOption<F> extends InPageFunctionOptionBase {
+  type: 'action';
+  handler: ProtocolHandler<F>;
+}
+type InPageFunctionOption<F> = InPageEventFunctionOption<F> | InPageQueryFunctionOption<F> | InPageActionFunctionOption<F>;
 /**
  * Functions implemented by {@link createPageScriptChannel}.
  *
@@ -140,7 +173,7 @@ interface InPageChannelCommonOptions {
 }
 /** Options for {@link createPageScriptChannel}. */
 interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Implementations of the protocol's page-script functions. */
+  /** Every page-script function declaration; event handlers may use `channel.on()`. */
   functions: CreatePageScriptChannelOptionsFunctions<Protocol>;
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
@@ -151,7 +184,7 @@ interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol
 }
 /** Options for {@link connectPanelChannel}. */
 interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Implementations of the protocol's panel functions. */
+  /** Every panel function declaration; event handlers may use `channel.on()`. */
   functions: ConnectPanelChannelOptionsFunctions<Protocol>;
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
@@ -181,7 +214,7 @@ interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = In
    */
   helloIntervalMs?: number;
   /**
-   * Maximum `callEvent` payloads buffered while `connecting`, flushed on
+   * Maximum `emit` payloads buffered while `connecting`, flushed on
    * connect; when full, the oldest is dropped with a console warning.
    * @default 64
    */
@@ -228,11 +261,12 @@ interface PageScriptChannel<P extends InPageChannelProtocol> {
   /** Currently connected panels. */
   readonly panels: readonly PanelPeer<P>[];
   readonly events: Pick<EventEmitter<PageScriptChannelEvents<P>>, 'on' | 'once'>;
-  /**
-   * Fan a fire-and-forget event out to every connected panel; panels that
-   * don't implement the function ignore it.
-   */
-  callEvent: <K extends keyof PanelFunctions<P> & string>(name: K, ...args: FnArgs<PanelFunctions<P>[K]>) => void;
+  /** Fan an event out to every connected panel. */
+  emit: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  /** @deprecated Use `emit()` instead. */
+  callEvent: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  /** Subscribe to an event emitted by a panel. Returns an unsubscribe function. */
+  on: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, listener: (...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void) => () => void;
   /** Page-script-authoritative shared states, replayed to joining panels. */
   readonly sharedState: InPageSharedStateHost<P>;
   /** Adopt a pre-established port as a panel peer (bring-your-own transport). */
@@ -270,10 +304,14 @@ interface PanelChannel<P extends InPageChannelProtocol> {
    */
   call: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => Promise<FnReturn<PageScriptFunctions<P>[K]>>;
   /**
-   * Fire-and-forget to the page script. While `connecting` the event is
-   * buffered (up to `eventBufferLimit`) and flushed on connect.
+   * Emit an event to the page script. While `connecting` the event is buffered
+   * (up to `eventBufferLimit`) and flushed on connect.
    */
-  callEvent: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => void;
+  emit: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  /** @deprecated Use `emit()` instead. */
+  callEvent: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  /** Subscribe to an event emitted by the page script. Returns an unsubscribe function. */
+  on: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, listener: (...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void) => () => void;
   /** Shared states mirrored from the page-script authority. */
   readonly sharedState: InPageSharedStateHost<P>;
   /** Tear the endpoint down permanently. */
@@ -294,7 +332,7 @@ type InPageChannelErrorCode = 'timeout' |
 /** A shared-state key was first accessed without its initial value. */
 'state-uninitialized';
 /** A coded in-page channel error; every failure mode carries a stable `code`. */
-declare class InPageChannelError extends Error {
+export declare class InPageChannelError extends Error {
   readonly code: InPageChannelErrorCode;
   name: string;
   constructor(code: InPageChannelErrorCode, message: string, options?: {
@@ -312,7 +350,7 @@ declare class InPageChannelError extends Error {
  * panels all handshake the same way, and a panel reload is simply a new
  * handshake. No server is involved at any point.
  */
-declare function createPageScriptChannel<P extends InPageChannelProtocol>(options: CreatePageScriptChannelOptions<P>): PageScriptChannel<P>;
+export declare function createPageScriptChannel<P extends InPageChannelProtocol>(options: CreatePageScriptChannelOptions<P>): PageScriptChannel<P>;
 //#endregion
 //#region src/in-page-channel/panel.d.ts
 /**
@@ -327,7 +365,7 @@ declare function createPageScriptChannel<P extends InPageChannelProtocol>(option
  * (e.g. the panel opened standalone), the endpoint stays `connecting` and
  * the UI can key a fallback state off `status` / `whenConnected()`.
  */
-declare function connectPanelChannel<P extends InPageChannelProtocol>(options: ConnectPanelChannelOptions<P>): PanelChannel<P>;
+export declare function connectPanelChannel<P extends InPageChannelProtocol>(options: ConnectPanelChannelOptions<P>): PanelChannel<P>;
 //#endregion
 //#region src/in-page-channel/index.d.ts
 /**
@@ -338,6 +376,6 @@ declare function connectPanelChannel<P extends InPageChannelProtocol>(options: C
  * shared protocol file carries only the contract type and the channel-name
  * constant.
  */
-declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
+export declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
 //#endregion
-export { type ConnectPanelChannelOptions, type CreatePageScriptChannelOptions, InPageChannelError, type InPageChannelErrorCode, type InPageChannelProtocol, type InPageChannelStatus, type InPageFunctionDefinition, type PageScriptChannel, type PanelChannel, type PanelPeer, connectPanelChannel, createPageScriptChannel, defineChannelFunction };
+export type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, InPageChannelErrorCode, InPageChannelProtocol, InPageChannelStatus, InPageFunctionDefinition, PageScriptChannel, PanelChannel, PanelPeer };