devframe 0.9.16 → 0.9.18

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

@@ -9,10 +9,18 @@ import { BirpcReturn } from "birpc";
  * channel-name constant declared next to it.
  */
 interface InPageChannelProtocol {
-  /** Functions and events received by the page script. */
-  pageScript?: Record<string, (...args: any[]) => any>;
-  /** Functions and events received by panels. */
-  panel?: Record<string, (...args: any[]) => any>;
+  functions?: {
+    /** Functions implemented by the page script. */
+    pageScript?: Record<string, (...args: any[]) => any>;
+    /** Functions implemented by panels. */
+    panel?: Record<string, (...args: any[]) => any>;
+  };
+  events?: {
+    /** Events emitted by panels and received by the page script. */
+    pageScript?: Record<string, (...args: any[]) => void>;
+    /** Events emitted by the page script and received by panels. */
+    panel?: Record<string, (...args: any[]) => void>;
+  };
   /**
    * Shared-state slots. The page script is the authority: it owns the
    * canonical value; panels are seeded on connect and converge through
@@ -21,21 +29,14 @@ interface InPageChannelProtocol {
   sharedStates?: Record<string, object>;
 }
 type SideFunctions<S> = S extends Record<string, (...args: any[]) => any> ? S : Record<string, never>;
-type PageScriptFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable<P['pageScript']>>;
-type PanelFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable<P['panel']>>;
+type SideDeclarations<P extends InPageChannelProtocol, Kind extends 'functions' | 'events', Side extends 'pageScript' | 'panel'> = Kind extends keyof P ? Side extends keyof NonNullable<P[Kind]> ? SideFunctions<NonNullable<NonNullable<P[Kind]>[Side]>> : Record<string, never> : Record<string, never>;
+type PageScriptFunctions<P extends InPageChannelProtocol> = SideDeclarations<P, 'functions', 'pageScript'>;
+type PanelFunctions<P extends InPageChannelProtocol> = SideDeclarations<P, 'functions', 'panel'>;
 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]; };
+type PageScriptEvents<P extends InPageChannelProtocol> = SideDeclarations<P, 'events', 'pageScript'>;
+type PanelEvents<P extends InPageChannelProtocol> = SideDeclarations<P, 'events', 'panel'>;
 /**
  * Converts a protocol function to its accepted endpoint handler.
  *
@@ -99,9 +100,10 @@ interface InPageFunctionOptionBase {
   jsonSerializable?: boolean;
 }
 interface InPageEventFunctionOption<F> extends InPageFunctionOptionBase {
-  type: 'event';
+  type?: 'event';
   handler?: ProtocolHandler<F>;
 }
+type InPageEventOption<F> = [F] extends [never] ? never : InPageEventFunctionOption<F>;
 interface InPageQueryFunctionOption<F> extends InPageFunctionOptionBase {
   type?: 'query';
   handler: ProtocolHandler<F>;
@@ -110,7 +112,7 @@ interface InPageActionFunctionOption<F> extends InPageFunctionOptionBase {
   type: 'action';
   handler: ProtocolHandler<F>;
 }
-type InPageFunctionOption<F> = InPageEventFunctionOption<F> | InPageQueryFunctionOption<F> | InPageActionFunctionOption<F>;
+type InPageFunctionOption<F> = InPageQueryFunctionOption<F> | InPageActionFunctionOption<F>;
 /**
  * Functions implemented by {@link createPageScriptChannel}.
  *
@@ -173,8 +175,10 @@ interface InPageChannelCommonOptions {
 }
 /** Options for {@link createPageScriptChannel}. */
 interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Every page-script function declaration; event handlers may use `channel.on()`. */
+  /** Every page-script function declaration, with a required handler. */
   functions: CreatePageScriptChannelOptionsFunctions<Protocol>;
+  /** Optional metadata or handlers for incoming events. Listeners may instead subscribe through `channel.on()`. */
+  events?: { [NAME in keyof PageScriptEvents<Protocol> & string]?: InPageEventOption<PageScriptEvents<Protocol>[NAME]>; };
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
    * global `window`; pass `false` to skip the handshake listener entirely
@@ -184,8 +188,10 @@ interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol
 }
 /** Options for {@link connectPanelChannel}. */
 interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Every panel function declaration; event handlers may use `channel.on()`. */
