From 1857a4b254ed9c87cbb3274d8e4140ded434495e Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Mon, 10 Aug 2026 12:44:15 +0200
Subject: [PATCH 1/3] =?UTF-8?q?feat(core):=20session-scoped=20dock=20UI=20?=
 =?UTF-8?q?state=20=E2=80=94=20restore=20open/selected=20dock,=20tab,=20an?=
 =?UTF-8?q?d=20scroll=20across=20reloads?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Splits the dock panel's persisted state in two: config (geometry/position/
mode/inactiveTimeout) stays in localStorage (vite-devtools-dock-state,
cross-tab), while *state* (open, selected dock, active tab, scroll position)
moves to sessionStorage (vite-devtools-dock-session, per-tab) — a full page
reload no longer leaves the panel open-but-empty or resets scroll/tab.

- createDocksContext (context.ts) now backs open + selectedId with a single
  useSessionStorage store, merged with the geometry-only panelStore into the
  same DockPanelStorage shape every dock component already reads/writes
  through context.panel.store — only open's backing store changes.
- A restored selectedId is validated once at boot (once dock entries have
  actually loaded) against being a real selectable leaf — not a group, a
  subTabs anchor, or a stale id — clearing it without routing through
  switchEntry (which would force the panel back open). Past that one-time
  check, switchEntry may legitimately land on a group/anchor id itself (e.g.
  a subTabs anchor with no live member yet) — this doesn't re-litigate that.
- DockEmbedded now mirrors DockStandalone's own auto-select-first-entry
  boot guard, gated on the panel actually being open.
- ViewJsonRender provides its dock entry id for descendants to inject, and
  restores/persists its own scroll position per dock, debounced.
- New useUncontrolledValue composable: session-persisted fallback for a
  json-render element's own uncontrolled value, keyed by the injected dock
  id plus a signature of the element's static shape (works around
  FlatElement.key not being forwarded to registry components). Tabs now
  uses it instead of its hand-rolled ref; Select/TextInput/Switch — until
  now inert while unbound — get it too.

Two behavior changes ship with this, both intentional:
- Opening the docks in one tab no longer auto-opens them in another tab of
  the same page (open moved from localStorage to sessionStorage).
- The very first load after this ships, the panel starts closed even if a
  user's old vite-devtools-dock-state said open: true — that key's open is
  simply never read again.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
 packages/core/src/client/inject/runtime.ts    |  10 +-
 .../components/dock/DockEmbedded.vue          |  17 ++-
 .../components/views/ViewJsonRender.vue       |  24 +++-
 .../json-render/components/Select.ts          |  16 ++-
 .../json-render/components/Switch.ts          |  13 +-
 .../json-render/components/Tabs.ts            |   5 +-
 .../json-render/components/TextInput.ts       |  13 +-
 .../json-render/composables/dock-entry-id.ts  |  10 ++
 .../composables/useUncontrolledValue.ts       |  45 ++++++
 .../state/__tests__/dock-session.test.ts      | 130 ++++++++++++++++++
 .../src/client/webcomponents/state/context.ts | 102 ++++++++++++--
 .../src/client/webcomponents/state/docks.ts   |  18 +++
 .../client/webcomponents.snapshot.d.ts        |   5 +
 .../devtools/client/webcomponents.snapshot.js |   1 +
 14 files changed, 386 insertions(+), 23 deletions(-)
 create mode 100644 packages/core/src/client/webcomponents/json-render/composables/dock-entry-id.ts
 create mode 100644 packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
 create mode 100644 packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts

diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 0a5d2c520..954e7d181 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -60,7 +60,14 @@ async function mountDock(): Promise<void> {
     ],
   })
 
