From 93473aae3e49cee052c9cd2daf9366435c4ebb90 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Tue, 4 Aug 2026 22:38:54 +0200
Subject: [PATCH 1/3] feat(kit,core): plugin-declared dock ordering, layout,
 and window defaults
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Unblocks a downstream Vite plugin that could not control dock-bar
category order, float-mode capacity, or first-run window placement.

- `DevToolsPluginOptions.dock` (`DevToolsDockConfig`): a plugin declares
  `categoryOrder`, `maxVisibleItems`, `defaultMode`, `defaultPosition`
  alongside its `setup()`. Collected across every plugin during the Vite
  plugin scan (last plugin wins per scalar key, `categoryOrder`
  shallow-merges), stashed on `ViteDevToolsNodeContext.dockConfig`, and
  handed to every client once via `ConnectionMeta.dockConfig` — riding the
  connection handshake every client already does, since the value is
  fixed for the life of the dev server.
- New `docksCategoriesOrder` user setting: category headers in the
  Settings dock panel are now drag-and-droppable, reusing the same
  machinery entry rows already use. The outer bar's sort pre-merges the
  plugin's `categoryOrder` beneath the user's own drag order into the
  `categoryOrderOverride` slot `docksGroupByCategories` already had for a
  group's own ordering — no new parameters needed there.
- `Dock.vue` folds a declared `maxVisibleItems` into the resolved float
  layout (an explicit `layout` prop still wins); `resolveDockLayout`
  clamps it to `>= 1`.
- The injected overlay seeds its `vite-devtools-dock-state` localStorage
  defaults (`mode`/`position`) from a declared `defaultMode`/
  `defaultPosition` — only for a developer with no stored preference yet.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
 packages/core/src/client/inject/runtime.ts    |  9 +-
 .../webcomponents/components/dock/Dock.vue    | 12 ++-
 .../components/dock/dock-layout.ts            |  6 +-
 .../views-builtin/SettingsAdvanced.vue        |  1 +
 .../views-builtin/SettingsDocks.vue           | 88 ++++++++++++++++++-
 .../state/__tests__/context-cache.test.ts     |  1 +
 .../state/__tests__/frame-nav.test.ts         |  1 +
 .../src/client/webcomponents/state/context.ts | 14 ++-
 .../webcomponents/state/dock-settings.ts      | 23 +++--
 .../webcomponents/stories/mock-context.ts     |  1 +
 packages/core/src/node/context.ts             | 18 +++-
 packages/core/src/node/rpc/index.ts           | 12 ++-
 packages/core/src/node/ws.ts                  |  1 +
 packages/kit/src/types/settings.ts            |  8 ++
 packages/kit/src/types/vite-plugin.ts         | 33 +++++++
 .../@vitejs/devtools-kit/index.snapshot.d.ts  |  8 ++
 16 files changed, 215 insertions(+), 21 deletions(-)

diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 0a5d2c520..14f38d4f8 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -60,15 +60,20 @@ async function mountDock(): Promise<void> {
     ],
   })
 
