fix(hub): address panel state review feedback

Author: dvcolomban

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

@@ -38,17 +38,21 @@ The context carries the [RPC client](/guide/client) (`rpc`) and the page's `clie
 
 ### 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:
+`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`](/references/events#client-context-events) for later changes:
 
 ```ts
 import type { DockClientScriptContext } from '@devframes/hub/client'
 import { HUB_EVENTS } from '@devframes/hub/constants'
 
 export default function setup(context: DockClientScriptContext) {
-  void context.rpc.call('my-devframe:panel-state', context.panel.state)
+  const reportPanelState = (panelState: typeof context.panel.state) => {
+    void context.rpc.call('my-devframe:panel-state', panelState).catch(error => console.error(error))
+  }
+
+  reportPanelState(context.panel.state)
   context.panel.events.on(
     HUB_EVENTS.client.docksPanelStateChanged,
-    panelState => void context.rpc.call('my-devframe:panel-state', panelState),
+    reportPanelState,
   )
 }
 ```

docs/content/8.references/6.hub-api.md

@@ -105,7 +105,7 @@ The properties of `DevframeClientContext` — [The client context](/guide/client
 | `rpc` | The [RPC client](/guide/client) — server/client functions, shared state. |
 | `clientType` | `'embedded'` (inside the user app) or `'standalone'` (independent hub page). |
 | `docks` | `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`, `register()` / `update()` for [client-only docks](/guide/client-context#client-only-docks). |
-| `panel` | Dock panel state: position, size, drag/resize. |
+| `panel` | Current `state`, local `events`, session, position, size, and drag/resize state for the dock panel. |
 | `commands` | Command palette: `register()`, `execute()`, `getKeybindings()`. |
 | `renderers` | Dock-renderer registry — `register()`, `get()`, `has()`, `mount(entry, container)`. Routes a dock `type` to a renderer (local boot or the hub's [manifest](/guide/hub-initiate#renderer-modules); local wins). `mount()` resolves a `status`: `mounted` (with `dispose`), `missing-renderer`, or `load-error` (with `error`). |
 | `when` | The [when-clause](/references/when-clauses) context. |

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

@@ -72,13 +72,11 @@ async function flushRestore(): Promise<void> {
   await Promise.resolve()
   await Promise.resolve()
   await nextTick()
-  await Promise.resolve()
-  await Promise.resolve()
 }
 
 describe('createDocksContext', () => {
   it('exposes restored panel state and emits selected, hidden, and closed changes', async () => {
-    expect.assertions(8)
+    expect.assertions(9)
 
     const { rpc, sharedStates, trust } = createStubRpc()
     const panelVisible = ref(false)
@@ -94,6 +92,13 @@ describe('createDocksContext', () => {
       panelState => panelStates.push(panelState),
     )
 
+    panelVisible.value = true
+    await nextTick()
+    expect(panelStates).toEqual([{ state: 'open', selectedDockId: 'git' }])
+    panelVisible.value = false
+    await nextTick()
+    panelStates.length = 0
+
     trust()
     sharedStates.get('devframe:docks')!.push([gitEntry])
     sharedStates.get('devframe:dock-renderers')!.push({})
@@ -129,11 +134,15 @@ describe('createDocksContext', () => {
   })
 
   it('mounts a restored dock once after all initial server state arrives', async () => {
-    expect.assertions(7)
+    expect.assertions(8)
 
     const { rpc, sharedStates, trust } = createStubRpc()
     const executeSetupScriptMock = vi.mocked(executeSetupScript)
     executeSetupScriptMock.mockClear()
+    let setupPanelState: DevframeDockPanelState | undefined
+    executeSetupScriptMock.mockImplementationOnce(async (_dockEntry, scriptContext) => {
+      setupPanelState = scriptContext.panel.state
+    })
     const session = ref<DockSessionStorage>({
       open: true,
       selectedDockId: 'git',
@@ -159,6 +168,7 @@ describe('createDocksContext', () => {
 
     expect(context.docks.selected?.id).toBe('git')
     expect(session.value.open).toBe(true)
+    expect(setupPanelState).toEqual({ state: 'open', selectedDockId: 'git' })
     expect(executeSetupScriptMock).toHaveBeenCalledOnce()
   })
 

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

@@ -272,6 +272,10 @@ export async function createDocksContext(
         return false
     }
 
+    initialRestorePending.value = false
+    selectedDockId.value = entry.id
+    sessionStore.value.open = true
+
     // If has import script, run it
     if (
       (entry.type === 'action')
@@ -302,9 +306,6 @@ export async function createDocksContext(
     if (entry.groupId)
       (sessionStore.value.groupLastChildIds ??= {})[entry.groupId] = entry.id
 
-    initialRestorePending.value = false
-    selectedDockId.value = entry.id
-    sessionStore.value.open = true
     // Only an iframe dock owns an address-bar route; ViewIframe keeps
     // `session.selectedDockRoute` current for it. Clear it for anything else so a stale
     // route from a previous iframe isn't persisted against a non-iframe dock.
@@ -687,26 +688,24 @@ export async function createDocksContext(
     initialRestorePending.value = false
     await switchEntry(restoreDockId)
   }
-  const startPanelStateEvents = (): void => {
-    let previousPanelState = docksContext.panel.state
-    watch(
-      [panelVisible, () => sessionStore.value.open, selectedDockId],
-      () => {
-        const panelState = docksContext.panel.state
-        if (
-          panelState.state === previousPanelState.state
-          && panelState.selectedDockId === previousPanelState.selectedDockId
-        ) {
-          return
-        }
+  let previousPanelState = docksContext.panel.state
+  watch(
+    [panelVisible, () => sessionStore.value.open, selectedDockId],
+    () => {
+      const panelState = docksContext.panel.state
+      if (
+        panelState.state === previousPanelState.state
+        && panelState.selectedDockId === previousPanelState.selectedDockId
+      ) {
+        return
+      }
 
-        previousPanelState = panelState
-        panelEvents.emit(HUB_EVENTS.client.docksPanelStateChanged, panelState)
-      },
-      { flush: 'post' },
-    )
-  }
-  void restoreAfterInitialization().then(startPanelStateEvents, startPanelStateEvents)
+      previousPanelState = panelState
+      panelEvents.emit(HUB_EVENTS.client.docksPanelStateChanged, panelState)
+    },
+    { flush: 'post' },
+  )
+  void restoreAfterInitialization()
 
   docksContextByRpc.set(rpc, docksContext)
   return docksContext

packages/hub/src/client/docks.ts

@@ -126,7 +126,7 @@ export interface WhenClauseContext {
 export type DevframeClientContext = DocksContext
 
 export interface DocksPanelEvents {
-  'panel:state:changed': (state: DevframeDockPanelState) => void
+  'panel:state:changed': (panelState: DevframeDockPanelState) => void
 }
 
 export interface DocksPanelContext {