refactor(hub): unify internal event names and document event channels

Rename the internal EventEmitter events on the subsystem hosts to the
plural subsystem vocabulary already used across every wire name, so the
bus lines up with its RPC/broadcast/shared-state counterparts:

- dock:activate           -> docks:activate
- dock:entry:updated      -> docks:entry:updated
- terminal:session:updated -> terminals:session:updated
- message:*               -> messages:*
- command:*               -> commands:*

Add a dedicated Hub Events Reference docs page tabling the three event
channels (internal node bus, hub: server RPC, devframe: broadcasts and
shared state) and their scope/flow.

Wire names (hub:*, devframe:*) are public API and stay unchanged.

Author: antfubot

docs/.vitepress/config.ts

@@ -50,6 +50,7 @@ function guideGroups(prefix: string) {
         { text: 'Serve a Hub Anywhere', link: `${prefix}/guide/hub-initiate` },
         { text: 'Cross-Plugin Services', link: `${prefix}/guide/services` },
         { text: 'Deep Linking', link: `${prefix}/guide/deep-linking` },
+        { text: 'Events Reference', link: `${prefix}/guide/events` },
       ],
     },
     {

docs/guide/events.md

@@ -0,0 +1,58 @@
+---
+outline: deep
+---
+
+# Hub Events Reference
+
+The hub carries change notifications across three distinct channels. What separates them is **direction and reach**: an in-process event bus that never leaves the node process, server RPC methods a client calls, and server-pushed broadcasts and shared state a client reads.
+
+Two naming prefixes mark the wire surface: `hub:` for hub-layer server RPC (client → server actions), and `devframe:` for the client-facing devframe protocol (broadcasts, shared state, and streams pushed server → client). The internal event bus mirrors the same plural subsystem vocabulary (`docks`, `terminals`, `messages`, `commands`), so each internal event lines up with its wire counterpart — `docks:activate` fans out to `devframe:docks:activate`.
+
+## Internal node event bus
+
+Each subsystem host emits on `ctx.<subsystem>.events`. These fire and are consumed **inside the same node process** — chiefly by `createHubContext`, which fans them out onto the wire. They never cross to the browser.
+
+| Event | Emitted by | Consumed by | Payload |
+|---|---|---|---|
+| `docks:entry:updated` | `DocksHost.register` / `update` | context → `devframe:docks` shared state | `DevframeDockUserEntry` |
+| `docks:activate` | `DocksHost.activate()` | context → broadcast + `devframe:docks:active` | `DevframeDockActivation` |
+| `terminals:session:updated` | `TerminalsHost` register / update / remove / status change | context → `devframe:terminals:updated`; terminals plugin | `DevframeTerminalSession` |
+| `messages:added` / `messages:updated` / `messages:removed` / `messages:cleared` | `MessagesHost` mutations | context → `devframe:messages:updated`; messages plugin | entry / entry / id / — |
+| `commands:registered` / `commands:unregistered` | `CommandsHost` register / update / unregister | context → `devframe:commands` shared state | entry / id |
+
+The `docks:entry:updated` and `terminals:session:updated` middle nouns (`entry`, `session`) name the specific record type; the messages and commands subsystems imply their record in the subsystem name, so they carry the verb directly.
+
+## Server RPC methods — client → server
+
+A connected client (any mounted iframe or panel, on its own RPC client) calls these; the hub node handles them. Carry the `hub:` prefix.
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `hub:docks:activate` | `({ dockId, params? }) => void` | Ask the viewer to switch its active dock — see [Deep Linking](./deep-linking). |
+| `hub:commands:execute` | `(id, ...args) => unknown` | Invoke a registered server command by id. |
+| `hub:messages:add` | `(input) => DevframeMessageEntry` | Add a message to the feed (marked `from: 'browser'`). |
+| `hub:messages:update` | `(id, patch) => DevframeMessageEntry \| undefined` | Patch a message by id. |
+| `hub:messages:remove` | `(id) => void` | Remove a message by id. |
+| `hub:messages:clear` | `() => void` | Remove every message. |
+| `hub:terminals:write` | `(id, data) => void` | Send input to an interactive PTY session. |
+| `hub:terminals:resize` | `(id, cols, rows) => void` | Resize an interactive PTY session. |
+| `hub:terminals:terminate` | `(id) => void` | Kill a session's process, keeping it registered. |
+| `hub:terminals:restart` | `(id) => void` | Re-run a session's command in place. |
+| `hub:terminals:remove` | `(id) => void` | Kill a session's process and drop it from the registry. |
+
+## Broadcasts & shared state — server → client
+
+The server pushes these; a hub-aware client reads or subscribes. Carry the `devframe:` prefix. A UI subscribes to broadcasts via `rpc.client.register(...)`; the [client host](./client-context) registers the `devframe:docks:activate` handler for you.
+
+| Name | Kind | Carries |
+|---|---|---|
+| `devframe:docks:activate` | broadcast | Live "switch active dock" request — the client host calls its local `switchEntry`. |
+| `devframe:terminals:updated` | broadcast | Terminal sessions changed; re-read terminal state. |
+| `devframe:messages:updated` | broadcast | Message list changed; re-read message state. |
+| `devframe:docks` | shared state | Projected dock entry list (`DevframeDockEntry[]`). |
+| `devframe:docks:active` | shared state | Most recent `DevframeDockActivation`, so a dock that mounts in response still converges on it. |
+| `devframe:commands` | shared state | Serializable command list, handlers stripped (`DevframeServerCommandEntry[]`). |
+| `devframe:user-settings` | shared state | Persisted per-workspace hub settings (`DevframeDocksUserSettings`). |
+| `devframe:terminals` | streaming channel | Live terminal output stream, keyed by session id. |
+
+The [`devframe:docks:active`](./shared-state) mirror pairs with the `devframe:docks:activate` broadcast: the broadcast reaches docks already on screen, while the mirror lets a dock that mounts *because* of the switch converge on the same request instead of missing it.

docs/guide/hub.md

@@ -275,7 +275,7 @@ A hub-aware UI doesn't import any hub classes; it reads three shared-state keys
 | `hub:commands:execute` RPC | `(id, ...args) => unknown` | Server-side command dispatch. |
 | `hub:docks:activate` RPC | `({ dockId, params? }) => void` | Switch the active dock from any client. |
 
-Plus broadcast notifications (`devframe:docks:activate`, `devframe:terminals:updated`, `devframe:messages:updated`) that a UI can subscribe to via `rpc.client.register(...)`. The client host registers the `devframe:docks:activate` handler for you.
+Plus broadcast notifications (`devframe:docks:activate`, `devframe:terminals:updated`, `devframe:messages:updated`) that a UI can subscribe to via `rpc.client.register(...)`. The client host registers the `devframe:docks:activate` handler for you. The [Events Reference](./events) tables every channel across all four subsystems.
 
 ## Running plugin code in the host page
 

packages/hub/src/node/__tests__/host-docks.test.ts

@@ -85,7 +85,7 @@ describe('devframeDockHost grouping', () => {
   it('registers a group entry: stored, projected, and emitted', () => {
     const host = new DevframeDocksHost(createContext())
     const emitted: string[] = []
-    host.events.on('dock:entry:updated', entry => emitted.push(entry.id))
+    host.events.on('docks:entry:updated', entry => emitted.push(entry.id))
 
     host.register({
       type: 'group',
@@ -192,12 +192,12 @@ describe('devframeDockHost grouping', () => {
 })
 
 describe('devframeDockHost activate', () => {
-  it('emits a dock:activate event carrying the id and params', () => {
+  it('emits a docks:activate event carrying the id and params', () => {
     const host = new DevframeDocksHost(createContext())
     host.register({ type: 'iframe', id: 'terminals', title: 'Terminals', icon: 'ph:terminal-window-duotone', url: '/__terminals/' })
 
     const activations: Array<{ dockId: string, params?: Record<string, unknown> }> = []
-    host.events.on('dock:activate', a => activations.push(a))
+    host.events.on('docks:activate', a => activations.push(a))
 
     host.activate('terminals', { sessionId: 'sess-1' })
     expect(activations).toEqual([{ dockId: 'terminals', params: { sessionId: 'sess-1' } }])
@@ -208,7 +208,7 @@ describe('devframeDockHost activate', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     try {
       const activations: string[] = []
-      host.events.on('dock:activate', a => activations.push(a.dockId))
+      host.events.on('docks:activate', a => activations.push(a.dockId))
 
       host.activate('nope')
       expect(activations).toEqual(['nope'])

packages/hub/src/node/__tests__/host-terminals.test.ts

@@ -261,7 +261,7 @@ describe('devframeTerminalHost child-process status lifecycle', () => {
   it('marks status stopped and emits an update on a clean exit', async () => {
     const { host } = createTerminalHost()
     const updates: string[] = []
-    host.events.on('terminal:session:updated', s => updates.push(s.status))
+    host.events.on('terminals:session:updated', s => updates.push(s.status))
 
     const session = await host.startChildProcess({
       command: process.execPath,
@@ -441,7 +441,7 @@ describe('devframeTerminalHost PTY status lifecycle', () => {
   itPty('marks status stopped and emits an update on a clean exit', async () => {
     const { host } = createTerminalHost()
     const updates: string[] = []
-    host.events.on('terminal:session:updated', s => updates.push(s.status))
+    host.events.on('terminals:session:updated', s => updates.push(s.status))
 
     const session = await host.startPtySession({
       command: NODE,

packages/hub/src/node/context.ts

@@ -155,7 +155,7 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
   const refreshDocks = debounce(() => {
     docksSharedState.mutate(() => docks.values())
   }, debounceMs)
-  docks.events.on('dock:entry:updated', refreshDocks)
+  docks.events.on('docks:entry:updated', refreshDocks)
   // A remote iframe dock registered before the WS transport finishes binding
   // (the common case: `initHub` installs devframes — and their docks — before
   // resolving an async side-car/shared-server port) gets projected without a
@@ -174,7 +174,7 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
     'devframe:docks:active',
     { initialValue: { activation: null } },
   )
-  docks.events.on('dock:activate', (activation) => {
+  docks.events.on('docks:activate', (activation) => {
     activeDockSharedState.mutate((state) => {
       state.activation = activation
     })
@@ -191,7 +191,7 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
     })
     docksSharedState.mutate(() => docks.values())
   }, debounceMs)
-  terminals.events.on('terminal:session:updated', broadcastTerminals)
+  terminals.events.on('terminals:session:updated', broadcastTerminals)
 
   const broadcastMessages = debounce(() => {
     context.rpc.broadcast({
@@ -200,17 +200,17 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
     })
     docksSharedState.mutate(() => docks.values())
   }, debounceMs)
-  messages.events.on('message:added', broadcastMessages)
-  messages.events.on('message:updated', broadcastMessages)
-  messages.events.on('message:removed', broadcastMessages)
-  messages.events.on('message:cleared', broadcastMessages)
+  messages.events.on('messages:added', broadcastMessages)
+  messages.events.on('messages:updated', broadcastMessages)
+  messages.events.on('messages:removed', broadcastMessages)
+  messages.events.on('messages:cleared', broadcastMessages)
 
   const commandsSharedState = await context.rpc.sharedState.get('devframe:commands', { initialValue: [] })
   const syncCommands = debounce(() => {
     commandsSharedState.mutate(() => commands.list())
   }, debounceMs)
-  commands.events.on('command:registered', syncCommands)
-  commands.events.on('command:unregistered', syncCommands)
+  commands.events.on('commands:registered', syncCommands)
+  commands.events.on('commands:unregistered', syncCommands)
 
   commandsSharedState.mutate(() => commands.list())
 

packages/hub/src/node/host-commands.ts

@@ -76,7 +76,7 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
     validateCommandIds(this.commands, command)
     this.validateAgentExposure(command)
     this.commands.set(command.id, command)
-    this.events.emit('command:registered', this.toSerializable(command))
+    this.events.emit('commands:registered', this.toSerializable(command))
     this.agentProvider?.notifyChanged()
 
     return {
@@ -97,7 +97,7 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
         validateCommandIds(this.commands, next, existing.id)
         this.validateAgentExposure(next)
         Object.assign(existing, patch)
-        this.events.emit('command:registered', this.toSerializable(existing))
+        this.events.emit('commands:registered', this.toSerializable(existing))
         this.agentProvider?.notifyChanged()
       },
       unregister: () => this.unregister(command.id),
@@ -107,7 +107,7 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
   unregister(id: string): boolean {
     const deleted = this.commands.delete(id)
     if (deleted) {
-      this.events.emit('command:unregistered', id)
+      this.events.emit('commands:unregistered', id)
       this.agentProvider?.notifyChanged()
     }
     return deleted

packages/hub/src/node/host-docks.ts

@@ -91,7 +91,7 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     this.validateGroupMembership(view)
     this.prepareRemoteRegistration(view)
     this.views.set(view.id, view)
-    this.events.emit('dock:entry:updated', view)
+    this.events.emit('docks:entry:updated', view)
 
     return {
       update: (patch) => {
@@ -115,7 +115,7 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     this.validateGroupMembership(view)
     this.prepareRemoteRegistration(view)
     this.views.set(view.id, view)
-    this.events.emit('dock:entry:updated', view)
+    this.events.emit('docks:entry:updated', view)
   }
 
   activate(dockId: string, params?: Record<string, unknown>): void {
@@ -125,7 +125,7 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     // rather than fatal.
     if (!this.views.has(dockId))
       diagnostics.DF8107({ id: dockId })
-    this.events.emit('dock:activate', { dockId, params })
+    this.events.emit('docks:activate', { dockId, params })
   }
 
   private validateGroupMembership(view: DevframeDockUserEntry): void {

packages/hub/src/node/host-messages.ts

@@ -69,7 +69,7 @@ export class DevframeMessagesHost implements DevframeMessagesHostType {
 
     this.entries.set(entry.id, entry)
     this.lastModified.set(entry.id, this._tick())
-    this.events.emit('message:added', entry)
+    this.events.emit('messages:added', entry)
 
     if (entry.autoDelete) {
       this._autoDeleteTimers.set(entry.id, setTimeout(() => {
@@ -95,7 +95,7 @@ export class DevframeMessagesHost implements DevframeMessagesHostType {
 
     this.entries.set(id, updated)
     this.lastModified.set(id, this._tick())
-    this.events.emit('message:updated', updated)
+    this.events.emit('messages:updated', updated)
 
     // Reset autoDelete timer if changed
     if (patch.autoDelete !== undefined) {
@@ -123,7 +123,7 @@ export class DevframeMessagesHost implements DevframeMessagesHostType {
     this.entries.delete(id)
     this.lastModified.delete(id)
     this._recordRemoval(id, this._tick())
-    this.events.emit('message:removed', id)
+    this.events.emit('messages:removed', id)
   }
 
   info(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
@@ -155,7 +155,7 @@ export class DevframeMessagesHost implements DevframeMessagesHostType {
       this._recordRemoval(id, tick)
     this.entries.clear()
     this.lastModified.clear()
-    this.events.emit('message:cleared')
+    this.events.emit('messages:cleared')
   }
 
   listSince(since?: number | null): DevframeMessagesListDelta {

packages/hub/src/node/host-terminals.ts

@@ -71,7 +71,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
     }
     this.sessions.set(session.id, session)
     this.bindStream(session)
-    this.events.emit('terminal:session:updated', session)
+    this.events.emit('terminals:session:updated', session)
     return session
   }
 
@@ -83,13 +83,13 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
     Object.assign(session, patch)
     this.sessions.set(patch.id, session)
     this.bindStream(session)
-    this.events.emit('terminal:session:updated', session)
+    this.events.emit('terminals:session:updated', session)
   }
 
   remove(session: DevframeTerminalSession): void {
     this._boundStreams.get(session.id)?.dispose()
     this.sessions.delete(session.id)
-    this.events.emit('terminal:session:updated', session)
+    this.events.emit('terminals:session:updated', session)
     this._boundStreams.delete(session.id)
   }
 
@@ -185,7 +185,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
       if (session.status === next)
         return
       session.status = next
-      this.events.emit('terminal:session:updated', session)
+      this.events.emit('terminals:session:updated', session)
     }
 
     const closeStream = () => {
@@ -376,7 +376,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
       if (session.status === next)
         return
       session.status = next
-      this.events.emit('terminal:session:updated', session)
+      this.events.emit('terminals:session:updated', session)
     }
 
     const closeStream = () => {