feat(hub): restore dock open/selection/route across reloads via session store

Introduce a per-tab `DockSessionStorage` (open, selectedId, route) distinct
from the browser-shared `DockPanelStorage` geometry. `open` moves out of the
panel store into this session store, joined by the selected dock id and the
selected iframe dock's live address-bar route.

The embedded and standalone bootstraps persist it to `sessionStorage`, and the
docks context re-applies the persisted selection once the RPC handshake makes
the client trusted — surviving the pre-handshake untrusted window that
force-closes the panel. A restored iframe boots deep-linked to its saved route
via a one-shot `consumeBootRoute`.

Created with the help of an agent.

Author: antfubot

packages/hub-ui/src/client/components/dock/Dock.vue

@@ -86,7 +86,7 @@ const isRpcTrusted = useIsRpcTrusted(context, (isTrusted) => {
   else if (!isTrusted) {
     // On revocation: close current tab and panel
     context.docks.switchEntry(null)
-    context.panel.store.open = false
+    context.panel.session.open = false
   }
 })
 
@@ -183,7 +183,7 @@ const isMinimized = computed(() => {
   // @ts-expect-error compatibility
   const isTouchDevice = 'ontouchstart' in window || navigator.maxTouchPoints > 0 || navigator.msMaxTouchPoints > 0
   return !context.panel.isDragging
-    && !context.panel.store.open
+    && !context.panel.session.open
     && !isHovering.value
     && !isTouchDevice
     && context.panel.store.inactiveTimeout
@@ -218,8 +218,8 @@ whenever(isMinimized, () => {
 })
 
 onMounted(() => {
-  if (context.panel.store.open && !isRpcTrusted.value)
-    context.panel.store.open = false
+  if (context.panel.session.open && !isRpcTrusted.value)
+    context.panel.session.open = false
   if (isRpcTrusted.value)
     bringUp()
   recalculateCounter.value++

packages/hub-ui/src/client/components/dock/DockEdge.stories.ts

@@ -38,7 +38,8 @@ function edgeStory(position: 'top' | 'right' | 'bottom' | 'left', open = true) {
         {
           entries: categorizedEntries,
           selectedId: open ? 'overview' : null,
-          panel: { mode: 'edge', position, open, height: 40, width: 30 },
+          panel: { mode: 'edge', position, height: 40, width: 30 },
+          session: { open },
         },
         ctx => [
           h(DockEdge, { context: ctx }, { view: ({ entry }: any) => body(entry) }),
@@ -75,7 +76,8 @@ export const CollapsedIdle: Story = {
       {
         entries: categorizedEntries,
         selectedId: null,
-        panel: { mode: 'edge', position: 'bottom', open: false, inactiveTimeout: 0 },
+        panel: { mode: 'edge', position: 'bottom', inactiveTimeout: 0 },
+        session: { open: false },
         settings: { autoCollapseEdgeToolbar: true },
       },
       ctx => [
@@ -93,7 +95,7 @@ export const WithGroup: Story = {
       {
         entries: groupedEntries,
         selectedId: 'nuxt:overview',
-        panel: { mode: 'edge', position: 'bottom', open: true, height: 45 },
+        panel: { mode: 'edge', position: 'bottom', height: 45 },
       },
       ctx => [
         h(DockEdge, { context: ctx }, { view: ({ entry }: any) => body(entry) }),

packages/hub-ui/src/client/components/dock/DockEdge.vue

@@ -37,7 +37,7 @@ const selectedEntry = computed(() => context.docks.selected)
 const activeGroup = computed(() => getEntryGroup(context.docks.entries, selectedEntry.value))
 const hasPanelContent = computed(() => {
   const entry = selectedEntry.value
-  return context.panel.store.open
+  return context.panel.session.open
     && !!entry
     && entry.type !== 'action'
 })

packages/hub-ui/src/client/components/dock/DockEmbedded.stories.ts

@@ -69,7 +69,7 @@ export const FloatReducedOverlap: Story = {
 export const Edge: Story = {
   render: () => ({
     setup: () => mountWithContext(
-      { entries: blankEntries, selectedId: 'overview', panel: { mode: 'edge', position: 'bottom', open: true, height: 45 } },
+      { entries: blankEntries, selectedId: 'overview', panel: { mode: 'edge', position: 'bottom', height: 45 } },
       ctx => h(DockEmbedded, { context: ctx }),
     ),
   }),

packages/hub-ui/src/client/components/dock/DockEmbedded.vue

@@ -33,7 +33,7 @@ useEventListener(window, 'mousedown', (e: MouseEvent) => {
     return
   if (isDockPopupOpen.value)
     return
-  if (!props.context.panel.store.open || props.context.panel.isDragging || props.context.panel.isResizing)
+  if (!props.context.panel.session.open || props.context.panel.isDragging || props.context.panel.isResizing)
     return
 
   const matched = e.composedPath().find((_el) => {

packages/hub-ui/src/client/components/views/ViewIframe.vue

@@ -224,19 +224,37 @@ let onIframeLoad: (() => void) | undefined
 
 onMounted(() => {
   const existed = props.panes.has(paneKey.value)
+  // Restore the address-bar route persisted before the last reload: the dock
+  // that was selected then boots deep-linked to where the developer left it,
+  // instead of the entry's default url. `consumeBootRoute` hands the saved URL
+  // back only for that dock, and only once, so a later switch can't reuse it.
+  const bootUrl = props.context.panel.consumeBootRoute?.(props.entry.id) ?? props.entry.url
+  if (!existed && bootUrl !== currentUrl.value) {
+    currentUrl.value = bootUrl
+    editingUrl.value = bootUrl
+  }
   // `src` is only assigned when the pane is first created, so re-mounting an
   // existing iframe (tab switch) preserves its navigation/scroll/JS state. For
   // a shared frame this is also the boot deep-link: the first member (or the
   // anchor) to become visible seeds the src, and every later switch soft-navs.
   const pane = props.panes.ensure(paneKey.value, {
-    src: props.entry.url,
+    src: bootUrl,
     style: { boxShadow: 'none', outline: 'none' },
   })
   const iframe = pane.iframe
 
   if (existed)
     updateCurrentUrl()
 
+  // Persist this dock's live route while it is the selected one, so the next
+  // reload can restore it. Only the selected dock writes, so switching docks
+  // never overwrites another's saved route.
+  const panelSession = props.context.panel.session
+  watchEffect(() => {
+    if (props.context.docks.selectedId === props.entry.id)
+      panelSession.route = currentUrl.value
+  })
+
   // Listen for iframe load events
   onIframeLoad = () => {
     isIframeLoading.value = false

packages/hub-ui/src/client/embedded/index.ts

@@ -1,8 +1,8 @@
-import type { DockPanelStorage } from '@devframes/hub/client'
+import type { DockPanelStorage, DockSessionStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
-import { useLocalStorage } from '@vueuse/core'
+import { useLocalStorage, useSessionStorage } from '@vueuse/core'
 import { applyPrimaryColor, setBranding } from '../state/branding'
-import { DEFAULT_DOCK_PANEL_STORE } from '../state/docks'
+import { DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 import { setupEmbeddedVisibility } from './visibility'
 
 /**
@@ -59,13 +59,23 @@ async function mountDock(): Promise<void> {
     { mergeDefaults: true },
   )
 
+  // Per-tab session UI state (open dock + its route). `sessionStorage`, not
+  // `localStorage`: selection is per-tab navigation state, so two tabs against
+  // the same server keep their own rather than fighting over a shared one. It
+  // survives a reload and is restored after the auth handshake.
+  const session = useSessionStorage<DockSessionStorage>(
+    'devframes-dock-session',
+    DEFAULT_DOCK_SESSION_STORE(),
+    { mergeDefaults: true },
+  )
+
   // Resolve branding before the dock exists so the primary color and logo are
   // in place on the first paint. Read from `ConnectionMeta.configs.ui.branding`,
   // carried by the connection we just established above.
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
 
   const { createDocksContext } = await import('../state/context')
-  const context = await createDocksContext('embedded', rpc, state)
+  const context = await createDocksContext('embedded', rpc, state, session)
   setDevframeClientContext(context)
 
   const { DockEmbedded } = await import('../components/DockEmbedded')

packages/hub-ui/src/client/standalone/main.ts

@@ -1,7 +1,10 @@
+import type { DockSessionStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
+import { useSessionStorage } from '@vueuse/core'
 import { watchEffect } from 'vue'
 import { applyDocumentHead, applyPrimaryColor, setBranding } from '../state/branding'
 import { isDark } from '../state/color-mode'
+import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 
 // The standalone viewer — a vanilla shell served at the hub base itself
 // (`DevframeHubUi.viewer`): resolve the shared connection, build the docks
@@ -37,8 +40,16 @@ async function main(): Promise<void> {
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
   applyDocumentHead(document, branding)
 
+  // Per-tab session UI state (which dock is open + its route). `sessionStorage`
+  // so a reload restores the selection after the auth handshake, per-tab.
+  const session = useSessionStorage<DockSessionStorage>(
+    'devframes-dock-session',
+    DEFAULT_DOCK_SESSION_STORE(),
+    { mergeDefaults: true },
+  )
+
   const { createDocksContext } = await import('../state/context')
-  const context = await createDocksContext('standalone', rpc)
+  const context = await createDocksContext('standalone', rpc, undefined, session)
   setDevframeClientContext(context)
 
   const { DockStandalone } = await import('../components/DockStandalone')

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

@@ -1,5 +1,5 @@
 import type { DevframeClientCommand, DevframeDockEntry, DevframeDockUserEntry, DevframeRpcClientFunctions, DevframeViewIframe } from '@devframes/hub'
-import type { CommandsContext, DevframeClientContext, DevframeRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DockRendererManifest, DocksContext } from '@devframes/hub/client'
+import type { CommandsContext, DevframeClientContext, DevframeRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DockRendererManifest, DocksContext, DockSessionStorage } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
@@ -11,7 +11,7 @@ import { BUILTIN_ENTRIES, BUILTIN_ENTRY_SETTINGS, DEFAULT_CATEGORIES_ORDER, HUB_
 import { useBranding } from './branding'
 import { createCommandsContext } from './commands'
 import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
-import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, sharedStateToRef, useDocksEntries } from './docks'
+import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE, sharedStateToRef, useDocksEntries } from './docks'
 import { createClientMessagesClient } from './messages-client'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDockPopupOpen } from './popup'
 import { executeSetupScript } from './setup-script'
@@ -21,6 +21,7 @@ export async function createDocksContext(
   clientType: 'embedded' | 'standalone',
   rpc: DevframeRpcClient,
   panelStore?: Ref<DockPanelStorage>,
+  sessionStore?: Ref<DockSessionStorage>,
 ): Promise<DocksContext> {
   if (docksContextByRpc.has(rpc)) {
     return docksContextByRpc.get(rpc)!
@@ -72,7 +73,29 @@ export async function createDocksContext(
     return [...base, BUILTIN_ENTRY_SETTINGS]
   })
 
-  const selectedId = ref<string | null>(null)
+  // Per-tab session UI state (open/selectedId/route). A caller (the embedded and
+  // standalone bootstraps) passes a `sessionStorage`-backed ref so it survives a
+  // reload; stories and the default path fall back to an in-memory ref.
+  sessionStore ||= ref(DEFAULT_DOCK_SESSION_STORE())
+
+  // Snapshot the persisted intent up front, before the pre-handshake untrusted
+  // window (Dock.vue's `open`-gate, a revocation `switchEntry(null)`) can clear
+  // the live session state. Re-applied once the RPC becomes trusted so a reload
+  // lands back on the same dock — see the restore effect near the end.
+  const restoreIntent = {
+    open: sessionStore.value.open,
+    selectedId: sessionStore.value.selectedId,
+    route: sessionStore.value.route,
+  }
+
+  // `selectedId` is backed by the session store so the current selection both
+  // drives the UI and persists across reloads through one source of truth.
+  const selectedId = computed<string | null>({
+    get: () => sessionStore.value.selectedId,
+    set: (id) => {
+      sessionStore.value.selectedId = id
+    },
+  })
   const selected = computed(
     () => entries.value.find(entry => entry.id === selectedId.value)
       ?? BUILTIN_ENTRIES.find(entry => entry.id === selectedId.value)
@@ -154,7 +177,7 @@ export async function createDocksContext(
   const isDockPopupOpen = useIsDockPopupOpen()
   const getWhenContext = (): WhenContext => ({
     clientType,
-    dockOpen: panelStore.value.open,
+    dockOpen: sessionStore.value.open,
     paletteOpen: commandsContext?.paletteOpen ?? false,
     dockSelectedId: selectedId.value ?? '',
     popupOpen: isDockPopupOpen.value,
@@ -173,12 +196,13 @@ export async function createDocksContext(
   const switchEntry = async (id: string | null = null) => {
     if (id == null) {
       selectedId.value = null
-      panelStore.value.open = false
+      sessionStore.value.open = false
+      sessionStore.value.route = null
       return true
     }
     if (id === '~client-auth-notice') {
       selectedId.value = id
-      panelStore.value.open = true
+      sessionStore.value.open = true
       return true
     }
     const entry = entries.value.find(e => e.id === id)
@@ -245,7 +269,12 @@ export async function createDocksContext(
       frameNavCurrentMember.set(entry.frameId, entry.id)
 
     selectedId.value = entry.id
-    panelStore.value.open = true
+    sessionStore.value.open = true
+    // Only an iframe dock owns an address-bar route; ViewIframe keeps
+    // `session.route` current for it. Clear it for anything else so a stale
+    // route from a previous iframe isn't persisted against a non-iframe dock.
+    if (entry.type !== 'iframe')
+      sessionStore.value.route = null
     return true
   }
 
@@ -385,7 +414,7 @@ export async function createDocksContext(
       when: 'dockOpen && !paletteOpen',
       keybindings: [{ key: 'Escape' }],
       action: () => {
-        panelStore.value.open = false
+        sessionStore.value.open = false
         selectedId.value = null
       },
     },
@@ -501,12 +530,27 @@ export async function createDocksContext(
     }
   })
 
+  // One-shot boot route (see `DocksPanelContext.consumeBootRoute`): the persisted
+  // address-bar URL is handed back to exactly the iframe dock that was selected
+  // before the reload, once.
+  let bootRoute: string | null = restoreIntent.selectedId != null ? restoreIntent.route : null
+  const consumeBootRoute = (id: string): string | null => {
+    if (bootRoute != null && id === restoreIntent.selectedId) {
+      const route = bootRoute
+      bootRoute = null
+      return route
+    }
+    return null
+  }
+
   docksContext = reactive({
     panel: {
       store: panelStore,
+      session: sessionStore,
       isDragging: false,
       isResizing: false,
       isVertical: computed(() => panelStore.value.position === 'left' || panelStore.value.position === 'right'),
+      consumeBootRoute,
     },
     docks: {
       selectedId,
@@ -552,6 +596,29 @@ export async function createDocksContext(
     return switchEntry(entry.id)
   })
 
+  // Restore the persisted selection once the RPC is trusted. A reload starts
+  // untrusted, and Dock.vue force-closes the panel during that window (and a
+  // revocation clears the selection), so the durable intent captured in
+  // `restoreIntent` is re-applied here after the handshake — re-running the
+  // dock's setup script and re-opening the panel on the dock the developer left
+  // open. `switchEntry` reads `session.route` back through `consumeBootRoute`
+  // when the restored iframe boots.
+  const applyRestore = (): void => {
+    if (restoreIntent.open && restoreIntent.selectedId != null)
+      void switchEntry(restoreIntent.selectedId)
+  }
+  if (rpc.isTrusted) {
+    applyRestore()
+  }
+  else {
+    const off = rpc.events.on('rpc:is-trusted:updated', (isTrusted) => {
+      if (!isTrusted)
+        return
+      off()
+      applyRestore()
+    })
+  }
+
   docksContextByRpc.set(rpc, docksContext)
   return docksContext
 }

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

@@ -1,5 +1,5 @@
 import type { DevframeDockEntry } from '@devframes/hub'
-import type { DevframeRpcClient, DockEntryState, DockEntryStateEvents, DockPanelStorage } from '@devframes/hub/client'
+import type { DevframeRpcClient, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockSessionStorage } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { Ref, ShallowRef } from 'vue'
 import { createEventEmitter } from 'devframe/utils/events'
@@ -13,11 +13,25 @@ export function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage {
     top: 0,
     left: 10,
     position: 'bottom',
-    open: false,
     inactiveTimeout: 3_000,
   }
 }
 
+/**
+ * The per-tab session UI state seed — `open`/`selectedId`/`route`. Persisted to
+ * `sessionStorage` by the embedded and standalone bootstraps so a reload (and
+ * the RPC auth handshake that follows one) restores the panel to the dock and
+ * route the developer left open. Distinct from {@link DEFAULT_DOCK_PANEL_STORE}
+ * (browser-shared `localStorage` geometry), because selection is per-tab.
+ */
+export function DEFAULT_DOCK_SESSION_STORE(): DockSessionStorage {
+  return {
+    open: false,
+    selectedId: null,
+    route: null,
+  }
+}
+
 export function createDockEntryState(
   entry: DevframeDockEntry,
   selected: Ref<DevframeDockEntry | null>,