From 3e5c5e73ab7db271efea2aae04285402e825b4ed Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 10 Jul 2026 03:20:16 +0000
Subject: [PATCH 1/3] feat: hide Devframe Inspector by default and auto-hide
 empty terminals/messages docks

---
 .../views-builtin/SettingsAdvanced.vue        | 22 ++++++
 .../state/__tests__/dock-groups.test.ts       | 29 +++++++-
 .../webcomponents/state/dock-settings.ts      |  6 ++
 packages/core/src/node/plugins/index.ts       | 67 +++++++++++++++++--
 packages/kit/src/constants.ts                 |  8 +++
 packages/kit/src/types/settings.ts            | 19 +++++-
 .../devtools-kit/constants.snapshot.d.ts      |  1 +
 .../devtools-kit/constants.snapshot.js        |  1 +
 8 files changed, 147 insertions(+), 6 deletions(-)

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 6c1be72c..5f661b33 100644
--- a/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
+++ b/packages/core/src/client/webcomponents/components/views-builtin/SettingsAdvanced.vue
@@ -4,12 +4,14 @@ import type { SharedState } from 'devframe/utils/shared-state'
 import type { DevToolsDocksUserSettings } from '../../state/dock-settings'
 import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
 import { useConfirm } from '../../state/confirm'
+import { sharedStateToRef } from '../../state/docks'
 
 const props = defineProps<{
   context: DocksContext
   settingsStore: SharedState<DevToolsDocksUserSettings>
 }>()
 
