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 0a5d2c520..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,8 +98,12 @@ async function mountDock(): Promise<void> {
     ],
   })
 
+  // 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: 'float',
       width: 80,
@@ -74,6 +116,8 @@ async function mountDock(): Promise<void> {
     },
     { 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 5935b1747..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,7 +34,11 @@ 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/host-declared `maxVisibleItems` is the default; an explicit `layout` prop wins.
+const layout = computed(() => resolveDockLayout({
+  maxVisibleItems: context.dockConfig.maxVisibleItems,
+  ...props.layout,
+}))
 
 const isSafari = navigator.userAgent.includes('Safari') && !navigator.userAgent.includes('Chrome')
 
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/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 3f32bb93e..c2b0d3886 100644
--- a/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
+++ b/packages/core/src/client/webcomponents/components/dock/dock-layout.ts
@@ -94,7 +94,12 @@ export const DEFAULT_DOCK_LAYOUT: DockLayout = Object.freeze({
 export function resolveDockLayout(overrides?: Partial<DockLayout>): DockLayout {
   if (!overrides)
     return DEFAULT_DOCK_LAYOUT
-  return { ...DEFAULT_DOCK_LAYOUT, ...overrides }
+  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/SettingsAdvanced.vue b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
index 0ab084af2..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,6 +46,7 @@ async function resetDocks() {
       state.docksHidden = defaults.docksHidden
       state.docksCategoriesHidden = defaults.docksCategoriesHidden
       state.docksCustomOrder = defaults.docksCustomOrder
+      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 b83cf65fd..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,12 +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 categories = computed<DevToolsDockEntriesGrouped>(() => {
+const configCategoryOrder = computed(() => props.context.dockConfig.categoryOrder)
+
+function groupByCategories(categoryOrderOverride?: Record<string, number>): DevToolsDockEntriesGrouped {
   return docksGroupByCategories(props.context.docks.entries, settings.value, {
     includeHidden: true,
     collapseGroups: true,
+    categoryOrderOverride,
   })
-})
+}
+
+// User drag order over the plugin/host-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, {
@@ -44,6 +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 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}`
+
+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)
@@ -55,6 +90,8 @@ function parseGroupContainer(container: string): { groupId: string, subcategory:
 }
 
 function itemsOfContainer(container: string): DevToolsDockEntry[] {
+  if (container === CATEGORY_ORDER_CONTAINER)
+    return categoryOrderItems(categories.value)
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
     return subcategoriesOf(groupId).find(([cat]) => cat === subcategory)?.[1] ?? []
@@ -64,6 +101,8 @@ function itemsOfContainer(container: string): DevToolsDockEntry[] {
 }
 
 function defaultItemsOfContainer(container: string): DevToolsDockEntry[] {
+  if (container === CATEGORY_ORDER_CONTAINER)
+    return categoryOrderItems(groupByCategories(configCategoryOrder.value))
   const noCustomOrder = { ...settings.value, docksCustomOrder: {} }
   if (container.startsWith('grp:')) {
     const { groupId, subcategory } = parseGroupContainer(container)
@@ -107,11 +146,13 @@ 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])
   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
     })
   })
 }
@@ -274,28 +315,53 @@ function doesContainerHaveCustomOrder(container: string): boolean {
 function resetCustomOrderForContainer(container: string) {
   const ids = customOrderIdsForContainer(container)
   props.settingsStore.mutate((state) => {
+    const order = orderRecord(state, container)
     ids.forEach((id) => {
-      delete state.docksCustomOrder[id]
+      delete order[orderKey(container, id)]
     })
   })
 }
 </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"
+      @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">
+    <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) => 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 === dragId ? 'op30 bg-gray/10' : '',
+            dragOverId === dragId ? 'ring-1.5 ring-purple/50 rounded' : '',
+          ]"
         >
+          <!-- drag icon -->
+          <div
+            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 === dragId ? '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/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 a1f44e805..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,6 +22,11 @@ function createMockRpc(entries: DevToolsDockEntry[] = []): DevToolsRpcClient {
     enablePatches: false,
   })
 
+  const dockConfigState = createSharedState({
+    initialValue: {},
+    enablePatches: false,
+  })
+
   return {
     client: {
       register: () => () => {},
@@ -34,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 3051abb6b..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,6 +10,7 @@ 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: () => () => {} },
@@ -21,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 52060b2c9..7c02e8a61 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'
@@ -17,18 +17,35 @@ 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)
 
+  // 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
   // `devframe:docks` docks by id, and never sync to shared state. Mirrors the
@@ -111,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 () => {
@@ -333,7 +350,9 @@ 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 })
+    // 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 })
   })
 
   // Initialize commands context with reactive when-context
@@ -488,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 5e5c54996..8e9f0a7c6 100644
--- a/packages/core/src/client/webcomponents/state/dock-settings.ts
+++ b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -29,7 +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}), 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.
@@ -242,9 +243,11 @@ export function resolveGroupDefaultChild(
  *
  * `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.
+ * {@link DevToolsViewGroup.categoryOrder} to its in-group sub-category split,
+ * and by top-level callers to layer the user's category order over the
+ * 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.
  */
 export function docksGroupByCategories(
   entries: DevToolsDockEntry[],
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 ec5c664ad..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
@@ -58,6 +63,7 @@ function createMockRpc(
 
   const rpc = {
     events,
+    connectionMeta: { backend: 'websocket' },
     get isTrusted() {
       return trusted
     },
@@ -80,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}`)
       },
     },
@@ -93,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
@@ -102,7 +110,7 @@ function createMockRpc(
  */
 export async function createMockDocksContext(
   options: CreateMockContextOptions = {},
-): Promise<DocksContext & { rpc: MockRpcClient }> {
+): Promise<DevToolsDocksContext & { rpc: MockRpcClient }> {
   const {
     entries = [],
     clientType = 'embedded',
@@ -110,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)
@@ -122,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 2aca61e9b..a93b8ceee 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, 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,7 +115,12 @@ 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, 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)
@@ -118,6 +129,7 @@ export async function createDevToolsContext(
       debugSetup(`skipping plugin ${JSON.stringify(plugin.name)} due to disabled capabilities in ${mode} mode`)
       continue
     }
+    Object.assign(pluginCategoryOrder, plugin.devtools.dock?.categoryOrder)
     try {
       debugSetup(`setting up plugin ${JSON.stringify(plugin.name)}`)
       await plugin.devtools?.setup?.(context)
@@ -127,5 +139,15 @@ export async function createDevToolsContext(
     }
   }
 
+  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 a8d4988a9..1465e86ae 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'
@@ -68,5 +68,6 @@ declare module 'devframe/types' {
     'devframe:commands': DevToolsServerCommandEntry[]
     'devframe:docks': DevToolsDockEntry[]
     'devframe:user-settings': DevToolsDocksUserSettings
+    '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/kit/src/types/settings.ts b/packages/kit/src/types/settings.ts
index 9466f1f28..297f4030a 100644
--- a/packages/kit/src/types/settings.ts
+++ b/packages/kit/src/types/settings.ts
@@ -15,4 +15,10 @@ 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, lower first.
+   * 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 d715a5cc2..0fa7fb12c 100644
--- a/packages/kit/src/types/vite-plugin.ts
+++ b/packages/kit/src/types/vite-plugin.ts
@@ -1,12 +1,52 @@
 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'
 
+/**
+ * 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. */
+  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'
+}
+
+/**
+ * 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
   }
+  /** This plugin's dock defaults — see {@link DevToolsPluginDockConfig}. */
+  dock?: DevToolsPluginDockConfig
   setup: (context: ViteDevToolsNodeContext) => void | Promise<void>
 }
 
@@ -21,4 +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` 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 c05eb04dc..e2b0b9630 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;
 }
@@ -14,11 +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?: DevToolsPluginDockConfig;
   setup: (_: ViteDevToolsNodeContext) => void | Promise<void>;
 }
 export interface DevToolsViewJsonRender extends DevframeDockEntryBase {
@@ -48,11 +58,13 @@ export interface PluginWithDevTools extends Plugin {
 export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig;
   readonly viteServer?: ViteDevServer;
+  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