fix(core): keep a group's defaultChildId reachable regardless of visibility, respecting when (#472)

* fix(core): keep a group's defaultChildId reachable when its target is visibility-hidden

DockGroupButton resolved defaultChildId against the visibility-filtered member
list, so a target with visibility: 'false' was never found and the click fell
through to the (empty) popover instead of jumping to it directly. Resolve
against the unfiltered member list instead, matching switchEntry's own
group-to-member resolution and the documented render-only visibility
contract. DockEntries' empty-group check is updated the same way so the group
button doesn't disappear when its only member is a hidden default child.

* fix(core): honor when, ignore visibility, when resolving a group's defaultChildId

resolveGroupDefaultChild (new, in dock-settings.ts) centralizes the
group->member resolution used by DockGroupButton's click handler,
DockEntries' empty-group check, and switchEntry's own group activation:

- Ignores the target's render-only `visibility` clause entirely, since
  visibility never affects reachability (docs/kit/when-clauses.md).
- Still checks the target's `when` clause, so a conditionally-unavailable
  member (e.g. when: 'clientType == embedded' evaluating false) is never
  treated as a valid defaultChildId target.

DockGroupButton.vue and DockEntries.vue now call the shared helper instead
of re-deriving membership themselves. switchEntry's group resolution
(state/context.ts) needed settings/getWhenContext hoisted above its
declaration to evaluate `when`; those are now established immediately
before switchEntry instead of much later in the file.

Replaces the getGroupMembers-based defaultChildId resolution landed in the
previous commit, which ignored when clauses along with visibility.

Author: antfubot

packages/core/src/client/webcomponents/components/dock/DockEntries.vue

@@ -3,7 +3,7 @@ import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
 import type { DocksContext } from '@vitejs/devtools-kit/client'
 import { evaluateWhen } from 'devframe/utils/when'
 import { toRefs } from 'vue'
-import { getGroupMembers } from '../../state/dock-settings'
+import { getGroupMembers, resolveGroupDefaultChild } from '../../state/dock-settings'
 import { sharedStateToRef } from '../../state/docks'
 import DockEntry from './DockEntry.vue'
 import DockGroupButton from './DockGroupButton.vue'
