fix: separate in-page channel events from functions

Author: posva

docs/content/1.guide/12.in-page-channel.md

@@ -37,14 +37,15 @@ import type { InPageChannelProtocol } from 'devframe/in-page-channel'
 export const MY_CHANNEL = 'devframes:plugin:my-tool'
 
 export interface MyChannelProtocol extends InPageChannelProtocol {
-  /** implemented by the page script, callable by panels */
-  pageScript: {
-    highlight: (selector: string) => void
-    measure: (selector: string) => { width: number, height: number }
+  functions: {
+    pageScript: {
+      measure: (selector: string) => { width: number, height: number }
+      reset: () => Promise<void>
+    }
   }
-  /** implemented by panels, callable by the page script */
-  panel: {
-    flash: (message: string) => void
+  events: {
+    pageScript: { highlight: (selector: string) => void }
+    panel: { flash: (message: string) => void }
   }
   sharedStates: {
     state: { selections: string[] }
@@ -56,7 +57,9 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-The required `functions` object declares every function on that endpoint's protocol side, preserving a compile-time completeness check. Request/response declarations require a `handler`; an event declaration uses `type: 'event'`, and the receiving endpoint may provide an optional `handler` or subscribe at runtime with `on()`. Functions use the same Standard-Schema `args`/`returns` and `jsonSerializable` metadata as `defineRpcFunction`, narrowed to the browser. Each handler is contextually typed from its key and the corresponding protocol function. `defineChannelFunction` retains the named definition shape for lower-level authoring. Define each side's functions in that side's source files; the shared protocol file carries only types.
+The required `functions` and `events` options declare every incoming name on the endpoint's protocol side; use `{}` for an empty direction. Functions require a `handler`. Events accept an optional `handler`, and `{}` registers an event for runtime subscriptions through `on()`. Handlers are contextually typed from the shared protocol and support Standard-Schema argument validation and `jsonSerializable` metadata. `defineChannelFunction` retains the named definition shape for lower-level authoring.
+
+`call()` accepts names from `functions`, including actions returning `void` or `Promise<void>`: callers can await completion and catch errors or timeouts. `emit()`, its deprecated alias `callEvent()`, and `on()` use the names declared in `events`. Function and event names have separate namespaces.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
@@ -67,26 +70,28 @@ import { MY_CHANNEL } from '../shared/protocol'
 const pageChannel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   functions: {
-    highlight: {
-      type: 'event', // fire-and-forget
-      jsonSerializable: true,
-      handler: selector => drawRing(document.querySelector(selector)),
-    },
+    reset: { type: 'action', handler: async () => clearSelections() },
     measure: { // request/response (the default `query` type)
       handler: (selector) => {
         const rect = document.querySelector(selector)!.getBoundingClientRect()
         return { width: rect.width, height: rect.height }
       },
     },
   },
+  events: {
+    highlight: {
+      jsonSerializable: true,
+      handler: selector => drawRing(document.querySelector(selector)),
+    },
+  },
 })
 
 pageChannel.emit('flash', 'scanning…') // received by each panel endpoint
 pageChannel.events.on('panel:connected', panel => console.log(panel.id))
 pageChannel.events.on('panel:disconnected', () => pauseWorkIfNobodyWatches())
 ```
 
-`emit` on the page-script endpoint is 1:N: it fans out to every connected panel endpoint. Request/response *to* a panel goes through an explicit peer handle: `pageChannel.panels[0].call('flash', '…')`.
+`emit` on the page-script endpoint fans out to every connected panel endpoint. Functions declared under `functions.panel` are called through a specific `pageChannel.panels[0].call()` peer handle.
 
 ## The panel endpoint
 
@@ -98,14 +103,16 @@ import { MY_CHANNEL } from '../shared/protocol'
 
 const panelChannel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
-  functions: {
-    flash: { type: 'event' },
+  functions: {},
+  events: {
+    flash: {},
   },
 })
 
 const offFlash = panelChannel.on('flash', message => showFlash(message))
 panelChannel.emit('highlight', '.hero') // received by the page-script endpoint
 const size = await panelChannel.call('measure', '.hero')
+await panelChannel.call('reset')
 
 offFlash() // stop listening
 ```
@@ -162,6 +169,8 @@ import { toRaw } from 'vue'
 const channel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   serialize: value => toRawDeep(value), // applied to every outgoing argument and result
+  functions: {},
+  events: { flash: {} },
 })
 ```
 
@@ -172,7 +181,7 @@ Declaring a function `jsonSerializable: true` additionally enforces strict JSON
 The same app open in two tabs means two page scripts on one origin. Each page script carries a per-tab instance id (persisted in `sessionStorage`), and handshakes are targeted `postMessage`, so a dock panel always pairs with its own tab's page script. A panel can also pin explicitly:
 
 ```ts
-connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, instanceId })
+connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, instanceId, functions: {}, events: { flash: {} } })
 ```
 
 ## Custom transports
@@ -182,7 +191,7 @@ Both endpoints accept a pre-established `MessagePort` that bypasses the handshak
 ```ts
 const { port1, port2 } = new MessageChannel()
 pageScript.addPanelPort(port1)
-const panel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, transport: port2 })
+const panel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, transport: port2, functions: {}, events: { flash: {} } })
 ```
 
 ## When to use the in-page channel vs RPC

docs/content/6.errors/DF0077.md

@@ -1,23 +1,24 @@
 ---
-title: 'DF0077: In-Page Channel Function Not Registered'
-description: 'An in-page channel listener names a function that is not registered on its endpoint.'
+title: 'DF0077: In-Page Channel Event Not Registered'
+description: 'An in-page channel listener names an event that is not registered on its endpoint.'
 ---
 
 ## Message
 
-> In-page channel function "{name}" is not registered on this endpoint.
+> In-page channel event "{name}" is not registered on this endpoint.
 
 ## Cause
 
-`channel.on(name, listener)` received a name absent from that endpoint's required `functions` option. A page-script endpoint subscribes to functions declared under `pageScript`; a panel endpoint subscribes to functions declared under `panel`.
+`channel.on(name, listener)` received a name absent from that endpoint's required `events` option. A page-script endpoint subscribes to events declared under `events.pageScript`; a panel endpoint subscribes to events declared under `events.panel`.
 
 ## Example
 
 ```ts
 const channel = connectPanelChannel<MyProtocol>({
   name: MY_CHANNEL,
-  functions: {
-    notify: { type: 'event' },
+  functions: {},
+  events: {
+    notify: {},
   },
 })
 
@@ -26,7 +27,7 @@ channel.on('missing' as any, () => {}) // ✗ throws DF0077
 
 ## Fix
 
-Declare the event in the endpoint's protocol side and `functions` option, then pass that declared name to `on()`.
+Declare the event in the endpoint's protocol side and `events` option, then pass that declared name to `on()`.
 
 ## Source
 

docs/content/6.errors/index.md

@@ -83,7 +83,7 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous |
 | [DF0075](/errors/DF0075) | warn | No RPC Transport On This Runtime |
 | [DF0076](/errors/DF0076) | error | WebSocket Upgrade Unsupported On This Runtime |
-| [DF0077](/errors/DF0077) | error | In-Page Channel Function Not Registered |
+| [DF0077](/errors/DF0077) | error | In-Page Channel Event Not Registered |
 
 ## Hub: context & lifecycle (DF80xx)
 

docs/content/8.references/5.browser-api.md

@@ -50,6 +50,8 @@ The values of `rpc.status`: [Handling connection and auth errors](/guide/client#
 
 The browser-only endpoint methods of the [in-page channel](/guide/in-page-channel). `emit()` sends to the opposite endpoint; `on()` handles events arriving from that endpoint.
 
+`InPageChannelProtocol` separates `functions` and `events`. Each section has optional `pageScript` and `panel` maps naming the receiving direction. Endpoint options require a complete `functions` map with handlers and a complete `events` map with optional handlers; use `{}` for empty maps. `call()` uses function names regardless of return type, while `emit()`, `callEvent()` (deprecated), and `on()` use event names. A function returning `void` or `Promise<void>` remains an awaitable request/response call.
+
 | Method or property | Page-script endpoint | Panel endpoint |
 |--------------------|-------------|-------|
 | `emit(name, ...args)` | Fans an event out to every connected panel. | Sends an event to the page script, buffering while connecting. |

packages/devframe/src/in-page-channel/diagnostics.ts

@@ -4,8 +4,8 @@ export const diagnostics = /* #__PURE__ */ defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
   codes: {
     DF0077: {
-      why: (p: { name: string }) => `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()`.',
+      why: (p: { name: string }) => `In-page channel event "${p.name}" is not registered on this endpoint.`,
+      fix: 'Declare the event in this endpoint\'s `events` option before subscribing with `on()`.',
     },
   },
 })

packages/devframe/src/in-page-channel/events.test-d.ts

