feat(hub): reinterpret grouped dock entry category as in-group sub-category

Adopt the refined dock-grouping semantics downstream viewers are moving to:
when a dock entry's groupId resolves to a registered group, the group's own
category is the entry's outer dock-bar bucket, and the entry's own category is
reinterpreted as an in-group sub-category. Orphan entries (groupId with no
registered group) keep using their own category as the outer bucket.

- Document the dual role of category/groupId and the group's category on the
  types (DevframeDockEntryBase, DevframeViewGroup) plus the hub grouping docs.
- Make the client host's groupByCategory bucket grouped members under their
  group's category (default fallback), orphans under their own, so hub's own
  groupedEntries agrees with the refined semantics for standalone viewers.
- Reconcile DEFAULT_CATEGORIES_ORDER to put framework first (matching what
  Vite DevTools ships) and export it from the main, node and client public
  entry points so downstream kits can import the single source of truth.

Created with the help of an agent.

Author: antfubot

docs/guide/client-context.md

@@ -50,7 +50,7 @@ Boot the host once per page: a second boot replaces the published context and lo
 |----------|-------------|
 | `rpc` | The [RPC client](./client) — call server functions, register client-side functions, access shared state. |
 | `clientType` | `'embedded'` (runtime inside your app) or `'standalone'` (independent hub page). |