+  // A plugin-declared `defaultMode`/`defaultPosition` (`ctx.docks` config,
+  // handed to us once via `rpc.connectionMeta.dockConfig`) only seeds these
+  // two defaults — `mergeDefaults` below fills them in solely for a developer
+  // with no stored preference yet, and never overwrites one who already has.
+  const dockConfig = rpc.connectionMeta.dockConfig
   const state = useLocalStorage<DockPanelStorage>(
     'vite-devtools-dock-state',
     {
-      mode: 'float',
+      mode: dockConfig?.defaultMode ?? 'float',
       width: 80,
       height: 80,
       top: 0,
       left: 0,
-      position: 'left',
+      position: dockConfig?.defaultPosition ?? 'left',
       open: false,
       inactiveTimeout: 3_000,
     },
diff --git a/packages/core/src/client/webcomponents/components/dock/Dock.vue b/packages/core/src/client/webcomponents/components/dock/Dock.vue
index 5935b1747..d90deb1be 100644
--- a/packages/core/src/client/webcomponents/components/dock/Dock.vue
+++ b/packages/core/src/client/webcomponents/components/dock/Dock.vue
@@ -34,7 +34,17 @@ const props = defineProps<{
 // Here we directly destructure is as we don't expect context to be changed
 const context = props.context
 
-const layout = computed(() => resolveDockLayout(props.layout))
+// A plugin-declared `maxVisibleItems` (`rpc.connectionMeta.dockConfig`) sets
+// the default; an explicit `layout` prop (Storybook, embedders) still wins.
+// Only spread the config override when it's actually set — an own `undefined`
+// key would otherwise beat `DEFAULT_DOCK_LAYOUT`'s value in the merge below.
+const layout = computed(() => {
+  const configuredMaxVisibleItems = context.rpc.connectionMeta.dockConfig?.maxVisibleItems
+  return resolveDockLayout({
+    ...(configuredMaxVisibleItems !== undefined && { maxVisibleItems: configuredMaxVisibleItems }),
+    ...props.layout,
+  })
+})
 
 const isSafari = navigator.userAgent.includes('Safari') && !navigator.userAgent.includes('Chrome')
 
diff --git a/packages/core/src/client/webcomponents/components/dock/dock-layout.ts b/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
index 3f32bb93e..74ca28602 100644
--- a/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
+++ b/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
@@ -90,11 +90,13 @@ export const DEFAULT_DOCK_LAYOUT: DockLayout = Object.freeze({
   edgeZoneHeight: 70,
 })
 
-/** Merge partial overrides over {@link DEFAULT_DOCK_LAYOUT}. */
+/** Merge partial overrides over {@link DEFAULT_DOCK_LAYOUT}. `maxVisibleItems` is clamped to `>= 1` — a whole overflow button for zero inline items has nothing to anchor to. */
 export function resolveDockLayout(overrides?: Partial<DockLayout>): DockLayout {
   if (!overrides)
     return DEFAULT_DOCK_LAYOUT
-  return { ...DEFAULT_DOCK_LAYOUT, ...overrides }
+  const merged = { ...DEFAULT_DOCK_LAYOUT, ...overrides }
+  merged.maxVisibleItems = Math.max(1, merged.maxVisibleItems)
+  return merged
 }
 
 /**
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
index 0ab084af2..ce79bdfee 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
@@ -46,6 +46,7 @@ async function resetDocks() {
       state.docksHidden = defaults.docksHidden
       state.docksCategoriesHidden = defaults.docksCategoriesHidden
       state.docksCustomOrder = defaults.docksCustomOrder
+      state.docksCategoriesOrder = {}
       state.docksPinned = defaults.docksPinned
     })
   }
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
index b83cf65fd..a8f14ca01 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
@@ -21,10 +21,18 @@ const settings = sharedStateToRef(props.settingsStore)
 // group button. A group's members are split by their in-group sub-category, and
 // each sub-category is its own reorderable container (`grp:<id>:::<subcat>`);
 // category containers are keyed `cat:<name>`.
+const configCategoryOrder = computed(() => props.context.rpc.connectionMeta.dockConfig?.categoryOrder)
+
+// The outer bar's `categoryOrderOverride` pre-merges the plugin-declared
+// config beneath the user's own drag order (user wins on a shared key) — the
+// same one-slot convention `dock-settings.ts` documents for `docksGroupByCategories`.
+const categoryOrderOverride = computed(() => ({ ...configCategoryOrder.value, ...settings.value.docksCategoriesOrder }))
+
 const categories = computed<DevToolsDockEntriesGrouped>(() => {
   return docksGroupByCategories(props.context.docks.entries, settings.value, {
     includeHidden: true,
     collapseGroups: true,
+    categoryOrderOverride: categoryOrderOverride.value,
   })
 })
 
@@ -44,6 +52,23 @@ const GROUP_SUBCAT_SEPARATOR = ':::'
 const CATEGORY_CONTAINER = (category: string) => `cat:${category}`
 const GROUP_SUBCAT_CONTAINER = (groupId: string, subcategory: string) => `grp:${groupId}${GROUP_SUBCAT_SEPARATOR}${subcategory}`
 
+// The category *headers* are themselves a reorderable container, keyed by
+// this fixed id (distinct from a `cat:<name>` per-category entry container).
+// Its "items" are pseudo dock-entries — one per hideable category — whose id
+// is prefixed to keep it out of the real dock-id namespace `entryEls`/drag
+// state share with every other container (a category name could otherwise
+// collide with an actual dock id).
+const CATEGORY_ORDER_CONTAINER = 'cat-order'
+const CATEGORY_ORDER_ID_PREFIX = 'cat-order:'
+const categoryOrderId = (category: string) => `${CATEGORY_ORDER_ID_PREFIX}${category}`
+const categoryFromOrderId = (id: string) => id.slice(CATEGORY_ORDER_ID_PREFIX.length)
+
+function categoryPseudoEntries(cats: DevToolsDockEntriesGrouped): DevToolsDockEntry[] {
+  return cats
+    .filter(([category]) => isCategoryHideable(category))
+    .map(([category]) => ({ id: categoryOrderId(category), title: getCategoryLabel(category) }) as DevToolsDockEntry)
+}
+
 /** Split a `grp:<id>:::<subcat>` container back into its group id + sub-category. */
 function parseGroupContainer(container: string): { groupId: string, subcategory: string } {
   const rest = container.slice(4)
@@ -55,6 +80,8 @@ function parseGroupContainer(container: string): { groupId: string, subcategory:
 }
 
 function itemsOfContainer(container: string): DevToolsDockEntry[] {
+  if (container === CATEGORY_ORDER_CONTAINER)
+    return categoryPseudoEntries(categories.value)
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
     return subcategoriesOf(groupId).find(([cat]) => cat === subcategory)?.[1] ?? []
@@ -64,6 +91,15 @@ function itemsOfContainer(container: string): DevToolsDockEntry[] {
 }
 
 function defaultItemsOfContainer(container: string): DevToolsDockEntry[] {
+  if (container === CATEGORY_ORDER_CONTAINER) {
+    // "Default" for the category-order container omits the user's own drag
+    // order (unlike `categories` above) — it's what dragging back to would reset to.
+    return categoryPseudoEntries(docksGroupByCategories(props.context.docks.entries, settings.value, {
+      includeHidden: true,
+      collapseGroups: true,
+      categoryOrderOverride: configCategoryOrder.value,
+    }))
+  }
   const noCustomOrder = { ...settings.value, docksCustomOrder: {} }
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
@@ -106,6 +142,19 @@ function isInteractiveElement(el: HTMLElement | null): boolean {
 function applyOrder(container: string, items: DevToolsDockEntry[]) {
   const def = defaultItemsOfContainer(container).map(i => i.id)
   const isDefault = items.length === def.length && items.every((item, i) => item.id === def[i])
+  if (container === CATEGORY_ORDER_CONTAINER) {
+    props.settingsStore.mutate((state) => {
+      state.docksCategoriesOrder ??= {}
+      items.forEach((item, index) => {
+        const category = categoryFromOrderId(item.id)
+        if (isDefault)
+          delete state.docksCategoriesOrder![category]
+        else
+          state.docksCategoriesOrder![category] = index
+      })
+    })
+    return
+  }
   props.settingsStore.mutate((state) => {
     items.forEach((item, index) => {
       if (isDefault)
@@ -273,6 +322,14 @@ function doesContainerHaveCustomOrder(container: string): boolean {
 
 function resetCustomOrderForContainer(container: string) {
   const ids = customOrderIdsForContainer(container)
+  if (container === CATEGORY_ORDER_CONTAINER) {
+    props.settingsStore.mutate((state) => {
+      ids.forEach((id) => {
+        delete state.docksCategoriesOrder?.[categoryFromOrderId(id)]
+      })
+    })
+    return
+  }
   props.settingsStore.mutate((state) => {
     ids.forEach((id) => {
       delete state.docksCustomOrder[id]
@@ -282,9 +339,21 @@ function resetCustomOrderForContainer(container: string) {
 </script>
 
 <template>
-  <p class="text-sm op50 mb-4">
-    Manage visibility and order of dock entries. Hidden entries will not appear in the dock bar.
-  </p>
+  <div class="flex items-start gap-2 mb-4">
+    <p class="text-sm op50 flex-auto">
+      Manage visibility and order of dock entries. Hidden entries will not appear in the dock bar. Drag a category's
+      header to reorder the dock bar's sections.
+    </p>
+    <button
+      v-if="doesContainerHaveCustomOrder(CATEGORY_ORDER_CONTAINER)"
+      class="flex items-center gap-1 px-2 py-1 rounded hover:bg-gray/20 transition-colors text-xs op60 shrink-0"
+      title="Reset category order"
+      @click="resetCustomOrderForContainer(CATEGORY_ORDER_CONTAINER)"
+    >
+      <div class="i-ph-arrows-counter-clockwise-duotone" />
+      Reset category order
+    </button>
+  </div>
 
   <div ref="sortContainer" class="flex flex-col gap-4">
     <template v-for="[category, entries] of categories" :key="category">
@@ -294,8 +363,21 @@ function resetCustomOrderForContainer(container: string) {
       >
         <!-- Category header -->
         <div
+          :ref="(el: any) => isCategoryHideable(category) && setEntryRef(el, categoryOrderId(category), CATEGORY_ORDER_CONTAINER)"
+          :data-dock-id="isCategoryHideable(category) ? categoryOrderId(category) : undefined"
+          :data-container="isCategoryHideable(category) ? CATEGORY_ORDER_CONTAINER : undefined"
           class="flex items-center gap-2 px-4 py-3 bg-gray/5 cursor-pointer select-none border-b border-base"
+          :class="[
+            hasMoved && draggingId === categoryOrderId(category) ? 'op30 bg-gray/10' : '',
+            dragOverId === categoryOrderId(category) ? 'ring-1.5 ring-purple/50 rounded' : '',
+          ]"
         >
+          <!-- drag icon (headers of ~pinned/~builtin never carry a container, so they never drag) -->
+          <div
+            v-if="isCategoryHideable(category)"
+            class="i-ph-dots-six-vertical w-4 h-4 shrink-0 op25 hover:op50 transition-opacity cursor-grab"
+            :style="hasMoved && draggingId === categoryOrderId(category) ? 'cursor: grabbing' : ''"
+          />
           <button
             class="w-5 h-5 flex items-center justify-center rounded transition-colors"
             :class="[
diff --git a/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts b/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
index a1f44e805..062535ffa 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
@@ -26,6 +26,7 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
     client: {
       register: () => () => {},
     },
+    connectionMeta: { backend: 'websocket' },
     sharedState: {
       get: async (key: string) => {
         if (key === 'devframe:docks')
diff --git a/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts b/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
index 3051abb6b..143140b43 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
@@ -13,6 +13,7 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
 
   return {
     client: { register: () => () => {} },
+    connectionMeta: { backend: 'websocket' },
     sharedState: {
       get: async (key: string) => {
         if (key === 'devframe:docks')
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index 52060b2c9..540f36b71 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -1,4 +1,4 @@
-import type { DevToolsClientCommand, DevToolsDockEntry, DevToolsDockUserEntry, DevToolsRpcClientFunctions, DevToolsViewIframe } from '@vitejs/devtools-kit'
+import type { DevToolsClientCommand, DevToolsDockConfig, DevToolsDockEntry, DevToolsDockUserEntry, DevToolsRpcClientFunctions, DevToolsViewIframe } from '@vitejs/devtools-kit'
 import type { CommandsContext, DevToolsRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DockRegistration, DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
@@ -29,6 +29,12 @@ export async function createDocksContext(
 
   const dockEntries = await useDocksEntries(rpc)
 
+  // Host-level dock config, merged from every plugin's `devtools.dock`
+  // declaration by `createDevToolsContext` and handed to us once as part of
+  // the connection handshake (`rpc.connectionMeta`) — fixed for the life of
+  // the dev server, so no shared-state subscription is needed to read it.
+  const dockConfig: DevToolsDockConfig | undefined = rpc.connectionMeta.dockConfig
+
   // Client-only dock registry (0.7.10 `DocksEntriesContext` API). Docks
   // registered here live in this page only, merged over the server-provided
   // `devframe:docks` docks by id, and never sync to shared state. Mirrors the
@@ -333,7 +339,11 @@ export async function createDocksContext(
   // Settings store, `settings`, and `getWhenContext` are established earlier
   // (right before `switchEntry`) — its group→member resolution needs them.
   const groupedEntries = computed(() => {
-    return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true })
+    // Pre-merge the plugin-declared config beneath the user's own drag order
+    // into the one `categoryOrderOverride` slot `docksGroupByCategories`
+    // already has (user wins on a key both set).
+    const categoryOrderOverride = { ...dockConfig?.categoryOrder, ...settings.value.docksCategoriesOrder }
+    return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true, categoryOrderOverride })
   })
 
   // Initialize commands context with reactive when-context
diff --git a/packages/core/src/client/webcomponents/state/dock-settings.ts b/packages/core/src/client/webcomponents/state/dock-settings.ts
index 5e5c54996..a30b3a727 100644
--- a/packages/core/src/client/webcomponents/state/dock-settings.ts
+++ b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -28,11 +28,14 @@ export const PINNED_CATEGORY_ORDER = -100000
 
 /**
  * Resolve a category's sort weight, layering the local {@link PINNED_CATEGORY}
- * override, then a caller-supplied `overrides` map (a group's own
- * {@link DevToolsViewGroup.categoryOrder}), on top of the upstream
- * {@link DEFAULT_CATEGORIES_ORDER} table. `overrides` is per-call — passing a
- * group's map only reweights that group's in-group sub-categories, never the
- * outer bar or any other group.
+ * override, then a caller-supplied `overrides` map, on top of the upstream
+ * {@link DEFAULT_CATEGORIES_ORDER} table. `overrides` is per-call — a caller
+ * that wants a plugin-declared `DevToolsDockConfig.categoryOrder` layered
+ * beneath the user's own drag-and-drop order pre-merges both into the one map
+ * it passes (e.g. `{ ...config?.categoryOrder, ...docksCategoriesOrder }`);
+ * {@link getGroupMembersGrouped} instead passes a group's own
+ * {@link DevToolsViewGroup.categoryOrder}, reweighting only that group's
+ * in-group sub-categories.
  */
 function categoryOrder(category: string, overrides?: Record<string, number>): number {
   if (category === PINNED_CATEGORY)
@@ -241,10 +244,14 @@ export function resolveGroupDefaultChild(
  * category is hidden.
  *
  * `categoryOrderOverride` reweights the categories produced by *this call*
- * (used by {@link getGroupMembersGrouped} to apply a group's own
- * {@link DevToolsViewGroup.categoryOrder} to its in-group sub-category split)
  * — it never touches the shared {@link DEFAULT_CATEGORIES_ORDER} table, so it
- * has no effect on any other call, group, or the outer bar.
+ * has no effect on any other call, group, or the outer bar. Two distinct
+ * callers use this same slot for two distinct purposes: {@link getGroupMembersGrouped}
+ * passes a group's own {@link DevToolsViewGroup.categoryOrder} to reweight its
+ * in-group sub-category split, while a top-level caller (the dock bar, the
+ * Settings management view) pre-merges a plugin-declared
+ * `DevToolsDockConfig.categoryOrder` with the user's own drag-and-drop
+ * `docksCategoriesOrder` into the map it passes here.
  */
 export function docksGroupByCategories(
   entries: DevToolsDockEntry[],
diff --git a/packages/core/src/client/webcomponents/stories/mock-context.ts b/packages/core/src/client/webcomponents/stories/mock-context.ts
index ec5c664ad..859089723 100644
--- a/packages/core/src/client/webcomponents/stories/mock-context.ts
+++ b/packages/core/src/client/webcomponents/stories/mock-context.ts
@@ -58,6 +58,7 @@ function createMockRpc(
 
   const rpc = {
     events,
+    connectionMeta: { backend: 'websocket' },
     get isTrusted() {
       return trusted
     },
diff --git a/packages/core/src/node/context.ts b/packages/core/src/node/context.ts
index 2aca61e9b..bfdbec0ed 100644
--- a/packages/core/src/node/context.ts
+++ b/packages/core/src/node/context.ts
@@ -1,4 +1,4 @@
-import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { RpcFunctionsHost } from 'devframe/node'
 import type { ResolvedConfig, ViteDevServer } from 'vite'
 import { DEVTOOLS_VITEPLUS_GROUP_ID } from '@vitejs/devtools-kit/constants'
@@ -109,7 +109,11 @@ export async function createDevToolsContext(
   if (viteServer || mode === 'build')
     context.views.hostStatic('/__devtools-assets/', dirAssets)
 
-  // Scan Vite plugins for `devtools` setup hooks.
+  // Scan Vite plugins for `devtools` setup hooks, merging each plugin's
+  // `devtools.dock` config along the way (last plugin wins per scalar key;
+  // `categoryOrder` shallow-merges) — a plugin skipped for this mode's
+  // capabilities contributes nothing.
+  const dockConfig: DevToolsDockConfig = {}
   const plugins = viteConfig.plugins.filter(plugin => 'devtools' in plugin)
   for (const plugin of plugins) {
     if (!plugin.devtools?.setup)
@@ -118,6 +122,11 @@ export async function createDevToolsContext(
       debugSetup(`skipping plugin ${JSON.stringify(plugin.name)} due to disabled capabilities in ${mode} mode`)
       continue
     }
+    if (plugin.devtools.dock) {
+      Object.assign(dockConfig, plugin.devtools.dock, {
+        categoryOrder: { ...dockConfig.categoryOrder, ...plugin.devtools.dock.categoryOrder },
+      })
+    }
     try {
       debugSetup(`setting up plugin ${JSON.stringify(plugin.name)}`)
       await plugin.devtools?.setup?.(context)
@@ -126,6 +135,11 @@ export async function createDevToolsContext(
       throw diagnostics.DTK0014({ name: plugin.name, cause: error })
     }
   }
+  // Riding on `ConnectionMeta` rather than shared state (see the `ConnectionMeta`
+  // augmentation in `node/rpc/index.ts`) — `createWsServer`'s `getConnectionMeta`
+  // closure (`node/ws.ts`) reads it off this same context object, which is
+  // already fully built by the time that closure is created.
+  context.dockConfig = dockConfig
 
   return context
 }
diff --git a/packages/core/src/node/rpc/index.ts b/packages/core/src/node/rpc/index.ts
index a8d4988a9..ae2c6c0dc 100644
--- a/packages/core/src/node/rpc/index.ts
+++ b/packages/core/src/node/rpc/index.ts
@@ -1,4 +1,4 @@
-import type { DevToolsDockEntry, DevToolsDocksUserSettings, DevToolsServerCommandEntry, RpcDefinitionsFilter, RpcDefinitionsToFunctions } from '@vitejs/devtools-kit'
+import type { DevToolsDockConfig, DevToolsDockEntry, DevToolsDocksUserSettings, DevToolsServerCommandEntry, RpcDefinitionsFilter, RpcDefinitionsToFunctions } from '@vitejs/devtools-kit'
 import { commandsExecute } from './internal/commands-execute'
 import { commandsList } from './internal/commands-list'
 import { docksOnLaunch } from './internal/docks-on-launch'
@@ -69,4 +69,14 @@ declare module 'devframe/types' {
     'devframe:docks': DevToolsDockEntry[]
     'devframe:user-settings': DevToolsDocksUserSettings
   }
+
+  // Host-level dock config (`DevToolsDockConfig`, merged from every plugin's
+  // `devtools.dock` declaration in `createDevToolsContext`) rides on
+  // `ConnectionMeta` instead of a shared-state key: it is fixed for the life
+  // of the dev server, set once from `vite.config.ts` before any client
+  // connects, so it needs none of shared state's live-broadcast machinery —
+  // just the connection handshake every client already does once.
+  interface ConnectionMeta {
+    dockConfig?: DevToolsDockConfig
+  }
 }
diff --git a/packages/core/src/node/ws.ts b/packages/core/src/node/ws.ts
index da5ffaf4d..1d1069ae9 100644
--- a/packages/core/src/node/ws.ts
+++ b/packages/core/src/node/ws.ts
@@ -211,6 +211,7 @@ export async function createWsServer(options: CreateWsServerOptions) {
       // client (proxy-safe); the dedicated-port form is a bare port number.
       websocket: routeBound ? { path: DEVTOOLS_WS_ROUTE } : port!,
       jsonSerializableMethods,
+      dockConfig: context.dockConfig,
     }
   }
 
diff --git a/packages/kit/src/types/settings.ts b/packages/kit/src/types/settings.ts
index 9466f1f28..98b029dcf 100644
--- a/packages/kit/src/types/settings.ts
+++ b/packages/kit/src/types/settings.ts
@@ -15,4 +15,12 @@ export interface DevToolsDocksUserSettings extends DevframeDocksUserSettings {
    * dock out of the dock bar until the user opts in from Settings → Advanced.
    */
   showDevframeInspector?: boolean
+
+  /**
+   * User drag-and-drop order for top-level dock categories, keyed by category
+   * id with lower first — the same convention as a plugin's declared
+   * `DevToolsDockConfig.categoryOrder`, which this overrides. Absent
+   * categories fall back to the declared or upstream order.
+   */
+  docksCategoriesOrder?: Record<string, number>
 }
diff --git a/packages/kit/src/types/vite-plugin.ts b/packages/kit/src/types/vite-plugin.ts
index d715a5cc2..a7b701904 100644
--- a/packages/kit/src/types/vite-plugin.ts
+++ b/packages/kit/src/types/vite-plugin.ts
@@ -2,11 +2,38 @@ import type { DevframeCapabilities } from '@devframes/hub/types'
 import type { ResolvedConfig, ViteDevServer } from 'vite'
 import type { KitNodeContext } from '../node/context'
 
+/**
+ * Host-level dock defaults a plugin can declare alongside its `setup()`. Every
+ * field here is host-global rather than per-entry, so plugins share one
+ * config object instead of each dock entry needing its own "which entry wins"
+ * rule. Collected from every plugin's `devtools.dock` during the Vite plugin
+ * scan (`createDevToolsContext`), merged (later plugins win per scalar key;
+ * `categoryOrder` shallow-merges) onto {@link ViteDevToolsNodeContext.dockConfig},
+ * and handed to every client once via `ConnectionMeta`.
+ */
+export interface DevToolsDockConfig {
+  /**
+   * Top-level category weights, lower first. Layered over
+   * `DEFAULT_CATEGORIES_ORDER`, beneath the user's own drag-and-drop order.
+   * Name and shape deliberately mirror hub's own
+   * `createDevframeClientHost({ categoryOrder })` and `DevframeViewGroup.categoryOrder`.
+   */
+  categoryOrder?: Record<string, number>
+  /** Items shown inline on the float bar before the overflow button. Defaults to 5; clamped to `>= 1`. */
+  maxVisibleItems?: number
+  /** Display mode on first run, before the developer has a stored preference. */
+  defaultMode?: 'float' | 'edge'
+  /** Viewport edge to attach to on first run. Only meaningful with `defaultMode: 'edge'`. */
+  defaultPosition?: 'top' | 'right' | 'bottom' | 'left'
+}
+
 export interface DevToolsPluginOptions {
   capabilities?: {
     dev?: DevframeCapabilities | boolean
     build?: DevframeCapabilities | boolean
   }
+  /** Host-level dock defaults — see {@link DevToolsDockConfig}. */
+  dock?: DevToolsDockConfig
   setup: (context: ViteDevToolsNodeContext) => void | Promise<void>
 }
 
@@ -21,4 +48,10 @@ export interface DevToolsPluginOptions {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig
   readonly viteServer?: ViteDevServer
+  /**
+   * Dock config merged from every plugin's `devtools.dock` declaration,
+   * assigned once by `createDevToolsContext` after its plugin scan. Read by
+   * `createWsServer`'s `getConnectionMeta` to hand it to every client.
+   */
+  dockConfig?: DevToolsDockConfig
 }
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
index c05eb04dc..73cd3b50a 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
@@ -6,6 +6,12 @@ export interface CreateKitContextOptions extends CreateHubContextOptions {
   viteConfig?: ResolvedConfig;
   viteServer?: ViteDevServer;
 }
+export interface DevToolsDockConfig {
+  categoryOrder?: Record<string, number>;
+  maxVisibleItems?: number;
+  defaultMode?: 'float' | 'edge';
+  defaultPosition?: 'top' | 'right' | 'bottom' | 'left';
+}
 export interface DevToolsLaunchPayload {
   root?: string;
 }
@@ -19,6 +25,7 @@ export interface DevToolsPluginOptions {
     dev?: DevframeCapabilities | boolean;
     build?: DevframeCapabilities | boolean;
   };
+  dock?: DevToolsDockConfig;
   setup: (_: ViteDevToolsNodeContext) => void | Promise<void>;
 }
 export interface DevToolsViewJsonRender extends DevframeDockEntryBase {
@@ -48,6 +55,7 @@ export interface PluginWithDevTools extends Plugin {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig;
   readonly viteServer?: ViteDevServer;
+  dockConfig?: DevToolsDockConfig;
 }
 // #endregion
 

From 6c645f5275a068ed203cdd5f4d1569df3574746e Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Tue, 4 Aug 2026 23:40:38 +0200
Subject: [PATCH 2/3] refactor(core,kit): quieter dock-config diff
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trims the explanatory comment blocks added with the dock-config feature down
to one-liners, and simplifies the code they were explaining:

- `resolveDockLayout` folds the `maxVisibleItems` clamp into its merge and
  tolerates an undefined override, so `Dock.vue` spreads the plugin config
  directly instead of a conditional-spread guard.
- `SettingsDocks.vue` resolves the settings record and key through `orderRecord`
  / `orderKey`, dropping the duplicated category-order branches in `applyOrder`
  and `resetCustomOrderForContainer` along with their non-null assertions; the
  template loops over a `categoryHeaders` computed carrying a `dragId` instead
  of repeating `isCategoryHideable(category)` five times.
- Restores the pre-existing `dock-settings.ts` doc wording.

Adds a test for the `resolveDockLayout` merge/clamp path.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
 packages/core/src/client/inject/runtime.ts    |   6 +-
 .../webcomponents/components/dock/Dock.vue    |  16 +--
 .../dock/__tests__/dock-layout.test.ts        |  20 ++++
 .../components/dock/dock-layout.ts            |  11 +-
 .../views-builtin/SettingsDocks.vue           | 106 ++++++++----------
 .../src/client/webcomponents/state/context.ts |   9 +-
 .../webcomponents/state/dock-settings.ts      |  28 ++---
 packages/core/src/node/context.ts             |  18 +--
 packages/core/src/node/rpc/index.ts           |   7 +-
 packages/kit/src/types/settings.ts            |   6 +-
 packages/kit/src/types/vite-plugin.ts         |  18 +--
 11 files changed, 105 insertions(+), 140 deletions(-)
 create mode 100644 packages/core/src/client/webcomponents/components/dock/__tests__/dock-layout.test.ts

diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 14f38d4f8..635bd80d5 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -60,10 +60,8 @@ async function mountDock(): Promise<void> {
     ],
   })
 
-  // A plugin-declared `defaultMode`/`defaultPosition` (`ctx.docks` config,
-  // handed to us once via `rpc.connectionMeta.dockConfig`) only seeds these
-  // two defaults — `mergeDefaults` below fills them in solely for a developer
-  // with no stored preference yet, and never overwrites one who already has.
+  // Plugin-declared mode/position only seed the defaults — `mergeDefaults` never
+  // overwrites a developer's stored preference.
   const dockConfig = rpc.connectionMeta.dockConfig
   const state = useLocalStorage<DockPanelStorage>(
     'vite-devtools-dock-state',
diff --git a/packages/core/src/client/webcomponents/components/dock/Dock.vue b/packages/core/src/client/webcomponents/components/dock/Dock.vue
index d90deb1be..d0ed5e1fb 100644
--- a/packages/core/src/client/webcomponents/components/dock/Dock.vue
+++ b/packages/core/src/client/webcomponents/components/dock/Dock.vue
@@ -34,17 +34,11 @@ const props = defineProps<{
 // Here we directly destructure is as we don't expect context to be changed
 const context = props.context
 
-// A plugin-declared `maxVisibleItems` (`rpc.connectionMeta.dockConfig`) sets
-// the default; an explicit `layout` prop (Storybook, embedders) still wins.
-// Only spread the config override when it's actually set — an own `undefined`
-// key would otherwise beat `DEFAULT_DOCK_LAYOUT`'s value in the merge below.
-const layout = computed(() => {
-  const configuredMaxVisibleItems = context.rpc.connectionMeta.dockConfig?.maxVisibleItems
-  return resolveDockLayout({
-    ...(configuredMaxVisibleItems !== undefined && { maxVisibleItems: configuredMaxVisibleItems }),
-    ...props.layout,
-  })
-})
+// A plugin-declared `maxVisibleItems` is the default; an explicit `layout` prop wins.
+const layout = computed(() => resolveDockLayout({
+  maxVisibleItems: context.rpc.connectionMeta.dockConfig?.maxVisibleItems,
+  ...props.layout,
+}))
 
 const isSafari = navigator.userAgent.includes('Safari') && !navigator.userAgent.includes('Chrome')
 
diff --git a/packages/core/src/client/webcomponents/components/dock/__tests__/dock-layout.test.ts b/packages/core/src/client/webcomponents/components/dock/__tests__/dock-layout.test.ts
new file mode 100644
index 000000000..d82714091
--- /dev/null
+++ b/packages/core/src/client/webcomponents/components/dock/__tests__/dock-layout.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_DOCK_LAYOUT, resolveDockLayout } from '../dock-layout'
+
+describe('resolveDockLayout', () => {
+  it('returns the defaults untouched without overrides', () => {
+    expect.assertions(1)
+    expect(resolveDockLayout()).toBe(DEFAULT_DOCK_LAYOUT)
+  })
+
+  it('ignores an undefined maxVisibleItems override', () => {
+    expect.assertions(1)
+    expect(resolveDockLayout({ maxVisibleItems: undefined }).maxVisibleItems).toBe(DEFAULT_DOCK_LAYOUT.maxVisibleItems)
+  })
+
+  it('clamps maxVisibleItems to at least one', () => {
+    expect.assertions(2)
+    expect(resolveDockLayout({ maxVisibleItems: 0 }).maxVisibleItems).toBe(1)
+    expect(resolveDockLayout({ maxVisibleItems: 10 }).maxVisibleItems).toBe(10)
+  })
+})
diff --git a/packages/core/src/client/webcomponents/components/dock/dock-layout.ts b/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
index 74ca28602..c2b0d3886 100644
--- a/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
+++ b/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
@@ -90,13 +90,16 @@ export const DEFAULT_DOCK_LAYOUT: DockLayout = Object.freeze({
   edgeZoneHeight: 70,
 })
 
-/** Merge partial overrides over {@link DEFAULT_DOCK_LAYOUT}. `maxVisibleItems` is clamped to `>= 1` — a whole overflow button for zero inline items has nothing to anchor to. */
+/** Merge partial overrides over {@link DEFAULT_DOCK_LAYOUT}. */
 export function resolveDockLayout(overrides?: Partial<DockLayout>): DockLayout {
   if (!overrides)
     return DEFAULT_DOCK_LAYOUT
-  const merged = { ...DEFAULT_DOCK_LAYOUT, ...overrides }
-  merged.maxVisibleItems = Math.max(1, merged.maxVisibleItems)
-  return merged
+  return {
+    ...DEFAULT_DOCK_LAYOUT,
+    ...overrides,
+    // An overflow button with zero inline items has nothing to sit beside.
+    maxVisibleItems: Math.max(1, overrides.maxVisibleItems ?? DEFAULT_DOCK_LAYOUT.maxVisibleItems),
+  }
 }
 
 /**
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
index a8f14ca01..f92dfce68 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
@@ -23,18 +23,16 @@ const settings = sharedStateToRef(props.settingsStore)
 // category containers are keyed `cat:<name>`.
 const configCategoryOrder = computed(() => props.context.rpc.connectionMeta.dockConfig?.categoryOrder)
 
-// The outer bar's `categoryOrderOverride` pre-merges the plugin-declared
-// config beneath the user's own drag order (user wins on a shared key) — the
-// same one-slot convention `dock-settings.ts` documents for `docksGroupByCategories`.
-const categoryOrderOverride = computed(() => ({ ...configCategoryOrder.value, ...settings.value.docksCategoriesOrder }))
-
-const categories = computed<DevToolsDockEntriesGrouped>(() => {
+function groupByCategories(categoryOrderOverride?: Record<string, number>): DevToolsDockEntriesGrouped {
   return docksGroupByCategories(props.context.docks.entries, settings.value, {
     includeHidden: true,
     collapseGroups: true,
-    categoryOrderOverride: categoryOrderOverride.value,
+    categoryOrderOverride,
   })
-})
+}
+
+// User drag order over the plugin-declared one.
+const categories = computed(() => groupByCategories({ ...configCategoryOrder.value, ...settings.value.docksCategoriesOrder }))
 
 function membersOf(groupId: string): DevToolsDockEntry[] {
   return getGroupMembers(props.context.docks.entries, groupId, settings.value, {
@@ -52,23 +50,35 @@ const GROUP_SUBCAT_SEPARATOR = ':::'
 const CATEGORY_CONTAINER = (category: string) => `cat:${category}`
 const GROUP_SUBCAT_CONTAINER = (groupId: string, subcategory: string) => `grp:${groupId}${GROUP_SUBCAT_SEPARATOR}${subcategory}`
 
-// The category *headers* are themselves a reorderable container, keyed by
-// this fixed id (distinct from a `cat:<name>` per-category entry container).
-// Its "items" are pseudo dock-entries — one per hideable category — whose id
-// is prefixed to keep it out of the real dock-id namespace `entryEls`/drag
-// state share with every other container (a category name could otherwise
-// collide with an actual dock id).
+// The category headers are one more reorderable container, whose items are
+// pseudo dock-entries (one per hideable category). Their ids carry a prefix so a
+// category name can never collide with a real dock id in the shared drag state.
 const CATEGORY_ORDER_CONTAINER = 'cat-order'
 const CATEGORY_ORDER_ID_PREFIX = 'cat-order:'
 const categoryOrderId = (category: string) => `${CATEGORY_ORDER_ID_PREFIX}${category}`
-const categoryFromOrderId = (id: string) => id.slice(CATEGORY_ORDER_ID_PREFIX.length)
 
-function categoryPseudoEntries(cats: DevToolsDockEntriesGrouped): DevToolsDockEntry[] {
-  return cats
+function categoryOrderItems(grouped: DevToolsDockEntriesGrouped): DevToolsDockEntry[] {
+  return grouped
     .filter(([category]) => isCategoryHideable(category))
     .map(([category]) => ({ id: categoryOrderId(category), title: getCategoryLabel(category) }) as DevToolsDockEntry)
 }
 
+/** Header rows for the template; `dragId` is absent on `~pinned`/`~builtin`, which never drag. */
+const categoryHeaders = computed(() => categories.value.map(([category, entries]) => ({
+  category,
+  entries,
+  dragId: isCategoryHideable(category) ? categoryOrderId(category) : undefined,
+})))
+
+/** Settings key an item's order index lives under — category rows drop their `cat-order:` prefix. */
+function orderKey(container: string, id: string): string {
+  return container === CATEGORY_ORDER_CONTAINER ? id.slice(CATEGORY_ORDER_ID_PREFIX.length) : id
+}
+
+function orderRecord(state: DevToolsDocksUserSettings, container: string): Record<string, number> {
+  return container === CATEGORY_ORDER_CONTAINER ? (state.docksCategoriesOrder ??= {}) : state.docksCustomOrder
+}
+
 /** Split a `grp:<id>:::<subcat>` container back into its group id + sub-category. */
 function parseGroupContainer(container: string): { groupId: string, subcategory: string } {
   const rest = container.slice(4)
@@ -81,7 +91,7 @@ function parseGroupContainer(container: string): { groupId: string, subcategory:
 
 function itemsOfContainer(container: string): DevToolsDockEntry[] {
   if (container === CATEGORY_ORDER_CONTAINER)
-    return categoryPseudoEntries(categories.value)
+    return categoryOrderItems(categories.value)
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
     return subcategoriesOf(groupId).find(([cat]) => cat === subcategory)?.[1] ?? []
@@ -91,15 +101,8 @@ function itemsOfContainer(container: string): DevToolsDockEntry[] {
 }
 
 function defaultItemsOfContainer(container: string): DevToolsDockEntry[] {
-  if (container === CATEGORY_ORDER_CONTAINER) {
-    // "Default" for the category-order container omits the user's own drag
-    // order (unlike `categories` above) — it's what dragging back to would reset to.
-    return categoryPseudoEntries(docksGroupByCategories(props.context.docks.entries, settings.value, {
-      includeHidden: true,
-      collapseGroups: true,
-      categoryOrderOverride: configCategoryOrder.value,
-    }))
-  }
+  if (container === CATEGORY_ORDER_CONTAINER)
+    return categoryOrderItems(groupByCategories(configCategoryOrder.value))
   const noCustomOrder = { ...settings.value, docksCustomOrder: {} }
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
@@ -142,25 +145,14 @@ function isInteractiveElement(el: HTMLElement | null): boolean {
 function applyOrder(container: string, items: DevToolsDockEntry[]) {
   const def = defaultItemsOfContainer(container).map(i => i.id)
   const isDefault = items.length === def.length && items.every((item, i) => item.id === def[i])
-  if (container === CATEGORY_ORDER_CONTAINER) {
-    props.settingsStore.mutate((state) => {
-      state.docksCategoriesOrder ??= {}
-      items.forEach((item, index) => {
-        const category = categoryFromOrderId(item.id)
-        if (isDefault)
-          delete state.docksCategoriesOrder![category]
-        else
-          state.docksCategoriesOrder![category] = index
-      })
-    })
-    return
-  }
   props.settingsStore.mutate((state) => {
+    const order = orderRecord(state, container)
     items.forEach((item, index) => {
+      const key = orderKey(container, item.id)
       if (isDefault)
-        delete state.docksCustomOrder[item.id]
+        delete order[key]
       else
-        state.docksCustomOrder[item.id] = index
+        order[key] = index
     })
   })
 }
@@ -322,17 +314,10 @@ function doesContainerHaveCustomOrder(container: string): boolean {
 
 function resetCustomOrderForContainer(container: string) {
   const ids = customOrderIdsForContainer(container)
-  if (container === CATEGORY_ORDER_CONTAINER) {
-    props.settingsStore.mutate((state) => {
-      ids.forEach((id) => {
-        delete state.docksCategoriesOrder?.[categoryFromOrderId(id)]
-      })
-    })
-    return
-  }
   props.settingsStore.mutate((state) => {
+    const order = orderRecord(state, container)
     ids.forEach((id) => {
-      delete state.docksCustomOrder[id]
+      delete order[orderKey(container, id)]
     })
   })
 }
@@ -347,7 +332,6 @@ function resetCustomOrderForContainer(container: string) {
     <button
       v-if="doesContainerHaveCustomOrder(CATEGORY_ORDER_CONTAINER)"
       class="flex items-center gap-1 px-2 py-1 rounded hover:bg-gray/20 transition-colors text-xs op60 shrink-0"
-      title="Reset category order"
       @click="resetCustomOrderForContainer(CATEGORY_ORDER_CONTAINER)"
     >
       <div class="i-ph-arrows-counter-clockwise-duotone" />
@@ -356,27 +340,27 @@ function resetCustomOrderForContainer(container: string) {
   </div>
 
   <div ref="sortContainer" class="flex flex-col gap-4">
-    <template v-for="[category, entries] of categories" :key="category">
+    <template v-for="{ category, entries, dragId } of categoryHeaders" :key="category">
       <div
         class="border border-base rounded-lg overflow-hidden transition-opacity"
         :class="settings.docksCategoriesHidden.includes(category) ? 'op40' : ''"
       >
         <!-- Category header -->
         <div
-          :ref="(el: any) => isCategoryHideable(category) && setEntryRef(el, categoryOrderId(category), CATEGORY_ORDER_CONTAINER)"
-          :data-dock-id="isCategoryHideable(category) ? categoryOrderId(category) : undefined"
-          :data-container="isCategoryHideable(category) ? CATEGORY_ORDER_CONTAINER : undefined"
+          :ref="(el: any) => dragId && setEntryRef(el, dragId, CATEGORY_ORDER_CONTAINER)"
+          :data-dock-id="dragId"
+          :data-container="dragId && CATEGORY_ORDER_CONTAINER"
           class="flex items-center gap-2 px-4 py-3 bg-gray/5 cursor-pointer select-none border-b border-base"
           :class="[
-            hasMoved && draggingId === categoryOrderId(category) ? 'op30 bg-gray/10' : '',
-            dragOverId === categoryOrderId(category) ? 'ring-1.5 ring-purple/50 rounded' : '',
+            hasMoved && draggingId === dragId ? 'op30 bg-gray/10' : '',
+            dragOverId === dragId ? 'ring-1.5 ring-purple/50 rounded' : '',
           ]"
         >
-          <!-- drag icon (headers of ~pinned/~builtin never carry a container, so they never drag) -->
+          <!-- drag icon -->
           <div
-            v-if="isCategoryHideable(category)"
+            v-if="dragId"
             class="i-ph-dots-six-vertical w-4 h-4 shrink-0 op25 hover:op50 transition-opacity cursor-grab"
-            :style="hasMoved && draggingId === categoryOrderId(category) ? 'cursor: grabbing' : ''"
+            :style="hasMoved && draggingId === dragId ? 'cursor: grabbing' : ''"
           />
           <button
             class="w-5 h-5 flex items-center justify-center rounded transition-colors"
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index 540f36b71..9e70bf4af 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -29,10 +29,7 @@ export async function createDocksContext(
 
   const dockEntries = await useDocksEntries(rpc)
 
-  // Host-level dock config, merged from every plugin's `devtools.dock`
-  // declaration by `createDevToolsContext` and handed to us once as part of
-  // the connection handshake (`rpc.connectionMeta`) — fixed for the life of
-  // the dev server, so no shared-state subscription is needed to read it.
+  /** Host dock config, handed over once in the connection handshake. */
   const dockConfig: DevToolsDockConfig | undefined = rpc.connectionMeta.dockConfig
 
   // Client-only dock registry (0.7.10 `DocksEntriesContext` API). Docks
@@ -339,9 +336,7 @@ export async function createDocksContext(
   // Settings store, `settings`, and `getWhenContext` are established earlier
   // (right before `switchEntry`) — its group→member resolution needs them.
   const groupedEntries = computed(() => {
-    // Pre-merge the plugin-declared config beneath the user's own drag order
-    // into the one `categoryOrderOverride` slot `docksGroupByCategories`
-    // already has (user wins on a key both set).
+    // User drag order over the plugin-declared one.
     const categoryOrderOverride = { ...dockConfig?.categoryOrder, ...settings.value.docksCategoriesOrder }
     return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true, categoryOrderOverride })
   })
diff --git a/packages/core/src/client/webcomponents/state/dock-settings.ts b/packages/core/src/client/webcomponents/state/dock-settings.ts
index a30b3a727..25f13a07b 100644
--- a/packages/core/src/client/webcomponents/state/dock-settings.ts
+++ b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -28,14 +28,12 @@ export const PINNED_CATEGORY_ORDER = -100000
 
 /**
  * Resolve a category's sort weight, layering the local {@link PINNED_CATEGORY}
- * override, then a caller-supplied `overrides` map, on top of the upstream
- * {@link DEFAULT_CATEGORIES_ORDER} table. `overrides` is per-call — a caller
- * that wants a plugin-declared `DevToolsDockConfig.categoryOrder` layered
- * beneath the user's own drag-and-drop order pre-merges both into the one map
- * it passes (e.g. `{ ...config?.categoryOrder, ...docksCategoriesOrder }`);
- * {@link getGroupMembersGrouped} instead passes a group's own
- * {@link DevToolsViewGroup.categoryOrder}, reweighting only that group's
- * in-group sub-categories.
+ * override, then a caller-supplied `overrides` map (a group's own
+ * {@link DevToolsViewGroup.categoryOrder}, or a plugin-declared category order
+ * merged with the user's own), on top of the upstream
+ * {@link DEFAULT_CATEGORIES_ORDER} table. `overrides` is per-call — passing a
+ * group's map only reweights that group's in-group sub-categories, never the
+ * outer bar or any other group.
  */
 function categoryOrder(category: string, overrides?: Record<string, number>): number {
   if (category === PINNED_CATEGORY)
@@ -244,14 +242,12 @@ export function resolveGroupDefaultChild(
  * category is hidden.
  *
  * `categoryOrderOverride` reweights the categories produced by *this call*
- * — it never touches the shared {@link DEFAULT_CATEGORIES_ORDER} table, so it
- * has no effect on any other call, group, or the outer bar. Two distinct
- * callers use this same slot for two distinct purposes: {@link getGroupMembersGrouped}
- * passes a group's own {@link DevToolsViewGroup.categoryOrder} to reweight its
- * in-group sub-category split, while a top-level caller (the dock bar, the
- * Settings management view) pre-merges a plugin-declared
- * `DevToolsDockConfig.categoryOrder` with the user's own drag-and-drop
- * `docksCategoriesOrder` into the map it passes here.
+ * (used by {@link getGroupMembersGrouped} to apply a group's own
+ * {@link DevToolsViewGroup.categoryOrder} to its in-group sub-category split,
+ * and by top-level callers to layer the user's category order over the
+ * plugin-declared one) — it never touches the shared
+ * {@link DEFAULT_CATEGORIES_ORDER} table, so it has no effect on any other
+ * call, group, or the outer bar.
  */
 export function docksGroupByCategories(
   entries: DevToolsDockEntry[],
diff --git a/packages/core/src/node/context.ts b/packages/core/src/node/context.ts
index bfdbec0ed..2ddd8de36 100644
--- a/packages/core/src/node/context.ts
+++ b/packages/core/src/node/context.ts
@@ -109,10 +109,8 @@ export async function createDevToolsContext(
   if (viteServer || mode === 'build')
     context.views.hostStatic('/__devtools-assets/', dirAssets)
 
-  // Scan Vite plugins for `devtools` setup hooks, merging each plugin's
-  // `devtools.dock` config along the way (last plugin wins per scalar key;
-  // `categoryOrder` shallow-merges) — a plugin skipped for this mode's
-  // capabilities contributes nothing.
+  // Scan Vite plugins for `devtools` setup hooks, merging each plugin's declared
+  // dock config along the way (last wins per key; `categoryOrder` shallow-merges).
   const dockConfig: DevToolsDockConfig = {}
   const plugins = viteConfig.plugins.filter(plugin => 'devtools' in plugin)
   for (const plugin of plugins) {
@@ -122,11 +120,9 @@ export async function createDevToolsContext(
       debugSetup(`skipping plugin ${JSON.stringify(plugin.name)} due to disabled capabilities in ${mode} mode`)
       continue
     }
-    if (plugin.devtools.dock) {
-      Object.assign(dockConfig, plugin.devtools.dock, {
-        categoryOrder: { ...dockConfig.categoryOrder, ...plugin.devtools.dock.categoryOrder },
-      })
-    }
+    const dock = plugin.devtools.dock
+    if (dock)
+      Object.assign(dockConfig, dock, { categoryOrder: { ...dockConfig.categoryOrder, ...dock.categoryOrder } })
     try {
       debugSetup(`setting up plugin ${JSON.stringify(plugin.name)}`)
       await plugin.devtools?.setup?.(context)
@@ -135,10 +131,6 @@ export async function createDevToolsContext(
       throw diagnostics.DTK0014({ name: plugin.name, cause: error })
     }
   }
-  // Riding on `ConnectionMeta` rather than shared state (see the `ConnectionMeta`
-  // augmentation in `node/rpc/index.ts`) — `createWsServer`'s `getConnectionMeta`
-  // closure (`node/ws.ts`) reads it off this same context object, which is
-  // already fully built by the time that closure is created.
   context.dockConfig = dockConfig
 
   return context
diff --git a/packages/core/src/node/rpc/index.ts b/packages/core/src/node/rpc/index.ts
index ae2c6c0dc..913d599c8 100644
--- a/packages/core/src/node/rpc/index.ts
+++ b/packages/core/src/node/rpc/index.ts
@@ -70,13 +70,8 @@ declare module 'devframe/types' {
     'devframe:user-settings': DevToolsDocksUserSettings
   }
 
-  // Host-level dock config (`DevToolsDockConfig`, merged from every plugin's
-  // `devtools.dock` declaration in `createDevToolsContext`) rides on
-  // `ConnectionMeta` instead of a shared-state key: it is fixed for the life
-  // of the dev server, set once from `vite.config.ts` before any client
-  // connects, so it needs none of shared state's live-broadcast machinery —
-  // just the connection handshake every client already does once.
   interface ConnectionMeta {
+    /** Host dock config, fixed for the life of the dev server, so it rides the handshake instead of shared state. */
     dockConfig?: DevToolsDockConfig
   }
 }
diff --git a/packages/kit/src/types/settings.ts b/packages/kit/src/types/settings.ts
index 98b029dcf..e3ac46675 100644
--- a/packages/kit/src/types/settings.ts
+++ b/packages/kit/src/types/settings.ts
@@ -17,10 +17,8 @@ export interface DevToolsDocksUserSettings extends DevframeDocksUserSettings {
   showDevframeInspector?: boolean
 
   /**
-   * User drag-and-drop order for top-level dock categories, keyed by category
-   * id with lower first — the same convention as a plugin's declared
-   * `DevToolsDockConfig.categoryOrder`, which this overrides. Absent
-   * categories fall back to the declared or upstream order.
+   * User drag-and-drop order for top-level dock categories, lower first.
+   * Overrides a plugin's declared `DevToolsDockConfig.categoryOrder`.
    */
   docksCategoriesOrder?: Record<string, number>
 }
diff --git a/packages/kit/src/types/vite-plugin.ts b/packages/kit/src/types/vite-plugin.ts
index a7b701904..2240ff5fe 100644
--- a/packages/kit/src/types/vite-plugin.ts
+++ b/packages/kit/src/types/vite-plugin.ts
@@ -3,20 +3,14 @@ import type { ResolvedConfig, ViteDevServer } from 'vite'
 import type { KitNodeContext } from '../node/context'
 
 /**
- * Host-level dock defaults a plugin can declare alongside its `setup()`. Every
- * field here is host-global rather than per-entry, so plugins share one
- * config object instead of each dock entry needing its own "which entry wins"
- * rule. Collected from every plugin's `devtools.dock` during the Vite plugin
- * scan (`createDevToolsContext`), merged (later plugins win per scalar key;
- * `categoryOrder` shallow-merges) onto {@link ViteDevToolsNodeContext.dockConfig},
- * and handed to every client once via `ConnectionMeta`.
+ * Host-wide dock defaults a plugin declares alongside its `setup()`. Collected
+ * from every plugin during the Vite plugin scan (`createDevToolsContext`, last
+ * wins per key) and handed to every client once via `ConnectionMeta`.
  */
 export interface DevToolsDockConfig {
   /**
    * Top-level category weights, lower first. Layered over
    * `DEFAULT_CATEGORIES_ORDER`, beneath the user's own drag-and-drop order.
-   * Name and shape deliberately mirror hub's own
-   * `createDevframeClientHost({ categoryOrder })` and `DevframeViewGroup.categoryOrder`.
    */
   categoryOrder?: Record<string, number>
   /** Items shown inline on the float bar before the overflow button. Defaults to 5; clamped to `>= 1`. */
@@ -48,10 +42,6 @@ export interface DevToolsPluginOptions {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig
   readonly viteServer?: ViteDevServer
-  /**
-   * Dock config merged from every plugin's `devtools.dock` declaration,
-   * assigned once by `createDevToolsContext` after its plugin scan. Read by
-   * `createWsServer`'s `getConnectionMeta` to hand it to every client.
-   */
+  /** Dock config merged from every plugin's `devtools.dock`, assigned once after the plugin scan. */
   dockConfig?: DevToolsDockConfig
 }

From f128ced22913fbf1c554d30bb2fc723dfdae9b30 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 6 Aug 2026 12:29:53 +0200
Subject: [PATCH 3/3] refactore(core): move dock to shared state

---
 docs/guide/index.md                           | 26 ++++++
 docs/kit/devtools-plugin.md                   | 33 ++++++++
 .../core/src/client/inject/runtime.test.ts    | 83 ++++++++++++++++++-
 packages/core/src/client/inject/runtime.ts    | 55 ++++++++++--
 packages/core/src/client/standalone/App.vue   |  4 +-
 .../webcomponents/components/DockEmbedded.ts  |  4 +-
 .../components/DockStandalone.ts              |  4 +-
 .../webcomponents/components/dock/Dock.vue    |  8 +-
 .../components/dock/DockContextMenu.ts        | 10 +--
 .../components/dock/DockEdge.vue              |  4 +-
 .../components/dock/DockEmbedded.vue          |  4 +-
 .../components/dock/DockEntries.vue           |  4 +-
 .../dock/DockEntriesWithCategories.vue        |  4 +-
 .../components/dock/DockEntry.vue             |  4 +-
 .../components/dock/DockGroupButton.vue       |  4 +-
 .../components/dock/DockOverflowButton.vue    |  4 +-
 .../components/dock/DockPanel.vue             |  4 +-
 .../components/dock/DockStandalone.vue        |  4 +-
 .../views-builtin/SettingsAdvanced.vue        |  2 +-
 .../views-builtin/SettingsAppearance.vue      |  4 +-
 .../views-builtin/SettingsDocks.vue           |  8 +-
 .../views-builtin/ViewBuiltinSettings.vue     |  4 +-
 .../components/views/ViewEntry.vue            |  4 +-
 .../core/src/client/webcomponents/index.ts    |  1 +
 .../state/__tests__/context-cache.test.ts     |  8 +-
 .../state/__tests__/frame-nav.test.ts         |  4 +-
 .../state/__tests__/popup.test.ts             | 14 ++--
 .../src/client/webcomponents/state/context.ts | 29 +++++--
 .../webcomponents/state/dock-settings.ts      |  6 +-
 .../src/client/webcomponents/state/popup.ts   | 18 ++--
 .../webcomponents/stories/mock-context.ts     | 20 +++--
 .../webcomponents/stories/story-helpers.ts    |  6 +-
 packages/core/src/node/context.ts             | 32 +++++--
 packages/core/src/node/plugins/build.ts       |  6 +-
 packages/core/src/node/plugins/index.ts       | 14 +++-
 packages/core/src/node/plugins/server.ts      | 11 ++-
 packages/core/src/node/rpc/index.ts           |  6 +-
 packages/core/src/node/standalone.ts          | 12 ++-
 packages/core/src/node/ws.ts                  |  1 -
 packages/kit/src/types/settings.ts            |  2 +-
 packages/kit/src/types/vite-plugin.ts         | 45 +++++++---
 playgrounds/core/vite.config.ts               | 26 ++++++
 .../@vitejs/devtools-kit/index.snapshot.d.ts  |  8 +-
 .../client/webcomponents.snapshot.d.ts        |  7 +-
 .../@vitejs/devtools/index.snapshot.d.ts      |  2 +-
 .../tsnapi/@vitejs/devtools/index.snapshot.js |  2 +-
 46 files changed, 434 insertions(+), 131 deletions(-)

diff --git a/docs/guide/index.md b/docs/guide/index.md
index a04cfcc58..ed4236095 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -114,6 +114,32 @@ export default defineConfig({
 })
 ```
 
+#### Dock defaults
+
+`dock` sets host-wide dock defaults — category order, the float bar's inline
+capacity, and the initial window placement:
+
+```ts [vite.config.ts] twoslash
+import { DevTools } from '@vitejs/devtools'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    DevTools({
+      dock: {
+        categoryOrder: { web: -60, advanced: -50, app: -40 },
+        maxVisibleItems: 8,
+        defaultMode: 'edge',
+        defaultPosition: 'left',
+      },
+    }),
+  ],
+})
+```
+
+A plugin may additionally declare its own `devtools.dock.categoryOrder` to
+weigh the categories it contributes — see [Dock config](/kit/devtools-plugin#dock-config).
+
 #### Projects without an HTML entry
 
 For apps where Vite doesn't serve the HTML (JS-only entries, backend integration, middleware mode), import the client injector from a browser entry instead. One entry per visibility mode — import whichever one you want:
diff --git a/docs/kit/devtools-plugin.md b/docs/kit/devtools-plugin.md
index 9221f3ccd..de63ff9bd 100644
--- a/docs/kit/devtools-plugin.md
+++ b/docs/kit/devtools-plugin.md
@@ -85,6 +85,7 @@ const plugin: Plugin = {
 | Property | Type | Description |
 |----------|------|-------------|
 | `ctx.docks` | `DocksHost` | Register and manage [dock entries](./dock-system) |
+| `ctx.dockConfig` | `SharedState<DevToolsDockConfig>` | Merged dock config — see [Dock config](#dock-config) below |
 | `ctx.views` | `ViewsHost` | Host static files for your DevTools UI |
 | `ctx.rpc` | `RpcHost` | Register [RPC functions](./rpc) and broadcast to clients |
 | `ctx.viteConfig` | `ResolvedConfig` | The resolved Vite configuration |
@@ -93,6 +94,38 @@ const plugin: Plugin = {
 | `ctx.cwd` | `string` | Current working directory |
 | `ctx.workspaceRoot` | `string` | Workspace root directory |
 
+### Dock config
+
+A plugin can declare `devtools.dock.categoryOrder` alongside `setup()` to weigh
+the categories its own entries fall into — it shallow-merges with every other
+plugin's declaration:
+
+```ts
+const plugin: Plugin = {
+  devtools: {
+    dock: {
+      categoryOrder: { 'my-plugin': -40 },
+    },
+    setup(ctx) {
+      // ...
+    },
+  },
+}
+```
+
+`maxVisibleItems`, `defaultMode`, and `defaultPosition` are properties of the
+one shared dock bar, not of any single plugin, so they're set once by the host
+via `DevTools({ dock })` instead (see the [Getting Started guide](/guide/#the-devtools-plugin)).
+
+The merged result is `ctx.dockConfig` — a `SharedState`, synced to every
+connected client, that a plugin can `mutate()` to reconfigure them live:
+
+```ts
+ctx.dockConfig.mutate((config) => {
+  config.maxVisibleItems = 8
+})
+```
+
 ### Example: accessing Vite config
 
 ```ts
diff --git a/packages/core/src/client/inject/runtime.test.ts b/packages/core/src/client/inject/runtime.test.ts
index d653aaf5e..563b596c4 100644
--- a/packages/core/src/client/inject/runtime.test.ts
+++ b/packages/core/src/client/inject/runtime.test.ts
@@ -1,5 +1,10 @@
+import type { DevToolsDockConfig } from '@vitejs/devtools-kit'
+import type { DevToolsRpcClient, DockPanelStorage } from '@vitejs/devtools-kit/client'
+import type { Ref } from 'vue'
+import { createSharedState } from 'devframe/utils/shared-state'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { startDevTools } from './runtime'
+import { ref } from 'vue'
+import { seedWindowDefaultsOnce, startDevTools } from './runtime'
 
 const mocks = vi.hoisted(() => ({
   getDevToolsRpcClient: vi.fn(
@@ -51,3 +56,79 @@ describe('injected DevTools runtime', () => {
     )
   })
 })
+
+describe('seedWindowDefaultsOnce', () => {
+  function mockRpc(initialValue: DevToolsDockConfig) {
+    const state = createSharedState({ initialValue, enablePatches: false })
+    return {
+      sharedState: {
+        get: async () => state,
+      },
+    } as unknown as DevToolsRpcClient
+  }
+
+  function panelState(): Ref<DockPanelStorage> {
+    return ref<DockPanelStorage>({
+      mode: 'float',
+      width: 80,
+      height: 80,
+      top: 0,
+      left: 0,
+      position: 'left',
+      open: false,
+      inactiveTimeout: 3_000,
+    })
+  }
+
+  it('applies an already-available default mode and position', async () => {
+    const state = panelState()
+    await seedWindowDefaultsOnce(mockRpc({ defaultMode: 'edge', defaultPosition: 'right' }), state)
+
+    expect(state.value.mode).toBe('edge')
+    expect(state.value.position).toBe('right')
+  })
+
+  it('leaves the fallback untouched when nothing is declared', async () => {
+    const state = panelState()
+    await seedWindowDefaultsOnce(mockRpc({}), state)
+
+    expect(state.value.mode).toBe('float')
+    expect(state.value.position).toBe('left')
+  })
+
+  it('applies only the declared field, leaving the other at its fallback', async () => {
+    const state = panelState()
+    await seedWindowDefaultsOnce(mockRpc({ defaultMode: 'edge' }), state)
+
+    expect(state.value.mode).toBe('edge')
+    expect(state.value.position).toBe('left')
+  })
+
+  it('applies the default once it arrives later, and only once', async () => {
+    const sharedState = createSharedState<DevToolsDockConfig>({ initialValue: {}, enablePatches: false })
+    const rpc = {
+      sharedState: {
+        get: async () => sharedState,
+      },
+    } as unknown as DevToolsRpcClient
+    const state = panelState()
+
+    const seeded = seedWindowDefaultsOnce(rpc, state)
+    sharedState.mutate((config) => {
+      config.defaultMode = 'edge'
+      config.defaultPosition = 'right'
+    })
+    await seeded
+
+    expect(state.value.mode).toBe('edge')
+    expect(state.value.position).toBe('right')
+
+    // A later reconfiguration (e.g. `ctx.dockConfig.mutate()`) must not keep
+    // repositioning a dock the developer has since moved.
+    state.value.mode = 'float'
+    sharedState.mutate((config) => {
+      config.defaultMode = 'edge'
+    })
+    expect(state.value.mode).toBe('float')
+  })
+})
diff --git a/packages/core/src/client/inject/runtime.ts b/packages/core/src/client/inject/runtime.ts
index 635bd80d5..d262921e5 100644
--- a/packages/core/src/client/inject/runtime.ts
+++ b/packages/core/src/client/inject/runtime.ts
@@ -1,13 +1,17 @@
 /// <reference types="vite/client" />
 /// <reference lib="dom" />
 
-import type { DockPanelStorage } from '@vitejs/devtools-kit/client'
+import type { DevToolsDockConfig } from '@vitejs/devtools-kit'
+import type { DevToolsRpcClient, DockPanelStorage } from '@vitejs/devtools-kit/client'
+import type { Ref } from 'vue'
 import { CLIENT_CONTEXT_KEY, getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
 import { DEVTOOLS_MOUNT_PATH } from '@vitejs/devtools-kit/constants'
 import { useLocalStorage } from '@vueuse/core'
 import { DEVTOOLS_HIDE_EVENT, DEVTOOLS_MODE_FILENAME } from '../../constants'
 import { createDocksContext } from '../webcomponents/state/context'
 
+const DOCK_STATE_STORAGE_KEY = 'vite-devtools-dock-state'
+
 export type InjectMode = 'passive' | 'normal' | 'hidden'
 
 // Persistence endpoint the node middleware serves next to `__connection.json`.
@@ -33,6 +37,40 @@ function matchesActivation(event: KeyboardEvent): boolean {
     && (event.code === 'KeyD' || event.key === 'd' || event.key === 'D')
 }
 
+/**
+ * Seeds `state.mode`/`.position` from the host's declared `defaultMode`/
+ * `defaultPosition`, once, for a developer with no stored preference yet.
+ *
+ * The client's `sharedState.get()` resolves immediately with just
+ * `initialValue` while the connection is still untrusted — the normal
+ * first-load case — so the declared config usually lands after `state` (and
+ * the dock) already exist. Applying it retroactively here, exactly once,
+ * avoids depending on `useLocalStorage`'s `mergeDefaults`, which would have
+ * already persisted the fallback `float`/`left` and made the seed a no-op on
+ * every later load too.
+ */
+export async function seedWindowDefaultsOnce(rpc: DevToolsRpcClient, state: Ref<DockPanelStorage>): Promise<void> {
+  const configState = await rpc.sharedState.get<DevToolsDockConfig>('devtools:dock-config', { initialValue: {} })
+
+  const applyOnce = (config: DevToolsDockConfig): boolean => {
+    if (config.defaultMode == null && config.defaultPosition == null)
+      return false
+    if (config.defaultMode != null)
+      state.value.mode = config.defaultMode
+    if (config.defaultPosition != null)
+      state.value.position = config.defaultPosition
+    return true
+  }
+
+  if (applyOnce(configState.value()))
+    return
+
+  const unsubscribe = configState.on('updated', (config) => {
+    if (applyOnce(config))
+      unsubscribe()
+  })
+}
+
 async function persistNormalMode(enabled: boolean): Promise<void> {
   try {
     await fetch(MODE_URL, {
@@ -60,23 +98,26 @@ async function mountDock(): Promise<void> {
     ],
   })
 
-  // Plugin-declared mode/position only seed the defaults — `mergeDefaults` never
-  // overwrites a developer's stored preference.
-  const dockConfig = rpc.connectionMeta.dockConfig
+  // Read before `useLocalStorage` creates/touches the entry below — the write
+  // it does on every load would otherwise erase the "nothing stored yet"
+  // signal `seedWindowDefaultsOnce` needs.
+  const hasStoredDockState = localStorage.getItem(DOCK_STATE_STORAGE_KEY) !== null
   const state = useLocalStorage<DockPanelStorage>(
-    'vite-devtools-dock-state',
+    DOCK_STATE_STORAGE_KEY,
     {
-      mode: dockConfig?.defaultMode ?? 'float',
+      mode: 'float',
       width: 80,
       height: 80,
       top: 0,
       left: 0,
-      position: dockConfig?.defaultPosition ?? 'left',
+      position: 'left',
       open: false,
       inactiveTimeout: 3_000,
     },
     { mergeDefaults: true },
   )
+  if (!hasStoredDockState)
+    void seedWindowDefaultsOnce(rpc, state)
 
   const context = await createDocksContext(
     'embedded',
diff --git a/packages/core/src/client/standalone/App.vue b/packages/core/src/client/standalone/App.vue
index 043d85e54..0813ee8ce 100644
--- a/packages/core/src/client/standalone/App.vue
+++ b/packages/core/src/client/standalone/App.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../webcomponents/state/context'
 import { CLIENT_CONTEXT_KEY, getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
 import { watchEffect } from 'vue'
 import DockStandalone from '../webcomponents/components/dock/DockStandalone.vue'
@@ -21,7 +21,7 @@ const rpc = await getDevToolsRpcClient()
 // eslint-disable-next-line no-console
 console.log('[VITE DEVTOOLS] RPC', rpc)
 
-const context: DocksContext = await createDocksContext(
+const context: DevToolsDocksContext = await createDocksContext(
   'standalone',
   rpc,
 )
diff --git a/packages/core/src/client/webcomponents/components/DockEmbedded.ts b/packages/core/src/client/webcomponents/components/DockEmbedded.ts
index f08fa9ed5..e4f94bfe5 100644
--- a/packages/core/src/client/webcomponents/components/DockEmbedded.ts
+++ b/packages/core/src/client/webcomponents/components/DockEmbedded.ts
@@ -1,5 +1,5 @@
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { VueElementConstructor } from 'vue'
+import type { DevToolsDocksContext } from '../state/context'
 import { defineCustomElement } from 'vue'
 import css from '../.generated/css'
 import Component from './dock/DockEmbedded.vue'
@@ -11,7 +11,7 @@ export const DockEmbedded = defineCustomElement(
     styles: [css],
   },
 ) as VueElementConstructor<{
-  context: DocksContext
+  context: DevToolsDocksContext
 }>
 
 customElements.define('vite-devtools-dock-embedded', DockEmbedded)
diff --git a/packages/core/src/client/webcomponents/components/DockStandalone.ts b/packages/core/src/client/webcomponents/components/DockStandalone.ts
index 8614ac1b3..260e55e1b 100644
--- a/packages/core/src/client/webcomponents/components/DockStandalone.ts
+++ b/packages/core/src/client/webcomponents/components/DockStandalone.ts
@@ -1,5 +1,5 @@
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { VueElementConstructor } from 'vue'
+import type { DevToolsDocksContext } from '../state/context'
 import { defineCustomElement } from 'vue'
 import css from '../.generated/css'
 import Component from './dock/DockStandalone.vue'
@@ -11,7 +11,7 @@ export const DockStandalone = defineCustomElement(
     styles: [css],
   },
 ) as VueElementConstructor<{
-  context: DocksContext
+  context: DevToolsDocksContext
 }>
 
 if (!customElements.get('vite-devtools-dock-standalone'))
diff --git a/packages/core/src/client/webcomponents/components/dock/Dock.vue b/packages/core/src/client/webcomponents/components/dock/Dock.vue
index d0ed5e1fb..511697463 100644
--- a/packages/core/src/client/webcomponents/components/dock/Dock.vue
+++ b/packages/core/src/client/webcomponents/components/dock/Dock.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { CSSProperties } from 'vue'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DockLayout } from './dock-layout'
 import { useEventListener, useScreenSafeArea, whenever } from '@vueuse/core'
 import { computed, onMounted, reactive, ref, useTemplateRef } from 'vue'
@@ -23,7 +23,7 @@ import DockEntriesWithCategories from './DockEntriesWithCategories.vue'
 import DockOverflowButton from './DockOverflowButton.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   /**
    * Override individual dock layout tunables (bar height, item capacity,
    * viewport margin, snapping, ...). Merged over `DEFAULT_DOCK_LAYOUT`.
@@ -34,9 +34,9 @@ const props = defineProps<{
 // Here we directly destructure is as we don't expect context to be changed
 const context = props.context
 
-// A plugin-declared `maxVisibleItems` is the default; an explicit `layout` prop wins.
+// A plugin/host-declared `maxVisibleItems` is the default; an explicit `layout` prop wins.
 const layout = computed(() => resolveDockLayout({
-  maxVisibleItems: context.rpc.connectionMeta.dockConfig?.maxVisibleItems,
+  maxVisibleItems: context.dockConfig.maxVisibleItems,
   ...props.layout,
 }))
 
diff --git a/packages/core/src/client/webcomponents/components/dock/DockContextMenu.ts b/packages/core/src/client/webcomponents/components/dock/DockContextMenu.ts
index f85948ee2..a4216624f 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockContextMenu.ts
+++ b/packages/core/src/client/webcomponents/components/dock/DockContextMenu.ts
@@ -1,5 +1,5 @@
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { h } from 'vue'
 import { setDockContextMenu } from '../../state/floating-tooltip'
 import { isDockPopupSupported, requestDockPopupOpen, useIsDockPopupOpen } from '../../state/popup'
@@ -23,7 +23,7 @@ function renderMenuItem(item: DockMenuItem) {
   ])
 }
 
-function hideDock(context: DocksContext, entry: DevToolsDockEntry) {
+function hideDock(context: DevToolsDocksContext, entry: DevToolsDockEntry) {
   const settingsStore = context.docks.settings
   const id = entry.id
   settingsStore.mutate((state) => {
@@ -35,7 +35,7 @@ function hideDock(context: DocksContext, entry: DevToolsDockEntry) {
   setDockContextMenu(null)
 }
 
-function refreshDock(context: DocksContext, entry: DevToolsDockEntry) {
+function refreshDock(context: DevToolsDocksContext, entry: DevToolsDockEntry) {
   const state = context.docks.getStateById(entry.id)
   const iframe = state?.domElements.iframe
   if (!iframe) {
@@ -48,7 +48,7 @@ function refreshDock(context: DocksContext, entry: DevToolsDockEntry) {
   setDockContextMenu(null)
 }
 
-function canHide(context: DocksContext, entry: DevToolsDockEntry) {
+function canHide(context: DevToolsDocksContext, entry: DevToolsDockEntry) {
   if (entry.id === '~settings')
     return false
   return context.docks.entries.some(item => item.id === entry.id)
@@ -59,7 +59,7 @@ function canRefresh(entry: DevToolsDockEntry) {
 }
 
 export function openDockContextMenu(options: {
-  context: DocksContext
+  context: DevToolsDocksContext
   entry: DevToolsDockEntry
   el: HTMLElement
   gap?: number
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEdge.vue b/packages/core/src/client/webcomponents/components/dock/DockEdge.vue
index b676df964..61592993f 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEdge.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEdge.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { CSSProperties } from 'vue'
+import type { DevToolsDocksContext } from '../../state/context'
 import { computed, h, useTemplateRef } from 'vue'
 import { getEntryGroup } from '../../state/dock-settings'
 import { setEdgePositionDropdown, setFloatingTooltip, useEdgePositionDropdown } from '../../state/floating-tooltip'
@@ -11,7 +11,7 @@ import DockGroupSidebar from './DockGroupSidebar.vue'
 import DockPanelResizer from './DockPanelResizer.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
 }>()
 
 const context = props.context
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
index 142773512..fe76bc8da 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEmbedded.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DockLayout } from './dock-layout'
 import { useEventListener } from '@vueuse/core'
 import { onUnmounted } from 'vue'
@@ -16,7 +16,7 @@ import DockEdge from './DockEdge.vue'
 import DockPanel from './DockPanel.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   /** Override dock layout tunables (forwarded to the float-mode bar + panel). */
   layout?: Partial<DockLayout>
 }>()
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntries.vue b/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
index 299d628e3..35f409feb 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { evaluateWhen } from 'devframe/utils/when'
 import { toRefs } from 'vue'
 import { getGroupMembers, resolveGroupDefaultChild } from '../../state/dock-settings'
@@ -9,7 +9,7 @@ import DockEntry from './DockEntry.vue'
 import DockGroupButton from './DockGroupButton.vue'
 
 const props = withDefaults(defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   entries: DevToolsDockEntry[]
   selected: DevToolsDockEntry | null
   isVertical: boolean
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntriesWithCategories.vue b/packages/core/src/client/webcomponents/components/dock/DockEntriesWithCategories.vue
index 38063cdaa..8430a7071 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntriesWithCategories.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntriesWithCategories.vue
@@ -1,11 +1,11 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DevToolsDockEntriesGrouped } from '../../state/dock-settings'
 import DockEntries from './DockEntries.vue'
 
 withDefaults(defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   groups: DevToolsDockEntriesGrouped
   selected: DevToolsDockEntry | null
   isVertical: boolean
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
index a94574bd6..04b7dc9c2 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { DevToolsDockEntryBase } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { useEventListener } from '@vueuse/core'
 import { computed, useTemplateRef } from 'vue'
 import { setFloatingTooltip } from '../../state/floating-tooltip'
@@ -10,7 +10,7 @@ import DockIcon from './DockIcon.vue'
 
 const props = withDefaults(
   defineProps<{
-    context: DocksContext
+    context: DevToolsDocksContext
     dock: DevToolsDockEntryBase
     isAction?: boolean
     isSelected?: boolean
diff --git a/packages/core/src/client/webcomponents/components/dock/DockGroupButton.vue b/packages/core/src/client/webcomponents/components/dock/DockGroupButton.vue
index 27a9125b8..ad4b3e763 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockGroupButton.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockGroupButton.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry, DevToolsViewGroup } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { watchDebounced } from '@vueuse/core'
 import { computed, h, ref, useTemplateRef } from 'vue'
 import { getGroupMembers, getGroupMembersGrouped, resolveGroupDefaultChild } from '../../state/dock-settings'
@@ -10,7 +10,7 @@ import DockEntry from './DockEntry.vue'
 import DockGroupPopover from './DockGroupPopover.vue'
 
 const props = withDefaults(defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   group: DevToolsViewGroup
   isVertical: boolean
   selected: DevToolsDockEntry | null
diff --git a/packages/core/src/client/webcomponents/components/dock/DockOverflowButton.vue b/packages/core/src/client/webcomponents/components/dock/DockOverflowButton.vue
index acd1ed052..3010a94e1 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockOverflowButton.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockOverflowButton.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DevToolsDockEntriesGrouped } from '../../state/dock-settings'
 import { watchDebounced } from '@vueuse/core'
 import { computed, h, ref, useTemplateRef } from 'vue'
@@ -9,7 +9,7 @@ import DockEntriesWithCategories from './DockEntriesWithCategories.vue'
 import DockEntry from './DockEntry.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   isVertical: boolean
   groups: DevToolsDockEntriesGrouped
   selected: DevToolsDockEntry | null
diff --git a/packages/core/src/client/webcomponents/components/dock/DockPanel.vue b/packages/core/src/client/webcomponents/components/dock/DockPanel.vue
index b5a16d075..2da2edd19 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockPanel.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockPanel.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { CSSProperties } from 'vue'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DockLayout } from './dock-layout'
 import { useElementBounding, useWindowSize } from '@vueuse/core'
 import { computed, onMounted, reactive, ref, toRefs, useTemplateRef } from 'vue'
@@ -14,7 +14,7 @@ import DockGroupSidebar from './DockGroupSidebar.vue'
 import DockPanelResizer from './DockPanelResizer.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   selected: DevToolsDockEntry | null
   dockEl?: HTMLDivElement
   panelMargins: { left: number, top: number, right: number, bottom: number }
diff --git a/packages/core/src/client/webcomponents/components/dock/DockStandalone.vue b/packages/core/src/client/webcomponents/components/dock/DockStandalone.vue
index 1b71657ab..cd667ef7f 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockStandalone.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockStandalone.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { computed, useTemplateRef, watch } from 'vue'
 import { getEntryGroup } from '../../state/dock-settings'
 import { getEntryPaneKey, useIframePanes } from '../../utils/useIframePanes'
@@ -16,7 +16,7 @@ import DockEntriesWithCategories from './DockEntriesWithCategories.vue'
 import DockGroupSidebar from './DockGroupSidebar.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
 }>()
 
 const context = props.context
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
index ce79bdfee..99612f4c3 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
@@ -46,7 +46,7 @@ async function resetDocks() {
       state.docksHidden = defaults.docksHidden
       state.docksCategoriesHidden = defaults.docksCategoriesHidden
       state.docksCustomOrder = defaults.docksCustomOrder
-      state.docksCategoriesOrder = {}
+      delete state.docksCategoriesOrder
       state.docksPinned = defaults.docksPinned
     })
   }
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAppearance.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAppearance.vue
index 651309bff..6e63835d7 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAppearance.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAppearance.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DevToolsDocksUserSettings } from '../../state/dock-settings'
 import { computed } from 'vue'
 import { colorSchemePreference, setColorSchemePreference } from '../../state/color-mode'
@@ -8,7 +8,7 @@ import { sharedStateToRef } from '../../state/docks'
 import { isDockPopupSupported, requestDockPopupOpen, useIsDockPopupOpen } from '../../state/popup'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   settingsStore: SharedState<DevToolsDocksUserSettings>
 }>()
 
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
index f92dfce68..5fa99a035 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsDocks.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
+import type { DevToolsDocksContext } from '../../state/context'
 import type { DevToolsDockEntriesGrouped, DevToolsDocksUserSettings } from '../../state/dock-settings'
 import { useDraggable } from '@vueuse/core'
 import { computed, ref, useTemplateRef } from 'vue'
@@ -11,7 +11,7 @@ import HashBadge from '../display/HashBadge.vue'
 import DockIcon from '../dock/DockIcon.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   settingsStore: SharedState<DevToolsDocksUserSettings>
 }>()
 
@@ -21,7 +21,7 @@ const settings = sharedStateToRef(props.settingsStore)
 // group button. A group's members are split by their in-group sub-category, and
 // each sub-category is its own reorderable container (`grp:<id>:::<subcat>`);
 // category containers are keyed `cat:<name>`.
-const configCategoryOrder = computed(() => props.context.rpc.connectionMeta.dockConfig?.categoryOrder)
+const configCategoryOrder = computed(() => props.context.dockConfig.categoryOrder)
 
 function groupByCategories(categoryOrderOverride?: Record<string, number>): DevToolsDockEntriesGrouped {
   return docksGroupByCategories(props.context.docks.entries, settings.value, {
@@ -31,7 +31,7 @@ function groupByCategories(categoryOrderOverride?: Record<string, number>): DevT
   })
 }
 
-// User drag order over the plugin-declared one.
+// User drag order over the plugin/host-declared one.
 const categories = computed(() => groupByCategories({ ...configCategoryOrder.value, ...settings.value.docksCategoriesOrder }))
 
 function membersOf(groupId: string): DevToolsDockEntry[] {
diff --git a/packages/core/src/client/webcomponents/components/views-builtin/ViewBuiltinSettings.vue b/packages/core/src/client/webcomponents/components/views-builtin/ViewBuiltinSettings.vue
index 51d372103..1fa76a946 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/ViewBuiltinSettings.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/ViewBuiltinSettings.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { DevToolsViewBuiltin } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../../state/context'
 import { ref } from 'vue'
 import SettingsAdvanced from './SettingsAdvanced.vue'
 import SettingsAppearance from './SettingsAppearance.vue'
@@ -8,7 +8,7 @@ import SettingsDocks from './SettingsDocks.vue'
 import SettingsShortcuts from './SettingsShortcuts.vue'
 
 const props = defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   entry: DevToolsViewBuiltin
 }>()
 
diff --git a/packages/core/src/client/webcomponents/components/views/ViewEntry.vue b/packages/core/src/client/webcomponents/components/views/ViewEntry.vue
index 931a9de24..0d9739f91 100644
--- a/packages/core/src/client/webcomponents/components/views/ViewEntry.vue
+++ b/packages/core/src/client/webcomponents/components/views/ViewEntry.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import type { DocksContext } from '@vitejs/devtools-kit/client'
 import type { IframePanes } from 'iframe-pane'
 import type { CSSProperties } from 'vue'
+import type { DevToolsDocksContext } from '../../state/context'
 import { defineAsyncComponent } from 'vue'
 import ViewBuiltinClientAuthNotice from '../views-builtin/ViewBuiltinClientAuthNotice.vue'
 import ViewBuiltinSettings from '../views-builtin/ViewBuiltinSettings.vue'
@@ -11,7 +11,7 @@ import ViewIframe from './ViewIframe.vue'
 import ViewLauncher from './ViewLauncher.vue'
 
 defineProps<{
-  context: DocksContext
+  context: DevToolsDocksContext
   entry: DevToolsDockEntry
   panes: IframePanes
   iframeStyle?: CSSProperties
diff --git a/packages/core/src/client/webcomponents/index.ts b/packages/core/src/client/webcomponents/index.ts
index c7c0ba582..bf7e65531 100644
--- a/packages/core/src/client/webcomponents/index.ts
+++ b/packages/core/src/client/webcomponents/index.ts
@@ -28,5 +28,6 @@ export type {
   TextProps,
   TreeProps,
 } from './json-render/registry'
+export type { DevToolsDocksContext } from './state/context'
 
 export * from './state/docks'
diff --git a/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts b/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
index 062535ffa..eac95caed 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/context-cache.test.ts
@@ -22,11 +22,15 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
     enablePatches: false,
   })
 
+  const dockConfigState = createSharedState({
+    initialValue: {},
+    enablePatches: false,
+  })
+
   return {
     client: {
       register: () => () => {},
     },
-    connectionMeta: { backend: 'websocket' },
     sharedState: {
       get: async (key: string) => {
         if (key === 'devframe:docks')
@@ -35,6 +39,8 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
           return settingsState as any
         if (key === 'devframe:commands')
           return commandsState as any
+        if (key === 'devtools:dock-config')
+          return dockConfigState as any
         throw new Error(`Unexpected shared state key: ${key}`)
       },
     },
diff --git a/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts b/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
index 143140b43..10646783d 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/frame-nav.test.ts
@@ -10,10 +10,10 @@ 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 })
+  const dockConfigState = createSharedState({ initialValue: {}, enablePatches: false })
 
   return {
     client: { register: () => () => {} },
-    connectionMeta: { backend: 'websocket' },
     sharedState: {
       get: async (key: string) => {
         if (key === 'devframe:docks')
@@ -22,6 +22,8 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
           return settingsState as any
         if (key === 'devframe:commands')
           return commandsState as any
+        if (key === 'devtools:dock-config')
+          return dockConfigState as any
         throw new Error(`Unexpected shared state key: ${key}`)
       },
     },
diff --git a/packages/core/src/client/webcomponents/state/__tests__/popup.test.ts b/packages/core/src/client/webcomponents/state/__tests__/popup.test.ts
index 6fba0d537..dfe6491ca 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/popup.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/popup.test.ts
@@ -1,4 +1,4 @@
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../context'
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import { setDocksOverflowPanel, useDocksOverflowPanel } from '../floating-tooltip'
 import { closeDockPopup, isDockPopupSupported, openDockPopup, setDockStandaloneLoaderForTest, useDockPopupWindow, useIsDockPopupOpen } from '../popup'
@@ -9,12 +9,12 @@ const {
   dockElementRemoveMock,
 } = vi.hoisted(() => {
   const dockElementRemoveMock = vi.fn()
-  const dockStandaloneCtorCalls: Array<{ context: DocksContext }> = []
+  const dockStandaloneCtorCalls: Array<{ context: DevToolsDocksContext }> = []
   class DockStandaloneElementMock {
-    context: DocksContext
+    context: DevToolsDocksContext
     remove: () => void
     style: Record<string, string>
-    constructor({ context }: { context: DocksContext }) {
+    constructor({ context }: { context: DevToolsDocksContext }) {
       this.context = context
       this.remove = dockElementRemoveMock
       this.style = {}
@@ -22,7 +22,7 @@ const {
     }
   }
   return {
-    DockStandaloneElementMock: DockStandaloneElementMock as unknown as new (props: { context: DocksContext }) => HTMLElement,
+    DockStandaloneElementMock: DockStandaloneElementMock as unknown as new (props: { context: DevToolsDocksContext }) => HTMLElement,
     dockStandaloneCtorCalls,
     dockElementRemoveMock,
   }
@@ -36,7 +36,7 @@ function createMockContext(
     width?: number
     height?: number
   } = {},
-): DocksContext {
+): DevToolsDocksContext {
   return {
     panel: {
       store: {
@@ -55,7 +55,7 @@ function createMockContext(
     rpc: {
       connectionMeta: { backend: 'ws' },
     },
-  } as unknown as DocksContext
+  } as unknown as DevToolsDocksContext
 }
 
 function createMockDocument() {
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
index 9e70bf4af..7c02e8a61 100644
--- a/packages/core/src/client/webcomponents/state/context.ts
+++ b/packages/core/src/client/webcomponents/state/context.ts
@@ -17,20 +17,34 @@ import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDo
 import { createDockRenderers } from './renderers'
 import { executeSetupScript } from './setup-script'
 
-const docksContextByRpc = new WeakMap<DevToolsRpcClient, DocksContext>()
+/**
+ * `DocksContext` plus the host's dock config, synced over shared state rather
+ * than part of the upstream `devframe`/`hub` context shape. Assigned from a
+ * `ShallowRef` below; `reactive()` unwraps it as a direct property, so it
+ * reads as a plain object here — same convention as `panel.store`.
+ */
+export interface DevToolsDocksContext extends DocksContext {
+  /** Host dock config. Read-only from the client — mutate it on the node context instead. */
+  readonly dockConfig: DevToolsDockConfig
+}
+
+const docksContextByRpc = new WeakMap<DevToolsRpcClient, DevToolsDocksContext>()
 export async function createDocksContext(
   clientType: 'embedded' | 'standalone',
   rpc: DevToolsRpcClient,
   panelStore?: Ref<DockPanelStorage>,
-): Promise<DocksContext> {
+): Promise<DevToolsDocksContext> {
   if (docksContextByRpc.has(rpc)) {
     return docksContextByRpc.get(rpc)!
   }
 
   const dockEntries = await useDocksEntries(rpc)
 
-  /** Host dock config, handed over once in the connection handshake. */
-  const dockConfig: DevToolsDockConfig | undefined = rpc.connectionMeta.dockConfig
+  // Client's `initialValue` must stay empty — the client merges
+  // `{ ...initialValue, ...serverState }`, so anything else would leak stale
+  // keys the server deliberately omitted once the real value arrives.
+  const dockConfigState = await rpc.sharedState.get<DevToolsDockConfig>('devtools:dock-config', { initialValue: {} })
+  const dockConfig = sharedStateToRef(dockConfigState)
 
   // Client-only dock registry (0.7.10 `DocksEntriesContext` API). Docks
   // registered here live in this page only, merged over the server-provided
@@ -114,7 +128,7 @@ export async function createDocksContext(
   }
 
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
-  let docksContext: DocksContext
+  let docksContext: DevToolsDocksContext
 
   let _settingsStorePromise: Promise<SharedState<DevToolsDocksUserSettings>> | undefined
   const getSettingsStore = async () => {
@@ -336,8 +350,8 @@ export async function createDocksContext(
   // Settings store, `settings`, and `getWhenContext` are established earlier
   // (right before `switchEntry`) — its group→member resolution needs them.
   const groupedEntries = computed(() => {
-    // User drag order over the plugin-declared one.
-    const categoryOrderOverride = { ...dockConfig?.categoryOrder, ...settings.value.docksCategoriesOrder }
+    // User drag order over the plugin/host-declared one.
+    const categoryOrderOverride = { ...dockConfig.value.categoryOrder, ...settings.value.docksCategoriesOrder }
     return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true, categoryOrderOverride })
   })
 
@@ -493,6 +507,7 @@ export async function createDocksContext(
   })
 
   docksContext = reactive({
+    dockConfig,
     panel: {
       store: panelStore,
       isDragging: false,
diff --git a/packages/core/src/client/webcomponents/state/dock-settings.ts b/packages/core/src/client/webcomponents/state/dock-settings.ts
index 25f13a07b..8e9f0a7c6 100644
--- a/packages/core/src/client/webcomponents/state/dock-settings.ts
+++ b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -29,8 +29,8 @@ export const PINNED_CATEGORY_ORDER = -100000
 /**
  * Resolve a category's sort weight, layering the local {@link PINNED_CATEGORY}
  * override, then a caller-supplied `overrides` map (a group's own
- * {@link DevToolsViewGroup.categoryOrder}, or a plugin-declared category order
- * merged with the user's own), on top of the upstream
+ * {@link DevToolsViewGroup.categoryOrder}, or the host/plugin-declared category
+ * order merged with the user's own), on top of the upstream
  * {@link DEFAULT_CATEGORIES_ORDER} table. `overrides` is per-call — passing a
  * group's map only reweights that group's in-group sub-categories, never the
  * outer bar or any other group.
@@ -245,7 +245,7 @@ export function resolveGroupDefaultChild(
  * (used by {@link getGroupMembersGrouped} to apply a group's own
  * {@link DevToolsViewGroup.categoryOrder} to its in-group sub-category split,
  * and by top-level callers to layer the user's category order over the
- * plugin-declared one) — it never touches the shared
+ * host/plugin-declared one) — it never touches the shared
  * {@link DEFAULT_CATEGORIES_ORDER} table, so it has no effect on any other
  * call, group, or the outer bar.
  */
diff --git a/packages/core/src/client/webcomponents/state/popup.ts b/packages/core/src/client/webcomponents/state/popup.ts
index 5d5cf20e2..80f5adcc8 100644
--- a/packages/core/src/client/webcomponents/state/popup.ts
+++ b/packages/core/src/client/webcomponents/state/popup.ts
@@ -1,4 +1,4 @@
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from './context'
 import { createEventEmitter } from 'devframe/utils/events'
 import { shallowRef, watch } from 'vue'
 import { isDark } from './color-mode'
@@ -9,7 +9,7 @@ interface DocumentPictureInPicture {
 }
 
 interface DockPopupEvents {
-  'popup:open-requested': (context: DocksContext) => void
+  'popup:open-requested': (context: DevToolsDocksContext) => void
 }
 type MainFrameDockActionHandler = (entryId: string) => Promise<boolean> | boolean
 
@@ -26,8 +26,8 @@ const popupEvents = createEventEmitter<DockPopupEvents>()
 let detachPopupListeners: (() => void) | undefined
 let detachColorModeSync: (() => void) | undefined
 let popupDockElement: (HTMLElement & { remove: () => void }) | undefined
-let popupContext: DocksContext | undefined
-let loadDockStandalone: () => Promise<new (props: { context: DocksContext }) => HTMLElement> = async () => {
+let popupContext: DevToolsDocksContext | undefined
+let loadDockStandalone: () => Promise<new (props: { context: DevToolsDocksContext }) => HTMLElement> = async () => {
   return await import('../components/DockStandalone').then(m => m.DockStandalone)
 }
 
@@ -80,14 +80,14 @@ function clamp(value: number, min: number, max: number) {
   return Math.min(Math.max(value, min), max)
 }
 
-function syncPanelSizeFromPopup(context: DocksContext, popup: Window) {
+function syncPanelSizeFromPopup(context: DevToolsDocksContext, popup: Window) {
   if (window.innerWidth <= 0 || window.innerHeight <= 0)
     return
   context.panel.store.width = clamp(Math.round(popup.innerWidth / window.innerWidth * 100), PANEL_MIN_SIZE, PANEL_MAX_SIZE)
   context.panel.store.height = clamp(Math.round(popup.innerHeight / window.innerHeight * 100), PANEL_MIN_SIZE, PANEL_MAX_SIZE)
 }
 
-async function mountStandaloneApp(context: DocksContext, popup: Window) {
+async function mountStandaloneApp(context: DevToolsDocksContext, popup: Window) {
   const DockStandaloneElement = await loadDockStandalone()
 
   const baseStyle = popup.document.createElement('style')
@@ -179,7 +179,7 @@ export function useIsDockPopupOpen() {
   return isPopupOpen as Readonly<typeof isPopupOpen>
 }
 
-export function requestDockPopupOpen(context: DocksContext) {
+export function requestDockPopupOpen(context: DevToolsDocksContext) {
   popupEvents.emit('popup:open-requested', context)
 }
 
@@ -191,13 +191,13 @@ export function closeDockPopup() {
   popup.close()
 }
 
-export function setDockStandaloneLoaderForTest(loader?: () => Promise<new (props: { context: DocksContext }) => HTMLElement>) {
+export function setDockStandaloneLoaderForTest(loader?: () => Promise<new (props: { context: DevToolsDocksContext }) => HTMLElement>) {
   loadDockStandalone = loader || (async () => {
     return await import('../components/DockStandalone').then(m => m.DockStandalone)
   })
 }
 
-export async function openDockPopup(context: DocksContext): Promise<Window | null> {
+export async function openDockPopup(context: DevToolsDocksContext): Promise<Window | null> {
   setDocksOverflowPanel(null)
 
   const currentPopup = popupWindow.value
diff --git a/packages/core/src/client/webcomponents/stories/mock-context.ts b/packages/core/src/client/webcomponents/stories/mock-context.ts
index 859089723..95ff590c1 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 { DevToolsDockConfig, DevToolsDockEntry, DevToolsDocksUserSettings } from '@vitejs/devtools-kit'
+import type { DevToolsRpcClient, DockPanelStorage, RpcClientEvents } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../state/context'
 import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
 import { createEventEmitter } from 'devframe/utils/events'
 import { createSharedState } from 'devframe/utils/shared-state'
@@ -31,11 +32,14 @@ export interface CreateMockContextOptions {
   selectedId?: string | null
   /** Initial trust state. Defaults to `true`. */
   isTrusted?: boolean
+  /** Overrides seeded into `devtools:dock-config` (category order, `maxVisibleItems`, ...). */
+  dockConfig?: DevToolsDockConfig
 }
 
 function createMockRpc(
   entries: DevToolsDockEntry[],
   settings: Partial<DevToolsDocksUserSettings>,
+  dockConfig: DevToolsDockConfig,
   initialTrusted: boolean,
 ): MockRpcClient {
   const docksState = createSharedState({ initialValue: entries, enablePatches: false })
@@ -44,6 +48,7 @@ function createMockRpc(
     enablePatches: false,
   })
   const commandsState = createSharedState({ initialValue: [] as any[], enablePatches: false })
+  const dockConfigState = createSharedState({ initialValue: dockConfig, enablePatches: false })
   const events = createEventEmitter<RpcClientEvents>()
 
   let trusted = initialTrusted
@@ -81,6 +86,8 @@ function createMockRpc(
           return settingsState
         if (key === 'devframe:commands')
           return commandsState
+        if (key === 'devtools:dock-config')
+          return dockConfigState
         throw new Error(`[mock-rpc] Unexpected shared state key: ${key}`)
       },
     },
@@ -94,7 +101,7 @@ function createMockRpc(
 }
 
 /**
- * Build a real {@link DocksContext} wired to an in-memory {@link MockRpcClient}.
+ * Build a real {@link DevToolsDocksContext} wired to an in-memory {@link MockRpcClient}.
  *
  * This is the same `createDocksContext` the client boots with, so grouping,
  * `switchEntry`, commands and when-clauses all behave exactly as they do at
@@ -103,7 +110,7 @@ function createMockRpc(
  */
 export async function createMockDocksContext(
   options: CreateMockContextOptions = {},
-): Promise<DocksContext & { rpc: MockRpcClient }> {
+): Promise<DevToolsDocksContext & { rpc: MockRpcClient }> {
   const {
     entries = [],
     clientType = 'embedded',
@@ -111,9 +118,10 @@ export async function createMockDocksContext(
     settings = {},
     selectedId = null,
     isTrusted = true,
+    dockConfig = {},
   } = options
 
-  const rpc = createMockRpc(entries, settings, isTrusted)
+  const rpc = createMockRpc(entries, settings, dockConfig, isTrusted)
   const panelStore = ref<DockPanelStorage>({ ...DEFAULT_DOCK_PANEL_STORE(), ...panel })
 
   const context = await createDocksContext(clientType, rpc, panelStore)
@@ -123,5 +131,5 @@ export async function createMockDocksContext(
     context.panel.store.open = true
   }
 
-  return context as DocksContext & { rpc: MockRpcClient }
+  return context as DevToolsDocksContext & { rpc: MockRpcClient }
 }
diff --git a/packages/core/src/client/webcomponents/stories/story-helpers.ts b/packages/core/src/client/webcomponents/stories/story-helpers.ts
index 437167107..64788bb62 100644
--- a/packages/core/src/client/webcomponents/stories/story-helpers.ts
+++ b/packages/core/src/client/webcomponents/stories/story-helpers.ts
@@ -1,10 +1,10 @@
-import type { DocksContext } from '@vitejs/devtools-kit/client'
+import type { DevToolsDocksContext } from '../state/context'
 import type { CreateMockContextOptions } from './mock-context'
 import { defineComponent, h, Suspense } from 'vue'
 import { createMockDocksContext } from './mock-context'
 
 /**
- * Render a component tree that needs a live {@link DocksContext}.
+ * Render a component tree that needs a live {@link DevToolsDocksContext}.
  *
  * `createMockDocksContext` is async (it boots the real dock context over a mock
  * transport), so we resolve it inside an async `setup` wrapped in `<Suspense>`.
@@ -24,7 +24,7 @@ import { createMockDocksContext } from './mock-context'
  */
 export function mountWithContext(
   options: CreateMockContextOptions,
-  slot: (context: DocksContext) => unknown,
+  slot: (context: DevToolsDocksContext) => unknown,
 ): () => unknown {
   const Inner = defineComponent({
     name: 'MockContextProvider',
diff --git a/packages/core/src/node/context.ts b/packages/core/src/node/context.ts
index 2ddd8de36..a93b8ceee 100644
--- a/packages/core/src/node/context.ts
+++ b/packages/core/src/node/context.ts
@@ -1,4 +1,4 @@
-import type { DevToolsDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsDockConfig, DevToolsHostDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { RpcFunctionsHost } from 'devframe/node'
 import type { ResolvedConfig, ViteDevServer } from 'vite'
 import { DEVTOOLS_VITEPLUS_GROUP_ID } from '@vitejs/devtools-kit/constants'
@@ -24,9 +24,15 @@ function shouldSkipSetupByCapabilities(
   return Object.values(modeCapabilities).includes(false)
 }
 
+export interface CreateDevToolsContextOptions {
+  /** Host-wide dock defaults — see {@link DevToolsHostDockConfig}. */
+  dock?: DevToolsHostDockConfig
+}
+
 export async function createDevToolsContext(
   viteConfig: ResolvedConfig,
   viteServer?: ViteDevServer,
+  options: CreateDevToolsContextOptions = {},
 ): Promise<ViteDevToolsNodeContext> {
   const cwd = viteConfig.root
 
@@ -109,9 +115,12 @@ export async function createDevToolsContext(
   if (viteServer || mode === 'build')
     context.views.hostStatic('/__devtools-assets/', dirAssets)
 
-  // Scan Vite plugins for `devtools` setup hooks, merging each plugin's declared
-  // dock config along the way (last wins per key; `categoryOrder` shallow-merges).
-  const dockConfig: DevToolsDockConfig = {}
+  // Scan Vite plugins for `devtools` setup hooks, shallow-merging each
+  // plugin's declared `categoryOrder` along the way — it's the one dock
+  // setting that's meaningful per plugin. `maxVisibleItems`/`defaultMode`/
+  // `defaultPosition` are properties of the one shared dock bar, so they come
+  // only from the host's own `options.dock`, layered on top below.
+  const pluginCategoryOrder: Record<string, number> = {}
   const plugins = viteConfig.plugins.filter(plugin => 'devtools' in plugin)
   for (const plugin of plugins) {
     if (!plugin.devtools?.setup)
@@ -120,9 +129,7 @@ export async function createDevToolsContext(
       debugSetup(`skipping plugin ${JSON.stringify(plugin.name)} due to disabled capabilities in ${mode} mode`)
       continue
     }
-    const dock = plugin.devtools.dock
-    if (dock)
-      Object.assign(dockConfig, dock, { categoryOrder: { ...dockConfig.categoryOrder, ...dock.categoryOrder } })
+    Object.assign(pluginCategoryOrder, plugin.devtools.dock?.categoryOrder)
     try {
       debugSetup(`setting up plugin ${JSON.stringify(plugin.name)}`)
       await plugin.devtools?.setup?.(context)
@@ -131,7 +138,16 @@ export async function createDevToolsContext(
       throw diagnostics.DTK0014({ name: plugin.name, cause: error })
     }
   }
-  context.dockConfig = dockConfig
+
+  const dockConfig: DevToolsDockConfig = {
+    ...options.dock,
+    categoryOrder: { ...pluginCategoryOrder, ...options.dock?.categoryOrder },
+  }
+  // Created unconditionally, including in build mode, so the key exists in
+  // `host.keys()` and the static RPC dump picks it up for the built SPA.
+  context.dockConfig = await context.rpc.sharedState.get('devtools:dock-config', {
+    initialValue: dockConfig,
+  })
 
   return context
 }
diff --git a/packages/core/src/node/plugins/build.ts b/packages/core/src/node/plugins/build.ts
index 45ca1736e..a025e8243 100644
--- a/packages/core/src/node/plugins/build.ts
+++ b/packages/core/src/node/plugins/build.ts
@@ -1,6 +1,6 @@
 /* eslint-disable no-console */
 
-import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsHostDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin, ResolvedConfig } from 'vite'
 import { colors as c } from 'devframe/utils/colors'
 import { resolve } from 'pathe'
@@ -8,6 +8,8 @@ import { MARK_NODE } from '../constants'
 
 export interface DevToolsBuildOptions {
   outDir?: string
+  /** Host-wide dock defaults — see {@link DevToolsHostDockConfig}. */
+  dock?: DevToolsHostDockConfig
 }
 
 export function DevToolsBuild(options: DevToolsBuildOptions = {}): Plugin {
@@ -24,7 +26,7 @@ export function DevToolsBuild(options: DevToolsBuildOptions = {}): Plugin {
 
     async buildStart() {
       const { createDevToolsContext } = await import('../context')
-      context = await createDevToolsContext(resolvedConfig)
+      context = await createDevToolsContext(resolvedConfig, undefined, { dock: options.dock })
     },
 
     async closeBundle() {
diff --git a/packages/core/src/node/plugins/index.ts b/packages/core/src/node/plugins/index.ts
index 912cfae30..695228abb 100644
--- a/packages/core/src/node/plugins/index.ts
+++ b/packages/core/src/node/plugins/index.ts
@@ -1,3 +1,4 @@
+import type { DevToolsHostDockConfig } from '@vitejs/devtools-kit'
 import type { Plugin } from 'vite'
 import type { DevToolsVisibility } from './injection'
 import { DevToolsBuild } from './build'
@@ -30,6 +31,14 @@ export interface DevToolsOptions {
    */
   visibility?: DevToolsVisibility
 
+  /**
+   * Host-wide dock defaults — category order, float-mode capacity, and
+   * initial window placement. A plugin may additionally declare its own
+   * `devtools.dock.categoryOrder`; this option decides the rest, and wins
+   * over a plugin's `categoryOrder` where both set the same category.
+   */
+  dock?: DevToolsHostDockConfig
+
   /**
    * Options for building static DevTools output alongside `vite build`.
    */
@@ -53,15 +62,16 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
     builtinDevTools = true,
     build,
     visibility = 'normal',
+    dock,
   } = options
 
   const plugins = [
     DevToolsInjection({ visibility }),
-    DevToolsServer(),
+    DevToolsServer({ dock }),
   ]
 
   if (build?.withApp) {
-    plugins.push(DevToolsBuild({ outDir: build.outDir }))
+    plugins.push(DevToolsBuild({ outDir: build.outDir, dock }))
   }
 
   plugins.unshift(
diff --git a/packages/core/src/node/plugins/server.ts b/packages/core/src/node/plugins/server.ts
index c287e9810..e8048144c 100644
--- a/packages/core/src/node/plugins/server.ts
+++ b/packages/core/src/node/plugins/server.ts
@@ -1,4 +1,4 @@
-import type { ClientScriptEntry, DevToolsDockEntry, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ClientScriptEntry, DevToolsDockEntry, DevToolsHostDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin } from 'vite'
 import {
   DEVTOOLS_DOCK_IMPORTS_VIRTUAL_ID,
@@ -35,14 +35,19 @@ export function renderDockImportsMap(docks: Iterable<DevToolsDockEntry>): string
   ].join('\n')
 }
 
-export function DevToolsServer(): Plugin {
+export interface DevToolsServerOptions {
+  /** Host-wide dock defaults — see {@link DevToolsHostDockConfig}. */
+  dock?: DevToolsHostDockConfig
+}
+
+export function DevToolsServer(options: DevToolsServerOptions = {}): Plugin {
   let context: ViteDevToolsNodeContext
   return {
     name: 'vite:devtools:server',
     enforce: 'post',
     apply: 'serve',
     async configureServer(viteDevServer) {
-      context = await createDevToolsContext(viteDevServer.config, viteDevServer)
+      context = await createDevToolsContext(viteDevServer.config, viteDevServer, { dock: options.dock })
 
       const host = viteDevServer.config.server.host === true
         ? '0.0.0.0'
diff --git a/packages/core/src/node/rpc/index.ts b/packages/core/src/node/rpc/index.ts
index 913d599c8..1465e86ae 100644
--- a/packages/core/src/node/rpc/index.ts
+++ b/packages/core/src/node/rpc/index.ts
@@ -68,10 +68,6 @@ declare module 'devframe/types' {
     'devframe:commands': DevToolsServerCommandEntry[]
     'devframe:docks': DevToolsDockEntry[]
     'devframe:user-settings': DevToolsDocksUserSettings
-  }
-
-  interface ConnectionMeta {
-    /** Host dock config, fixed for the life of the dev server, so it rides the handshake instead of shared state. */
-    dockConfig?: DevToolsDockConfig
+    'devtools:dock-config': DevToolsDockConfig
   }
 }
diff --git a/packages/core/src/node/standalone.ts b/packages/core/src/node/standalone.ts
index aaa7017fc..23e18d8c1 100644
--- a/packages/core/src/node/standalone.ts
+++ b/packages/core/src/node/standalone.ts
@@ -1,4 +1,4 @@
-import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsHostDockConfig, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin, ResolvedConfig } from 'vite'
 import process from 'node:process'
 import { createDevToolsContext } from './context'
@@ -10,6 +10,8 @@ export interface StandaloneDevToolsOptions {
   config?: string
   command?: 'build' | 'serve'
   mode?: 'development' | 'production'
+  /** Host-wide dock defaults — see {@link DevToolsHostDockConfig}. */
+  dock?: DevToolsHostDockConfig
 }
 
 export async function startStandaloneDevTools(options: StandaloneDevToolsOptions = {}): Promise<{
@@ -20,6 +22,7 @@ export async function startStandaloneDevTools(options: StandaloneDevToolsOptions
     cwd = process.cwd(),
     command = 'build',
     mode = 'production',
+    dock,
   } = options
 
   const { resolveConfig } = await import('vite')
@@ -28,7 +31,7 @@ export async function startStandaloneDevTools(options: StandaloneDevToolsOptions
       configFile: options.config,
       root: cwd,
       plugins: [
-        DevTools({ cwd }),
+        DevTools({ cwd, dock }),
       ],
     },
     command,
@@ -40,7 +43,10 @@ export async function startStandaloneDevTools(options: StandaloneDevToolsOptions
     plugin => plugin.name?.startsWith('vite:devtools'),
   )
 
-  const context = await createDevToolsContext(resolved)
+  // `resolveConfig` only resolves the `DevTools()` plugin's own hooks; it
+  // never surfaces the options it was constructed with, so `dock` is passed
+  // straight through rather than picked back out of `resolved.plugins`.
+  const context = await createDevToolsContext(resolved, undefined, { dock })
 
   return {
     config: resolved,
diff --git a/packages/core/src/node/ws.ts b/packages/core/src/node/ws.ts
index 1d1069ae9..da5ffaf4d 100644
--- a/packages/core/src/node/ws.ts
+++ b/packages/core/src/node/ws.ts
@@ -211,7 +211,6 @@ export async function createWsServer(options: CreateWsServerOptions) {
       // client (proxy-safe); the dedicated-port form is a bare port number.
       websocket: routeBound ? { path: DEVTOOLS_WS_ROUTE } : port!,
       jsonSerializableMethods,
-      dockConfig: context.dockConfig,
     }
   }
 
diff --git a/packages/kit/src/types/settings.ts b/packages/kit/src/types/settings.ts
index e3ac46675..297f4030a 100644
--- a/packages/kit/src/types/settings.ts
+++ b/packages/kit/src/types/settings.ts
@@ -18,7 +18,7 @@ export interface DevToolsDocksUserSettings extends DevframeDocksUserSettings {
 
   /**
    * User drag-and-drop order for top-level dock categories, lower first.
-   * Overrides a plugin's declared `DevToolsDockConfig.categoryOrder`.
+   * Overrides the merged plugin/host `DevToolsDockConfig.categoryOrder`.
    */
   docksCategoriesOrder?: Record<string, number>
 }
diff --git a/packages/kit/src/types/vite-plugin.ts b/packages/kit/src/types/vite-plugin.ts
index 2240ff5fe..0fa7fb12c 100644
--- a/packages/kit/src/types/vite-plugin.ts
+++ b/packages/kit/src/types/vite-plugin.ts
@@ -1,17 +1,17 @@
 import type { DevframeCapabilities } from '@devframes/hub/types'
+import type { SharedState } from 'devframe/utils/shared-state'
 import type { ResolvedConfig, ViteDevServer } from 'vite'
 import type { KitNodeContext } from '../node/context'
 
 /**
- * Host-wide dock defaults a plugin declares alongside its `setup()`. Collected
- * from every plugin during the Vite plugin scan (`createDevToolsContext`, last
- * wins per key) and handed to every client once via `ConnectionMeta`.
+ * Resolved dock defaults for the whole host, synced to every client over
+ * shared state (`devtools:dock-config`). Layers, lowest priority first:
+ * `DEFAULT_CATEGORIES_ORDER` < every plugin's declared `categoryOrder`
+ * (shallow-merged) < {@link DevToolsHostDockConfig} < the user's own
+ * drag-and-drop order.
  */
 export interface DevToolsDockConfig {
-  /**
-   * Top-level category weights, lower first. Layered over
-   * `DEFAULT_CATEGORIES_ORDER`, beneath the user's own drag-and-drop order.
-   */
+  /** Top-level category weights, lower first. */
   categoryOrder?: Record<string, number>
   /** Items shown inline on the float bar before the overflow button. Defaults to 5; clamped to `>= 1`. */
   maxVisibleItems?: number
@@ -21,13 +21,32 @@ export interface DevToolsDockConfig {
   defaultPosition?: 'top' | 'right' | 'bottom' | 'left'
 }
 
+/**
+ * Host-wide dock defaults, set once on `DevTools({ dock })` rather than by a
+ * plugin — `maxVisibleItems`/`defaultMode`/`defaultPosition` are properties of
+ * the one shared dock bar, so a single owner picks them instead of leaving Vite's
+ * plugin array order to arbitrate between disagreeing plugins.
+ */
+export type DevToolsHostDockConfig = DevToolsDockConfig
+
+/**
+ * A plugin's own contribution to the dock config, declared alongside its
+ * `setup()`. Only `categoryOrder` is here — it is the one setting that is
+ * meaningful per plugin, since it just weighs the categories that plugin's own
+ * entries fall into and shallow-merges across every plugin's declaration.
+ */
+export interface DevToolsPluginDockConfig {
+  /** This plugin's category weights, lower first — shallow-merged with every other plugin's. */
+  categoryOrder?: Record<string, number>
+}
+
 export interface DevToolsPluginOptions {
   capabilities?: {
     dev?: DevframeCapabilities | boolean
     build?: DevframeCapabilities | boolean
   }
-  /** Host-level dock defaults — see {@link DevToolsDockConfig}. */
-  dock?: DevToolsDockConfig
+  /** This plugin's dock defaults — see {@link DevToolsPluginDockConfig}. */
+  dock?: DevToolsPluginDockConfig
   setup: (context: ViteDevToolsNodeContext) => void | Promise<void>
 }
 
@@ -42,6 +61,10 @@ export interface DevToolsPluginOptions {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig
   readonly viteServer?: ViteDevServer
-  /** Dock config merged from every plugin's `devtools.dock`, assigned once after the plugin scan. */
-  dockConfig?: DevToolsDockConfig
+  /**
+   * Dock config merged from every plugin's `devtools.dock` and the host's own
+   * `DevTools({ dock })`, synced to every client over shared state. Mutate to
+   * reconfigure already-connected clients live.
+   */
+  dockConfig: SharedState<DevToolsDockConfig>
 }
diff --git a/playgrounds/core/vite.config.ts b/playgrounds/core/vite.config.ts
index 4022cc9bd..dc4335e77 100644
--- a/playgrounds/core/vite.config.ts
+++ b/playgrounds/core/vite.config.ts
@@ -86,6 +86,12 @@ export default defineConfig({
     // For local playground only. As a user you don't install this plugin directly.
     DevTools({
       builtinDevTools: false,
+      // Host-wide dock defaults — layered over every plugin's own
+      // `categoryOrder` (the "local" plugin above declares `playground: -30`).
+      dock: {
+        categoryOrder: { web: -60, advanced: -50, app: -40 },
+        maxVisibleItems: 8,
+      },
     }),
     DevToolsRolldownUI(),
     DevToolsViteUI(),
@@ -130,6 +136,11 @@ export default defineConfig({
     {
       name: 'local',
       devtools: {
+        // Only `categoryOrder` is a plugin's own to declare — it just weighs
+        // the categories *this* plugin contributes to. `maxVisibleItems`/
+        // `defaultMode`/`defaultPosition` are host-wide and live on
+        // `DevTools({ dock })` below instead.
+        dock: { categoryOrder: { playground: -30 } },
         async setup(ctx) {
           ctx.docks.register({
             type: 'action',
@@ -296,6 +307,21 @@ export default defineConfig({
             })
           })
 
+          // `ctx.dockConfig` is a live `SharedState` — mutating it reconfigures
+          // every already-connected client immediately, no reload. Try it from
+          // the command palette with the dock already open.
+          ctx.commands.register({
+            id: 'playground:toggle-dock-capacity',
+            title: 'Toggle Dock Capacity (4 / 8)',
+            icon: 'ph:arrows-out-line-horizontal-duotone',
+            category: 'playground',
+            handler: () => {
+              ctx.dockConfig.mutate((config) => {
+                config.maxVisibleItems = config.maxVisibleItems === 4 ? 8 : 4
+              })
+            },
+          })
+
           // setInterval(() => {
           //   counterState.mutate((current) => {
           //     current.count = (current.count + 1) % 5
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
index 73cd3b50a..e2b0b9630 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
@@ -20,12 +20,15 @@ export interface DevToolsLaunchRoot {
   label: string;
   description?: string;
 }
+export interface DevToolsPluginDockConfig {
+  categoryOrder?: Record<string, number>;
+}
 export interface DevToolsPluginOptions {
   capabilities?: {
     dev?: DevframeCapabilities | boolean;
     build?: DevframeCapabilities | boolean;
   };
-  dock?: DevToolsDockConfig;
+  dock?: DevToolsPluginDockConfig;
   setup: (_: ViteDevToolsNodeContext) => void | Promise<void>;
 }
 export interface DevToolsViewJsonRender extends DevframeDockEntryBase {
@@ -55,12 +58,13 @@ export interface PluginWithDevTools extends Plugin {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig;
   readonly viteServer?: ViteDevServer;
-  dockConfig?: DevToolsDockConfig;
+  dockConfig: SharedState<DevToolsDockConfig>;
 }
 // #endregion
 
 // #region Types
 export type DevToolsDockEntryCategory = DevframeDockEntryCategory;
+export type DevToolsHostDockConfig = DevToolsDockConfig;
 export type JsonRenderElement = UIElement;
 export type JsonRenderSpec = DevframeJsonRenderSpec;
 // #endregion
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..202caa7b9 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/client/webcomponents.snapshot.d.ts
@@ -38,6 +38,9 @@ export interface DataTableProps {
   rows?: Record<string, unknown>[];
   height?: number;
 }
+export interface DevToolsDocksContext extends DocksContext {
+  readonly dockConfig: DevToolsDockConfig;
+}
 export interface DividerProps {
   label?: string;
 }
@@ -142,9 +145,9 @@ export declare function useDocksEntries(_: DevToolsRpcClient): Promise<Ref<DevTo
 
 // #region Variables
 export declare const DockEmbedded: VueElementConstructor<{
-  context: DocksContext;
+  context: DevToolsDocksContext;
 }>;
 export declare const DockStandalone: VueElementConstructor<{
-  context: DocksContext;
+  context: DevToolsDocksContext;
 }>;
 // #endregion
\ No newline at end of file
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.d.ts
index 568aac89b..2c6e8b313 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.d.ts
@@ -15,7 +15,7 @@ export type BuiltinServerFunctions = RpcDefinitionsToFunctions<typeof builtinRpc
 // #endregion
 
 // #region Functions
-export declare function createDevToolsContext(_: ResolvedConfig, _?: ViteDevServer): Promise<ViteDevToolsNodeContext>;
+export declare function createDevToolsContext(_: ResolvedConfig, _?: ViteDevServer, _?: CreateDevToolsContextOptions): Promise<ViteDevToolsNodeContext>;
 export declare function createDevToolsMiddleware(_: CreateWsServerOptions): Promise<DevToolsMiddleware>;
 export declare function DevTools(_?: DevToolsOptions): Promise<Plugin[]>;
 // #endregion
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.js b/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.js
index 00c6e4117..dc7bee129 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.js
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools/index.snapshot.js
@@ -2,7 +2,7 @@
  * Generated by tsnapi — public API snapshot of `@vitejs/devtools`
  */
 // #region Functions
-export async function createDevToolsContext(_, _) {}
+export async function createDevToolsContext(_, _, _) {}
 export async function createDevToolsMiddleware(_) {}
 export async function DevTools(_) {}
 // #endregion
\ No newline at end of file