feat(hub-ui): open a scoped palette for groups without defaultChildId

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.

Author: SaKaNa-Y

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`
 

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`. |

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

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

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
 

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',
+    ])
+  })
+})