+const settings = sharedStateToRef(props.settingsStore)
 const confirm = useConfirm()
 
 async function resetAllSettings() {
@@ -64,6 +66,26 @@ async function deauthorize() {
 
 <template>
   <div class="flex flex-col gap-6">
+    <!-- Show Devframe Inspector toggle -->
+    <label class="flex items-center gap-3 cursor-pointer group">
+      <button
+        class="w-10 h-6 rounded-full transition-colors relative shrink-0"
+        :class="settings.showDevframeInspector ? 'bg-lime' : 'bg-gray/30'"
+        @click="settingsStore.mutate((s) => { s.showDevframeInspector = !s.showDevframeInspector })"
+      >
+        <div
+          class="absolute top-1 w-4 h-4 rounded-full bg-white shadow transition-transform"
+          :class="settings.showDevframeInspector ? 'translate-x-5' : 'translate-x-1'"
+        />
+      </button>
+      <div class="flex flex-col">
+        <span class="text-sm">Show Devframe Inspector</span>
+        <span class="text-xs op50">Reveal the experimental Devframe Inspector dock — the DevTools for the DevTools</span>
+      </div>
+    </label>
+
+    <div class="border-t border-base" />
+
     <!-- Reset Shortcuts -->
     <div class="flex items-start gap-4">
       <div class="flex-1">
diff --git a/packages/core/src/client/webcomponents/state/__tests__/dock-groups.test.ts b/packages/core/src/client/webcomponents/state/__tests__/dock-groups.test.ts
index b8cd5f11..21170090 100644
--- a/packages/core/src/client/webcomponents/state/__tests__/dock-groups.test.ts
+++ b/packages/core/src/client/webcomponents/state/__tests__/dock-groups.test.ts
@@ -1,5 +1,5 @@
 import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
-import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
+import { DEFAULT_STATE_USER_SETTINGS, DEVTOOLS_INSPECTOR_DOCK_ID } from '@vitejs/devtools-kit/constants'
 import { describe, expect, it } from 'vitest'
 import {
   docksGroupByCategories,
@@ -92,6 +92,33 @@ describe('dock groups', () => {
   })
 })
 
+describe('devframe inspector visibility (settings: showDevframeInspector)', () => {
+  const entries: DevToolsDockEntry[] = [
+    iframe('a'),
+    iframe(DEVTOOLS_INSPECTOR_DOCK_ID),
+  ]
+
+  it('hides the inspector from the dock bar by default', () => {
+    const grouped = docksGroupByCategories(entries, settings)
+    const ids = grouped.flatMap(([, items]) => items.map(i => i.id))
+    expect(ids).toContain('a')
+    expect(ids).not.toContain(DEVTOOLS_INSPECTOR_DOCK_ID)
+  })
+
+  it('reveals the inspector when showDevframeInspector is enabled', () => {
+    const enabled = { ...settings, showDevframeInspector: true }
+    const grouped = docksGroupByCategories(entries, enabled)
+    const ids = grouped.flatMap(([, items]) => items.map(i => i.id))
+    expect(ids).toContain(DEVTOOLS_INSPECTOR_DOCK_ID)
+  })
+
+  it('still lists the inspector in the settings management view (includeHidden)', () => {
+    const grouped = docksGroupByCategories(entries, settings, { includeHidden: true })
+    const ids = grouped.flatMap(([, items]) => items.map(i => i.id))
+    expect(ids).toContain(DEVTOOLS_INSPECTOR_DOCK_ID)
+  })
+})
+
 describe('resolveCommandIcon (dock icon → command icon projection)', () => {
   it('passes string icons through unchanged', () => {
     expect(resolveCommandIcon('logos:nuxt-icon')).toBe('logos:nuxt-icon')
diff --git a/packages/core/src/client/webcomponents/state/dock-settings.ts b/packages/core/src/client/webcomponents/state/dock-settings.ts
index 1bd0f00a..2f5e1b63 100644
--- a/packages/core/src/client/webcomponents/state/dock-settings.ts
+++ b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -1,6 +1,7 @@
 import type { DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDocksUserSettings, DevToolsViewGroup } from '@vitejs/devtools-kit'
 import type { Immutable } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
+import { DEVTOOLS_INSPECTOR_DOCK_ID } from '@vitejs/devtools-kit/constants'
 import { evaluateWhen } from 'devframe/utils/when'
 import { DEFAULT_CATEGORIES_ORDER } from '../constants'
 
@@ -104,6 +105,11 @@ export function docksGroupByCategories(
       continue
     if (entry.when && !whenContext && entry.when === 'false' && !includeHidden)
       continue
+    // The Devframe Inspector is hidden by default; it only joins the dock bar
+    // once opted into via Settings → Advanced. The settings management view
+    // (`includeHidden`) still lists it so users can discover the toggle.
+    if (!includeHidden && entry.id === DEVTOOLS_INSPECTOR_DOCK_ID && !settings.showDevframeInspector)
+      continue
     if (!includeHidden && docksHidden.includes(entry.id))
       continue
 
diff --git a/packages/core/src/node/plugins/index.ts b/packages/core/src/node/plugins/index.ts
index a2dd5b53..a749242f 100644
--- a/packages/core/src/node/plugins/index.ts
+++ b/packages/core/src/node/plugins/index.ts
@@ -1,7 +1,9 @@
+import type { KitNodeContext } from '@vitejs/devtools-kit/node'
 import type { Plugin } from 'vite'
 import { createInspectDevframe } from '@devframes/plugin-inspect'
 import { createMessagesDevframe } from '@devframes/plugin-messages'
 import { createTerminalsDevframe } from '@devframes/plugin-terminals'
+import { DEVTOOLS_INSPECTOR_DOCK_ID } from '@vitejs/devtools-kit/constants'
 import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
 import { DevToolsBuild } from './build'
 import { DevToolsInjection } from './injection'
@@ -58,17 +60,47 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
     // dock — rather than the `~viteplus` group (which collects integrations
     // like Rolldown). The hub's own `~terminals` / `~messages` docks are
     // suppressed via `builtinDocks` in `createDevToolsContext`.
-    plugins.push(createPluginFromDevframe(createTerminalsDevframe(), {
+    //
+    // The hub's built-in `~terminals` / `~messages` docks auto-hid themselves
+    // when empty; the plugin-mounted iframe docks that replaced them carry no
+    // such rule, so we restore it here — the dock is filtered out of the bar
+    // (`when: 'false'`) whenever there are no sessions / messages.
+    const terminalsDevframe = createTerminalsDevframe()
+    plugins.push(createPluginFromDevframe(terminalsDevframe, {
       dock: { category: '~builtin' },
+      setup(ctx) {
+        hideDockWhenEmpty(
+          ctx,
+          terminalsDevframe.id,
+          () => ctx.terminals.sessions.size === 0,
+          refresh => ctx.terminals.events.on('terminal:session:updated', refresh),
+        )
+      },
     }))
-    plugins.push(createPluginFromDevframe(createMessagesDevframe(), {
+    const messagesDevframe = createMessagesDevframe()
+    plugins.push(createPluginFromDevframe(messagesDevframe, {
       dock: { category: '~builtin' },
+      setup(ctx) {
+        hideDockWhenEmpty(
+          ctx,
+          messagesDevframe.id,
+          () => ctx.messages.entries.size === 0,
+          (refresh) => {
+            ctx.messages.events.on('message:added', refresh)
+            ctx.messages.events.on('message:updated', refresh)
+            ctx.messages.events.on('message:removed', refresh)
+            ctx.messages.events.on('message:cleared', refresh)
+          },
+        )
+      },
     }))
 
     // Meta-introspection ("DevTools for the DevTools"), provided by the
     // official devframe inspector plugin (replaces the former
-    // `@vitejs/devtools-self-inspect` package).
-    plugins.push(createPluginFromDevframe(createInspectDevframe(), {
+    // `@vitejs/devtools-self-inspect` package). Pinned to a stable id so the
+    // client can gate it behind the `showDevframeInspector` user setting;
+    // hidden by default (opt in via Settings → Advanced).
+    plugins.push(createPluginFromDevframe(createInspectDevframe({ id: DEVTOOLS_INSPECTOR_DOCK_ID }), {
       dock: { category: '~builtin', icon: 'ph:stethoscope-duotone' },
     }))
   }
@@ -76,6 +108,33 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
   return plugins
 }
 
+/**
+ * Keep a dock entry out of the dock bar while its backing collection is empty.
+ *
+ * Mirrors the hub's built-in `~terminals` / `~messages` auto-hide: sets the
+ * dock's `when` clause to `'false'` (unconditionally hidden) when `isEmpty()`
+ * and clears it otherwise, re-evaluating whenever the passed `subscribe`
+ * callback fires. Each `docks.update` re-broadcasts the dock shared state.
+ */
+function hideDockWhenEmpty(
+  ctx: KitNodeContext,
+  dockId: string,
+  isEmpty: () => boolean,
+  subscribe: (refresh: () => void) => void,
+): void {
+  const sync = (): void => {
+    const view = ctx.docks.views.get(dockId)
+    if (!view)
+      return
+    const when = isEmpty() ? 'false' : undefined
+    if (view.when === when)
+      return
+    ctx.docks.update({ ...view, when })
+  }
+  subscribe(sync)
+  sync()
+}
+
 export {
   DevToolsBuild,
   DevToolsInjection,
diff --git a/packages/kit/src/constants.ts b/packages/kit/src/constants.ts
index 37e57dd8..0894f181 100644
--- a/packages/kit/src/constants.ts
+++ b/packages/kit/src/constants.ts
@@ -40,6 +40,14 @@ export const DEVTOOLS_DOCK_IMPORTS_VIRTUAL_ID = '/__devtools-client-imports.js'
  */
 export const DEVTOOLS_VITEPLUS_GROUP_ID = '~viteplus'
 
+/**
+ * Dock id of the built-in Devframe Inspector (mounted from
+ * `@devframes/plugin-inspect`). Shared between the node side (which pins the
+ * mounted devframe to this id) and the client (which gates the dock behind the
+ * `showDevframeInspector` user setting).
+ */
+export const DEVTOOLS_INSPECTOR_DOCK_ID = 'devframes-plugin-inspect'
+
 export const DEFAULT_CATEGORIES_ORDER: Record<string, number> = {
   'default': 0,
   'app': 100,
diff --git a/packages/kit/src/types/settings.ts b/packages/kit/src/types/settings.ts
index 165992f9..9466f1f2 100644
--- a/packages/kit/src/types/settings.ts
+++ b/packages/kit/src/types/settings.ts
@@ -1 +1,18 @@
-export type { DevframeDocksUserSettings as DevToolsDocksUserSettings } from '@devframes/hub/types'
+import type { DevframeDocksUserSettings } from '@devframes/hub/types'
+
+/**
+ * Vite DevTools user settings — the hub's {@link DevframeDocksUserSettings}
+ * widened with Vite-flavored toggles that only Vite DevTools ships.
+ *
+ * The extra fields are optional so the hub's `DEFAULT_STATE_USER_SETTINGS()`
+ * (which knows nothing about them) stays assignable; an absent value reads as
+ * its documented default.
+ */
+export interface DevToolsDocksUserSettings extends DevframeDocksUserSettings {
+  /**
+   * Reveal the Devframe Inspector dock (the "DevTools for the DevTools"
+   * meta-introspection panel). Hidden by default — an absent value keeps the
+   * dock out of the dock bar until the user opts in from Settings → Advanced.
+   */
+  showDevframeInspector?: boolean
+}
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.d.ts
index 075fd4a3..00e445dd 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.d.ts
@@ -5,6 +5,7 @@
 export declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
 export declare const DEVTOOLS_DIRNAME: string;
 export declare const DEVTOOLS_DOCK_IMPORTS_VIRTUAL_ID: string;
+export declare const DEVTOOLS_INSPECTOR_DOCK_ID: string;
 export declare const DEVTOOLS_MOUNT_PATH: string;
 export declare const DEVTOOLS_MOUNT_PATH_NO_TRAILING_SLASH: string;
 export declare const DEVTOOLS_VITEPLUS_GROUP_ID: string;
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.js b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.js
index 7d4a7cf2..2f2cf2a4 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.js
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/constants.snapshot.js
@@ -5,6 +5,7 @@
 export var DEFAULT_CATEGORIES_ORDER /* const */
 export var DEVTOOLS_DIRNAME /* const */
 export var DEVTOOLS_DOCK_IMPORTS_VIRTUAL_ID /* const */
+export var DEVTOOLS_INSPECTOR_DOCK_ID /* const */
 export var DEVTOOLS_MOUNT_PATH /* const */
 export var DEVTOOLS_MOUNT_PATH_NO_TRAILING_SLASH /* const */
 export var DEVTOOLS_VITEPLUS_GROUP_ID /* const */

From aa13f4cdea9eae542f6fd13a34410ebecb9feb54 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 10 Jul 2026 04:35:17 +0000
Subject: [PATCH 2/3] refactor: auto-hide empty docks via a native when getter
 instead of event wiring

---
 packages/core/src/node/plugins/index.ts | 54 ++++++++++---------------
 1 file changed, 21 insertions(+), 33 deletions(-)

diff --git a/packages/core/src/node/plugins/index.ts b/packages/core/src/node/plugins/index.ts
index a749242f..71bfb63a 100644
--- a/packages/core/src/node/plugins/index.ts
+++ b/packages/core/src/node/plugins/index.ts
@@ -69,29 +69,14 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
     plugins.push(createPluginFromDevframe(terminalsDevframe, {
       dock: { category: '~builtin' },
       setup(ctx) {
-        hideDockWhenEmpty(
-          ctx,
-          terminalsDevframe.id,
-          () => ctx.terminals.sessions.size === 0,
-          refresh => ctx.terminals.events.on('terminal:session:updated', refresh),
-        )
+        hideDockWhenEmpty(ctx, terminalsDevframe.id, () => ctx.terminals.sessions.size === 0)
       },
     }))
     const messagesDevframe = createMessagesDevframe()
     plugins.push(createPluginFromDevframe(messagesDevframe, {
       dock: { category: '~builtin' },
       setup(ctx) {
-        hideDockWhenEmpty(
-          ctx,
-          messagesDevframe.id,
-          () => ctx.messages.entries.size === 0,
-          (refresh) => {
-            ctx.messages.events.on('message:added', refresh)
-            ctx.messages.events.on('message:updated', refresh)
-            ctx.messages.events.on('message:removed', refresh)
-            ctx.messages.events.on('message:cleared', refresh)
-          },
-        )
+        hideDockWhenEmpty(ctx, messagesDevframe.id, () => ctx.messages.entries.size === 0)
       },
     }))
 
@@ -111,28 +96,31 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
 /**
  * Keep a dock entry out of the dock bar while its backing collection is empty.
  *
- * Mirrors the hub's built-in `~terminals` / `~messages` auto-hide: sets the
- * dock's `when` clause to `'false'` (unconditionally hidden) when `isEmpty()`
- * and clears it otherwise, re-evaluating whenever the passed `subscribe`
- * callback fires. Each `docks.update` re-broadcasts the dock shared state.
+ * Mirrors the hub's built-in `~terminals` / `~messages` docks: attaches a live
+ * `when` getter to the registered entry that resolves to `'false'`
+ * (unconditionally hidden) while `isEmpty()` and `undefined` (visible)
+ * otherwise. The hub already re-serializes the dock shared state on every
+ * terminal / message change, so the getter is re-read at exactly the right
+ * moments — no explicit event subscription needed here.
+ *
+ * TODO: once devframe/hub ships first-class support for a functional `when`
+ * (`when?: () => string | boolean | undefined`, resolved during dock
+ * serialization), this can become a plain `dock: { when: () => ... }` option
+ * on `createPluginFromDevframe` and the getter trick can be deleted.
  */
 function hideDockWhenEmpty(
   ctx: KitNodeContext,
   dockId: string,
   isEmpty: () => boolean,
-  subscribe: (refresh: () => void) => void,
 ): void {
-  const sync = (): void => {
-    const view = ctx.docks.views.get(dockId)
-    if (!view)
-      return
-    const when = isEmpty() ? 'false' : undefined
-    if (view.when === when)
-      return
-    ctx.docks.update({ ...view, when })
-  }
-  subscribe(sync)
-  sync()
+  const view = ctx.docks.views.get(dockId)
+  if (!view)
+    return
+  Object.defineProperty(view, 'when', {
+    enumerable: true,
+    configurable: true,
+    get: () => (isEmpty() ? 'false' : undefined),
+  })
 }
 
 export {

From dbd2d4830697c1fa4b1a0fb2e59b1d83774d0f0b Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 10 Jul 2026 05:30:41 +0000
Subject: [PATCH 3/3] fix: apply empty-dock auto-hide in playground; extract
 hideDockWhenEmpty helper

---
 packages/core/playground/vite.config.ts       | 28 ++++++++++---
 .../node/plugins/__tests__/auto-hide.test.ts  | 41 +++++++++++++++++++
 packages/core/src/node/plugins/auto-hide.ts   | 34 +++++++++++++++
 packages/core/src/node/plugins/index.ts       | 32 +--------------
 4 files changed, 98 insertions(+), 37 deletions(-)
 create mode 100644 packages/core/src/node/plugins/__tests__/auto-hide.test.ts
 create mode 100644 packages/core/src/node/plugins/auto-hide.ts

diff --git a/packages/core/playground/vite.config.ts b/packages/core/playground/vite.config.ts
index 1d4e6c4e..54bd570c 100644
--- a/packages/core/playground/vite.config.ts
+++ b/packages/core/playground/vite.config.ts
@@ -13,6 +13,7 @@ import { A11yCheckerPlugin } from '../../../examples/plugin-a11y-checker/src/nod
 import { GitUIPlugin } from '../../../examples/plugin-git-ui/src/node'
 import { DevTools } from '../../core/src'
 import { buildCSS } from '../../core/src/client/webcomponents/scripts/build-css'
+import { hideDockWhenEmpty } from '../../core/src/node/plugins/auto-hide'
 // eslint-disable-next-line ts/ban-ts-comment
 // @ts-ignore ignore the type error
 import { DevToolsRolldownUI } from '../../rolldown/src/node'
@@ -35,12 +36,27 @@ export default defineConfig({
   plugins: [
     VueRouter(),
     Vue(),
-    createPluginFromDevframe(createTerminalsDevframe(), {
-      dock: { category: '~builtin' },
-    }),
-    createPluginFromDevframe(createMessagesDevframe(), {
-      dock: { category: '~builtin' },
-    }),
+    ...(() => {
+      // Mirror the shipped `DevTools()` mounts (the playground runs with
+      // `builtinDevTools: false`, so it re-creates them by hand): terminals
+      // and messages auto-hide from the dock bar while empty.
+      const terminalsDevframe = createTerminalsDevframe()
+      const messagesDevframe = createMessagesDevframe()
+      return [
+        createPluginFromDevframe(terminalsDevframe, {
+          dock: { category: '~builtin' },
+          setup(ctx) {
+            hideDockWhenEmpty(ctx, terminalsDevframe.id, () => ctx.terminals.sessions.size === 0)
+          },
+        }),
+        createPluginFromDevframe(messagesDevframe, {
+          dock: { category: '~builtin' },
+          setup(ctx) {
+            hideDockWhenEmpty(ctx, messagesDevframe.id, () => ctx.messages.entries.size === 0)
+          },
+        }),
+      ]
+    })(),
     createPluginFromDevframe(createInspectDevframe(), {
       dock: { category: '~builtin', icon: 'ph:stethoscope-duotone' },
     }),
diff --git a/packages/core/src/node/plugins/__tests__/auto-hide.test.ts b/packages/core/src/node/plugins/__tests__/auto-hide.test.ts
new file mode 100644
index 00000000..27352f51
--- /dev/null
+++ b/packages/core/src/node/plugins/__tests__/auto-hide.test.ts
@@ -0,0 +1,41 @@
+import type { KitNodeContext } from '@vitejs/devtools-kit/node'
+import { describe, expect, it } from 'vitest'
+import { hideDockWhenEmpty } from '../auto-hide'
+
+interface FakeView { id: string, type: string, url: string, title: string, when?: string }
+
+function fakeCtx(views: FakeView[]): { ctx: KitNodeContext, get: (id: string) => FakeView } {
+  const map = new Map(views.map(v => [v.id, v]))
+  const ctx = { docks: { views: map } } as unknown as KitNodeContext
+  return { ctx, get: id => map.get(id)! }
+}
+
+describe('hideDockWhenEmpty', () => {
+  it('resolves `when` live from the isEmpty callback', () => {
+    let empty = true
+    const { ctx, get } = fakeCtx([{ id: 'x', type: 'iframe', url: '/', title: 'X' }])
+
+    hideDockWhenEmpty(ctx, 'x', () => empty)
+
+    // Hidden while empty, visible once populated — re-read on every access.
+    expect(get('x').when).toBe('false')
+    empty = false
+    expect(get('x').when).toBeUndefined()
+    empty = true
+    expect(get('x').when).toBe('false')
+  })
+
+  it('attaches an enumerable `when` so it survives serialization', () => {
+    const { ctx, get } = fakeCtx([{ id: 'x', type: 'iframe', url: '/', title: 'X' }])
+    hideDockWhenEmpty(ctx, 'x', () => true)
+
+    // Enumerable getters are picked up by JSON.stringify (the shared-state wire
+    // format), so the resolved value reaches the client filter.
+    expect(JSON.parse(JSON.stringify(get('x'))).when).toBe('false')
+  })
+
+  it('is a no-op when the dock id is not registered', () => {
+    const { ctx } = fakeCtx([])
+    expect(() => hideDockWhenEmpty(ctx, 'missing', () => true)).not.toThrow()
+  })
+})
diff --git a/packages/core/src/node/plugins/auto-hide.ts b/packages/core/src/node/plugins/auto-hide.ts
new file mode 100644
index 00000000..be0776ed
--- /dev/null
+++ b/packages/core/src/node/plugins/auto-hide.ts
@@ -0,0 +1,34 @@
+import type { KitNodeContext } from '@vitejs/devtools-kit/node'
+
+/**
+ * Keep a dock entry out of the dock bar while its backing collection is empty.
+ *
+ * Mirrors the hub's built-in `~terminals` / `~messages` docks: attaches a live
+ * `when` getter to the registered entry that resolves to `'false'`
+ * (unconditionally hidden) while `isEmpty()` and `undefined` (visible)
+ * otherwise. The hub already re-serializes the dock shared state on every
+ * terminal / message change, so the getter is re-read at exactly the right
+ * moments — no explicit event subscription needed here.
+ *
+ * Call this from the `setup(ctx)` hook of the `createPluginFromDevframe` mount,
+ * after the auto-derived dock entry has been registered.
+ *
+ * TODO: once devframe/hub ships first-class support for a functional `when`
+ * (`when?: () => string | boolean | undefined`, resolved during dock
+ * serialization), this can become a plain `dock: { when: () => ... }` option
+ * on `createPluginFromDevframe` and the getter trick can be deleted.
+ */
+export function hideDockWhenEmpty(
+  ctx: KitNodeContext,
+  dockId: string,
+  isEmpty: () => boolean,
+): void {
+  const view = ctx.docks.views.get(dockId)
+  if (!view)
+    return
+  Object.defineProperty(view, 'when', {
+    enumerable: true,
+    configurable: true,
+    get: () => (isEmpty() ? 'false' : undefined),
+  })
+}
diff --git a/packages/core/src/node/plugins/index.ts b/packages/core/src/node/plugins/index.ts
index 71bfb63a..31372fd2 100644
--- a/packages/core/src/node/plugins/index.ts
+++ b/packages/core/src/node/plugins/index.ts
@@ -1,10 +1,10 @@
-import type { KitNodeContext } from '@vitejs/devtools-kit/node'
 import type { Plugin } from 'vite'
 import { createInspectDevframe } from '@devframes/plugin-inspect'
 import { createMessagesDevframe } from '@devframes/plugin-messages'
 import { createTerminalsDevframe } from '@devframes/plugin-terminals'
 import { DEVTOOLS_INSPECTOR_DOCK_ID } from '@vitejs/devtools-kit/constants'
 import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
+import { hideDockWhenEmpty } from './auto-hide'
 import { DevToolsBuild } from './build'
 import { DevToolsInjection } from './injection'
 import { DevToolsServer } from './server'
@@ -93,36 +93,6 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
   return plugins
 }
 
-/**
- * Keep a dock entry out of the dock bar while its backing collection is empty.
- *
- * Mirrors the hub's built-in `~terminals` / `~messages` docks: attaches a live
- * `when` getter to the registered entry that resolves to `'false'`
- * (unconditionally hidden) while `isEmpty()` and `undefined` (visible)
- * otherwise. The hub already re-serializes the dock shared state on every
- * terminal / message change, so the getter is re-read at exactly the right
- * moments — no explicit event subscription needed here.
- *
- * TODO: once devframe/hub ships first-class support for a functional `when`
- * (`when?: () => string | boolean | undefined`, resolved during dock
- * serialization), this can become a plain `dock: { when: () => ... }` option
- * on `createPluginFromDevframe` and the getter trick can be deleted.
- */
-function hideDockWhenEmpty(
-  ctx: KitNodeContext,
-  dockId: string,
-  isEmpty: () => boolean,
-): void {
-  const view = ctx.docks.views.get(dockId)
-  if (!view)
-    return
-  Object.defineProperty(view, 'when', {
-    enumerable: true,
-    configurable: true,
-    get: () => (isEmpty() ? 'false' : undefined),
-  })
-}
-
 export {
   DevToolsBuild,
   DevToolsInjection,