@@ -25,9 +25,15 @@ const settings = sharedStateToRef(props.context.docks.settings)
 
 function isDockVisible(dock: DevToolsDockEntry): boolean {
   // Hide empty groups — a group button with no members has nothing to reveal.
+  // A `defaultChildId` still counts as "something to reveal" even when its
+  // target is render-only hidden via `visibility`: clicking the group button
+  // jumps straight to that member instead of opening the (visibly empty)
+  // popover, so the button must stay reachable. Only treat the group as empty
+  // when no member is visible AND no reachable `defaultChildId` target exists
+  // (a target hidden by its own `when` clause doesn't count as reachable).
   if (dock.type === 'group') {
     const members = getGroupMembers(props.context.docks.entries, dock.id, settings.value, { whenContext: props.context.when.context })
-    if (members.length === 0)
+    if (members.length === 0 && !resolveGroupDefaultChild(props.context.docks.entries, dock.id, dock.defaultChildId, props.context.when.context))
       return false
   }
   if (dock.when && !evaluateWhen(dock.when, props.context.when.context))

packages/core/src/client/webcomponents/components/dock/DockGroupButton.vue

@@ -3,7 +3,7 @@ import type { DevToolsDockEntry, DevToolsViewGroup } from '@vitejs/devtools-kit'
 import type { DocksContext } from '@vitejs/devtools-kit/client'
 import { watchDebounced } from '@vueuse/core'
 import { computed, h, ref, useTemplateRef } from 'vue'
-import { getGroupMembers, getGroupMembersGrouped } from '../../state/dock-settings'
+import { getGroupMembers, getGroupMembersGrouped, resolveGroupDefaultChild } from '../../state/dock-settings'
 import { sharedStateToRef } from '../../state/docks'
 import { setDocksGroupPanel, useDocksGroupPanel } from '../../state/floating-tooltip'
 import DockEntry from './DockEntry.vue'
@@ -98,8 +98,14 @@ function onClick() {
     return
   }
   // `defaultChildId` opens its member directly; otherwise reveal the popover.
-  const fallback = props.group.defaultChildId
-    && members.value.find(m => m.id === props.group.defaultChildId)
+  // Resolved regardless of the target's render-only `visibility` (a hidden
+  // button must still fire), but honoring its `when` clause.
+  const fallback = resolveGroupDefaultChild(
+    props.context.docks.entries,
+    props.group.id,
+    props.group.defaultChildId,
+    props.context.when.context,
+  )
   if (fallback) {
     hidePanel()
     emit('select', fallback)

packages/core/src/client/webcomponents/state/__tests__/dock-groups.test.ts

@@ -12,6 +12,7 @@ import {
   PINNED_CATEGORY,
   PINNED_CATEGORY_ORDER,
   resolveCommandIcon,
+  resolveGroupDefaultChild,
 } from '../dock-settings'
 
 function iframe(id: string, extra: Partial<DevToolsDockEntry> = {}): DevToolsDockEntry {
@@ -139,6 +140,69 @@ describe('render-only `visibility` (subTabs anchor use case)', () => {
   })
 })
 
+describe('resolveGroupDefaultChild (group→member resolution ignores `visibility`, respects `when`)', () => {
+  it('resolves a plain, fully-visible default child', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'g:a' } as any),
+      iframe('g:a', { groupId: 'g' }),
+      iframe('g:b', { groupId: 'g' }),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:a')?.id).toBe('g:a')
+  })
+
+  it('resolves the target even when it is render-only hidden via `visibility`', () => {
+    // The core bug fixed here: a defaultChildId target with `visibility: 'false'`
+    // must still fire — visibility only hides the target's own dock-bar button.
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'g:hidden' } as any),
+      iframe('g:hidden', { groupId: 'g', visibility: 'false' } as any),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:hidden')?.id).toBe('g:hidden')
+  })
+
+  it('does NOT resolve the target when its own `when` clause evaluates false', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'g:embedded-only' } as any),
+      iframe('g:embedded-only', { groupId: 'g', when: 'clientType == embedded' } as any),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:embedded-only', { clientType: 'standalone' } as any)).toBeUndefined()
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:embedded-only', { clientType: 'embedded' } as any)?.id).toBe('g:embedded-only')
+  })
+
+  it('does NOT resolve an unconditionally `when: false` target with no whenContext', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'g:off' } as any),
+      iframe('g:off', { groupId: 'g', when: 'false' } as any),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:off')).toBeUndefined()
+  })
+
+  it('resolves the target even when `when`-hidden AND `visibility`-hidden together, as long as `when` passes', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'g:both' } as any),
+      iframe('g:both', { groupId: 'g', when: 'clientType == embedded', visibility: 'false' } as any),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'g:both', { clientType: 'embedded' } as any)?.id).toBe('g:both')
+  })
+
+  it('returns undefined when there is no defaultChildId', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g'),
+      iframe('g:a', { groupId: 'g' }),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', undefined)).toBeUndefined()
+  })
+
+  it('returns undefined when defaultChildId does not reference a member of this group', () => {
+    const entries: DevToolsDockEntry[] = [
+      group('g', { defaultChildId: 'other:x' } as any),
+      iframe('g:a', { groupId: 'g' }),
+      iframe('other:x', { groupId: 'other-group' }),
+    ]
+    expect(resolveGroupDefaultChild(entries, 'g', 'other:x')).toBeUndefined()
+  })
+})
+
 describe('in-group sub-categories (dual role of `category`)', () => {
   // The group carries category 'framework' (the OUTER bucket for the whole
   // group); its members carry their own categories, which act as IN-GROUP

packages/core/src/client/webcomponents/state/context.ts

@@ -10,7 +10,7 @@ import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vu
 import { DEVTOOLS_HIDE_EVENT, DEVTOOLS_MODE_FILENAME } from '../../../constants'
 import { BUILTIN_ENTRIES } from '../constants'
 import { createCommandsContext } from './commands'
-import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon } from './dock-settings'
+import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
 import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, sharedStateToRef, useDocksEntries } from './docks'
 import { createClientMessagesClient } from './messages-client'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction } from './popup'
