fix: reject unknown in-page listeners

Author: posva

docs/content/6.errors/DF0077.md

@@ -0,0 +1,33 @@
+---
+title: 'DF0077: In-Page Channel Function Not Registered'
+description: 'An in-page channel listener names a function that is not registered on its endpoint.'
+---
+
+## Message
+
+> In-page channel function "{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`.
+
+## Example
+
+```ts
+const channel = connectPanelChannel<MyProtocol>({
+  name: MY_CHANNEL,
+  functions: {
+    notify: { type: 'event' },
+  },
+})
+
+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()`.
+
+## Source
+
+- [`packages/devframe/src/in-page-channel/internal.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/in-page-channel/internal.ts): `createLocalFunctionRegistry().on()` throws this when no local definition matches the listener name.

docs/content/6.errors/index.md

@@ -83,6 +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 |
 
 ## Hub: context & lifecycle (DF80xx)
 

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

@@ -0,0 +1,11 @@
+import { defineDiagnostics } from 'devframe/utils/nostics'
+
+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()`.',
+    },
+  },
+})

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

@@ -1,4 +1,5 @@
 import type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, InPageChannelProtocol, PageScriptChannel, PanelChannel } from './types'
+import { Diagnostic } from 'devframe/utils/nostics'
 import { describe, expect, it, vi } from 'vitest'
 import { InPageChannelError } from './internal'
 import { createPageScriptChannel } from './page-script'
@@ -120,6 +121,28 @@ describe('in-page channel over bring-your-own ports', () => {
     }
   })
 
+  it('reports and rejects listeners for unknown functions', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { panel, dispose } = createLinkedPair()
+    try {
+      let rejection: unknown
+      try {
+        panel.on('missing' as any, () => {})
+      }
+      catch (error) {
+        rejection = error
+      }
+      expect(rejection).toBeInstanceOf(Diagnostic)
+      expect(rejection).toMatchObject({ name: 'DF0077' })
+      expect(warn).toHaveBeenCalledOnce()
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('[DF0077]'))
+    }
+    finally {
+      dispose()
+      warn.mockRestore()
+    }
+  })
+
   it('enforces jsonSerializable payloads with a coded error', async () => {
     const { panel, dispose } = createLinkedPair()
     try {

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

@@ -4,13 +4,13 @@ import type { RpcArgsSchema } from '../rpc/types'
 import type { InPageChannelControlFrame } from './protocol'
 import type { InPageFunctionDefinitionAny } from './types'
 import { createBirpc } from 'birpc'
+import { diagnostics } from './diagnostics'
 import { isControlFrame } from './protocol'
 
 /**
- * Shared internals of the two endpoints: the coded error surface (browser
- * code, so plain coded `Error`s, since `nostics` diagnostics are node-side only),
- * the local function table with its receive pipeline, and the birpc wiring
- * of one `MessagePort`.
+ * Shared internals of the two endpoints: the coded error surface, the local
+ * function table with its receive pipeline, and the birpc wiring of one
+ * `MessagePort`.
  */
 
 export const DEFAULT_CALL_TIMEOUT_MS = 15_000
@@ -176,6 +176,8 @@ export function createLocalFunctionRegistry(codec: InPageChannelSerialization):
       definitions.set(definition.name, definition)
     },
     on(name, listener) {
+      if (!definitions.has(name))
+        throw diagnostics.DF0077({ name })
       let registered = listeners.get(name)
       if (!registered) {
         registered = new Set()