-  const state = useLocalStorage<DockPanelStorage>(
+  // `open` is intentionally not part of this localStorage-persisted geometry
+  // — it's session-scoped (sessionStorage, per-tab) inside `createDocksContext`
+  // instead, so opening the docks in one tab no longer auto-opens them in
+  // another. Two behavior changes ship with this: (a) that cross-tab
+  // auto-open, and (b) after this change deploys, the panel starts closed on
+  // the very first load even for a user whose old `vite-devtools-dock-state`
+  // said `open: true` — the old key's `open` is simply never read again.
+  const state = useLocalStorage<Omit<DockPanelStorage, 'open'>>(
     'vite-devtools-dock-state',
     {
       mode: 'float',
@@ -69,7 +76,6 @@ async function mountDock(): Promise<void> {
       top: 0,
       left: 0,
       position: 'left',
-      open: false,
       inactiveTimeout: 3_000,
     },
     { mergeDefaults: true },
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
index 142773512..f819760ce 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
@@ -2,7 +2,7 @@
 import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { DockLayout } from './dock-layout'
 import { useEventListener } from '@vueuse/core'
-import { onUnmounted } from 'vue'
+import { onUnmounted, watch } from 'vue'
 import { sharedStateToRef } from '../../state/docks'
 import { closeDockPopup, useIsDockPopupOpen } from '../../state/popup'
 import { useIsRpcTrusted } from '../../utils/useIsRpcTrusted'
@@ -21,12 +21,27 @@ const props = defineProps<{
   layout?: Partial<DockLayout>
 }>()
 
+const context = props.context
+
 const isDockPopupOpen = useIsDockPopupOpen()
 const settings = sharedStateToRef(props.context.docks.settings)
 
 // Force float mode when unauthorized, regardless of store setting
 const isRpcTrusted = useIsRpcTrusted(props.context)
 
+// If the panel is open (restored from `vite-devtools-dock-session`, or
+// opened otherwise) but nothing valid is selected — e.g. the persisted
+// `selectedId` didn't resolve to a real entry — fall back to the first
+// available one, mirroring `DockStandalone`'s own boot guard.
+watch(
+  () => context.docks.entries,
+  () => {
+    if (context.panel.store.open)
+      context.docks.selectedId ||= context.docks.entries[0]?.id ?? null
+  },
+  { immediate: true },
+)
+
 // Close the dock when clicking outside of it
 useEventListener(window, 'mousedown', (e: MouseEvent) => {
   if (!settings.value.closeOnOutsideClick)
diff --git a/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue b/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
index 723e93d57..e7fb78930 100644
--- a/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
+++ b/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
@@ -3,7 +3,9 @@ import type { Spec } from '@json-render/core'
 import type { DevToolsViewJsonRender } from '@vitejs/devtools-kit'
 import type { DocksContext } from '@vitejs/devtools-kit/client'
 import { JSONUIProvider, Renderer } from '@json-render/vue'
-import { computed, markRaw, onMounted, ref, shallowRef, watch } from 'vue'
+import { useDebounceFn, useSessionStorage } from '@vueuse/core'
+import { computed, markRaw, onMounted, provide, ref, shallowRef, useTemplateRef, watch } from 'vue'
+import { DOCK_ENTRY_ID_KEY } from '../../json-render/composables/dock-entry-id'
 import { devtoolsRegistry, UnsupportedComponent } from '../../json-render/registry'
 
 const props = defineProps<{
@@ -11,10 +13,28 @@ const props = defineProps<{
   entry: DevToolsViewJsonRender
 }>()
 
+// Descendants (e.g. `useUncontrolledValue`) `inject()` this to scope
+// session-persisted state to "this dock" — the entry's own id, stable for
+// this component instance's lifetime (`ViewEntry` re-keys on entry change).
+provide(DOCK_ENTRY_ID_KEY, props.entry.id)
+
 const spec = shallowRef<Spec | null>(null)
 const isLoading = ref(true)
 const error = ref<string | null>(null)
 
+// Restores/persists the scroll position of this dock's own view, per tab,
+// across a reload — keyed by the dock entry id so switching docks doesn't
+// bleed one dock's scroll into another's.
+const scrollContainer = useTemplateRef<HTMLElement>('scrollContainer')
+const scrollTop = useSessionStorage(`vite-devtools-scroll:${props.entry.id}`, 0)
+onMounted(() => {
+  if (scrollContainer.value)
+    scrollContainer.value.scrollTop = scrollTop.value
+})
+const persistScrollTop = useDebounceFn(() => {
+  scrollTop.value = scrollContainer.value?.scrollTop ?? 0
+}, 200)
+
 // Resolve spec from entry.ui._stateKey
 async function loadSpec() {
   try {
@@ -87,7 +107,7 @@ watch(() => props.entry.ui?._stateKey, loadSpec)
 </script>
 
 <template>
-  <div class="vite-devtools-view-json-render w-full h-full overflow-auto" style="padding: 16px; scrollbar-gutter: stable;">
+  <div ref="scrollContainer" class="vite-devtools-view-json-render w-full h-full overflow-auto" style="padding: 16px; scrollbar-gutter: stable;" @scroll="persistScrollTop">
     <div v-if="isLoading" style="display: flex; align-items: center; justify-content: center; height: 100%; opacity: 0.5; font-size: 13px;">
       Loading...
     </div>
diff --git a/packages/core/src/client/webcomponents/json-render/components/Select.ts b/packages/core/src/client/webcomponents/json-render/components/Select.ts
index ea74d1e85..f6abc822a 100644
--- a/packages/core/src/client/webcomponents/json-render/components/Select.ts
+++ b/packages/core/src/client/webcomponents/json-render/components/Select.ts
@@ -2,6 +2,7 @@ import { useBoundProp } from '@json-render/vue'
 import { defineComponent, h, ref, useId, useTemplateRef, watch } from 'vue'
 import DockIcon from '../../components/dock/DockIcon.vue'
 import FloatingPopover from '../../components/floating/FloatingPopover'
+import { useUncontrolledValue } from '../composables/useUncontrolledValue'
 import { bg, borderInput, borderSolid, surfaceSubtle } from './tokens'
 import { registryProps } from './types'
 
@@ -42,6 +43,10 @@ export const Select = defineComponent({
     const activeIndex = ref(0)
     const listboxId = useId()
 
+    /** Local, session-persisted fallback for when `value` has no `$bindState` binding — `useBoundProp`'s setter is a no-op without one. */
+    const uncontrolledValue = useUncontrolledValue(ctx, 'value', ctx.element.props.value)
+    const controlled = ctx.bindings?.value != null
+
     const close = (options: { refocus?: boolean } = {}) => {
       open.value = false
       if (options.refocus)
@@ -57,14 +62,21 @@ export const Select = defineComponent({
         return
       query.value = ''
       const options = (ctx.element.props.options ?? []).map(normalizeOption)
-      const index = options.findIndex(option => option.value === ctx.element.props.value)
+      const currentValue = controlled ? ctx.element.props.value : uncontrolledValue.value
+      const index = options.findIndex(option => option.value === currentValue)
       activeIndex.value = index >= 0 ? index : 0
     })
 
     return () => {
       const { placeholder, label, disabled, searchable } = ctx.element.props
       const options = (ctx.element.props.options ?? []).map(normalizeOption)
-      const [value, setValue] = useBoundProp<string>(ctx.element.props.value, ctx.bindings?.value)
+      const [boundValue, setBoundValue] = useBoundProp<string>(ctx.element.props.value, ctx.bindings?.value)
+      const value = controlled ? boundValue : uncontrolledValue.value
+      const setValue = (next: string) => {
+        if (controlled)
+          setBoundValue(next)
+        else uncontrolledValue.value = next
+      }
       const change = ctx.on('change')
 
       const filtered = searchable && query.value
diff --git a/packages/core/src/client/webcomponents/json-render/components/Switch.ts b/packages/core/src/client/webcomponents/json-render/components/Switch.ts
index 177e1ecf1..d733b5ff0 100644
--- a/packages/core/src/client/webcomponents/json-render/components/Switch.ts
+++ b/packages/core/src/client/webcomponents/json-render/components/Switch.ts
@@ -1,5 +1,6 @@
 import { useBoundProp } from '@json-render/vue'
 import { defineComponent, h } from 'vue'
+import { useUncontrolledValue } from '../composables/useUncontrolledValue'
 import { primary, surfaceSubtle } from './tokens'
 import { registryProps } from './types'
 
@@ -14,9 +15,19 @@ export const Switch = defineComponent({
   name: 'JrSwitch',
   props: registryProps<'Switch', SwitchProps>(),
   setup(ctx) {
+    /** Local, session-persisted fallback for when `value` has no `$bindState` binding — `useBoundProp`'s setter is a no-op without one. */
+    const uncontrolledValue = useUncontrolledValue(ctx, 'value', ctx.element.props.value)
+    const controlled = ctx.bindings?.value != null
+
     return () => {
       const { label, disabled } = ctx.element.props
-      const [value, setValue] = useBoundProp<boolean>(ctx.element.props.value, ctx.bindings?.value)
+      const [boundValue, setBoundValue] = useBoundProp<boolean>(ctx.element.props.value, ctx.bindings?.value)
+      const value = controlled ? boundValue : uncontrolledValue.value
+      const setValue = (next: boolean) => {
+        if (controlled)
+          setBoundValue(next)
+        else uncontrolledValue.value = next
+      }
       const change = ctx.on('change')
       const checked = !!value
 
diff --git a/packages/core/src/client/webcomponents/json-render/components/Tabs.ts b/packages/core/src/client/webcomponents/json-render/components/Tabs.ts
index f3145325e..10dbecc82 100644
--- a/packages/core/src/client/webcomponents/json-render/components/Tabs.ts
+++ b/packages/core/src/client/webcomponents/json-render/components/Tabs.ts
@@ -1,6 +1,7 @@
 import { useBoundProp } from '@json-render/vue'
 import { defineComponent, h, ref, watchEffect } from 'vue'
 import { getIconifySvg } from '../../utils/iconify'
+import { useUncontrolledValue } from '../composables/useUncontrolledValue'
 import { colors, primary, surfaceSubtle } from './tokens'
 import { registryProps } from './types'
 
@@ -26,8 +27,8 @@ export const Tabs = defineComponent({
   name: 'JrTabs',
   props: registryProps<'Tabs', TabsProps>(),
   setup(ctx, { slots }) {
-    /** Local fallback for when `value` has no `$bindState` binding — `useBoundProp`'s setter is a no-op without one. */
-    const uncontrolledValue = ref<string | undefined>(ctx.element.props.defaultValue ?? ctx.element.props.tabs?.[0]?.value)
+    /** Local, session-persisted fallback for when `value` has no `$bindState` binding — `useBoundProp`'s setter is a no-op without one. */
+    const uncontrolledValue = useUncontrolledValue(ctx, 'value', ctx.element.props.defaultValue ?? ctx.element.props.tabs?.[0]?.value)
 
     /** Icon SVGs keyed by name, resolved like `Icon.ts` — one tab's icon changing shouldn't refetch the others. */
     const iconSvgs = ref<Record<string, string>>({})
diff --git a/packages/core/src/client/webcomponents/json-render/components/TextInput.ts b/packages/core/src/client/webcomponents/json-render/components/TextInput.ts
index a56dfcd2c..f2d1b0eed 100644
--- a/packages/core/src/client/webcomponents/json-render/components/TextInput.ts
+++ b/packages/core/src/client/webcomponents/json-render/components/TextInput.ts
@@ -1,6 +1,7 @@
 import { useBoundProp } from '@json-render/vue'
 import { defineComponent, h } from 'vue'
 import DockIcon from '../../components/dock/DockIcon.vue'
+import { useUncontrolledValue } from '../composables/useUncontrolledValue'
 import { borderInput, borderSolid } from './tokens'
 import { registryProps } from './types'
 
@@ -19,9 +20,19 @@ export const TextInput = defineComponent({
   name: 'JrTextInput',
   props: registryProps<'TextInput', TextInputProps>(),
   setup(ctx) {
+    /** Local, session-persisted fallback for when `value` has no `$bindState` binding — `useBoundProp`'s setter is a no-op without one. */
+    const uncontrolledValue = useUncontrolledValue(ctx, 'value', ctx.element.props.value)
+    const controlled = ctx.bindings?.value != null
+
     return () => {
       const { placeholder, label, type = 'text', disabled, loading } = ctx.element.props
-      const [value, setValue] = useBoundProp<string>(ctx.element.props.value, ctx.bindings?.value)
+      const [boundValue, setBoundValue] = useBoundProp<string>(ctx.element.props.value, ctx.bindings?.value)
+      const value = controlled ? boundValue : uncontrolledValue.value
+      const setValue = (next: string) => {
+        if (controlled)
+          setBoundValue(next)
+        else uncontrolledValue.value = next
+      }
       const change = ctx.on('change')
 
       const input = h('input', {
diff --git a/packages/core/src/client/webcomponents/json-render/composables/dock-entry-id.ts b/packages/core/src/client/webcomponents/json-render/composables/dock-entry-id.ts
new file mode 100644
index 000000000..03d3f002d
--- /dev/null
+++ b/packages/core/src/client/webcomponents/json-render/composables/dock-entry-id.ts
@@ -0,0 +1,10 @@
+import type { InjectionKey } from 'vue'
+
+/**
+ * Injection key for the current dock entry's id. `ViewJsonRender.vue`
+ * `provide()`s it once per dock; any json-render component or composable that
+ * needs an identity scoped to "this dock" — e.g. {@link useUncontrolledValue}'s
+ * session-persistence key, or a per-dock scroll position — `inject()`s it
+ * instead of threading the id through every registry component's props.
+ */
+export const DOCK_ENTRY_ID_KEY: InjectionKey<string | undefined> = Symbol('vite-devtools:dock-entry-id')
diff --git a/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts b/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
new file mode 100644
index 000000000..528a53b48
--- /dev/null
+++ b/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
@@ -0,0 +1,45 @@
+import type { Ref } from 'vue'
+import type { RegistryComponentProps } from '../components/types'
+import { useSessionStorage } from '@vueuse/core'
+import { inject } from 'vue'
+import { DOCK_ENTRY_ID_KEY } from './dock-entry-id'
+
+/**
+ * Session-persisted fallback for a json-render element's own *uncontrolled*
+ * value — the local state a `Tabs`/`Select`/`TextInput`/`Switch` falls back
+ * to while its `value` prop has no `$bindState` binding. Never touches a
+ * genuinely controlled (bound) value — callers keep using `useBoundProp` for
+ * that side and only read from this composable when unbound, exactly as
+ * `Tabs.ts` already split `controlled`/`uncontrolledValue` before this existed.
+ *
+ * Persistence is on by default (not opt-in per element) — just calling this
+ * instead of a plain `ref(default)` gets you a value that survives a reload
+ * within the same tab.
+ *
+ * ### Stable key
+ * `UIElement` (what registry components actually receive) carries no id of
+ * its own — identity lives on the sibling `FlatElement.key`, which
+ * `@json-render/vue`'s `ElementRenderer` does not forward into the
+ * component's props (it's only used internally for Vue's own `:key` and a
+ * devtools-only debug attribute). Absent that, this derives a stable-enough
+ * key from the current dock's id (`provide`d by `ViewJsonRender.vue`, read
+ * via {@link DOCK_ENTRY_ID_KEY}) plus a signature of the element's own static
+ * shape — its `props` minus the bound prop itself (e.g. `Tabs`' own `tabs`
+ * list, `Select`'s own `options`). If that shape changes, the derived key
+ * changes with it and persistence naturally falls back to `defaultValue`
+ * instead of restoring a stale value for a different element — that's
+ * intended, not a bug to fix.
+ */
+export function useUncontrolledValue<Type extends string, Props extends Record<string, any>, Prop extends keyof Props>(
+  ctx: RegistryComponentProps<Type, Props>,
+  prop: Prop,
+  defaultValue: Props[Prop],
+): Ref<Props[Prop]> {
+  const dockEntryId = inject(DOCK_ENTRY_ID_KEY, undefined)
+
+  const staticShape: Record<string, unknown> = { ...ctx.element.props }
+  delete staticShape[prop as string]
+
+  const key = `vite-devtools-uncontrolled:${dockEntryId ?? '~'}:${ctx.element.type}:${JSON.stringify(staticShape)}`
+  return useSessionStorage<Props[Prop]>(key, defaultValue)
+}
diff --git a/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
new file mode 100644
index 000000000..1185524da
--- /dev/null
+++ b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
@@ -0,0 +1,130 @@
+import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
+import type { DevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import type { Ref } from 'vue'
+import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
+import { createSharedState } from 'devframe/utils/shared-state'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ref } from 'vue'
+import { createDocksContext } from '../context'
+
+// Stands in for the real `useSessionStorage` (browser `sessionStorage`,
+// unavailable in this Node test environment) with an in-memory ref keyed the
+// same way, so tests can pre-seed "what a reload restored" and assert what
+// `createDocksContext` writes back — without touching real browser storage.
+const mocks = vi.hoisted(() => ({
+  sessionStores: new Map<string, Ref<any>>(),
+}))
+
+vi.mock('@vueuse/core', async importOriginal => ({
+  ...(await importOriginal<typeof import('@vueuse/core')>()),
+  useSessionStorage: vi.fn((key: string, defaults: unknown) => {
+    if (!mocks.sessionStores.has(key))
+      mocks.sessionStores.set(key, ref(defaults))
+    return mocks.sessionStores.get(key)
+  }),
+}))
+
+function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
+  const docksState = createSharedState({ initialValue: entries, enablePatches: false })
+  const settingsState = createSharedState({ initialValue: DEFAULT_STATE_USER_SETTINGS(), enablePatches: false })
+  const commandsState = createSharedState({ initialValue: [] as any[], enablePatches: false })
+
+  return {
+    client: { register: () => () => {} },
+    sharedState: {
+      get: async (key: string) => {
+        if (key === 'devframe:docks')
+          return docksState as any
+        if (key === 'devframe:user-settings')
+          return settingsState as any
+        if (key === 'devframe:commands')
+          return commandsState as any
+        throw new Error(`Unexpected shared state key: ${key}`)
+      },
+    },
+  } as unknown as DevToolsRpcClient
+}
+
+function iframe(id: string, extra: Partial<DevToolsDockEntry> = {}): DevToolsDockEntry {
+  return { id, type: 'iframe', url: '/', title: id, icon: 'i', ...extra } as DevToolsDockEntry
+}
+
+function group(id: string): DevToolsDockEntry {
+  return { id, type: 'group', title: id, icon: 'i' } as DevToolsDockEntry
+}
+
+function seedSession(selectedId: string | null, open = true) {
+  mocks.sessionStores.set('vite-devtools-dock-session', ref({ open, selectedId }))
+}
+
+describe('session-scoped dock state', () => {
+  afterEach(() => {
+    mocks.sessionStores.clear()
+  })
+
+  it('keeps a restored selectedId that resolves to a real leaf entry', async () => {
+    seedSession('a')
+    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]))
+
+    expect(context.docks.selectedId).toBe('a')
+    expect(context.panel.store.open).toBe(true)
+  })
+
+  it('keeps a restored selectedId of the ~client-auth-notice pseudo-entry', async () => {
+    seedSession('~client-auth-notice')
+    const context = await createDocksContext('embedded', createMockRpc([]))
+
+    expect(context.docks.selectedId).toBe('~client-auth-notice')
+  })
+
+  it('clears a restored selectedId pointing at a group (not a selectable leaf)', async () => {
+    seedSession('nuxt-group')
+    const context = await createDocksContext('embedded', createMockRpc([group('nuxt-group')]))
+
+    expect(context.docks.selectedId).toBeNull()
+  })
+
+  it('clears a restored selectedId pointing at a subTabs anchor (not a selectable leaf)', async () => {
+    seedSession('nuxt')
+    const context = await createDocksContext('embedded', createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]))
+
+    expect(context.docks.selectedId).toBeNull()
+  })
+
+  it('clears a restored selectedId that no longer resolves to any entry, without forcing the panel open', async () => {
+    seedSession('gone', false)
+    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]))
+
+    expect(context.docks.selectedId).toBeNull()
+    // Clearing an invalid restored id must not route through `switchEntry`
+    // (which would force `open = true`) — the panel stays exactly as restored.
+    expect(context.panel.store.open).toBe(false)
+  })
+
+  it('does not clear an id `switchEntry` itself legitimately selects later (a subTabs anchor with no live member yet)', async () => {
+    const context = await createDocksContext('embedded', createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]))
+
+    await context.docks.switchEntry('nuxt')
+
+    expect(context.docks.selectedId).toBe('nuxt')
+  })
+
+  it('routes panel.store.open through the session store, not the geometry ref passed in', async () => {
+    const geometry = ref({ mode: 'float' as const, width: 80, height: 80, top: 0, left: 0, position: 'left' as const, inactiveTimeout: 3_000 })
+    const context = await createDocksContext('embedded', createMockRpc([]), geometry)
+
+    context.panel.store.open = true
+
+    expect(context.panel.store.open).toBe(true)
+    expect(geometry.value).not.toHaveProperty('open')
+  })
+
+  it('still routes panel.store geometry fields (e.g. mode) through the passed-in geometry ref', async () => {
+    const geometry = ref({ mode: 'float' as const, width: 80, height: 80, top: 0, left: 0, position: 'left' as const, inactiveTimeout: 3_000 })
+    const context = await createDocksContext('embedded', createMockRpc([]), geometry)
+
+    context.panel.store.mode = 'edge'
+
+    expect(geometry.value.mode).toBe('edge')
+  })
+})
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index 52060b2c9..983d5e80d 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -4,14 +4,16 @@ import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
 import type { DevToolsDocksUserSettings } from './dock-settings'
+import type { DockSessionStorage } from './docks'
 import { attachDevToolsFrameNav } from '@vitejs/devtools-kit/client'
 import { DEFAULT_STATE_USER_SETTINGS, DEVTOOLS_MOUNT_PATH } from '@vitejs/devtools-kit/constants'
+import { useSessionStorage } from '@vueuse/core'
 import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vue'
 import { DEVTOOLS_HIDE_EVENT, DEVTOOLS_MODE_FILENAME } from '../../../constants'
 import { BUILTIN_ENTRIES } from '../constants'
 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 { createDockRenderers } from './renderers'
@@ -21,7 +23,7 @@ const docksContextByRpc = new WeakMap<DevToolsRpcClient, DocksContext>()
 export async function createDocksContext(
   clientType: 'embedded' | 'standalone',
   rpc: DevToolsRpcClient,
-  panelStore?: Ref<DockPanelStorage>,
+  panelStore?: Ref<Omit<DockPanelStorage, 'open'>>,
 ): Promise<DocksContext> {
   if (docksContextByRpc.has(rpc)) {
     return docksContextByRpc.get(rpc)!
@@ -52,13 +54,64 @@ export async function createDocksContext(
     return merged
   })
 
-  const selectedId = ref<string | null>(null)
+  // Session-scoped dock UI state (`vite-devtools-dock-session`, sessionStorage)
+  // — which dock is open and selected, restored on a reload of this same tab.
+  // Unlike the panel's geometry/mode (`vite-devtools-dock-state`,
+  // localStorage), this deliberately doesn't sync across tabs: opening the
+  // docks in one tab no longer auto-opens them in another.
+  const sessionStore = useSessionStorage<DockSessionStorage>(
+    'vite-devtools-dock-session',
+    DEFAULT_DOCK_SESSION_STORE(),
+    { mergeDefaults: true },
+  )
+
+  const selectedId = computed<string | null>({
+    get: () => sessionStore.value.selectedId,
+    set: (value) => { sessionStore.value.selectedId = value },
+  })
   const selected = computed(
     () => entries.value.find(entry => entry.id === selectedId.value)
       ?? BUILTIN_ENTRIES.find(entry => entry.id === selectedId.value)
       ?? null,
   )
 
+  // A `selectedId` restored from `sessionStore` may point at an entry that
+  // isn't directly selectable — a group (no view of its own) or a `subTabs`
+  // anchor (owns a shared frame, not a view). `switchEntry` resolves those on
+  // click, but restoring on boot must not route through it (it would force
+  // `panel.value.open = true`, reopening a panel the user closed) — so
+  // validate the restored id directly instead, once. `entries` starts empty
+  // and fills in async via `devframe:docks`, so an empty list here just means
+  // "not loaded yet"; wait for it rather than clearing a legitimate restored
+  // selection. This is boot-only: past this point `switchEntry` itself may
+  // legitimately land `selectedId` on a group/anchor id (e.g. a `subTabs`
+  // anchor with no live member to redirect to yet) — that's not something to
+  // keep correcting.
+  const isSelectableEntry = (id: string): boolean => {
+    if (id === '~client-auth-notice')
+      return true
+    const entry = entries.value.find(e => e.id === id)
+    if (!entry)
+      return false
+    if (entry.type === 'group')
+      return false
+    if (entry.type === 'iframe' && entry.subTabs)
+      return false
+    return true
+  }
+  let bootRestoreChecked = false
+  watch(
+    entries,
+    (list) => {
+      if (bootRestoreChecked || list.length === 0)
+        return
+      bootRestoreChecked = true
+      if (selectedId.value != null && !isSelectableEntry(selectedId.value))
+        selectedId.value = null
+    },
+    { immediate: true },
+  )
+
   const dockEntryStateMap: Map<string, DockEntryState> = reactive(new Map())
   watchEffect(() => {
     for (const entry of entries.value) {
@@ -111,6 +164,31 @@ export async function createDocksContext(
   }
 
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
+
+  // Merges the geometry-only `panelStore` (mode/size/position, localStorage)
+  // with the session store's `open` into the single `DockPanelStorage` shape
+  // every dock component already reads and writes through
+  // `context.panel.store` (`Dock.vue`, `DockEdge.vue`, `DockEmbedded.vue`,
+  // ...) — only `open`'s backing store moves to sessionStorage, its
+  // read/write semantics are unchanged.
+  const panel: Ref<DockPanelStorage> = ref(reactive({
+    get mode() { return panelStore.value.mode },
+    set mode(value: DockPanelStorage['mode']) { panelStore.value.mode = value },
+    get width() { return panelStore.value.width },
+    set width(value: number) { panelStore.value.width = value },
+    get height() { return panelStore.value.height },
+    set height(value: number) { panelStore.value.height = value },
+    get top() { return panelStore.value.top },
+    set top(value: number) { panelStore.value.top = value },
+    get left() { return panelStore.value.left },
+    set left(value: number) { panelStore.value.left = value },
+    get position() { return panelStore.value.position },
+    set position(value: DockPanelStorage['position']) { panelStore.value.position = value },
+    get inactiveTimeout() { return panelStore.value.inactiveTimeout },
+    set inactiveTimeout(value: number) { panelStore.value.inactiveTimeout = value },
+    get open() { return sessionStore.value.open },
+    set open(value: boolean) { sessionStore.value.open = value },
+  }))
   let docksContext: DocksContext
 
   let _settingsStorePromise: Promise<SharedState<DevToolsDocksUserSettings>> | undefined
@@ -134,7 +212,7 @@ export async function createDocksContext(
   const isDockPopupOpen = useIsDockPopupOpen()
   const getWhenContext = (): WhenContext => ({
     clientType,
-    dockOpen: panelStore.value.open,
+    dockOpen: panel.value.open,
     paletteOpen: commandsContext?.paletteOpen ?? false,
     dockSelectedId: selectedId.value ?? '',
     popupOpen: isDockPopupOpen.value,
@@ -153,12 +231,12 @@ export async function createDocksContext(
   const switchEntry = async (id: string | null = null) => {
     if (id == null) {
       selectedId.value = null
-      panelStore.value.open = false
+      panel.value.open = false
       return true
     }
     if (id === '~client-auth-notice') {
       selectedId.value = id
-      panelStore.value.open = true
+      panel.value.open = true
       return true
     }
     const entry = entries.value.find(e => e.id === id)
@@ -225,7 +303,7 @@ export async function createDocksContext(
       frameNavCurrentMember.set(entry.frameId, entry.id)
 
     selectedId.value = entry.id
-    panelStore.value.open = true
+    panel.value.open = true
     return true
   }
 
@@ -361,7 +439,7 @@ export async function createDocksContext(
       when: 'dockOpen && !paletteOpen',
       keybindings: [{ key: 'Escape' }],
       action: () => {
-        panelStore.value.open = false
+        panel.value.open = false
         selectedId.value = null
       },
     },
@@ -417,7 +495,7 @@ export async function createDocksContext(
           // own `when` and does not inherit the parent's.
           when: '!popupOpen',
           action: () => {
-            panelStore.value.mode = 'float'
+            panel.value.mode = 'float'
           },
         },
         {
@@ -427,7 +505,7 @@ export async function createDocksContext(
           icon: 'ph:square-half-bottom-duotone',
           when: '!popupOpen',
           action: () => {
-            panelStore.value.mode = 'edge'
+            panel.value.mode = 'edge'
           },
         },
       ],
@@ -489,10 +567,10 @@ export async function createDocksContext(
 
   docksContext = reactive({
     panel: {
-      store: panelStore,
+      store: panel,
       isDragging: false,
       isResizing: false,
-      isVertical: computed(() => panelStore.value.position === 'left' || panelStore.value.position === 'right'),
+      isVertical: computed(() => panel.value.position === 'left' || panel.value.position === 'right'),
     },
     docks: {
       selectedId,
diff --git a/packages/core/src/client/webcomponents/state/docks.ts b/packages/core/src/client/webcomponents/state/docks.ts
index b6dfa2f5a..244dee7ca 100644
--- a/packages/core/src/client/webcomponents/state/docks.ts
+++ b/packages/core/src/client/webcomponents/state/docks.ts
@@ -18,6 +18,24 @@ export function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage {
   }
 }
 
+/**
+ * Session-scoped dock UI state — which dock/tab is open. Unlike
+ * {@link DockPanelStorage} (`vite-devtools-dock-state`, localStorage,
+ * cross-tab geometry/mode), this is per-tab (sessionStorage): a reload
+ * restores it, a new tab starts fresh.
+ */
+export interface DockSessionStorage {
+  open: boolean
+  selectedId: string | null
+}
+
+export function DEFAULT_DOCK_SESSION_STORE(): DockSessionStorage {
+  return {
+    open: false,
+    selectedId: null,
+  }
+}
+
 export function createDockEntryState(
   entry: DevToolsDockEntry,
   selected: Ref<DevToolsDockEntry | null>,
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
index a26256ea0..87dfc758d 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
@@ -41,6 +41,10 @@ export interface DataTableProps {
 export interface DividerProps {
   label?: string;
 }
+export interface DockSessionStorage {
+  open: boolean;
+  selectedId: string | null;
+}
 export interface IconProps {
   name?: string;
   size?: number;
@@ -136,6 +140,7 @@ export interface TreeProps {
 // #region Functions
 export declare function createDockEntryState(_: DevToolsDockEntry, _: Ref<DevToolsDockEntry | null>): DockEntryState;
 export declare function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage;
+export declare function DEFAULT_DOCK_SESSION_STORE(): DockSessionStorage;
 export declare function sharedStateToRef<T>(_: SharedState<T>): ShallowRef<T>;
 export declare function useDocksEntries(_: DevToolsRpcClient): Promise<Ref<DevToolsDockEntry[]>>;
 // #endregion
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
index f07f79d53..d0b13b10e 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
@@ -8,6 +8,7 @@ export var DockEmbedded /* const */
 // #region Other
 export { createDockEntryState }
 export { DEFAULT_DOCK_PANEL_STORE }
+export { DEFAULT_DOCK_SESSION_STORE }
 export { DockStandalone }
 export { sharedStateToRef }
 export { useDocksEntries }

From be75233bef52075034a54e2cf578a9ff3d36304c Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Mon, 10 Aug 2026 16:42:03 +0200
Subject: [PATCH 2/3] refactor(core): keep dock session state in localStorage
 only, no sessionStorage split

Folds selectedId into the existing localStorage-backed panelStore instead of a
separate sessionStorage-scoped store: it's a browser-local singleton exactly
like open/mode/position, so it belongs in the same object and gets mirrored
for free once that object is shared over RPC. Only the active spec tab and
scroll position stay genuinely per-tab (still sessionStorage, via each
ViewJsonRender's own independent key) since nothing server-side needs them
and syncing them across tabs would be unwanted UX.
---
 packages/core/src/client/inject/runtime.ts    | 19 ++--
 .../state/__tests__/dock-session.test.ts      | 92 ++++++++++---------
 .../src/client/webcomponents/state/context.ts | 76 +++++----------
 .../src/client/webcomponents/state/docks.ts   | 30 +++---
 .../webcomponents/stories/mock-context.ts     |  7 +-
 .../client/webcomponents.snapshot.d.ts        | 10 +-
 .../devtools/client/webcomponents.snapshot.js |  1 -
 7 files changed, 100 insertions(+), 135 deletions(-)

diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 954e7d181..078250bce 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -1,7 +1,7 @@
 /// <reference types="vite/client" />
 /// <reference lib="dom" />
 
-import type { DockPanelStorage } from '@vitejs/devtools-kit/client'
+import type { DevToolsDockPanelStorage } from '../webcomponents/state/docks'
 import { CLIENT_CONTEXT_KEY, getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
 import { DEVTOOLS_MOUNT_PATH } from '@vitejs/devtools-kit/constants'
 import { useLocalStorage } from '@vueuse/core'
@@ -60,14 +60,13 @@ async function mountDock(): Promise<void> {
     ],
   })
 
-  // `open` is intentionally not part of this localStorage-persisted geometry
-  // — it's session-scoped (sessionStorage, per-tab) inside `createDocksContext`
-  // instead, so opening the docks in one tab no longer auto-opens them in
-  // another. Two behavior changes ship with this: (a) that cross-tab
-  // auto-open, and (b) after this change deploys, the panel starts closed on
-  // the very first load even for a user whose old `vite-devtools-dock-state`
-  // said `open: true` — the old key's `open` is simply never read again.
-  const state = useLocalStorage<Omit<DockPanelStorage, 'open'>>(
+  // `open` and (new) `selectedId` both live in this same localStorage value,
+  // alongside geometry/mode — cross-tab, like everything else already in it.
+  // A dock left open/selected in one tab shows the same way in the next; see
+  // `DevToolsDockPanelStorage`. (Defaults here are this injected client's
+  // own, deliberately different from `DEFAULT_DOCK_PANEL_STORE()`'s
+  // fallback used elsewhere — not a shared literal.)
+  const state = useLocalStorage<DevToolsDockPanelStorage>(
     'vite-devtools-dock-state',
     {
       mode: 'float',
@@ -76,7 +75,9 @@ async function mountDock(): Promise<void> {
       top: 0,
       left: 0,
       position: 'left',
+      open: false,
       inactiveTimeout: 3_000,
+      selectedId: null,
     },
     { mergeDefaults: true },
   )
diff --git a/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
index 1185524da..8fcf0fac7 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
@@ -1,28 +1,13 @@
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
 import type { DevToolsRpcClient } from '@vitejs/devtools-kit/client'
 import type { Ref } from 'vue'
+import type { DevToolsDockPanelStorage } from '../docks'
 import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
 import { createSharedState } from 'devframe/utils/shared-state'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { ref } from 'vue'
 import { createDocksContext } from '../context'
-
-// Stands in for the real `useSessionStorage` (browser `sessionStorage`,
-// unavailable in this Node test environment) with an in-memory ref keyed the
-// same way, so tests can pre-seed "what a reload restored" and assert what
-// `createDocksContext` writes back — without touching real browser storage.
-const mocks = vi.hoisted(() => ({
-  sessionStores: new Map<string, Ref<any>>(),
-}))
-
-vi.mock('@vueuse/core', async importOriginal => ({
-  ...(await importOriginal<typeof import('@vueuse/core')>()),
-  useSessionStorage: vi.fn((key: string, defaults: unknown) => {
-    if (!mocks.sessionStores.has(key))
-      mocks.sessionStores.set(key, ref(defaults))
-    return mocks.sessionStores.get(key)
-  }),
-}))
+import { DEFAULT_DOCK_PANEL_STORE } from '../docks'
 
 function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
   const docksState = createSharedState({ initialValue: entries, enablePatches: false })
@@ -53,47 +38,55 @@ function group(id: string): DevToolsDockEntry {
   return { id, type: 'group', title: id, icon: 'i' } as DevToolsDockEntry
 }
 
-function seedSession(selectedId: string | null, open = true) {
-  mocks.sessionStores.set('vite-devtools-dock-session', ref({ open, selectedId }))
+// `open`/`selectedId` are now plain fields on the same `panelStore` ref
+// `createDocksContext` is handed (`vite-devtools-dock-state`, localStorage in
+// the real client) — no separate session store to mock, seed the ref directly.
+function panelStore(selectedId: string | null, open = true): Ref<DevToolsDockPanelStorage> {
+  return ref({ ...DEFAULT_DOCK_PANEL_STORE(), open, selectedId })
 }
 
-describe('session-scoped dock state', () => {
-  afterEach(() => {
-    mocks.sessionStores.clear()
-  })
-
+describe('restored dock panel state (selectedId/open on the same panelStore ref)', () => {
   it('keeps a restored selectedId that resolves to a real leaf entry', async () => {
-    seedSession('a')
-    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]))
+    expect.assertions(2)
+
+    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]), panelStore('a'))
 
     expect(context.docks.selectedId).toBe('a')
     expect(context.panel.store.open).toBe(true)
   })
 
   it('keeps a restored selectedId of the ~client-auth-notice pseudo-entry', async () => {
-    seedSession('~client-auth-notice')
-    const context = await createDocksContext('embedded', createMockRpc([]))
+    expect.assertions(1)
+
+    const context = await createDocksContext('embedded', createMockRpc([]), panelStore('~client-auth-notice'))
 
     expect(context.docks.selectedId).toBe('~client-auth-notice')
   })
 
   it('clears a restored selectedId pointing at a group (not a selectable leaf)', async () => {
-    seedSession('nuxt-group')
-    const context = await createDocksContext('embedded', createMockRpc([group('nuxt-group')]))
+    expect.assertions(1)
+
+    const context = await createDocksContext('embedded', createMockRpc([group('nuxt-group')]), panelStore('nuxt-group'))
 
     expect(context.docks.selectedId).toBeNull()
   })
 
   it('clears a restored selectedId pointing at a subTabs anchor (not a selectable leaf)', async () => {
-    seedSession('nuxt')
-    const context = await createDocksContext('embedded', createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]))
+    expect.assertions(1)
+
+    const context = await createDocksContext(
+      'embedded',
+      createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]),
+      panelStore('nuxt'),
+    )
 
     expect(context.docks.selectedId).toBeNull()
   })
 
   it('clears a restored selectedId that no longer resolves to any entry, without forcing the panel open', async () => {
-    seedSession('gone', false)
-    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]))
+    expect.assertions(2)
+
+    const context = await createDocksContext('embedded', createMockRpc([iframe('a')]), panelStore('gone', false))
 
     expect(context.docks.selectedId).toBeNull()
     // Clearing an invalid restored id must not route through `switchEntry`
@@ -102,29 +95,40 @@ describe('session-scoped dock state', () => {
   })
 
   it('does not clear an id `switchEntry` itself legitimately selects later (a subTabs anchor with no live member yet)', async () => {
-    const context = await createDocksContext('embedded', createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]))
+    expect.assertions(1)
+
+    const context = await createDocksContext(
+      'embedded',
+      createMockRpc([iframe('nuxt', { subTabs: { protocol: 'postmessage' } })]),
+    )
 
     await context.docks.switchEntry('nuxt')
 
     expect(context.docks.selectedId).toBe('nuxt')
   })
 
-  it('routes panel.store.open through the session store, not the geometry ref passed in', async () => {
-    const geometry = ref({ mode: 'float' as const, width: 80, height: 80, top: 0, left: 0, position: 'left' as const, inactiveTimeout: 3_000 })
-    const context = await createDocksContext('embedded', createMockRpc([]), geometry)
+  it('routes selectedId/open through the same panelStore ref passed in, alongside geometry', async () => {
+    expect.assertions(3)
+
+    const store = ref({ ...DEFAULT_DOCK_PANEL_STORE(), mode: 'float' as const })
+    const context = await createDocksContext('embedded', createMockRpc([]), store)
 
     context.panel.store.open = true
+    context.docks.selectedId = null
 
     expect(context.panel.store.open).toBe(true)
-    expect(geometry.value).not.toHaveProperty('open')
+    expect(store.value.open).toBe(true)
+    expect(store.value.mode).toBe('float')
   })
 
-  it('still routes panel.store geometry fields (e.g. mode) through the passed-in geometry ref', async () => {
-    const geometry = ref({ mode: 'float' as const, width: 80, height: 80, top: 0, left: 0, position: 'left' as const, inactiveTimeout: 3_000 })
-    const context = await createDocksContext('embedded', createMockRpc([]), geometry)
+  it('still routes panel.store geometry fields (e.g. mode) through the same ref', async () => {
+    expect.assertions(1)
+
+    const store = ref(DEFAULT_DOCK_PANEL_STORE())
+    const context = await createDocksContext('embedded', createMockRpc([]), store)
 
     context.panel.store.mode = 'edge'
 
-    expect(geometry.value.mode).toBe('edge')
+    expect(store.value.mode).toBe('edge')
   })
 })
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index 983d5e80d..f16528db6 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -1,19 +1,18 @@
 import type { DevToolsClientCommand, DevToolsDockEntry, DevToolsDockUserEntry, DevToolsRpcClientFunctions, DevToolsViewIframe } from '@vitejs/devtools-kit'
-import type { CommandsContext, DevToolsRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DocksContext } from '@vitejs/devtools-kit/client'
+import type { CommandsContext, DevToolsRpcClient, DockClientScriptContext, DockEntryState, DockRegistration, DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
 import type { DevToolsDocksUserSettings } from './dock-settings'
-import type { DockSessionStorage } from './docks'
+import type { DevToolsDockPanelStorage } from './docks'
 import { attachDevToolsFrameNav } from '@vitejs/devtools-kit/client'
 import { DEFAULT_STATE_USER_SETTINGS, DEVTOOLS_MOUNT_PATH } from '@vitejs/devtools-kit/constants'
-import { useSessionStorage } from '@vueuse/core'
 import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vue'
 import { DEVTOOLS_HIDE_EVENT, DEVTOOLS_MODE_FILENAME } from '../../../constants'
 import { BUILTIN_ENTRIES } from '../constants'
 import { createCommandsContext } from './commands'
 import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
-import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE, sharedStateToRef, useDocksEntries } from './docks'
+import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, sharedStateToRef, useDocksEntries } from './docks'
 import { createClientMessagesClient } from './messages-client'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDockPopupOpen } from './popup'
 import { createDockRenderers } from './renderers'
@@ -23,7 +22,7 @@ const docksContextByRpc = new WeakMap<DevToolsRpcClient, DocksContext>()
 export async function createDocksContext(
   clientType: 'embedded' | 'standalone',
   rpc: DevToolsRpcClient,
-  panelStore?: Ref<Omit<DockPanelStorage, 'open'>>,
+  panelStore?: Ref<DevToolsDockPanelStorage>,
 ): Promise<DocksContext> {
   if (docksContextByRpc.has(rpc)) {
     return docksContextByRpc.get(rpc)!
@@ -54,20 +53,15 @@ export async function createDocksContext(
     return merged
   })
 
-  // Session-scoped dock UI state (`vite-devtools-dock-session`, sessionStorage)
-  // — which dock is open and selected, restored on a reload of this same tab.
-  // Unlike the panel's geometry/mode (`vite-devtools-dock-state`,
-  // localStorage), this deliberately doesn't sync across tabs: opening the
-  // docks in one tab no longer auto-opens them in another.
-  const sessionStore = useSessionStorage<DockSessionStorage>(
-    'vite-devtools-dock-session',
-    DEFAULT_DOCK_SESSION_STORE(),
-    { mergeDefaults: true },
-  )
+  panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
 
+  // `open` and `selectedId` both live in `panelStore` (`vite-devtools-dock-state`,
+  // localStorage) alongside geometry/mode — restored across a reload, and,
+  // like everything else already in that value, shared cross-tab (opening the
+  // docks in one tab shows the same way in the next; not per-tab session state).
   const selectedId = computed<string | null>({
-    get: () => sessionStore.value.selectedId,
-    set: (value) => { sessionStore.value.selectedId = value },
+    get: () => panelStore.value.selectedId,
+    set: (value) => { panelStore.value.selectedId = value },
   })
   const selected = computed(
     () => entries.value.find(entry => entry.id === selectedId.value)
@@ -75,11 +69,11 @@ export async function createDocksContext(
       ?? null,
   )
 
-  // A `selectedId` restored from `sessionStore` may point at an entry that
+  // A `selectedId` restored from `panelStore` may point at an entry that
   // isn't directly selectable — a group (no view of its own) or a `subTabs`
   // anchor (owns a shared frame, not a view). `switchEntry` resolves those on
   // click, but restoring on boot must not route through it (it would force
-  // `panel.value.open = true`, reopening a panel the user closed) — so
+  // `panelStore.value.open = true`, reopening a panel the user closed) — so
   // validate the restored id directly instead, once. `entries` starts empty
   // and fills in async via `devframe:docks`, so an empty list here just means
   // "not loaded yet"; wait for it rather than clearing a legitimate restored
@@ -163,32 +157,6 @@ export async function createDocksContext(
     clientDocks.set(entry.id, entry as DevToolsDockEntry)
   }
 
-  panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
-
-  // Merges the geometry-only `panelStore` (mode/size/position, localStorage)
-  // with the session store's `open` into the single `DockPanelStorage` shape
-  // every dock component already reads and writes through
-  // `context.panel.store` (`Dock.vue`, `DockEdge.vue`, `DockEmbedded.vue`,
-  // ...) — only `open`'s backing store moves to sessionStorage, its
-  // read/write semantics are unchanged.
-  const panel: Ref<DockPanelStorage> = ref(reactive({
-    get mode() { return panelStore.value.mode },
-    set mode(value: DockPanelStorage['mode']) { panelStore.value.mode = value },
-    get width() { return panelStore.value.width },
-    set width(value: number) { panelStore.value.width = value },
-    get height() { return panelStore.value.height },
-    set height(value: number) { panelStore.value.height = value },
-    get top() { return panelStore.value.top },
-    set top(value: number) { panelStore.value.top = value },
-    get left() { return panelStore.value.left },
-    set left(value: number) { panelStore.value.left = value },
-    get position() { return panelStore.value.position },
-    set position(value: DockPanelStorage['position']) { panelStore.value.position = value },
-    get inactiveTimeout() { return panelStore.value.inactiveTimeout },
-    set inactiveTimeout(value: number) { panelStore.value.inactiveTimeout = value },
-    get open() { return sessionStore.value.open },
-    set open(value: boolean) { sessionStore.value.open = value },
-  }))
   let docksContext: DocksContext
 
   let _settingsStorePromise: Promise<SharedState<DevToolsDocksUserSettings>> | undefined
@@ -212,7 +180,7 @@ export async function createDocksContext(
   const isDockPopupOpen = useIsDockPopupOpen()
   const getWhenContext = (): WhenContext => ({
     clientType,
-    dockOpen: panel.value.open,
+    dockOpen: panelStore.value.open,
     paletteOpen: commandsContext?.paletteOpen ?? false,
     dockSelectedId: selectedId.value ?? '',
     popupOpen: isDockPopupOpen.value,
@@ -231,12 +199,12 @@ export async function createDocksContext(
   const switchEntry = async (id: string | null = null) => {
     if (id == null) {
       selectedId.value = null
-      panel.value.open = false
+      panelStore.value.open = false
       return true
     }
     if (id === '~client-auth-notice') {
       selectedId.value = id
-      panel.value.open = true
+      panelStore.value.open = true
       return true
     }
     const entry = entries.value.find(e => e.id === id)
@@ -303,7 +271,7 @@ export async function createDocksContext(
       frameNavCurrentMember.set(entry.frameId, entry.id)
 
     selectedId.value = entry.id
-    panel.value.open = true
+    panelStore.value.open = true
     return true
   }
 
@@ -439,7 +407,7 @@ export async function createDocksContext(
       when: 'dockOpen && !paletteOpen',
       keybindings: [{ key: 'Escape' }],
       action: () => {
-        panel.value.open = false
+        panelStore.value.open = false
         selectedId.value = null
       },
     },
@@ -495,7 +463,7 @@ export async function createDocksContext(
           // own `when` and does not inherit the parent's.
           when: '!popupOpen',
           action: () => {
-            panel.value.mode = 'float'
+            panelStore.value.mode = 'float'
           },
         },
         {
@@ -505,7 +473,7 @@ export async function createDocksContext(
           icon: 'ph:square-half-bottom-duotone',
           when: '!popupOpen',
           action: () => {
-            panel.value.mode = 'edge'
+            panelStore.value.mode = 'edge'
           },
         },
       ],
@@ -567,10 +535,10 @@ export async function createDocksContext(
 
   docksContext = reactive({
     panel: {
-      store: panel,
+      store: panelStore,
       isDragging: false,
       isResizing: false,
-      isVertical: computed(() => panel.value.position === 'left' || panel.value.position === 'right'),
+      isVertical: computed(() => panelStore.value.position === 'left' || panelStore.value.position === 'right'),
     },
     docks: {
       selectedId,
diff --git a/packages/core/src/client/webcomponents/state/docks.ts b/packages/core/src/client/webcomponents/state/docks.ts
index 244dee7ca..0c19e2894 100644
--- a/packages/core/src/client/webcomponents/state/docks.ts
+++ b/packages/core/src/client/webcomponents/state/docks.ts
@@ -5,7 +5,18 @@ import type { Ref, ShallowRef } from 'vue'
 import { createEventEmitter } from 'devframe/utils/events'
 import { markRaw, reactive, shallowRef, watch } from 'vue'
 
-export function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage {
+/**
+ * {@link DockPanelStorage} (hub's own type — geometry/mode/`open`) plus
+ * `selectedId`, which the hub has no concept of. Both persist the same way:
+ * one `vite-devtools-dock-state` localStorage value, cross-tab like
+ * everything else in it already is — a dock left open/selected in one tab
+ * shows the same way in the next, exactly as `open` already behaves today.
+ */
+export interface DevToolsDockPanelStorage extends DockPanelStorage {
+  selectedId: string | null
+}
+
+export function DEFAULT_DOCK_PANEL_STORE(): DevToolsDockPanelStorage {
   return {
     mode: 'float',
     width: 80,
@@ -15,23 +26,6 @@ export function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage {
     position: 'bottom',
     open: false,
     inactiveTimeout: 3_000,
-  }
-}
-
-/**
- * Session-scoped dock UI state — which dock/tab is open. Unlike
- * {@link DockPanelStorage} (`vite-devtools-dock-state`, localStorage,
- * cross-tab geometry/mode), this is per-tab (sessionStorage): a reload
- * restores it, a new tab starts fresh.
- */
-export interface DockSessionStorage {
-  open: boolean
-  selectedId: string | null
-}
-
-export function DEFAULT_DOCK_SESSION_STORE(): DockSessionStorage {
-  return {
-    open: false,
     selectedId: null,
   }
 }
diff --git a/packages/core/src/client/webcomponents/stories/mock-context.ts b/packages/core/src/client/webcomponents/stories/mock-context.ts
index ec5c664ad..9947c6aa4 100644
--- a/packages/core/src/client/webcomponents/stories/mock-context.ts
+++ b/packages/core/src/client/webcomponents/stories/mock-context.ts
@@ -1,5 +1,6 @@
 import type { DevToolsDockEntry, DevToolsDocksUserSettings } from '@vitejs/devtools-kit'
-import type { DevToolsRpcClient, DockPanelStorage, DocksContext, RpcClientEvents } from '@vitejs/devtools-kit/client'
+import type { DevToolsRpcClient, DocksContext, RpcClientEvents } from '@vitejs/devtools-kit/client'
+import type { DevToolsDockPanelStorage } from '../state/docks'
 import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
 import { createEventEmitter } from 'devframe/utils/events'
 import { createSharedState } from 'devframe/utils/shared-state'
@@ -24,7 +25,7 @@ export interface CreateMockContextOptions {
   /** Which client shell the context represents. */
   clientType?: 'embedded' | 'standalone'
   /** Overrides merged over the default panel store (mode, position, open, ...). */
-  panel?: Partial<DockPanelStorage>
+  panel?: Partial<DevToolsDockPanelStorage>
   /** Overrides merged over the default user settings (hidden, pinned, order, ...). */
   settings?: Partial<DevToolsDocksUserSettings>
   /** Entry id to pre-select (also opens the panel). */
@@ -113,7 +114,7 @@ export async function createMockDocksContext(
   } = options
 
   const rpc = createMockRpc(entries, settings, isTrusted)
-  const panelStore = ref<DockPanelStorage>({ ...DEFAULT_DOCK_PANEL_STORE(), ...panel })
+  const panelStore = ref<DevToolsDockPanelStorage>({ ...DEFAULT_DOCK_PANEL_STORE(), ...panel })
 
   const context = await createDocksContext(clientType, rpc, panelStore)
 
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
index 87dfc758d..e67513ace 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
@@ -38,13 +38,12 @@ export interface DataTableProps {
   rows?: Record<string, unknown>[];
   height?: number;
 }
+export interface DevToolsDockPanelStorage extends DockPanelStorage {
+  selectedId: string | null;
+}
 export interface DividerProps {
   label?: string;
 }
-export interface DockSessionStorage {
-  open: boolean;
-  selectedId: string | null;
-}
 export interface IconProps {
   name?: string;
   size?: number;
@@ -139,8 +138,7 @@ export interface TreeProps {
 
 // #region Functions
 export declare function createDockEntryState(_: DevToolsDockEntry, _: Ref<DevToolsDockEntry | null>): DockEntryState;
-export declare function DEFAULT_DOCK_PANEL_STORE(): DockPanelStorage;
-export declare function DEFAULT_DOCK_SESSION_STORE(): DockSessionStorage;
+export declare function DEFAULT_DOCK_PANEL_STORE(): DevToolsDockPanelStorage;
 export declare function sharedStateToRef<T>(_: SharedState<T>): ShallowRef<T>;
 export declare function useDocksEntries(_: DevToolsRpcClient): Promise<Ref<DevToolsDockEntry[]>>;
 // #endregion
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
index d0b13b10e..f07f79d53 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.js
@@ -8,7 +8,6 @@ export var DockEmbedded /* const */
 // #region Other
 export { createDockEntryState }
 export { DEFAULT_DOCK_PANEL_STORE }
-export { DEFAULT_DOCK_SESSION_STORE }
 export { DockStandalone }
 export { sharedStateToRef }
 export { useDocksEntries }

From f3733c823f309cb5a935a1290c1bcd4ed0de8b4f Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Mon, 10 Aug 2026 17:11:45 +0200
Subject: [PATCH 3/3] docs(core): trim verbose comments in dock session-restore
 changes

---
 packages/core/src/client/inject/runtime.ts    | 11 +++----
 .../components/dock/DockEmbedded.vue          |  9 +++---
 .../components/views/ViewJsonRender.vue       | 16 ++++++----
 .../composables/useUncontrolledValue.ts       | 31 ++++++-------------
 .../state/__tests__/dock-session.test.ts      | 11 ++++---
 .../src/client/webcomponents/state/context.ts | 29 ++++++++---------
 .../src/client/webcomponents/state/docks.ts   |  7 ++---
 7 files changed, 51 insertions(+), 63 deletions(-)

diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 078250bce..04ee98ad0 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -60,12 +60,11 @@ async function mountDock(): Promise<void> {
     ],
   })
 
-  // `open` and (new) `selectedId` both live in this same localStorage value,
-  // alongside geometry/mode — cross-tab, like everything else already in it.
-  // A dock left open/selected in one tab shows the same way in the next; see
-  // `DevToolsDockPanelStorage`. (Defaults here are this injected client's
-  // own, deliberately different from `DEFAULT_DOCK_PANEL_STORE()`'s
-  // fallback used elsewhere — not a shared literal.)
+  /**
+   * Defaults here are this injected client's own — deliberately different
+   * from `DEFAULT_DOCK_PANEL_STORE()`'s fallback used elsewhere, not a shared
+   * literal. See `DevToolsDockPanelStorage` for what's persisted and why.
+   */
   const state = useLocalStorage<DevToolsDockPanelStorage>(
     'vite-devtools-dock-state',
     {
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
index f819760ce..146051077 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
@@ -29,10 +29,11 @@ const settings = sharedStateToRef(props.context.docks.settings)
 // Force float mode when unauthorized, regardless of store setting
 const isRpcTrusted = useIsRpcTrusted(props.context)
 
-// If the panel is open (restored from `vite-devtools-dock-session`, or
-// opened otherwise) but nothing valid is selected — e.g. the persisted
-// `selectedId` didn't resolve to a real entry — fall back to the first
-// available one, mirroring `DockStandalone`'s own boot guard.
+/**
+ * If the panel is open but nothing valid is selected (e.g. a restored
+ * `selectedId` didn't resolve to a real entry), fall back to the first
+ * available one — mirrors `DockStandalone`'s own boot guard.
+ */
 watch(
   () => context.docks.entries,
   () => {
diff --git a/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue b/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
index e7fb78930..f9350dcf9 100644
--- a/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
+++ b/packages/core/src/client/webcomponents/components/views/ViewJsonRender.vue
@@ -13,18 +13,22 @@ const props = defineProps<{
   entry: DevToolsViewJsonRender
 }>()
 
-// Descendants (e.g. `useUncontrolledValue`) `inject()` this to scope
-// session-persisted state to "this dock" — the entry's own id, stable for
-// this component instance's lifetime (`ViewEntry` re-keys on entry change).
+/**
+ * Descendants (e.g. `useUncontrolledValue`) `inject()` this to scope
+ * session-persisted state to "this dock" — the entry's own id, stable for
+ * this component instance's lifetime (`ViewEntry` re-keys on entry change).
+ */
 provide(DOCK_ENTRY_ID_KEY, props.entry.id)
 
 const spec = shallowRef<Spec | null>(null)
 const isLoading = ref(true)
 const error = ref<string | null>(null)
 
-// Restores/persists the scroll position of this dock's own view, per tab,
-// across a reload — keyed by the dock entry id so switching docks doesn't
-// bleed one dock's scroll into another's.
+/**
+ * Restores/persists the scroll position of this dock's own view, per tab,
+ * across a reload — keyed by the dock entry id so switching docks doesn't
+ * bleed one dock's scroll into another's.
+ */
 const scrollContainer = useTemplateRef<HTMLElement>('scrollContainer')
 const scrollTop = useSessionStorage(`vite-devtools-scroll:${props.entry.id}`, 0)
 onMounted(() => {
diff --git a/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts b/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
index 528a53b48..11670685e 100644
--- a/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
+++ b/packages/core/src/client/webcomponents/json-render/composables/useUncontrolledValue.ts
@@ -6,29 +6,16 @@ import { DOCK_ENTRY_ID_KEY } from './dock-entry-id'
 
 /**
  * Session-persisted fallback for a json-render element's own *uncontrolled*
- * value — the local state a `Tabs`/`Select`/`TextInput`/`Switch` falls back
- * to while its `value` prop has no `$bindState` binding. Never touches a
- * genuinely controlled (bound) value — callers keep using `useBoundProp` for
- * that side and only read from this composable when unbound, exactly as
- * `Tabs.ts` already split `controlled`/`uncontrolledValue` before this existed.
+ * value — the local state `Tabs`/`Select`/`TextInput`/`Switch` fall back to
+ * when `value` has no `$bindState` binding. On by default: calling this
+ * instead of a plain `ref(default)` survives a reload within the same tab.
  *
- * Persistence is on by default (not opt-in per element) — just calling this
- * instead of a plain `ref(default)` gets you a value that survives a reload
- * within the same tab.
- *
- * ### Stable key
- * `UIElement` (what registry components actually receive) carries no id of
- * its own — identity lives on the sibling `FlatElement.key`, which
- * `@json-render/vue`'s `ElementRenderer` does not forward into the
- * component's props (it's only used internally for Vue's own `:key` and a
- * devtools-only debug attribute). Absent that, this derives a stable-enough
- * key from the current dock's id (`provide`d by `ViewJsonRender.vue`, read
- * via {@link DOCK_ENTRY_ID_KEY}) plus a signature of the element's own static
- * shape — its `props` minus the bound prop itself (e.g. `Tabs`' own `tabs`
- * list, `Select`'s own `options`). If that shape changes, the derived key
- * changes with it and persistence naturally falls back to `defaultValue`
- * instead of restoring a stale value for a different element — that's
- * intended, not a bug to fix.
+ * The key is derived rather than passed in, since `UIElement` carries no id
+ * of its own: it combines the current dock's id ({@link DOCK_ENTRY_ID_KEY})
+ * with a signature of the element's own static props (minus the bound prop).
+ * A shape change yields a different key, so persistence falls back to
+ * `defaultValue` instead of restoring a stale value for a different element —
+ * intended, not a bug.
  */
 export function useUncontrolledValue<Type extends string, Props extends Record<string, any>, Prop extends keyof Props>(
   ctx: RegistryComponentProps<Type, Props>,
diff --git a/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
index 8fcf0fac7..8a2e59427 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/dock-session.test.ts
@@ -38,9 +38,11 @@ function group(id: string): DevToolsDockEntry {
   return { id, type: 'group', title: id, icon: 'i' } as DevToolsDockEntry
 }
 
-// `open`/`selectedId` are now plain fields on the same `panelStore` ref
-// `createDocksContext` is handed (`vite-devtools-dock-state`, localStorage in
-// the real client) — no separate session store to mock, seed the ref directly.
+/**
+ * `open`/`selectedId` are now plain fields on the same `panelStore` ref
+ * `createDocksContext` is handed (`vite-devtools-dock-state`, localStorage in
+ * the real client) — no separate session store to mock, seed the ref directly.
+ */
 function panelStore(selectedId: string | null, open = true): Ref<DevToolsDockPanelStorage> {
   return ref({ ...DEFAULT_DOCK_PANEL_STORE(), open, selectedId })
 }
@@ -89,8 +91,7 @@ describe('restored dock panel state (selectedId/open on the same panelStore ref)
     const context = await createDocksContext('embedded', createMockRpc([iframe('a')]), panelStore('gone', false))
 
     expect(context.docks.selectedId).toBeNull()
-    // Clearing an invalid restored id must not route through `switchEntry`
-    // (which would force `open = true`) — the panel stays exactly as restored.
+    /** Clearing an invalid restored id must not route through `switchEntry` (which would force `open = true`) — the panel stays exactly as restored. */
     expect(context.panel.store.open).toBe(false)
   })
 
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index f16528db6..ce6b715d1 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -55,10 +55,10 @@ export async function createDocksContext(
 
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
 
-  // `open` and `selectedId` both live in `panelStore` (`vite-devtools-dock-state`,
-  // localStorage) alongside geometry/mode — restored across a reload, and,
-  // like everything else already in that value, shared cross-tab (opening the
-  // docks in one tab shows the same way in the next; not per-tab session state).
+  /**
+   * `open`/`selectedId` both live in `panelStore` (localStorage), so both are
+   * restored across a reload and shared cross-tab, like the rest of that value.
+   */
   const selectedId = computed<string | null>({
     get: () => panelStore.value.selectedId,
     set: (value) => { panelStore.value.selectedId = value },
@@ -69,18 +69,15 @@ export async function createDocksContext(
       ?? null,
   )
 
-  // A `selectedId` restored from `panelStore` may point at an entry that
-  // isn't directly selectable — a group (no view of its own) or a `subTabs`
-  // anchor (owns a shared frame, not a view). `switchEntry` resolves those on
-  // click, but restoring on boot must not route through it (it would force
-  // `panelStore.value.open = true`, reopening a panel the user closed) — so
-  // validate the restored id directly instead, once. `entries` starts empty
-  // and fills in async via `devframe:docks`, so an empty list here just means
-  // "not loaded yet"; wait for it rather than clearing a legitimate restored
-  // selection. This is boot-only: past this point `switchEntry` itself may
-  // legitimately land `selectedId` on a group/anchor id (e.g. a `subTabs`
-  // anchor with no live member to redirect to yet) — that's not something to
-  // keep correcting.
+  /**
+   * A restored `selectedId` may point at a non-selectable entry (a group, or
+   * a `subTabs` anchor) — `switchEntry` would fix that on click, but routing
+   * through it here would force `panelStore.value.open = true`, reopening a
+   * closed panel. So validate once, on boot, directly instead — waiting for
+   * `entries` to load rather than clearing a still-legitimate selection. Past
+   * boot, `switchEntry` may itself land `selectedId` on a group/anchor
+   * (e.g. mid-redirect); that's not something to keep correcting.
+   */
   const isSelectableEntry = (id: string): boolean => {
     if (id === '~client-auth-notice')
       return true
diff --git a/packages/core/src/client/webcomponents/state/docks.ts b/packages/core/src/client/webcomponents/state/docks.ts
index 0c19e2894..3dff10594 100644
--- a/packages/core/src/client/webcomponents/state/docks.ts
+++ b/packages/core/src/client/webcomponents/state/docks.ts
@@ -7,10 +7,9 @@ import { markRaw, reactive, shallowRef, watch } from 'vue'
 
 /**
  * {@link DockPanelStorage} (hub's own type — geometry/mode/`open`) plus
- * `selectedId`, which the hub has no concept of. Both persist the same way:
- * one `vite-devtools-dock-state` localStorage value, cross-tab like
- * everything else in it already is — a dock left open/selected in one tab
- * shows the same way in the next, exactly as `open` already behaves today.
+ * `selectedId`, which the hub has no concept of. Both persist in the same
+ * `vite-devtools-dock-state` localStorage value, so both are cross-tab —
+ * a dock left open/selected in one tab shows the same way in the next.
  */
 export interface DevToolsDockPanelStorage extends DockPanelStorage {
   selectedId: string | null