docs: clarify in-page event direction

Author: posva

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

@@ -54,15 +54,15 @@ 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 may receive events through either its optional `handler` or runtime `channel.on()` listeners. 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` 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.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
 // inject/index.ts: runs in the user app's page
 import { createPageScriptChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = createPageScriptChannel<MyChannelProtocol>({
+const pageChannel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   functions: {
     highlight: {
@@ -79,12 +79,12 @@ const channel = createPageScriptChannel<MyChannelProtocol>({
   },
 })
 
-channel.emit('flash', 'scanning…') // fans out to every connected panel
-channel.events.on('panel:connected', panel => console.log(panel.id))
-channel.events.on('panel:disconnected', () => pauseWorkIfNobodyWatches())
+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 is 1:N: it fans out to every connected panel. Request/response *to* a panel goes through an explicit peer handle: `channel.panels[0].call('flash', '…')`.
+`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', '…')`.
 
 ## The panel endpoint
 
@@ -94,20 +94,22 @@ import type { MyChannelProtocol } from '../shared/protocol'
 import { connectPanelChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = connectPanelChannel<MyChannelProtocol>({
+const panelChannel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   functions: {
     flash: { type: 'event' },
   },
 })
 
-const offFlash = channel.on('flash', message => showFlash(message))
-channel.emit('highlight', '.hero') // buffered until connected
-const size = await channel.call('measure', '.hero')
+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')
 
 offFlash() // stop listening
 ```
 
+The snippets form one channel pair: `pageChannel.emit('flash', …)` invokes `panelChannel.on('flash', …)`. In the other direction, `panelChannel.emit('highlight', …)` invokes the page-script endpoint's `highlight` handler and any matching `pageChannel.on()` listeners. An endpoint never receives its own emission.
+
 ## Shared state
 
 The channel's shared-state layer mirrors [`rpc.sharedState`](/guide/shared-state) (same `SharedState<T>` handle, same accessor), with the page script playing the server's role as rendezvous and authority. Its first `get` of a key must provide the initial value; panels are seeded automatically on connect (including late joiners and re-connects) and converge through syncId-deduplicated patches.

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

@@ -47,9 +47,9 @@ The values of `rpc.status`: [Handling connection and auth errors](/guide/client#
 
 ## In-page channel endpoints
 
-The browser-only endpoint methods of the [in-page channel](/guide/in-page-channel).
+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.
 
-| Method or property | Page script | Panel |
+| 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. |
 | `on(name, listener)` | Subscribes to events emitted by a panel. | Subscribes to events emitted by the page script. Returns an unsubscribe function. |