@@ -113,6 +113,31 @@ export async function createDocksContext(
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
   let docksContext: DocksContext
 
+  let _settingsStorePromise: Promise<SharedState<DevToolsDocksUserSettings>> | undefined
+  const getSettingsStore = async () => {
+    if (!_settingsStorePromise) {
+      _settingsStorePromise = rpc.sharedState.get(
+        'devframe:user-settings',
+        { initialValue: DEFAULT_STATE_USER_SETTINGS() },
+      )
+    }
+    return _settingsStorePromise
+  }
+
+  // Get settings store ahead of `switchEntry` — its group→member resolution
+  // needs `getWhenContext` to honor a `defaultChildId` target's `when` clause.
+  const settingsStore = markRaw(await getSettingsStore())
+  const settings = sharedStateToRef(settingsStore)
+
+  // Shared when-context provider — used by both commands and docks
+  let commandsContext: CommandsContext
+  const getWhenContext = (): WhenContext => ({
+    clientType,
+    dockOpen: panelStore.value.open,
+    paletteOpen: commandsContext?.paletteOpen ?? false,
+    dockSelectedId: selectedId.value ?? '',
+  })
+
   const switchEntry = async (id: string | null = null) => {
     if (id == null) {
       selectedId.value = null
@@ -129,14 +154,14 @@ export async function createDocksContext(
       return false
 
     // A group has no view of its own — resolve to the member it represents.
-    // Prefer the author's `defaultChildId`, otherwise the first visible member.
-    // With neither, the group is popover-only and selecting it is a no-op here
-    // (the dock-bar group button opens the member popover instead).
+    // Prefer the author's `defaultChildId` (honoring its `when` clause but
+    // ignoring its render-only `visibility` — see `resolveGroupDefaultChild`),
+    // otherwise the first member. With neither, the group is popover-only and
+    // selecting it is a no-op here (the dock-bar group button opens the
+    // member popover instead).
     if (entry.type === 'group') {
-      const members = getGroupMembers(entries.value, entry.id)
-      const target = (entry.defaultChildId && members.some(m => m.id === entry.defaultChildId))
-        ? entry.defaultChildId
-        : members[0]?.id
+      const target = resolveGroupDefaultChild(entries.value, entry.id, entry.defaultChildId, getWhenContext())?.id
+        ?? getGroupMembers(entries.value, entry.id)[0]?.id
       if (!target)
         return false
       return switchEntry(target)
@@ -258,30 +283,8 @@ export async function createDocksContext(
     },
   })
 
-  let _settingsStorePromise: Promise<SharedState<DevToolsDocksUserSettings>> | undefined
-  const getSettingsStore = async () => {
-    if (!_settingsStorePromise) {
-      _settingsStorePromise = rpc.sharedState.get(
-        'devframe:user-settings',
-        { initialValue: DEFAULT_STATE_USER_SETTINGS() },
-      )
-    }
-    return _settingsStorePromise
-  }
-
-  // Get settings store and create computed grouped entries
-  const settingsStore = markRaw(await getSettingsStore())
-  const settings = sharedStateToRef(settingsStore)
-
-  // Shared when-context provider — used by both commands and docks
-  let commandsContext: CommandsContext
-  const getWhenContext = (): WhenContext => ({
-    clientType,
-    dockOpen: panelStore.value.open,
-    paletteOpen: commandsContext?.paletteOpen ?? false,
-    dockSelectedId: selectedId.value ?? '',
-  })
-
+  // Settings store, `settings`, and `getWhenContext` are established earlier
+  // (right before `switchEntry`) — its group→member resolution needs them.
   const groupedEntries = computed(() => {
     return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true })
   })

packages/core/src/client/webcomponents/state/dock-settings.ts

@@ -171,6 +171,44 @@ export function getGroupMembers(
   return getGroupMembersGrouped(entries, groupId, settings, options).flatMap(([, items]) => items)
 }
 
+/**
+ * Resolve a group's `defaultChildId` to its target member, for the "clicking
+ * the group button jumps straight to this member" behavior (the dock-bar
+ * button and `switchEntry`'s own group→member resolution both need this).
+ *
+ * Respects the member's own `when` clause — a conditionally-unavailable
+ * target (e.g. `when: 'clientType == embedded'` evaluating false) is not a
+ * valid default and this returns `undefined` so the caller falls back to its
+ * own behavior (open the popover, or pick another member). Deliberately
+ * ignores the render-only `visibility` clause: `visibility` never affects
+ * reachability (see {@link docksGroupByCategories}'s `visibility` check), and
+ * jumping straight to a `defaultChildId` target is exactly the kind of
+ * id-based activation the render-only contract says stays unaffected — only
+ * the target's own dock-bar button (if it has one) should disappear.
+ */
+export function resolveGroupDefaultChild(
+  entries: DevToolsDockEntry[],
+  groupId: string,
+  defaultChildId: string | undefined,
+  whenContext?: WhenContext,
+): DevToolsDockEntry | undefined {
+  if (!defaultChildId)
+    return undefined
+  const member = entries.find(e => e.type !== 'group' && e.groupId === groupId && e.id === defaultChildId)
+  if (!member)
+    return undefined
+  if (member.when) {
+    if (whenContext) {
+      if (!evaluateWhen(member.when, whenContext))
+        return undefined
+    }
+    else if (member.when === 'false') {
+      return undefined
+    }
+  }
+  return member
+}
+
 /**
  * Group and sort dock entries based on user settings.
  * Filters out hidden entries and categories, then sorts by custom order and