refactor(hub): emit panel state from client context

Author: dvcolomban

docs/content/1.guide/17.client-context.md

@@ -36,6 +36,29 @@ The context carries the [RPC client](/guide/client) (`rpc`) and the page's `clie
 
 `getDevframeClientContext()` returns the context anywhere; `undefined` before boot.
 
+### Tracking panel state
+
+`ctx.panel.state` is the current dock-panel snapshot. It contains `state: 'open' | 'closed' | 'hidden'` and includes `selectedDockId` while a dock is selected. Subscribe to `ctx.panel.events` for later changes:
+
+```ts
+import type { DevframeDockPanelState } from '@devframes/hub'
+import type { DockClientScriptContext } from '@devframes/hub/client'
+import { HUB_EVENTS } from '@devframes/hub/constants'
+
+export default function setup(context: DockClientScriptContext) {
+  const reportPanelState = (panelState: DevframeDockPanelState) =>
+    context.rpc.call('my-devframe:panel-state', panelState)
+
+  void reportPanelState(context.panel.state)
+  context.panel.events.on(
+    HUB_EVENTS.client.docksPanelStateChanged,
+    panelState => void reportPanelState(panelState),
+  )
+}
+```
+
+The custom RPC keeps node-side reporting opt-in. Its handler can call `ctx.rpc.getCurrentRpcSession()` when it needs the reporting connection's identity.
+
 ### Client-only docks
 
 A client runtime can register a dock local to the host page (unlike [node hub context](/guide/hub) docks synced via `devframe:docks`). `ctx.docks.register(entry)` — e.g. `type: 'custom-render'` with `renderer: { importFrom }` — returns a handle whose `update({ badge })` patches in place (id immutable) and `dispose()` removes it. One sharing a server dock's id overrides it locally; re-registering an owned id throws unless you pass `register(entry, true)`.

docs/content/8.references/3.events.md

@@ -2,17 +2,27 @@
 title: 'Events Reference'
 navigation:
   icon: i-lucide-radio-tower
-description: 'Devframe carries change notifications across channels of differing direction and reach: a node event bus, server RPC, and server-pushed broadcasts and shared state.'
+description: 'Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.'
 ---
 
-Devframe carries change notifications across channels of differing **direction and reach**: a node event bus, server RPC, and server-pushed broadcasts and shared state.
+Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.
 
 Two prefixes mark the wire protocol: `hub:` for hub-layer server RPC (client → server), `devframe:` for the client-facing protocol (server → client). The internal event bus mirrors the subsystem vocabulary (`docks`, `terminals`, `messages`, `commands`) — `docks:activate` fans out to `devframe:docks:activate`.
 
 Each name lives in code: [`HUB_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/hub/src/events.ts) (`@devframes/hub/constants`) backs the hub tables, [`DEVFRAME_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/events.ts) (`devframe/constants`) the core ones.
 
 ## Hub events
 
+### Client-context events
+
+Client scripts subscribe to these events on the client context inside the host page.
+
+| Event | Emitter | Payload |
+|---|---|---|
+| `panel:state:changed` | `ctx.panel.events` | `DevframeDockPanelState` |
+
+`ctx.panel.state` supplies the current snapshot when a client script loads. Later open, close, dock selection, and hub UI provider visibility changes emit `panel:state:changed`. The snapshot contains `state: 'open' | 'closed' | 'hidden'` and an optional `selectedDockId`.
+
 ### Internal node event bus
 
 Each subsystem emits on `ctx.<subsystem>.events`, consumed **inside the same node process** by `createHubContext`, which fans them onto the wire.
@@ -21,19 +31,15 @@ Each subsystem emits on `ctx.<subsystem>.events`, consumed **inside the same nod
 |---|---|---|---|
 | `docks:entry:updated` | `DocksHost.register` / `update` | context → `devframe:docks` shared state | `DevframeDockUserEntry` |
 | `docks:activate` | `DocksHost.activate()` | context → broadcast + `devframe:docks:active` | `DevframeDockActivation` |
