From 1dbec7fe9e5c8d530bc5837550fb7135cf0e65d2 Mon Sep 17 00:00:00 2001
From: yu859 <15715093608@163.com>
Date: Sat, 22 Aug 2026 11:48:14 +0800
Subject: [PATCH 1/2] fix(hub-ui): bind shortcuts to nested commands at any
 depth

Every consumer of the command tree walked a single level of `children`, so
anything deeper was unreachable: a dock group's members had no row in the
shortcut settings to bind, no entry in the keybinding collector to fire, and
no id the dispatcher could resolve.

Traversal now lives in one place. `walkCommands` visits the tree depth-first
with a `'skip'`/`'stop'` visitor signal, and `findCommandDeep`,
`collectAllKeybindings`, the shortcut settings rows and the palette's root
flatten all share it. `filterCommandsByWhen` keeps its own recursion since it
rebuilds a cloned tree per level.

The palette's flatten and drill-down stack move to `state/palette.ts`, where
`showInPalette: 'without-children'` prunes a whole subtree rather than one
level, and a row carries its full path for search while displaying only its
immediate parent. Shortcut rows indent by nesting level instead of a boolean.
---
 .../command-palette/CommandPalette.vue        |  85 ++++----
 .../views-builtin/SettingsShortcuts.vue       |  58 +++---
 .../src/client/state/keybindings.test.ts      | 191 ++++++++++++++++++
 .../hub-ui/src/client/state/keybindings.ts    |  96 ++++++---
 .../hub-ui/src/client/state/palette.test.ts   | 106 ++++++++++
 packages/hub-ui/src/client/state/palette.ts   |  81 ++++++++
 packages/hub/src/types/commands.ts            |   4 +-
 7 files changed, 534 insertions(+), 87 deletions(-)
 create mode 100644 packages/hub-ui/src/client/state/keybindings.test.ts
 create mode 100644 packages/hub-ui/src/client/state/palette.test.ts
 create mode 100644 packages/hub-ui/src/client/state/palette.ts

diff --git a/packages/hub-ui/src/client/components/command-palette/CommandPalette.vue b/packages/hub-ui/src/client/components/command-palette/CommandPalette.vue
index 1aba472c..6e5d1cd1 100644
--- a/packages/hub-ui/src/client/components/command-palette/CommandPalette.vue
+++ b/packages/hub-ui/src/client/components/command-palette/CommandPalette.vue
@@ -1,8 +1,10 @@
 <script setup lang="ts">
 import type { DevframeClientCommand, DevframeCommandEntry } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
+import type { PaletteCrumb, PaletteFlatItem } from '../../state/palette'
 import Fuse from 'fuse.js'
 import { computed, nextTick, ref, useTemplateRef, watch } from 'vue'
+import { flattenPaletteCommands, paletteScopeTrail } from '../../state/palette'
 import BrandWordmark from '../icons/BrandWordmark.vue'
 import CommandPaletteItem from './CommandPaletteItem.vue'
 
@@ -23,36 +25,14 @@ const listContainer = useTemplateRef<HTMLElement>('listContainer')
 const visible = ref(false)
 
 // Breadcrumb stack for sub-command drill-down
-const breadcrumb = ref<Array<{ title: string, items: DevframeCommandEntry[] }>>([])
+const breadcrumb = ref<PaletteCrumb[]>([])
 
-// Flattened items for top-level search (includes children with parent prefix)
-interface FlatItem {
-  entry: DevframeCommandEntry
-  parentTitle?: string
-  searchTitle: string
-}
-
-const flattenedItems = computed<FlatItem[]>(() => {
-  const result: FlatItem[] = []
-  for (const cmd of commandsCtx.value.paletteCommands) {
-    result.push({ entry: cmd, searchTitle: cmd.title })
-    if (cmd.children && cmd.showInPalette !== 'without-children') {
-      for (const child of cmd.children) {
-        if (child.showInPalette === false)
-          continue
-        result.push({
-          entry: child as DevframeCommandEntry,
-          parentTitle: cmd.title,
-          searchTitle: `${cmd.title} > ${child.title}`,
-        })
-      }
-    }
-  }
-  return result
-})
+const flattenedItems = computed<PaletteFlatItem[]>(
+  () => flattenPaletteCommands(commandsCtx.value.paletteCommands),
+)
 
 // Current items: either drilled-down sub-items or root items