+  /** Every panel function declaration, with a required handler. */
   functions: ConnectPanelChannelOptionsFunctions<Protocol>;
+  /** Optional metadata or handlers for incoming events. Listeners may instead subscribe through `channel.on()`. */
+  events?: { [NAME in keyof PanelEvents<Protocol> & string]?: InPageEventOption<PanelEvents<Protocol>[NAME]>; };
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
    * the global `window`; pass `false` with `transport` to skip the handshake.
@@ -262,11 +268,11 @@ interface PageScriptChannel<P extends InPageChannelProtocol> {
   readonly panels: readonly PanelPeer<P>[];
   readonly events: Pick<EventEmitter<PageScriptChannelEvents<P>>, 'on' | 'once'>;
   /** Fan an event out to every connected panel. */
-  emit: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  emit: <K extends keyof PanelEvents<P> & string>(name: K, ...args: FnArgs<PanelEvents<P>[K]>) => void;
   /** @deprecated Use `emit()` instead. */
-  callEvent: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  callEvent: <K extends keyof PanelEvents<P> & string>(name: K, ...args: FnArgs<PanelEvents<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;
+  on: <K extends keyof PageScriptEvents<P> & string>(name: K, listener: (...args: FnArgs<PageScriptEvents<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). */
@@ -307,11 +313,11 @@ interface PanelChannel<P extends InPageChannelProtocol> {
    * Emit an event to the page script. While `connecting` the event is buffered
    * (up to `eventBufferLimit`) and flushed on connect.
    */
-  emit: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  emit: <K extends keyof PageScriptEvents<P> & string>(name: K, ...args: FnArgs<PageScriptEvents<P>[K]>) => void;
   /** @deprecated Use `emit()` instead. */
-  callEvent: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  callEvent: <K extends keyof PageScriptEvents<P> & string>(name: K, ...args: FnArgs<PageScriptEvents<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;
+  on: <K extends keyof PanelEvents<P> & string>(name: K, listener: (...args: FnArgs<PanelEvents<P>[K]>) => void) => () => void;
   /** Shared states mirrored from the page-script authority. */
   readonly sharedState: InPageSharedStateHost<P>;
   /** Tear the endpoint down permanently. */

package/dist/in-page-channel/index.mjs

@@ -8,7 +8,7 @@ const diagnostics = /* #__PURE__ */ defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: { DF0077: {
 		why: (p) => `In-page channel function "${p.name}" is not registered on this endpoint.`,
-		fix: "Declare the function in this endpoint's `functions` option before subscribing with `on()`."
+		fix: "Declare the function in this endpoint's `functions` option."
 	} }
 });
 //#endregion
@@ -169,6 +169,10 @@ function serializeArgs(codec, args) {
 function deserializeResult(codec, result) {
 	return codec.deserialize && result !== void 0 ? codec.deserialize(result) : result;
 }
+function channelMethod(type, name) {
+	return `devframe:in-page:${type === "event" ? "event" : "function"}:${name}`;
+}
+const FUNCTION_METHOD_PREFIX = channelMethod("function", "");
 /**
 * An endpoint's local function table, resolved by name when the remote side
 * calls in. Each handler is wrapped with the receive pipeline: deserialize
@@ -180,19 +184,25 @@ function createLocalFunctionRegistry(codec) {
 	const listeners = /* @__PURE__ */ new Map();
 	return {
 		register(definition) {
-			definitions.set(definition.name, definition);
+			definitions.set(channelMethod(definition.type, definition.name), definition);
+		},
+		registerInternal(method, handler) {
+			definitions.set(method, {
+				name: method,
+				handler
+			});
 		},
 		on(name, listener) {
-			if (!definitions.has(name)) throw diagnostics.DF0077({ name });
-			let registered = listeners.get(name);
+			const key = channelMethod("event", name);
+			let registered = listeners.get(key);
 			if (!registered) {
 				registered = /* @__PURE__ */ new Set();
-				listeners.set(name, registered);
+				listeners.set(key, registered);
 			}
 			registered.add(listener);
 			return () => {
 				registered.delete(listener);
-				if (registered.size === 0) listeners.delete(name);
+				if (registered.size === 0) listeners.delete(key);
 			};
 		},
 		resolve(name) {
@@ -205,12 +215,28 @@ function createLocalFunctionRegistry(codec) {
 				if (definition?.args?.length) await validateArgs(definition.name, definition.args, args);
 				const result = await definition?.handler?.(...args);
 				for (const listener of [...listeners.get(name) ?? []]) listener(...args);
-				if (definition?.jsonSerializable) assertJsonSerializable(result, "its return value", definition.name);
+				if (definition?.type === "event") return void 0;
+				if (definition?.jsonSerializable && result !== void 0) assertJsonSerializable(result, "its return value", definition.name);
 				return codec.serialize && result !== void 0 ? codec.serialize(result) : result;
 			};
 		}
 	};
 }
+/**
+* Consult each registry in order and, only once none owns the name, fall back
+* to the coded "not registered" error for a `function:` call (events stay
+* silent). The fallback lives here, after every registry, so chaining a
+* state registry ahead of the user registry never masks a real handler.
+*/
+function resolveLocalHandler(name, registries) {
+	for (const registry of registries) {
+		const handler = registry(name);
+		if (handler) return handler;
+	}
+	if (name.startsWith(FUNCTION_METHOD_PREFIX)) return () => {
+		throw diagnostics.DF0077({ name: name.slice(FUNCTION_METHOD_PREFIX.length) });
+	};
+}
 function wrapPostError(error) {
 	if (error instanceof DOMException && error.name === "DataCloneError") return new InPageChannelError("not-cloneable", `a payload could not be structured-cloned across the in-page channel: ${error.message}. Strip non-cloneable values (functions, DOM nodes, framework reactivity proxies) before sending: declare the function \`jsonSerializable: true\` for a precise error, or provide a \`serialize\` hook.`, { cause: error });
 	return error;
@@ -482,13 +508,18 @@ function createPageScriptChannel(options) {
 		...definition,
 		name: fnName
 	});
+	for (const [eventName, definition] of Object.entries(options.events ?? {})) registry.register({
+		...definition,
+		name: eventName,
+		type: "event"
+	});
 	const stateHost = createPageScriptStateHost(function* () {
 		for (const peer of peers.values()) yield {
 			subscribedStates: peer.subscribedStates,
 			callEventRaw: (method, args) => {
 				peer.attached.rpc.$callRaw({
 					method,
-					args,
+					args: serializeArgs(codec, args),
 					event: true,
 					optional: true
 				}).catch(() => {});
@@ -517,14 +548,16 @@ function createPageScriptChannel(options) {
 			callEventRaw: (method, args) => {
 				internal.attached.rpc.$callRaw({
 					method,
-					args,
+					args: serializeArgs(codec, args),
 					event: true,
 					optional: true
 				}).catch(() => {});
 			}
 		});
+		const stateRegistry = createLocalFunctionRegistry(codec);
+		for (const [method, handler] of Object.entries(internal.internalHandlers)) stateRegistry.registerInternal(method, handler);
 		internal.attached = attachChannelPort(port, {
-			resolveLocal: (fnName) => internal.internalHandlers[fnName] ?? registry.resolve(fnName),
+			resolveLocal: (fnName) => resolveLocalHandler(fnName, [stateRegistry.resolve, registry.resolve]),
 			onControl: (kind) => {
 				if (kind === "ping") internal.attached.postControl("pong");
 			},
@@ -532,7 +565,7 @@ function createPageScriptChannel(options) {
 		});
 		internal.peer = {
 			id,
-			call: (fnName, ...args) => withCallDeadline(internal.attached.rpc.$call(fnName, ...serializeArgs(codec, args)).then((result) => deserializeResult(codec, result)), callTimeoutMs, () => `in-page channel "${name}": call "${fnName}" to panel "${id}" timed out after ${callTimeoutMs}ms`),
+			call: (fnName, ...args) => withCallDeadline(internal.attached.rpc.$call(channelMethod("function", fnName), ...serializeArgs(codec, args)).then((result) => deserializeResult(codec, result)), callTimeoutMs, () => `in-page channel "${name}": call "${fnName}" to panel "${id}" timed out after ${callTimeoutMs}ms`),
 			close: () => removePeer(id, {
 				bye: true,
 				reason: "the page script closed this panel"
@@ -550,8 +583,8 @@ function createPageScriptChannel(options) {
 		if (closed) return;
 		const data = event.data;
 		if (!isHandshakeMessage(data) || data.kind !== "hello" || data.name !== name) return;
-		if (data.v !== 1) {
-			warnOnce(`in-page channel "${name}": ignoring a hello with protocol version ${data.v} (this side speaks 1); align the devframe versions of the page script and the panel`);
+		if (data.v !== 2) {
+			warnOnce(`in-page channel "${name}": ignoring a hello with protocol version ${data.v} (this side speaks 2); align the devframe versions of the page script and the panel`);
 			return;
 		}
 		if (!allowedOrigins.includes("*") && !allowedOrigins.includes(event.origin)) {
@@ -565,7 +598,7 @@ function createPageScriptChannel(options) {
 		addPeer(messageChannel.port1, data.panelId);
 		const grant = {
 			channel: IN_PAGE_CHANNEL_TAG,
-			v: 1,
+			v: 2,
 			kind: "grant",
 			name,
 			panelId: data.panelId,
@@ -582,7 +615,7 @@ function createPageScriptChannel(options) {
 	const emit = (fnName, ...args) => {
 		const wireArgs = serializeArgs(codec, args);
 		for (const peer of peers.values()) peer.attached.rpc.$callRaw({
-			method: fnName,
+			method: channelMethod("event", fnName),
 			args: wireArgs,
 			event: true,
 			optional: true
@@ -651,6 +684,11 @@ function connectPanelChannel(options) {
 		...definition,
 		name: fnName
 	});
+	for (const [eventName, definition] of Object.entries(options.events ?? {})) registry.register({
+		...definition,
+		name: eventName,
+		type: "event"
+	});
 	let status = "connecting";
 	let attached;
 	let pageScriptInfo;
@@ -668,9 +706,11 @@ function connectPanelChannel(options) {
 	}
 	const stateHost = createPanelStateHost({
 		isConnected: () => status === "connected",
-		callEvent: (method, args) => sendEvent(method, args),
-		call: (method, args) => enqueueCall(method, args)
+		callEvent: (method, args) => sendEvent(method, serializeArgs(codec, args)),
+		call: (method, args) => enqueueCall(method, serializeArgs(codec, args))
 	});
+	const stateRegistry = createLocalFunctionRegistry(codec);
+	for (const [method, handler] of Object.entries(stateHost.handlers)) stateRegistry.registerInternal(method, handler);
 	function sendEventNow(method, args) {
 		attached?.rpc.$callRaw({
 			method,
@@ -716,7 +756,7 @@ function connectPanelChannel(options) {
 			reason: "the panel adopted a newer port"
 		});
 		attached = attachChannelPort(port, {
-			resolveLocal: (fnName) => stateHost.handlers[fnName] ?? registry.resolve(fnName),
+			resolveLocal: (fnName) => resolveLocalHandler(fnName, [stateRegistry.resolve, registry.resolve]),
 			onControl: (kind) => {
 				if (kind === "ping") attached?.postControl("pong");
 			},
@@ -761,7 +801,7 @@ function connectPanelChannel(options) {
 		const tick = () => {
 			const hello = {
 				channel: IN_PAGE_CHANNEL_TAG,
-				v: 1,
+				v: 2,
 				kind: "hello",
 				name,
 				panelId,
@@ -779,8 +819,8 @@ function connectPanelChannel(options) {
 		if (status === "closed") return;
 		const data = event.data;
 		if (!isHandshakeMessage(data) || data.kind !== "grant" || data.name !== name || data.panelId !== panelId) return;
-		if (data.v !== 1) {
-			warnOnce(`in-page channel "${name}": ignoring a grant with protocol version ${data.v} (this side speaks 1); align the devframe versions of the page script and the panel`);
+		if (data.v !== 2) {
+			warnOnce(`in-page channel "${name}": ignoring a grant with protocol version ${data.v} (this side speaks 2); align the devframe versions of the page script and the panel`);
 			return;
 		}
 		if (!allowedOrigins.includes("*") && !allowedOrigins.includes(event.origin)) {
@@ -825,9 +865,9 @@ function connectPanelChannel(options) {
 				}, timeoutMs);
 			});
 		},
-		call: (fnName, ...args) => enqueueCall(fnName, serializeArgs(codec, args)),
-		emit: (fnName, ...args) => sendEvent(fnName, serializeArgs(codec, args)),
-		callEvent: (fnName, ...args) => sendEvent(fnName, serializeArgs(codec, args)),
+		call: (fnName, ...args) => enqueueCall(channelMethod("function", fnName), serializeArgs(codec, args)),
+		emit: (fnName, ...args) => sendEvent(channelMethod("event", fnName), serializeArgs(codec, args)),
+		callEvent: (fnName, ...args) => sendEvent(channelMethod("event", fnName), serializeArgs(codec, args)),
 		on: (fnName, listener) => registry.on(fnName, listener),
 		sharedState: stateHost,
 		close: () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "description": "Framework for building one portable devtool integration that runs in any viewer.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",

package/skills/devframe/SKILL.md

@@ -438,7 +438,7 @@ Use `my.rpc.sharedState(key)` for observable state, `my.rpc.register(...)` to re
 
 ### In-page channel (page script ↔ panel, server-free)
 
-For a live inspect-the-page loop, `devframe/in-page-channel` connects a devframe's **page script** (in the user app's page) to its **panels** entirely in the browser — no server, so it works identically in dev and static builds. Declare one shared protocol type; the page script is `createPageScriptChannel<P>({ name, functions })`, each panel `connectPanelChannel<P>({ name })`. Functions use `defineChannelFunction` (the `defineRpcFunction` shape: `type: 'event'` fans out to every panel, `query`/`action` are request/response); `channel.sharedState.get(key)` mirrors `rpc.sharedState` with the page script as authority (panels get automatic replay). The handshake is panel-initiated with retry — boot order and reloads don't matter — and panels expose `status`/`whenConnected(ms)` for "page script not loaded" fallbacks. Channel names follow `devframes:plugin:<slug>`. The a11y inspector's scan/highlight loop is the reference use.
+For a live inspect-the-page loop, `devframe/in-page-channel` connects a devframe's **page script** (in the user app's page) to its **panels** entirely in the browser, in both dev and static builds. Declare a shared protocol type with separate `functions` and `events` sections, each with `pageScript` and `panel` maps naming the receiving direction. Both `createPageScriptChannel<P>()` and `connectPanelChannel<P>()` require `{ name, functions }` and accept optional `events`: function declarations require handlers; event declarations accept optional handlers or `{}` for dynamic `channel.on()` subscriptions. `call()` awaits functions, including void actions; `emit()` sends declared events. `channel.sharedState.get(key)` mirrors `rpc.sharedState` with the page script as authority and automatic replay to panels. The handshake retries across boot order and reloads; panels expose `status`/`whenConnected(ms)` for page-script availability fallbacks. Channel names follow `devframes:plugin:<slug>`. The a11y inspector's scan/highlight loop is the reference use.
 
 ## The Hub