-| `docks:panel:state` | viewer state reports and RPC disconnects | hub consumers | `DevframeDockPanelStateEvent` |
 | `terminals:session:updated` | `TerminalsHost` register / update / remove / status change | context → `devframe:terminals:updated`; the terminals devframe | `DevframeTerminalSession` |
 | `messages:added` / `messages:updated` / `messages:removed` / `messages:cleared` | `MessagesHost` mutations | context → `devframe:messages:updated`; the messages devframe | entry / entry / id / — |
 | `commands:registered` / `commands:unregistered` | `CommandsHost` register / update / unregister | context → `devframe:commands` shared state | entry / id |
 
-`docks:panel:state` emits `connected` with the first reported panel snapshot, `changed` when its state or selected dock changes, and `disconnected` when the reporting RPC connection closes. A snapshot contains `state: 'open' | 'closed' | 'hidden'` and an optional `selectedDockId`. Its numeric `sessionId` identifies that connection for the lifetime of the Node process. A reload or reconnect receives a new id.
-
 ### Server RPC methods — client → server
 
 | Method | Signature | Purpose |
 |---|---|---|
 | `hub:docks:activate` | `({ dockId, params? }) => void` | Ask the hub UI provider to switch its active dock — see [Deep Linking](/guide/deep-linking). |