-| `docks` | Dock entries and selection — `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`. |
+| `docks` | Dock entries and selection — `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`. `groupedEntries` buckets entries by outer category (a grouped member takes its group's category; see [Grouping dock entries](./hub#grouping-dock-entries)). |
 | `panel` | Dock panel state: position, size, drag/resize flags. |
 | `commands` | The command palette: `register()`, `execute()`, `getKeybindings()`. |
 | `renderers` | Dock-renderer registry — `register()`, `get()`, `has()`, `mount(entry, container)`. Routes a dock `type` to a host-registered renderer (e.g. [JSON-Render](./json-render)); the hub ships none. |

docs/guide/hub.md

@@ -199,6 +199,21 @@ ctx.docks.register({
 
 `groupId` lives on every entry kind, so iframes, launchers, custom-render views, and integration-contributed types (e.g. json-render panels) all join groups the same way. The group and its members stay independent top-level entries in `devframe:docks`; a downstream UI derives the visual collapse by matching each member's `groupId` to the group's `id` and renders members in a popover or sub-navigation. `defaultChildId` names the member opened when the group button is activated.
 
+### The dual role of `category`
+
+`category` decides an entry's outer bucket on the dock bar (ordered by `DEFAULT_CATEGORIES_ORDER`) — but its meaning shifts once an entry joins a group:
+
+- **Ungrouped entry** — `category` is the entry's outer dock-bar bucket, defaulting to `'default'`.
+- **Grouped entry** (a `groupId` that resolves to a registered group) — the outer bucket comes from the **group's** own `category` instead. The member's own `category` is reinterpreted as an **in-group sub-category** that sub-divides and sorts members inside the group's popover / sub-navigation.
+
+The group's `category` is therefore the single outer bucket shared by the group button and all its members. Fallbacks keep the rule total:
+
+- A **group** with no `category` buckets itself and its members under `'default'`.
+- A grouped **member** with no `category` defaults its in-group sub-category to `'default'`.
+- **Orphan tolerance** — a member whose `groupId` never resolves to a registered group renders as a normal top-level entry and uses its **own** `category` as the outer bucket, exactly as an ungrouped entry does.
+
+In the example above, `nuxt:overview` renders under the `framework` bucket (from the `nuxt` group) even though it could carry its own `category`; that own `category` would only sort it against sibling members inside the Nuxt group.
+
 Grouping is one level deep: members join a group, and a group is always a top-level button. A member whose group is never registered renders as a normal top-level entry, so registration order is free.
 
 ## The protocol — what the UI sees

packages/hub/src/client/__tests__/host.test.ts

@@ -62,6 +62,10 @@ function iframeEntry(id: string, extra?: Record<string, unknown>): DevframeDockE
   return { id, title: id, icon: 'ph:cube', type: 'iframe', url: `/__${id}/`, ...extra } as DevframeDockEntry
 }
 
+function groupEntry(id: string, extra?: Record<string, unknown>): DevframeDockEntry {
+  return { id, title: id, icon: 'ph:folder', type: 'group', ...extra } as DevframeDockEntry
+}
+
 describe('createDevframeClientHost', () => {
   it('publishes the global client context with the full surface', async () => {
     const { rpc } = createStubRpc()
@@ -95,6 +99,46 @@ describe('createDevframeClientHost', () => {
     host.dispose()
   })
 
+  it('groups entries by category — grouped members bucket under their group, orphans by their own', async () => {
+    const { rpc, states } = createStubRpc()
+    const host = await createDevframeClientHost({ rpc })
+
+    states.get('devframe:docks')!.push([
+      // (a) member with groupId + its own category → outer bucket = group's category ('framework'),
+      // and its own 'app' category is reinterpreted as an in-group sub-category.
+      groupEntry('nuxt', { category: 'framework' }),
+      iframeEntry('nuxt:overview', { groupId: 'nuxt', category: 'app' }),
+      // (b) group with no category → members bucket to 'default'.
+      groupEntry('misc'),
+      iframeEntry('misc:one', { groupId: 'misc', category: 'web' }),
+      // (c) orphan member (groupId with no registered group) → its own category ('web').
+      iframeEntry('orphan', { groupId: 'ghost', category: 'web' }),
+      // plain ungrouped entry keeps its own category.
+      iframeEntry('plain', { category: 'app' }),
+    ])
+
+    const grouped = Object.fromEntries(
+      host.context.docks.groupedEntries.map(([cat, entries]) => [cat, entries.map(e => e.id)]),
+    )
+
+    // (a) grouped member lands under the group's category, alongside the group button.
+    expect(grouped.framework).toEqual(['nuxt', 'nuxt:overview'])
+    // (b) group without a category, and its member, bucket to 'default'.
+    expect(grouped.default).toEqual(['misc', 'misc:one'])
+    // (c) orphan + plain keep their own categories.
+    expect(grouped.web).toEqual(['orphan'])
+    expect(grouped.app).toEqual(['plain'])
+
+    // Categories sort by DEFAULT_CATEGORIES_ORDER — framework first.
+    expect(host.context.docks.groupedEntries.map(([cat]) => cat)).toEqual([
+      'framework',
+      'default',
+      'app',
+      'web',
+    ])
+    host.dispose()
+  })
+
   it('switches entries with activation/deactivation events and when-context updates', async () => {
     const { rpc, states } = createStubRpc()
     const host = await createDevframeClientHost({ rpc })

packages/hub/src/client/host.ts

@@ -419,9 +419,22 @@ function createPanelContext(clientType: DockClientType): DocksPanelContext {
 }
 
 function groupByCategory(entries: DevframeDockEntry[]): DevframeDockEntriesGrouped {
+  // Index registered groups so a member whose `groupId` resolves takes its
+  // OUTER bucket from the group's category, not its own (which becomes the
+  // member's in-group sub-category). Orphan members — a `groupId` with no
+  // registered group — fall back to their own category.
+  const groupsById = new Map<string, DevframeDockEntry>()
+  for (const entry of entries) {
+    if (entry.type === 'group')
+      groupsById.set(entry.id, entry)
+  }
+
   const groups = new Map<string, DevframeDockEntry[]>()
   for (const entry of entries) {
-    const category = entry.category ?? 'default'
+    const resolvedGroup = entry.groupId ? groupsById.get(entry.groupId) : undefined
+    const category = resolvedGroup
+      ? resolvedGroup.category ?? 'default'
+      : entry.category ?? 'default'
     let list = groups.get(category)
     if (!list) {
       list = []

packages/hub/src/client/index.ts

@@ -1,3 +1,6 @@
+// Re-export the category-order table so client-side viewers can import the
+// single source of truth from `@devframes/hub/client`.
+export { DEFAULT_CATEGORIES_ORDER } from '../constants'
 export * from './client-script'
 export * from './context'
 export * from './docks'

packages/hub/src/constants.ts

@@ -2,10 +2,16 @@ import type { DevframeDocksUserSettings } from './types/settings'
 
 export * from 'devframe/constants'
 
+/**
+ * The default ordering weight for each known dock category — lower sorts
+ * earlier. Downstream viewers (e.g. `@vitejs/devtools-kit`) import this as the
+ * single source of truth so the hub and its viewers agree on category order.
+ * `framework` sorts first; `~builtin` (the viewer's own built-in views) last.
+ */
 export const DEFAULT_CATEGORIES_ORDER: Record<string, number> = {
+  'framework': -100,
   'default': 0,
   'app': 100,
-  'framework': 200,
   'web': 300,
   'advanced': 400,
   '~builtin': 1000,

packages/hub/src/index.ts

@@ -1,2 +1,3 @@
+export { DEFAULT_CATEGORIES_ORDER } from './constants'
 export * from './define'
 export type * from './types'

packages/hub/src/node/index.ts

@@ -1,3 +1,6 @@
+// Re-export the category-order table so node-side consumers can import the
+// single source of truth from `@devframes/hub/node`.
+export { DEFAULT_CATEGORIES_ORDER } from '../constants'
 export * from './context'
 export * from './host-commands'
 export * from './host-docks'

packages/hub/src/types/docks.ts

@@ -76,7 +76,19 @@ export interface DevframeDockEntryBase {
    */
   defaultOrder?: number
   /**
-   * The category of the entry
+   * The category of the entry — a field with a dual role that depends on
+   * whether {@link groupId} resolves to a registered {@link DevframeViewGroup}:
+   *
+   * - **Ungrouped (or orphan) entry** — `category` is the entry's OUTER bucket
+   *   on the dock bar, ordered by {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
+   * - **Grouped entry** (a `groupId` that resolves to a registered group) —
+   *   the OUTER bucket is instead the group's own `category`, and this field is
+   *   reinterpreted as the entry's IN-GROUP sub-category, used to sub-divide and
+   *   sort members inside the group's popover / sub-navigation.
+   *
+   * Falls back to `'default'` when omitted — both as an outer bucket and, for a
+   * grouped member, as its in-group sub-bucket.
+   *
    * @default 'default'
    */
   category?: DevframeDockEntryCategory
@@ -102,8 +114,14 @@ export interface DevframeDockEntryBase {
    *
    * This is a flat pointer — membership, not containment. The entry stays an
    * independently-registered, top-level entry; only its rendering is grouped
-   * downstream. If the referenced group is never registered, the entry renders
-   * as a normal top-level entry (orphan tolerance).
+   * downstream.
+   *
+   * When the referenced group **is** registered, it supplies the entry's OUTER
+   * dock-bar category (the group's own {@link category}), and this entry's own
+   * {@link category} is reinterpreted as its IN-GROUP sub-category. When the
+   * referenced group is **never** registered, the entry renders as a normal
+   * top-level entry and falls back to using its own {@link category} as the
+   * outer bucket (orphan tolerance).
    *
    * @see {@link DevframeViewGroup}
    */
@@ -277,6 +295,12 @@ export interface DevframeViewJsonRender extends DevframeDockEntryBase {
  * through the same `register`/`update`/`values` machinery as every other entry,
  * keyed by `id`.
  *
+ * The group's `category` is the OUTER bucket for the group button itself AND
+ * for every one of its members — a member's own `category` no longer decides
+ * its outer bucket, but is reinterpreted as an in-group sub-category that
+ * sub-divides and sorts members inside this group. A group with no `category`
+ * buckets itself and its members under `'default'`.
+ *
  * Grouping is one level deep: a group entry must not itself set `groupId`.
  */
 export interface DevframeViewGroup extends DevframeDockEntryBase {

tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts

@@ -130,6 +130,7 @@ export * from "devframe/client";
 // #endregion
 
 // #region Other
+export { DEFAULT_CATEGORIES_ORDER }
 export { DevframeClientRpcHost }
 export { RpcClientEvents }
 // #endregion