@@ -0,0 +1,92 @@
+import type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, PageScriptChannel, PanelChannel } from './types'
+import { expectTypeOf, it } from 'vitest'
+
+interface Protocol {
+  functions: {
+    pageScript: { save: (value: string) => void, reset: () => Promise<void> }
+    panel: { save: (value: string) => void, reset: () => Promise<void> }
+  }
+  events: {
+    pageScript: { note: (value: string, count?: number) => void }
+    panel: { notify: (message: string) => void }
+  }
+}
+
+declare const pageScript: PageScriptChannel<Protocol>
+declare const panel: PanelChannel<Protocol>
+
+it('distinguishes void actions from declared events in both directions', () => {
+  expectTypeOf(panel.call('save', 'draft')).toEqualTypeOf<Promise<void>>()
+  expectTypeOf(panel.call('reset')).toEqualTypeOf<Promise<void>>()
+  const peer = pageScript.panels[0]!
+  expectTypeOf(peer.call('save', 'draft')).toEqualTypeOf<Promise<void>>()
+  expectTypeOf(peer.call('reset')).toEqualTypeOf<Promise<void>>()
+  expectTypeOf(panel.emit('note', 'hello', 2)).toEqualTypeOf<void>()
+  expectTypeOf(pageScript.emit('notify', 'hello')).toEqualTypeOf<void>()
+  expectTypeOf(pageScript.on('note', (value, count) => {
+    expectTypeOf(value).toEqualTypeOf<string>()
+    expectTypeOf(count).toEqualTypeOf<number | undefined>()
+  })).toEqualTypeOf<() => void>()
+  // @ts-expect-error Events cannot be called as functions.
+  panel.call('note', 'hello')
+  // @ts-expect-error Events cannot be called on panel peers.
+  peer.call('notify', 'hello')
+  // @ts-expect-error A void action is still a function.
+  panel.emit('save', 'draft')
+  // @ts-expect-error An asynchronous void action is still a function.
+  panel.emit('reset')
+  // @ts-expect-error The deprecated alias has the same restriction.
+  panel.callEvent('save', 'draft')
+  // @ts-expect-error A panel void action is still a function.
+  pageScript.emit('save', 'draft')
+  // @ts-expect-error A panel asynchronous void action is still a function.
+  pageScript.callEvent('reset')
+  // @ts-expect-error Functions cannot receive event listeners.
+  pageScript.on('save', () => {})
+  // @ts-expect-error Functions cannot receive event listeners.
+  panel.on('reset', () => {})
+})
+
+it('requires function handlers and separate event declarations', () => {
+  const options: CreatePageScriptChannelOptions<Protocol> = {
+    name: 'test',
+    functions: {
+      save: { type: 'action', handler: (value) => {
+        expectTypeOf(value).toEqualTypeOf<string>()
+      } },
+      reset: { type: 'action', handler: async () => {} },
+    },
+    events: { note: {} },
+  }
+  // @ts-expect-error Actions require handlers even when returning void.
+  options.functions.save = { type: 'action' }
+  // @ts-expect-error Functions cannot be declared as events.
+  options.functions.reset = { type: 'event' }
+  // @ts-expect-error Events belong in the events option.
+  options.functions.note = { handler: () => {} }
+  // @ts-expect-error Event declarations must be complete.
+  options.events = {}
+  // @ts-expect-error Functions belong in the functions option.
+  options.events.save = {}
+  options.events.note = { handler: (value, count) => {
+    expectTypeOf(value).toEqualTypeOf<string>()
+    expectTypeOf(count).toEqualTypeOf<number | undefined>()
+  } }
+  // @ts-expect-error Event handlers must match the declared arguments.
+  options.events.note = { handler: (value: number) => void value }
+  // @ts-expect-error Event declarations cannot be actions.
+  options.events.note = { type: 'action', handler: () => {} }
+})
+
+it('supports omitted protocol sections without widening their keys', () => {
+  interface FunctionsOnly { functions: { pageScript: { run: () => void } } }
+  interface EventsOnly { events: { panel: { ready: () => void } } }
+  const options: ConnectPanelChannelOptions<FunctionsOnly> = { name: 'test', functions: {}, events: {} }
+  // @ts-expect-error This direction declares no events.
+  options.events.ready = {}
+  // @ts-expect-error This direction declares no functions.
+  options.functions.run = { handler: () => {} }
+  expectTypeOf<Parameters<PanelChannel<FunctionsOnly>['emit']>[0]>().toEqualTypeOf<never>()
+  expectTypeOf<Parameters<PanelChannel<EventsOnly>['call']>[0]>().toEqualTypeOf<never>()
+  expectTypeOf<Parameters<PageScriptChannel<EventsOnly>['on']>[0]>().toEqualTypeOf<never>()
+})