-| `hub:docks:panel:state` | `(panelState: DevframeDockPanelState) => void` | Report this viewer connection's current dock-panel state and selected dock. |
 | `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. |

examples/hub-vite-minimal/vite.config.ts

@@ -1,8 +1,6 @@
 import type { DevframeJsonRenderSpec } from '@devframes/json-render'
 import type { DevframeJsonRenderDockEntry } from '@devframes/json-render/hub'
-import { styleText } from 'node:util'
 import { createUi } from '@devframes/hub-ui'
-import { HUB_EVENTS } from '@devframes/hub/constants'
 import { jsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
 import { createA11yDevframe } from '@devframes/plugin-a11y'
 import { createAssetsDevframe } from '@devframes/plugin-assets'
@@ -80,10 +78,6 @@ export default defineConfig({
       // the same contract.
       renderers: [jsonRenderUiRenderer()],
       configure(ctx) {
-        ctx.docks.events.on(HUB_EVENTS.bus.docksPanelState, (event) => {
-          console.info(styleText('cyan', '🔄 [hub-vite-minimal]'), 'Dock panel state updated', event)
-        })
-
         ctx.docks.register(jsonRenderDock)
       },
       // Gate with devframe's interactive OTP (the default): the hub prints a

packages/hub-ui/src/client/embedded/visibility.test.ts

@@ -7,7 +7,7 @@ afterEach(() => {
 })
 
 describe('setupEmbeddedVisibility', () => {
-  it('reports the initial hidden state and later reveal and conceal transitions', () => {
+  it('handles the initial hidden state and later reveal and conceal transitions', () => {
     expect.assertions(5)
 
     const listeners = new Map<string, EventListener>()

packages/hub-ui/src/client/state/context.test.ts

@@ -1,4 +1,4 @@
-import type { DevframeDockEntry } from '@devframes/hub'
+import type { DevframeDockEntry, DevframeDockPanelState } from '@devframes/hub'
 import type { DevframeRpcClient, DockSessionStorage } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import { HUB_EVENTS } from '@devframes/hub/constants'
@@ -72,10 +72,12 @@ async function flushRestore(): Promise<void> {
   await Promise.resolve()
   await Promise.resolve()
   await nextTick()
+  await Promise.resolve()
+  await Promise.resolve()
 }
 
 describe('createDocksContext', () => {
-  it('reports restored, selected, hidden, and closed panel snapshots', async () => {
+  it('exposes restored panel state and emits selected, hidden, and closed changes', async () => {
     expect.assertions(8)
 
     const { rpc, sharedStates, trust } = createStubRpc()
@@ -85,7 +87,12 @@ describe('createDocksContext', () => {
       selectedDockId: 'git',
       selectedDockRoute: null,
     })
-    await createDocksContext('embedded', rpc, undefined, session, panelVisible)
+    const context = await createDocksContext('embedded', rpc, undefined, session, panelVisible)
+    const panelStates: DevframeDockPanelState[] = []
+    context.panel.events.on(
+      HUB_EVENTS.client.docksPanelStateChanged,
+      panelState => panelStates.push(panelState),
+    )
 
     trust()
     sharedStates.get('devframe:docks')!.push([gitEntry])
@@ -95,34 +102,30 @@ describe('createDocksContext', () => {
 
     panelVisible.value = true
     await nextTick()
-    await vi.waitFor(() => {
-      if (vi.mocked(rpc.call).mock.calls.length !== 1)
-        throw new Error('waiting for the restored panel state report')
-    })
-    expect(rpc.call).toHaveBeenCalledTimes(1)
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: 'git' })
+    expect(context.panel.state).toEqual({ state: 'open', selectedDockId: 'git' })
+    expect(panelStates).toEqual([])
 
     session.value.selectedDockId = '~settings'
     await nextTick()
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: '~settings' })
+    expect(panelStates.at(-1)).toEqual({ state: 'open', selectedDockId: '~settings' })
 
     panelVisible.value = false
     await nextTick()
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'hidden', selectedDockId: '~settings' })
+    expect(panelStates.at(-1)).toEqual({ state: 'hidden', selectedDockId: '~settings' })
 
     session.value.open = false
     session.value.selectedDockId = null
     await nextTick()
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'hidden' })
+    expect(panelStates.at(-1)).toEqual({ state: 'hidden' })
 
     panelVisible.value = true
     await nextTick()
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'closed' })
+    expect(panelStates.at(-1)).toEqual({ state: 'closed' })
 
     panelVisible.value = true
     session.value.open = false
     await nextTick()
-    expect(rpc.call).toHaveBeenCalledTimes(5)
+    expect(panelStates).toHaveLength(4)
   })
 
   it('mounts a restored dock once after all initial server state arrives', async () => {

packages/hub-ui/src/client/state/context.ts

@@ -1,12 +1,13 @@
 import type { DevframeClientCommand, DevframeDockEntry, DevframeDockPanelState, DevframeDockUserEntry, DevframeRpcClientFunctions, DevframeViewIframe } from '@devframes/hub'
-import type { CommandsContext, DevframeClientContext, DevframeRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DockRendererManifest, DocksContext, DockSessionStorage } from '@devframes/hub/client'
+import type { CommandsContext, DevframeClientContext, DevframeRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DockRendererManifest, DocksContext, DockSessionStorage, DocksPanelEvents } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
 import type { DevframeDocksUserSettings } from './dock-settings'
-import { attachFrameNavClient, createDockRenderersContext, reportDockPanelState } from '@devframes/hub/client'
+import { attachFrameNavClient, createDockRenderersContext } from '@devframes/hub/client'
 import { DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY, HUB_EVENTS } from '@devframes/hub/constants'
 import { DEVFRAME_EVENTS } from 'devframe/constants'
+import { createEventEmitter } from 'devframe/utils/events'
 import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vue'
 import { BUILTIN_ENTRIES, BUILTIN_ENTRY_SETTINGS, DEFAULT_CATEGORIES_ORDER, HUB_UI_HIDE_EVENT } from '../constants'
 import { useBranding } from './branding'
@@ -193,6 +194,7 @@ export async function createDocksContext(
   }
 
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
+  const panelEvents = createEventEmitter<DocksPanelEvents>()
   let docksContext: DocksContext
 
   let _settingsStorePromise: Promise<SharedState<DevframeDocksUserSettings>> | undefined
@@ -598,6 +600,14 @@ export async function createDocksContext(
 
   docksContext = reactive({
     panel: {
+      get state() {
+        return createDockPanelState(
+          panelVisible.value !== false,
+          sessionStore.value.open,
+          selectedDockId.value,
+        )
+      },
+      events: markRaw(panelEvents),
       store: panelStore,
       session: sessionStore,
       isDragging: false,
@@ -692,20 +702,26 @@ export async function createDocksContext(
     initialRestorePending.value = false
     await switchEntry(restoreDockId)
   }
-  const reportPanelStateAfterInitialization = async (): Promise<void> => {
-    await restoreAfterInitialization()
+  const startPanelStateEvents = (): void => {
+    let previousPanelState = docksContext.panel.state
     watch(
       [panelVisible, () => sessionStore.value.open, selectedDockId],
-      ([visible, open, currentSelectedDockId]) => {
-        if (visible === undefined)
+      () => {
+        const panelState = docksContext.panel.state
+        if (
+          panelState.state === previousPanelState.state
+          && panelState.selectedDockId === previousPanelState.selectedDockId
+        ) {
           return
-        const panelState = createDockPanelState(visible, open, currentSelectedDockId)
-        void reportDockPanelState(rpc, panelState).catch(() => {})
+        }
+
+        previousPanelState = panelState
+        panelEvents.emit(HUB_EVENTS.client.docksPanelStateChanged, panelState)
       },
-      { immediate: true },
+      { flush: 'post' },
     )
   }
-  void reportPanelStateAfterInitialization()
+  void restoreAfterInitialization().then(startPanelStateEvents, startPanelStateEvents)
 
   docksContextByRpc.set(rpc, docksContext)
   return docksContext

packages/hub/src/client/__tests__/host.test.ts

@@ -1,6 +1,6 @@
 import type { DevframeRpcClient } from 'devframe/client'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { DevframeDockEntry } from '../../types/docks'
+import type { DevframeDockEntry, DevframeDockPanelState } from '../../types/docks'
 import { createEventEmitter } from 'devframe/utils/events'
 import { describe, expect, it, vi } from 'vitest'
 import { HUB_EVENTS } from '../../events'
@@ -68,32 +68,39 @@ function groupEntry(id: string, extra?: Record<string, unknown>): DevframeDockEn
 }
 
 describe('createDevframeClientRuntime', () => {
-  it('reports complete panel snapshots and coalesces related session changes', async () => {
-    expect.assertions(4)
+  it('exposes panel state and emits coalesced changes', async () => {
+    expect.assertions(7)
 
     const { rpc, calls, states } = createStubRpc()
     const host = await createDevframeClientRuntime({ rpc, clientType: 'embedded' })
+    const panelStates: DevframeDockPanelState[] = []
 
-    expect(calls).toEqual([[HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }]])
+    expect(host.context.panel.state).toEqual({ state: 'closed' })
+    host.context.panel.events.on(
+      HUB_EVENTS.client.docksPanelStateChanged,
+      panelState => panelStates.push(panelState),
+    )
 
-    states.get('devframe:docks')!.push([iframeEntry('one')])
+    states.get('devframe:docks')!.push([iframeEntry('one'), iframeEntry('two')])
     host.context.panel.session.open = true
     const switched = host.context.docks.switchEntry('one')
     await switched
-    expect(calls).toEqual([
-      [HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }],
-      [HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: 'one' }],
-    ])
+    expect(panelStates).toEqual([{ state: 'open', selectedDockId: 'one' }])
+    expect(host.context.panel.state).toEqual({ state: 'open', selectedDockId: 'one' })
 
     host.context.panel.session.open = true
     host.context.panel.session.selectedDockId = 'one'
     await Promise.resolve()
-    expect(calls).toHaveLength(2)
+    expect(panelStates).toHaveLength(1)
+
+    await host.context.docks.switchEntry('two')
+    expect(panelStates.at(-1)).toEqual({ state: 'open', selectedDockId: 'two' })
 
     host.context.panel.session.open = false
     const cleared = host.context.docks.switchEntry(null)
     await cleared
-    expect(calls.at(-1)).toEqual([HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }])
+    expect(panelStates.at(-1)).toEqual({ state: 'closed' })
+    expect(calls).toEqual([])
     host.dispose()
   })
 

packages/hub/src/client/__tests__/panel-state.test.ts

@@ -3,7 +3,7 @@ import type { EventEmitter } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { DevframeClientCommand, DevframeCommandEntry, DevframeCommandKeybinding } from '../types/commands'
-import type { DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDockUserEntry } from '../types/docks'
+import type { DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDockPanelState, DevframeDockUserEntry } from '../types/docks'
 import type { DevframeDocksUserSettings } from '../types/settings'
 import type { DockRenderersContext } from './renderers'
 
@@ -125,7 +125,15 @@ export interface WhenClauseContext {
 
 export type DevframeClientContext = DocksContext
 
+export interface DocksPanelEvents {
+  'panel:state:changed': (state: DevframeDockPanelState) => void
+}
+
 export interface DocksPanelContext {
+  /** The current panel state snapshot. */
+  readonly state: DevframeDockPanelState
+  /** Subscribe to panel state changes after the current snapshot. */
+  readonly events: EventEmitter<DocksPanelEvents>
   store: DockPanelStorage
   /**
    * Per-tab session UI state — whether the panel is open, which dock is