feat: hide Devframe Inspector by default and auto-hide empty terminals/messages docks

Author: antfubot

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">

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')

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
 

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,24 +60,81 @@ 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' },
     }))
   }
 
   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,

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,

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
+}

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;

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 */