-const currentFlatItems = computed<FlatItem[]>(() => {
+const currentFlatItems = computed<PaletteFlatItem[]>(() => {
   if (breadcrumb.value.length > 0) {
     const current = breadcrumb.value.at(-1)!
     return current.items.map(entry => ({ entry, searchTitle: entry.title }))
@@ -62,7 +42,7 @@ const currentFlatItems = computed<FlatItem[]>(() => {
 
 // Dynamic sub-items from action() return
 const dynamicItems = ref<DevframeClientCommand[] | undefined>()
-const activeItems = computed<FlatItem[]>(() => {
+const activeItems = computed<PaletteFlatItem[]>(() => {
   if (dynamicItems.value) {
     return dynamicItems.value.map(entry => ({ entry, searchTitle: entry.title }))
   }
@@ -85,12 +65,17 @@ watch(search, () => {
   selectedIndex.value = 0
 })
 
+/** Show the rows at `scopeId`'s level, from a fresh search. */
+function showScope(scopeId: string | null) {
+  search.value = ''
+  selectedIndex.value = 0
+  dynamicItems.value = undefined
+  breadcrumb.value = paletteScopeTrail(commandsCtx.value.paletteCommands, scopeId)
+}
+
 watch(show, (v) => {
   if (v) {
-    search.value = ''
-    selectedIndex.value = 0
-    breadcrumb.value = []
-    dynamicItems.value = undefined
+    showScope(commandsCtx.value.paletteScopeId)
     // Trigger enter animation
     requestAnimationFrame(() => {
       visible.value = true
@@ -99,9 +84,22 @@ watch(show, (v) => {
   }
   else {
     visible.value = false
+    // Every close path funnels through `show` — Escape, the backdrop, running a
+    // command, and a bare `paletteOpen` toggle — so the scope is dropped here
+    // once rather than in each of them. A later Mod+K then opens at the root
+    // instead of resurrecting the group it was last scoped to.
+    commandsCtx.value.paletteScopeId = null
   }
 })
 
+// A scope also arrives while the palette is already open — activating a dock
+// group picked from the root list, say. `show` stays `true` throughout, so the
+// drill-down follows the scope itself rather than the open transition.
+watch(() => commandsCtx.value.paletteScopeId, (scopeId) => {
+  if (show.value && scopeId)
+    showScope(scopeId)
+})
+
 function moveSelected(delta: number) {
   const len = filtered.value.length
   if (len === 0)
@@ -121,7 +119,7 @@ function scrollToItem() {
 
 const loadingId = ref<string | null>(null)
 
-async function enterItem(flatItem: FlatItem) {
+async function enterItem(flatItem: PaletteFlatItem) {
   const entry = flatItem.entry
 
   // If has static children, drill down
@@ -195,6 +193,7 @@ function goBack() {
   }
   if (breadcrumb.value.length > 0) {
     breadcrumb.value.pop()
+    dropScopeAtRoot()
     search.value = ''
     selectedIndex.value = 0
     return
@@ -202,6 +201,24 @@ function goBack() {
   close()
 }
 
+/** Jump to the level the crumb at `index` sits above. */
+function goToCrumb(index: number) {
+  breadcrumb.value.splice(index)
+  dropScopeAtRoot()
+  search.value = ''
+  selectedIndex.value = 0
+}
+
+/**
+ * Stepping back out to the root list leaves the palette unscoped, so the
+ * shortcut that scoped it drills back in instead of reading as "press again to
+ * close".
+ */
+function dropScopeAtRoot() {
+  if (breadcrumb.value.length === 0)
+    commandsCtx.value.paletteScopeId = null
+}
+
 function onKeyDown(e: KeyboardEvent) {
   if (e.key === 'Backspace' && !search.value && (breadcrumb.value.length > 0 || dynamicItems.value)) {
     e.preventDefault()
@@ -275,7 +292,7 @@ function getKeybindings(id: string) {
                 v-for="(crumb, i) in breadcrumb"
                 :key="i"
                 class="text-xs op60 hover:op80 mr-1 flex items-center gap-0.5"
-                @click="breadcrumb.splice(i); search = ''; selectedIndex = 0"
+                @click="goToCrumb(i)"
               >
                 {{ crumb.title }}
                 <span class="op40">&rsaquo;</span>
diff --git a/packages/hub-ui/src/client/components/views-builtin/SettingsShortcuts.vue b/packages/hub-ui/src/client/components/views-builtin/SettingsShortcuts.vue
index c056d767..fec845c0 100644
--- a/packages/hub-ui/src/client/components/views-builtin/SettingsShortcuts.vue
+++ b/packages/hub-ui/src/client/components/views-builtin/SettingsShortcuts.vue
@@ -3,7 +3,7 @@ import type { DevframeCommandEntry, DevframeCommandKeybinding } from '@devframes
 import type { DocksContext } from '@devframes/hub/client'
 import DisplayKbd from '@antfu/design/components/Display/DisplayKbd.vue'
 import { computed, nextTick, ref, watch } from 'vue'
-import { filterCommandsByWhen, formatKeybinding, isKeybindingOverrideDifferentFromDefault, isMac, KNOWN_BROWSER_SHORTCUTS } from '../../state/keybindings'
+import { filterCommandsByWhen, findCommandDeep, formatKeybinding, isKeybindingOverrideDifferentFromDefault, isMac, KNOWN_BROWSER_SHORTCUTS, walkCommands } from '../../state/keybindings'
 import { useSettings } from '../../state/settings-defaults'
 import DockIcon from '../dock/DockIcon.vue'
 
@@ -19,7 +19,8 @@ const shortcutSearch = ref('')
 interface ShortcutRow {
   command: DevframeCommandEntry
   parentTitle?: string
-  indent: boolean
+  /** Nesting level — 0 for a top-level command, +1 per ancestor. */
+  depth: number
 }
 
 // This page is only reachable with the dock open and the palette closed, so `when`
@@ -34,20 +35,24 @@ const availableCommands = computed(() => filterCommandsByWhen(
   { ...props.context.when.context, dockOpen: true, paletteOpen: false },
 ))
 
+/**
+ * One row per command at every depth, in tree order, so anything the palette
+ * can run can be given a shortcut here.
+ *
+ * Nesting runs deeper than a parent and its children: a dock group's members sit
+ * two levels below the `Docks` command, and a devframe's own `children` go deeper
+ * still.
+ */
 const shortcutRows = computed<ShortcutRow[]>(() => {
   const rows: ShortcutRow[] = []
-  for (const cmd of availableCommands.value) {
-    rows.push({ command: cmd, indent: false })
-    if (cmd.children) {
-      for (const child of cmd.children) {
-        rows.push({
-          command: child as DevframeCommandEntry,
-          parentTitle: cmd.title,
-          indent: true,
-        })
-      }
-    }
-  }
+  walkCommands(availableCommands.value, (cmd, ancestors) => {
+    const parentTitle = ancestors.at(-1)?.title
+    rows.push({
+      command: cmd,
+      ...(parentTitle ? { parentTitle } : {}),
+      depth: ancestors.length,
+    })
+  })
   return rows
 })
 
@@ -66,6 +71,16 @@ function getEffectiveKeybindings(id: string): DevframeCommandKeybinding[] {
   return commandsCtx.getKeybindings(id)
 }
 
+/**
+ * Indent one step per nesting level. An inline style rather than a class, since
+ * the depth is only known at runtime and UnoCSS generates utilities from source
+ * — a computed `ml-${depth * 6}` would never be emitted. One step is `ml-6`
+ * worth of space.
+ */
+function rowIndentStyle(row: ShortcutRow): Record<string, string> {
+  return row.depth > 0 ? { marginLeft: `${row.depth * 1.5}rem` } : {}
+}
+
 function isExecutable(command: DevframeCommandEntry): boolean {
   return command.source === 'server' || !!command.action
 }
@@ -75,16 +90,7 @@ function isOverridden(id: string): boolean {
 }
 
 function getDefaultKeybindings(id: string): DevframeCommandKeybinding[] {
-  for (const cmd of commandsCtx.commands) {
-    if (cmd.id === id)
-      return cmd.keybindings ?? []
-    if (cmd.children) {
-      const child = cmd.children.find(c => c.id === id)
-      if (child)
-        return child.keybindings ?? []
-    }
-  }
-  return []
+  return findCommandDeep(commandsCtx.commands, id)?.keybindings ?? []
 }
 
 function clearShortcut(commandId: string) {
@@ -281,9 +287,9 @@ watch(editorOpen, async (v) => {
         v-if="row.command.icon"
         :icon="row.command.icon"
         class="w-4 h-4 shrink-0 op60"
-        :class="{ 'ml-6': row.indent }"
+        :style="rowIndentStyle(row)"
       />
-      <div v-else :class="{ 'ml-6': row.indent }" class="w-4 h-4 shrink-0" />
+      <div v-else :style="rowIndentStyle(row)" class="w-4 h-4 shrink-0" />
       <div class="flex-1 min-w-0">
         <div class="flex items-center gap-1.5">
           <span class="truncate text-sm">{{ row.command.title }}</span>
diff --git a/packages/hub-ui/src/client/state/keybindings.test.ts b/packages/hub-ui/src/client/state/keybindings.test.ts
new file mode 100644
index 00000000..7c724f06
--- /dev/null
+++ b/packages/hub-ui/src/client/state/keybindings.test.ts
@@ -0,0 +1,191 @@
+import type { DevframeCommandEntry, DevframeCommandKeybinding } from '@devframes/hub'
+import type { WhenContext } from 'devframe/utils/when'
+import { describe, expect, it } from 'vitest'
+import { collectAllKeybindings, filterCommandsByWhen, findCommandDeep, walkCommands } from './keybindings'
+
+/**
+ * Dock-navigation commands nest two deep (`Docks` › a group › its members), and
+ * a devframe is free to register its own `children` deeper still — this tree carries
+ * a third level so the traversal is exercised past any fixed depth.
+ */
+const commands = [
+  {
+    id: 'devframes:docks',
+    source: 'client',
+    title: 'Docks',
+    children: [
+      { id: 'devframes:docks:overview', source: 'client', title: 'Overview' },
+      {
+        id: 'devframes:docks:playground',
+        source: 'client',
+        title: 'Playground',
+        children: [
+          { id: 'devframes:docks:playground:one', source: 'client', title: 'One' },
+          { id: 'devframes:docks:playground:two', source: 'client', title: 'Two' },
+        ],
+      },
+      {
+        id: 'devframes:docks:tools',
+        source: 'client',
+        title: 'Tools',
+        children: [
+          {
+            id: 'host:tools:submenu',
+            source: 'client',
+            title: 'Advanced',
+            children: [
+              { id: 'devframes:docks:tools:graph', source: 'client', title: 'Graph' },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+] as unknown as DevframeCommandEntry[]
+
+const whenContext: WhenContext = {
+  clientType: 'embedded',
+  dockOpen: true,
+  paletteOpen: false,
+  dockSelectedId: '',
+  popupOpen: false,
+}
+
+describe('walkCommands', () => {
+  it('visits every command at every depth, parents before children', () => {
+    const seen: Array<[string, number]> = []
+    walkCommands(commands, (cmd, ancestors) => {
+      seen.push([cmd.id, ancestors.length])
+    })
+
+    expect(seen).toEqual([
+      ['devframes:docks', 0],
+      ['devframes:docks:overview', 1],
+      ['devframes:docks:playground', 1],
+      ['devframes:docks:playground:one', 2],
+      ['devframes:docks:playground:two', 2],
+      ['devframes:docks:tools', 1],
+      ['host:tools:submenu', 2],
+      ['devframes:docks:tools:graph', 3],
+    ])
+  })
+
+  it('hands each command its ancestor chain, outermost first', () => {
+    let ancestorTitles: string[] = []
+    walkCommands(commands, (cmd, ancestors) => {
+      if (cmd.id === 'devframes:docks:tools:graph')
+        ancestorTitles = ancestors.map(a => a.title)
+    })
+
+    expect(ancestorTitles).toEqual(['Docks', 'Tools', 'Advanced'])
+  })
+
+  it('leaves a subtree unvisited when the visitor returns `skip`', () => {
+    const seen: string[] = []
+    walkCommands(commands, (cmd) => {
+      seen.push(cmd.id)
+      if (cmd.id === 'devframes:docks:playground')
+        return 'skip'
+    })
+
+    expect(seen).toEqual([
+      'devframes:docks',
+      'devframes:docks:overview',
+      'devframes:docks:playground',
+      'devframes:docks:tools',
+      'host:tools:submenu',
+      'devframes:docks:tools:graph',
+    ])
+  })
+
+  it('ends the walk from any depth when the visitor returns `stop`', () => {
+    const seen: string[] = []
+    walkCommands(commands, (cmd) => {
+      seen.push(cmd.id)
+      if (cmd.id === 'devframes:docks:playground:one')
+        return 'stop'
+    })
+
+    expect(seen).toEqual([
+      'devframes:docks',
+      'devframes:docks:overview',
+      'devframes:docks:playground',
+      'devframes:docks:playground:one',
+    ])
+  })
+})
+
+describe('findCommandDeep', () => {
+  it('finds a group member nested two levels down', () => {
+    expect(findCommandDeep(commands, 'devframes:docks:playground:two')?.title).toBe('Two')
+  })
+
+  it('finds a command below a devframe submenu, three levels down', () => {
+    expect(findCommandDeep(commands, 'devframes:docks:tools:graph')?.title).toBe('Graph')
+  })
+
+  it('returns undefined for an unknown id', () => {
+    expect(findCommandDeep(commands, 'devframes:docks:nope')).toBeUndefined()
+  })
+})
+
+describe('collectAllKeybindings', () => {
+  it('collects bindings from nested commands at any depth', () => {
+    const bound: Record<string, DevframeCommandKeybinding[]> = {
+      'devframes:docks:playground:two': [{ key: 'Mod+2' }],
+      'devframes:docks:tools:graph': [{ key: 'Mod+G' }],
+    }
+
+    const result = collectAllKeybindings(
+      { value: commands },
+      id => bound[id] ?? [],
+    )
+
+    expect(result).toEqual([
+      { id: 'devframes:docks:playground:two', keybinding: { key: 'Mod+2' } },
+      { id: 'devframes:docks:tools:graph', keybinding: { key: 'Mod+G' } },
+    ])
+  })
+})
+
+describe('filterCommandsByWhen', () => {
+  it('evaluates `when` on descendants at every depth', () => {
+    const withWhen = [
+      {
+        id: 'root',
+        source: 'client',
+        title: 'Root',
+        children: [
+          {
+            id: 'branch',
+            source: 'client',
+            title: 'Branch',
+            children: [
+              { id: 'kept', source: 'client', title: 'Kept' },
+              { id: 'dropped', source: 'client', title: 'Dropped', when: 'clientType == standalone' },
+            ],
+          },
+        ],
+      },
+    ] as unknown as DevframeCommandEntry[]
+
+    const [root] = filterCommandsByWhen(withWhen, whenContext)
+    const branch = root?.children?.[0] as DevframeCommandEntry | undefined
+
+    expect(branch?.children?.map(c => c.id)).toEqual(['kept'])
+  })
+
+  it('drops a whole subtree when the parent itself is unavailable', () => {
+    const withWhen = [
+      {
+        id: 'root',
+        source: 'client',
+        title: 'Root',
+        when: 'clientType == standalone',
+        children: [{ id: 'child', source: 'client', title: 'Child' }],
+      },
+    ] as unknown as DevframeCommandEntry[]
+
+    expect(filterCommandsByWhen(withWhen, whenContext)).toEqual([])
+  })
+})
diff --git a/packages/hub-ui/src/client/state/keybindings.ts b/packages/hub-ui/src/client/state/keybindings.ts
index f7cf0605..54a69437 100644
--- a/packages/hub-ui/src/client/state/keybindings.ts
+++ b/packages/hub-ui/src/client/state/keybindings.ts
@@ -58,10 +58,63 @@ export function isKeybindingOverrideDifferentFromDefault(
   return override !== undefined && !areKeybindingsEqual(override, defaults)
 }
 
+/**
+ * What a `walkCommands` visitor can ask the walk to do next: `'skip'` leaves the
+ * current command's subtree unvisited, `'stop'` ends the whole walk.
+ */
+export type WalkCommandsSignal = 'skip' | 'stop'
+
+/**
+ * Walk the command tree depth-first, parents before their children, and hand
+ * each command its chain of ancestors (outermost first, empty at the top level).
+ *
+ * Commands nest arbitrarily deep — dock-navigation commands reach `Docks` ›
+ * group › member, and a devframe's own `children` go deeper still — so read-only
+ * consumers share this walk rather than recursing themselves. Transforms that
+ * rebuild the tree (see {@link filterCommandsByWhen}) still recurse on their
+ * own, since they need to return a new node per level.
+ */
+export function walkCommands(
+  commands: DevframeCommandEntry[],
+  visit: (cmd: DevframeCommandEntry, ancestors: DevframeCommandEntry[]) => WalkCommandsSignal | void,
+  ancestors: DevframeCommandEntry[] = [],
+): WalkCommandsSignal | void {
+  for (const cmd of commands) {
+    const signal = visit(cmd, ancestors)
+    if (signal === 'stop')
+      return 'stop'
+    if (signal === 'skip' || !cmd.children?.length)
+      continue
+    // `children` is typed `Server[] | Client[]` rather than `(Server | Client)[]`,
+    // so walking it widens the element type — same cast the other child-walking
+    // call sites use.
+    if (walkCommands(cmd.children as DevframeCommandEntry[], visit, [...ancestors, cmd]) === 'stop')
+      return 'stop'
+  }
+}
+
+/**
+ * Find a command by id at any depth. Returns the first match in depth-first
+ * order — ids are expected to be unique across the tree.
+ */
+export function findCommandDeep(
+  commands: DevframeCommandEntry[],
+  id: string,
+): DevframeCommandEntry | undefined {
+  let found: DevframeCommandEntry | undefined
+  walkCommands(commands, (cmd) => {
+    if (cmd.id !== id)
+      return
+    found = cmd
+    return 'stop'
+  })
+  return found
+}
+
 /**
  * Drop the commands whose `when` clause does not hold in the current context,
- * children included — `when` is documented to control palette visibility, but
- * nothing evaluated it for nested entries.
+ * descendants included at every depth — `when` controls palette visibility at
+ * any nesting level.
  *
  * A parent that survives is shallow-cloned so its `children` can be narrowed
  * without mutating the registry. Callers therefore get fresh parent objects on
@@ -73,21 +126,22 @@ export function filterCommandsByWhen(
 ): DevframeCommandEntry[] {
   const isAvailable = (cmd: { when?: string }) => !cmd.when || evaluateWhen(cmd.when, ctx)
 
-  const result: DevframeCommandEntry[] = []
-  for (const cmd of commands) {
-    if (!isAvailable(cmd))
-      continue
-    if (!cmd.children) {
-      result.push(cmd)
-      continue
+  const filter = (list: DevframeCommandEntry[]): DevframeCommandEntry[] => {
+    const result: DevframeCommandEntry[] = []
+    for (const cmd of list) {
+      if (!isAvailable(cmd))
+        continue
+      if (!cmd.children) {
+        result.push(cmd)
+        continue
+      }
+      const children = filter(cmd.children as DevframeCommandEntry[])
+      result.push({ ...cmd, children } as DevframeCommandEntry)
     }
-    // `children` is typed `Server[] | Client[]` rather than `(Server | Client)[]`,
-    // so filtering it in place widens the element type — same cast the other
-    // child-walking call sites use.
-    const children = (cmd.children as DevframeCommandEntry[]).filter(isAvailable)
-    result.push({ ...cmd, children } as DevframeCommandEntry)
+    return result
   }
-  return result
+
+  return filter(commands)
 }
 
 export function collectAllKeybindings(
@@ -96,19 +150,11 @@ export function collectAllKeybindings(
 ): Array<{ id: string, keybinding: DevframeCommandKeybinding }> {
   const result: Array<{ id: string, keybinding: DevframeCommandKeybinding }> = []
 
-  for (const cmd of commands.value) {
+  walkCommands(commands.value, (cmd) => {
     for (const kb of getKeybindings(cmd.id)) {
       result.push({ id: cmd.id, keybinding: kb })
     }
-    // Also collect from children
-    if (cmd.children) {
-      for (const child of cmd.children) {
-        for (const kb of getKeybindings(child.id)) {
-          result.push({ id: child.id, keybinding: kb })
-        }
-      }
-    }
-  }
+  })
 
   return result
 }
diff --git a/packages/hub-ui/src/client/state/palette.test.ts b/packages/hub-ui/src/client/state/palette.test.ts
new file mode 100644
index 00000000..c3959790
--- /dev/null
+++ b/packages/hub-ui/src/client/state/palette.test.ts
@@ -0,0 +1,106 @@
+import type { DevframeCommandEntry } from '@devframes/hub'
+import { describe, expect, it } from 'vitest'
+import { flattenPaletteCommands, paletteScopeTrail } from './palette'
+
+/**
+ * The shape the palette actually sees: dock navigation two deep (`Docks` › a
+ * group › its members), plus the two `showInPalette` opt-outs a devframe can set.
+ */
+const commands = [
+  {
+    id: 'devframes:docks',
+    source: 'client',
+    title: 'Docks',
+    children: [
+      { id: 'devframes:docks:overview', source: 'client', title: 'Overview' },
+      {
+        id: 'devframes:docks:tools',
+        source: 'client',
+        title: 'Tools',
+        children: [
+          { id: 'devframes:docks:tools:a', source: 'client', title: 'A' },
+          { id: 'devframes:docks:tools:b', source: 'client', title: 'B' },
+        ],
+      },
+    ],
+  },
+  {
+    id: 'host:drill',
+    source: 'client',
+    title: 'Drill',
+    showInPalette: 'without-children',
+    children: [
+      {
+        id: 'host:drill:child',
+        source: 'client',
+        title: 'Child',
+        children: [{ id: 'host:drill:grandchild', source: 'client', title: 'Grandchild' }],
+      },
+    ],
+  },
+  {
+    id: 'host:hidden',
+    source: 'client',
+    title: 'Hidden',
+    showInPalette: false,
+    children: [{ id: 'host:hidden:child', source: 'client', title: 'Hidden child' }],
+  },
+] as unknown as DevframeCommandEntry[]
+
+describe('flattenPaletteCommands', () => {
+  it('lists a nested command with its full path for search and its parent for display', () => {
+    const rows = flattenPaletteCommands(commands)
+    const row = rows.find(r => r.entry.id === 'devframes:docks:tools:b')
+
+    expect(row).toEqual({
+      entry: expect.objectContaining({ id: 'devframes:docks:tools:b' }),
+      parentTitle: 'Tools',
+      searchTitle: 'Docks > Tools > B',
+    })
+  })
+
+  it('omits `parentTitle` for a top-level command', () => {
+    const rows = flattenPaletteCommands(commands)
+
+    expect(rows.find(r => r.entry.id === 'devframes:docks')).not.toHaveProperty('parentTitle')
+  })
+
+  it('keeps the whole subtree of `showInPalette: without-children` out of root search', () => {
+    const ids = flattenPaletteCommands(commands).map(r => r.entry.id)
+
+    expect(ids).toContain('host:drill')
+    expect(ids).not.toContain('host:drill:child')
+    expect(ids).not.toContain('host:drill:grandchild')
+  })
+
+  it('drops a `showInPalette: false` command along with its children', () => {
+    const ids = flattenPaletteCommands(commands).map(r => r.entry.id)
+
+    expect(ids).not.toContain('host:hidden')
+    expect(ids).not.toContain('host:hidden:child')
+  })
+})
+
+describe('paletteScopeTrail', () => {
+  it('builds the crumb stack a user would have clicked to reach the scope', () => {
+    const trail = paletteScopeTrail(commands, 'devframes:docks:tools')
+
+    expect(trail.map(c => c.title)).toEqual(['Docks', 'Tools'])
+    expect(trail.at(-1)!.items.map(i => i.id)).toEqual([
+      'devframes:docks:tools:a',
+      'devframes:docks:tools:b',
+    ])
+  })
+
+  it('opens the root list for no scope', () => {
+    expect(paletteScopeTrail(commands, null)).toEqual([])
+  })
+
+  it('opens the root list when the scoped command is gone', () => {
+    expect(paletteScopeTrail(commands, 'devframes:docks:unregistered')).toEqual([])
+  })
+
+  it('opens the root list for a command with nothing to drill into', () => {
+    expect(paletteScopeTrail(commands, 'devframes:docks:overview')).toEqual([])
+  })
+})
diff --git a/packages/hub-ui/src/client/state/palette.ts b/packages/hub-ui/src/client/state/palette.ts
new file mode 100644
index 00000000..b3a6fb17
--- /dev/null
+++ b/packages/hub-ui/src/client/state/palette.ts
@@ -0,0 +1,81 @@
+import type { DevframeCommandEntry } from '@devframes/hub'
+import { walkCommands } from './keybindings'
+
+/**
+ * One level of the palette's drill-down stack: the command the user stepped
+ * into, and the rows that level shows.
+ */
+export interface PaletteCrumb {
+  title: string
+  items: DevframeCommandEntry[]
+}
+
+/** A palette row, flattened out of the command tree for root search. */
+export interface PaletteFlatItem {
+  entry: DevframeCommandEntry
+  parentTitle?: string
+  searchTitle: string
+}
+
+/**
+ * Every command at every depth, so root search finds a nested entry — a dock
+ * group's members, and anything a devframe nests below them — without drilling.
+ *
+ * `searchTitle` carries the full path, so typing "docks ping" and typing "ping"
+ * both match, while the row itself shows only the immediate parent: a deep entry
+ * rendered as a full breadcrumb truncates away the part the user was looking
+ * for.
+ *
+ * `showInPalette: 'without-children'` prunes the command's whole subtree, not
+ * just its direct children: the flag means "reach my descendants by drilling
+ * down", and leaking grandchildren into root search would invert that.
+ * `showInPalette: false` prunes the command itself along with its subtree.
+ */
+export function flattenPaletteCommands(commands: DevframeCommandEntry[]): PaletteFlatItem[] {
+  const result: PaletteFlatItem[] = []
+
+  walkCommands(commands, (cmd, ancestors) => {
+    if (cmd.showInPalette === false)
+      return 'skip'
+    const parentTitle = ancestors.at(-1)?.title
+    result.push({
+      entry: cmd,
+      ...(parentTitle ? { parentTitle } : {}),
+      searchTitle: [...ancestors.map(a => a.title), cmd.title].join(' > '),
+    })
+    if (cmd.showInPalette === 'without-children')
+      return 'skip'
+  })
+
+  return result
+}
+
+/**
+ * The drill-down stack that lands on `scopeId`'s children — one crumb per
+ * ancestor that has children, plus the command itself, so `openPalette(id)`
+ * looks exactly like the user clicked their way down to that command.
+ *
+ * Returns `[]` when the id is unknown or leads nowhere, which opens the root
+ * list: a scope pointing at a command that has since been unregistered should
+ * degrade to a normal palette, not an empty one.
+ */
+export function paletteScopeTrail(
+  commands: DevframeCommandEntry[],
+  scopeId: string | null,
+): PaletteCrumb[] {
+  if (!scopeId)
+    return []
+
+  let crumbs: PaletteCrumb[] = []
+  walkCommands(commands, (cmd, ancestors) => {
+    if (cmd.id !== scopeId)
+      return
+    if (cmd.children?.length) {
+      crumbs = [...ancestors, cmd]
+        .filter(c => c.children?.length)
+        .map(c => ({ title: c.title, items: c.children as DevframeCommandEntry[] }))
+    }
+    return 'stop'
+  })
+  return crumbs
+}
diff --git a/packages/hub/src/types/commands.ts b/packages/hub/src/types/commands.ts
index ab4b4ee7..4cb3622b 100644
--- a/packages/hub/src/types/commands.ts
+++ b/packages/hub/src/types/commands.ts
@@ -93,7 +93,7 @@ export interface DevframeServerCommandInput extends DevframeCommandBase {
    */
   agent?: DevframeCommandAgentOptions
   /**
-   * Static sub-commands. Two levels max (parent → children).
+   * Static sub-commands, nested arbitrarily deep.
    * Each child must have a globally unique `id`.
    */
   children?: DevframeServerCommandInput[]
@@ -118,7 +118,7 @@ export interface DevframeClientCommand extends DevframeCommandBase {
    */
   action?: (...args: any[]) => void | DevframeClientCommand[] | Promise<void | DevframeClientCommand[]>
   /**
-   * Static sub-commands. Two levels max (parent → children).
+   * Static sub-commands, nested arbitrarily deep.
    */
   children?: DevframeClientCommand[]
 }

From cb369f0448f2820955d746e91c9e9e37f7132ba9 Mon Sep 17 00:00:00 2001
From: yu859 <15715093608@163.com>
Date: Sat, 22 Aug 2026 11:48:59 +0800
Subject: [PATCH 2/2] feat(hub-ui): open a scoped palette for groups without
 defaultChildId
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A group has no view of its own, so activating one by id — its shortcut, a
palette pick, an RPC activation — used to fall back to whichever member
happened to come first. That picked for the user, and a group whose members
are peers has no member worth picking.

Activating a group now opens an unambiguous target directly: the author's
`defaultChildId`, or a lone visible member. With several peer members it opens
the command palette drilled into that group, so the choice stays with the user
and the group is reachable by keyboard alone. Pressing the same shortcut again
closes the palette; stepping back to the root list unscopes it, so the
shortcut drills back in rather than toggling.

`CommandsContext` gains `openPalette(atCommandId?)` and `paletteScopeId`.
Members hang directly off their group in the command tree — the dock bar's
sub-category dividers have no counterpart there, since a category is not
something you can run. A group with no visible member and no reachable
`defaultChildId` registers no command at all.

`switchEntry` is unchanged, so boot restore and `hub:docks:activate` behave
as before.
---
 docs/content/1.guide/16.hub.md                |  30 ++++-
 docs/content/1.guide/17.client-context.md     |   2 +-
 .../command-palette/CommandPalette.stories.ts |  22 ++++
 .../ViewBuiltinSettings.stories.ts            |  18 ++-
 packages/hub-ui/src/client/state/commands.ts  |  33 ++---
 .../hub-ui/src/client/state/context.test.ts   | 124 ++++++++++++++++++
 packages/hub-ui/src/client/state/context.ts   |  67 +++++++---
 packages/hub/src/client/docks.ts              |  14 ++
 packages/hub/src/client/host.ts               |   5 +
 .../@devframes/hub/client.snapshot.d.ts       |   2 +
 10 files changed, 274 insertions(+), 43 deletions(-)

diff --git a/docs/content/1.guide/16.hub.md b/docs/content/1.guide/16.hub.md
index 76ac6892..46f2dee2 100644
--- a/docs/content/1.guide/16.hub.md
+++ b/docs/content/1.guide/16.hub.md
@@ -51,6 +51,22 @@ ctx.commands.register({
 
 `args` takes positional [Standard Schema](https://standardschema.dev/) schemas (a single `v.object(...)` unwraps into the input); omit for zero-arg. `safety` defaults to `'action'`; `when` clauses are unenforced for agent calls.
 
+## Nested commands
+
+A command's `children` nest arbitrarily deep. The palette drills into each level, and every command in the tree is bindable at any depth — a shortcut assigned to a leaf several levels down fires as directly as one on a top-level command, and each appears as its own row under **Settings → Shortcuts**, indented by nesting level.
+
+```ts
+ctx.commands.register({
+  id: 'app:cache',
+  title: 'Cache',
+  children: [
+    { id: 'app:cache:clear', title: 'Clear', keybindings: [{ key: 'Mod+Shift+K' }], handler: clearCache },
+  ],
+})
+```
+
+Set `showInPalette: 'without-children'` on a parent to keep its whole subtree out of root search while leaving it reachable by drilling down.
+
 ## Cross-iframe dock activation
 
 A mounted devframe's iframe uses `hub:docks:activate` to switch the active dock.
@@ -199,7 +215,7 @@ ctx.docks.register({
   title: 'Nuxt',
   icon: 'logos:nuxt-icon',
   category: 'framework',
-  defaultChildId: 'nuxt:overview', // optional; popover-only when omitted
+  defaultChildId: 'nuxt:overview', // optional; see "Activating a group" below
 })
 
 ctx.docks.register({
@@ -212,7 +228,17 @@ ctx.docks.register({
 })
 ```
 
-Group and members stay independent top-level entries in `devframe:docks`; `defaultChildId` opens on activation. Grouping affects the dock rail, not iframes — to share **one** soft-navigated iframe, give docks a shared `frameId` and mark the anchor with `subTabs` ([Shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation)).
+Group and members stay independent top-level entries in `devframe:docks`. Grouping affects the dock rail, not iframes — to share **one** soft-navigated iframe, give docks a shared `frameId` and mark the anchor with `subTabs` ([Shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation)).
+
+### Activating a group
+
+Activating a group resolves to one of its members.
+
+**Clicking** the dock-rail button opens `defaultChildId` when the group declares one, and reveals the member popover otherwise.
+
+**By id** — a keyboard shortcut on the group, a command-palette pick, or a `hub:docks:activate` call — opens the member the group points at: `defaultChildId`, or the only visible member when there is exactly one. A group with several members and no `defaultChildId` opens the command palette listing just those members, so the choice stays with the user and the group remains reachable by keyboard alone. Pressing the same shortcut again closes that palette.
+
+Declare `defaultChildId` when one member is the natural landing spot; leave it off when the members are peers.
 
 ### The dual role of `category`
 
diff --git a/docs/content/1.guide/17.client-context.md b/docs/content/1.guide/17.client-context.md
index 44f90b2c..99888171 100644
--- a/docs/content/1.guide/17.client-context.md
+++ b/docs/content/1.guide/17.client-context.md
@@ -40,7 +40,7 @@ A second boot replaces the context and warns; `dispose()` tears down listeners a
 | `clientType` | `'embedded'` (inside the user app) or `'standalone'` (independent hub page). |
 | `docks` | `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`, `register()` / `update()` for [client-only docks](#client-only-docks). |
 | `panel` | Dock panel state: position, size, drag/resize. |
-| `commands` | Command palette: `register()`, `execute()`, `getKeybindings()`. |
+| `commands` | Command palette: `register()`, `execute()`, `getKeybindings()`, `openPalette(atCommandId?)` — with an id, the palette opens drilled into that command's children and records it in `paletteScopeId` (how [activating a group](/guide/hub#activating-a-group) offers its members). |
 | `renderers` | Dock-renderer registry — `register()`, `get()`, `has()`, `mount(entry, container)`. Routes a dock `type` to a renderer (local boot or the hub's [manifest](/guide/hub-initiate#renderer-modules); local wins). `mount()` resolves a `status`: `mounted` (with `dispose`), `missing-renderer`, or `load-error` (with `error`). |
 | `when` | The [when-clause](/references/when-clauses) context. |
 | `connection` | Live [connection status](/guide/client#handling-connection-and-auth-errors) — `status`, `error`, `events`. |
diff --git a/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts b/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts
index b6709144..ccf9eb0a 100644
--- a/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts
+++ b/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts
@@ -45,3 +45,25 @@ export const Open: Story = {
     ),
   }),
 }
+
+/**
+ * The palette opened *scoped* to a dock group, listing only that group's
+ * members — what activating a group with no `defaultChildId` does, so a group
+ * stays reachable by keyboard with the choice of member left to the user.
+ * Backspace or Escape steps back out to the root list.
+ */
+export const ScopedToGroup: Story = {
+  render: () => ({
+    setup: () => mountWithContext(
+      { entries: groupedEntries },
+      ctx => h(defineComponent({
+        setup() {
+          onMounted(() => {
+            ctx.commands.openPalette('devframes:docks:playground')
+          })
+          return () => h(CommandPalette, { context: ctx })
+        },
+      })),
+    ),
+  }),
+}
diff --git a/packages/hub-ui/src/client/components/views-builtin/ViewBuiltinSettings.stories.ts b/packages/hub-ui/src/client/components/views-builtin/ViewBuiltinSettings.stories.ts
index 350575fb..b9316eb8 100644
--- a/packages/hub-ui/src/client/components/views-builtin/ViewBuiltinSettings.stories.ts
+++ b/packages/hub-ui/src/client/components/views-builtin/ViewBuiltinSettings.stories.ts
@@ -1,7 +1,7 @@
 import type { DevframeViewBuiltin } from '@devframes/hub'
 import type { Meta, StoryObj } from '@storybook/vue3-vite'
 import { h } from 'vue'
-import { groupedEntries } from '../../stories/fixtures'
+import { groupedEntries, subcategorizedGroupEntries } from '../../stories/fixtures'
 import { mountWithContext } from '../../stories/story-helpers'
 import ViewBuiltinSettings from './ViewBuiltinSettings.vue'
 
@@ -51,3 +51,19 @@ export const Standalone: Story = {
     ),
   }),
 }
+
+/**
+ * A group whose members split into in-group sub-categories — open the
+ * **Shortcuts** tab to see them listed directly under their group (`Docks` ›
+ * Tools › a member), each indented by nesting level and bindable like any other
+ * command. The rail's sub-category dividers stay in the rail; every row here is
+ * something you can actually run.
+ */
+export const DeeplyNestedShortcuts: Story = {
+  render: () => ({
+    setup: () => mountWithContext(
+      { entries: subcategorizedGroupEntries, clientType: 'embedded' },
+      ctx => stage(h(ViewBuiltinSettings, { context: ctx, entry })),
+    ),
+  }),
+}
diff --git a/packages/hub-ui/src/client/state/commands.ts b/packages/hub-ui/src/client/state/commands.ts
index ab6d9eba..f600ef05 100644
--- a/packages/hub-ui/src/client/state/commands.ts
+++ b/packages/hub-ui/src/client/state/commands.ts
@@ -6,7 +6,7 @@ import type { ShallowRef } from 'vue'
 import { evaluateWhen } from 'devframe/utils/when'
 import { computed, markRaw, reactive, ref, watch } from 'vue'
 import { sharedStateToRef } from './docks'
-import { collectAllKeybindings, filterCommandsByWhen, normalizeKeyEvent } from './keybindings'
+import { collectAllKeybindings, filterCommandsByWhen, findCommandDeep, normalizeKeyEvent } from './keybindings'
 import { useDockPopupWindow, useIsDockPopupOpen } from './popup'
 
 const commandsContextByRpc = new WeakMap<DevframeRpcClient, CommandsContext>()
@@ -33,6 +33,9 @@ export async function createCommandsContext(
   const shortcutOverrides = computed(() => settings.value.commandShortcuts ?? {})
 
   const paletteOpen = ref(false)
+  // See `CommandsContext.paletteScopeId` for the contract; the palette owns
+  // clearing it.
+  const paletteScopeId = ref<string | null>(null)
   const isDockPopupOpen = useIsDockPopupOpen()
 
   const getWhenContext = (): WhenContext => {
@@ -71,25 +74,13 @@ export async function createCommandsContext(
     }
   }
 
-  function findCommand(id: string): DevframeCommandEntry | undefined {
-    // Search top-level
-    const topLevel = commands.value.find(c => c.id === id)
-    if (topLevel)
-      return topLevel
-
-    // Search children
-    for (const cmd of commands.value) {
-      if (cmd.children) {
-        const child = cmd.children.find(c => c.id === id)
-        if (child)
-          return child as DevframeCommandEntry
-      }
-    }
-    return undefined
+  function openPalette(atCommandId?: string): void {
+    paletteScopeId.value = atCommandId ?? null
+    paletteOpen.value = true
   }
 
   async function execute(id: string, ...args: any[]): Promise<unknown> {
-    const cmd = findCommand(id)
+    const cmd = findCommandDeep(commands.value, id)
     if (!cmd) {
       throw new Error(`Command "${id}" not found`)
     }
@@ -119,7 +110,7 @@ export async function createCommandsContext(
     if (overrides !== undefined)
       return overrides
 
-    const cmd = findCommand(id)
+    const cmd = findCommandDeep(commands.value, id)
     return cmd?.keybindings ?? []
   }
 
@@ -136,6 +127,8 @@ export async function createCommandsContext(
     getKeybindings,
     settings: markRaw(settingsState),
     paletteOpen,
+    paletteScopeId,
+    openPalette,
   })
 
   commandsContextByRpc.set(rpc, commandsContext)
@@ -162,9 +155,7 @@ function setupShortcutListener(
       if (keybinding.key !== pressed)
         continue
       // Check command-level when clause
-      const cmd: DevframeCommandEntry | undefined
-        = commands.value.find(c => c.id === id)
-          ?? commands.value.flatMap(c => c.children as DevframeCommandEntry[] ?? []).find(c => c.id === id)
+      const cmd = findCommandDeep(commands.value, id)
       if (cmd?.when && !evaluateWhen(cmd.when, whenCtx))
         continue
 
diff --git a/packages/hub-ui/src/client/state/context.test.ts b/packages/hub-ui/src/client/state/context.test.ts
index 7df400d9..0a339ebf 100644
--- a/packages/hub-ui/src/client/state/context.test.ts
+++ b/packages/hub-ui/src/client/state/context.test.ts
@@ -152,3 +152,127 @@ describe('createDocksContext', () => {
     expect(session.value.open).toBe(false)
   })
 })
+
+const groupEntries = [
+  { id: 'tools', type: 'group', title: 'Tools', icon: 'ph:wrench-duotone' },
+  { id: 'tools:a', type: 'iframe', title: 'A', icon: 'ph:file-duotone', url: '/a', groupId: 'tools' },
+  { id: 'tools:b', type: 'iframe', title: 'B', icon: 'ph:file-duotone', url: '/b', groupId: 'tools', category: 'app' },
+  { id: 'solo', type: 'group', title: 'Solo', icon: 'ph:circle-duotone' },
+  { id: 'solo:only', type: 'iframe', title: 'Only', icon: 'ph:file-duotone', url: '/only', groupId: 'solo' },
+  { id: 'defaulted', type: 'group', title: 'Defaulted', icon: 'ph:star-duotone', defaultChildId: 'defaulted:second' },
+  { id: 'defaulted:first', type: 'iframe', title: 'First', icon: 'ph:file-duotone', url: '/first', groupId: 'defaulted' },
+  { id: 'defaulted:second', type: 'iframe', title: 'Second', icon: 'ph:file-duotone', url: '/second', groupId: 'defaulted' },
+  { id: 'empty', type: 'group', title: 'Empty', icon: 'ph:prohibit-duotone' },
+] satisfies DevframeDockEntry[]
+
+async function createGroupedContext() {
+  const { rpc, sharedStates, trust } = createStubRpc()
+  const context = await createDocksContext('embedded', rpc, undefined, ref<DockSessionStorage>({
+    open: false,
+    selectedDockId: null,
+    selectedDockRoute: null,
+  }))
+
+  trust()
+  sharedStates.get('devframe:docks')!.push(groupEntries)
+  sharedStates.get('devframe:dock-renderers')!.push({})
+  await flushRestore()
+
+  return context
+}
+
+/**
+ * Activating a group by id — what a keyboard shortcut and a palette pick both
+ * do — must never invent a member for the user.
+ */
+describe('dock group command activation', () => {
+  it('opens the palette scoped to the group when no member is an obvious target', async () => {
+    expect.assertions(3)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:tools')
+
+    expect(context.commands.paletteOpen).toBe(true)
+    expect(context.commands.paletteScopeId).toBe('devframes:docks:tools')
+    // No member was picked on the user's behalf.
+    expect(context.docks.selected).toBeNull()
+  })
+
+  it('closes that palette again on a second activation while it stays scoped', async () => {
+    expect.assertions(1)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:tools')
+    await context.commands.execute('devframes:docks:tools')
+
+    expect(context.commands.paletteOpen).toBe(false)
+  })
+
+  it('re-scopes instead of closing once the palette has stepped back to the root', async () => {
+    expect.assertions(2)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:tools')
+    // What the palette does when Escape or Backspace pops the last crumb: the
+    // list is still open, but no longer showing the group.
+    context.commands.paletteScopeId = null
+    await context.commands.execute('devframes:docks:tools')
+
+    expect(context.commands.paletteOpen).toBe(true)
+    expect(context.commands.paletteScopeId).toBe('devframes:docks:tools')
+  })
+
+  it('opens the sole visible member directly instead of a one-item palette', async () => {
+    expect.assertions(2)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:solo')
+
+    expect(context.docks.selected?.id).toBe('solo:only')
+    expect(context.commands.paletteOpen).toBe(false)
+  })
+
+  it('honors `defaultChildId` over both the palette and member order', async () => {
+    expect.assertions(2)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:defaulted')
+
+    expect(context.docks.selected?.id).toBe('defaulted:second')
+    expect(context.commands.paletteOpen).toBe(false)
+  })
+
+  it('registers no command for a group with nothing to activate', async () => {
+    expect.assertions(1)
+
+    const context = await createGroupedContext()
+
+    await expect(context.commands.execute('devframes:docks:empty')).rejects.toThrow(/not found/)
+  })
+
+  it('executes a group member command nested below its group', async () => {
+    expect.assertions(1)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:tools:b')
+
+    expect(context.docks.selected?.id).toBe('tools:b')
+  })
+
+  it('hangs members directly off their group even when sub-categories differ', async () => {
+    expect.assertions(1)
+
+    const context = await createGroupedContext()
+    const docks = context.commands.commands.find(c => c.id === 'devframes:docks')
+    const tools = docks?.children?.find(c => c.id === 'devframes:docks:tools')
+
+    // `tools:a` (default) and `tools:b` (app) land in different in-group
+    // sub-categories. The dock rail draws a divider between them; the command
+    // tree keeps them siblings, so reaching one is a single step rather than
+    // picking an inert category row first.
+    expect(tools?.children?.map(c => c.id)).toEqual([
+      'devframes:docks:tools:a',
+      'devframes:docks:tools:b',
+    ])
+  })
+})
diff --git a/packages/hub-ui/src/client/state/context.ts b/packages/hub-ui/src/client/state/context.ts
index e40743d7..0bbb3956 100644
--- a/packages/hub-ui/src/client/state/context.ts
+++ b/packages/hub-ui/src/client/state/context.ts
@@ -11,7 +11,7 @@ import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vu
 import { BUILTIN_ENTRIES, BUILTIN_ENTRY_SETTINGS, DEFAULT_CATEGORIES_ORDER, HUB_UI_HIDE_EVENT } from '../constants'
 import { useBranding } from './branding'
 import { createCommandsContext } from './commands'
-import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
+import { docksGroupByCategories, getGroupMembers, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
 import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE, sharedStateToRef, useDocksEntries, waitForInitialSharedStateSync } from './docks'
 import { createClientMessagesClient } from './messages-client'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDockPopupOpen } from './popup'
@@ -516,31 +516,62 @@ export async function createDocksContext(
       },
     })
 
+    // Activating a *group* by id — its shortcut, or picking it in the palette —
+    // must not guess a member on the user's behalf. An unambiguous target (the
+    // author's `defaultChildId`, or a lone visible member, which is a choice of
+    // one rather than a guess) opens directly, exactly like an ungrouped dock.
+    // Anything else hands the choice back to the user through the palette,
+    // scoped to that group's members, so a group stays reachable by keyboard
+    // alone without a default being invented for it. The dock-rail button is
+    // unaffected — clicking still opens the member popover.
+    const activateGroup = (
+      commandId: string,
+      directId: string | undefined,
+    ) => {
+      if (directId) {
+        toggleEntry(directId)
+        return
+      }
+      // Pressing the same shortcut again closes the palette it just opened.
+      if (commandsContext.paletteOpen && commandsContext.paletteScopeId === commandId) {
+        commandsContext.paletteOpen = false
+        return
+      }
+      commandsContext.openPalette(commandId)
+    }
+
     // Mirror the dock-bar collapse in the palette: members nest under their
     // group's command, and grouped members drop out of the top level.
     const registeredGroupIds = getRegisteredGroupIds(entries.value)
     const dockChildren: DevframeClientCommand[] = entries.value
       .filter(entry => entry.type !== '~builtin')
       .filter(entry => !(entry.groupId && registeredGroupIds.has(entry.groupId)))
-      .map((entry) => {
+      .flatMap((entry): DevframeClientCommand[] => {
         if (entry.type !== 'group')
-          return toCommand(entry)
-        // Members nest under the group, split by their in-group sub-category.
-        // A single sub-category (the common case) is flattened directly so the
-        // palette doesn't add a pointless one-item drill-down level.
-        const memberGroups = getGroupMembersGrouped(entries.value, entry.id, settings.value, { whenContext: getWhenContext() })
-        const children: DevframeClientCommand[] = memberGroups.length <= 1
-          ? (memberGroups[0]?.[1] ?? []).map(toCommand)
-          : memberGroups.map(([category, members]) => ({
-              id: `devframes:docks:${entry.id}:cat:${category}`,
-              source: 'client' as const,
-              title: getCategoryLabel(category),
-              children: members.map(toCommand),
-            }))
-        return {
+          return [toCommand(entry)]
+        // Members hang directly off their group, in the dock rail's sub-category
+        // order. The rail's sub-category *dividers* have no counterpart here: a
+        // category is not something you can run, so turning one into a command
+        // would put an inert row between the user and every member — an extra
+        // keystroke in the palette, and a row in the shortcut settings with
+        // nothing to bind. Ordering carries the grouping instead.
+        const visibleMembers = getGroupMembers(entries.value, entry.id, settings.value, { whenContext: getWhenContext() })
+        const defaultChildId = resolveGroupDefaultChild(entries.value, entry.id, entry.defaultChildId, getWhenContext())?.id
+        // Same empty-group rule the dock rail applies (`DockEntries.isDockVisible`):
+        // with no visible member and no reachable `defaultChildId` there is
+        // nothing to activate, so the group gets no command at all rather than a
+        // dead row in the palette and the shortcut settings.
+        if (visibleMembers.length === 0 && !defaultChildId)
+          return []
+        const commandId = `devframes:docks:${entry.id}`
+        return [{
           ...toCommand(entry),
-          children,
-        }
+          action: () => activateGroup(
+            commandId,
+            defaultChildId ?? (visibleMembers.length === 1 ? visibleMembers[0]!.id : undefined),
+          ),
+          children: visibleMembers.map(toCommand),
+        }]
       })
 
     if (dockChildren.length > 0) {
diff --git a/packages/hub/src/client/docks.ts b/packages/hub/src/client/docks.ts
index 019fae37..34dc6ee9 100644
--- a/packages/hub/src/client/docks.ts
+++ b/packages/hub/src/client/docks.ts
@@ -247,4 +247,18 @@ export interface CommandsContext {
    * Whether the command palette is open
    */
   paletteOpen: boolean
+  /**
+   * The command whose children the palette should open drilled into, or `null`
+   * for the root list. Set by {@link CommandsContext.openPalette}; the palette
+   * reads it when it opens and clears it when it closes.
+   */
+  paletteScopeId: string | null
+  /**
+   * Open the command palette, optionally scoped to one command's children —
+   * e.g. a dock group with no `defaultChildId` opens the palette listing just
+   * that group's members instead of guessing one for the user.
+   *
+   * Passing no id opens the root list, the same as setting `paletteOpen` true.
+   */
+  openPalette: (atCommandId?: string) => void
 }
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index 1bc8b685..79d9b874 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -467,6 +467,11 @@ export async function createDevframeClientRuntime(
       },
       settings,
       paletteOpen: false,
+      paletteScopeId: null,
+      openPalette(atCommandId?: string) {
+        ctx.paletteScopeId = atCommandId ?? null
+        ctx.paletteOpen = true
+      },
     }
     return ctx
   }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 42fca8c4..1e93e902 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -10,6 +10,8 @@ export interface CommandsContext {
   getKeybindings: (_: string) => DevframeCommandKeybinding[];
   settings: SharedState<DevframeDocksUserSettings>;
   paletteOpen: boolean;
+  paletteScopeId: string | null;
+  openPalette: (_?: string) => void;
 }
 export interface CreateDockRenderersContextOptions {
   context: () => DevframeClientContext;