From bf2a697f074955057998484d8e12a5a7f7ddd620 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 23 Jul 2026 08:59:01 +0000
Subject: [PATCH] feat(hub): allow per-group and hub-wide dock category order
 overrides

- DevframeViewGroup.categoryOrder overrides the default category order
  for its members' in-group sub-categories, scoped to that group only.
- DevframeClientHostOptions.categoryOrder overrides the top-level
  dock-bar category order hub-wide.

Both mirror DEFAULT_CATEGORIES_ORDER's shape and merge-over-defaults
semantics.
---
 packages/hub/src/client/host.ts               | 22 ++++++++++++++++++
 packages/hub/src/types/docks.ts               | 23 +++++++++++++++++++
 .../@devframes/hub/client.snapshot.d.ts       |  1 +
 3 files changed, 46 insertions(+)

diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index ec21f80..6086453 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -63,6 +63,28 @@ export interface DevframeClientHostOptions {
    * `@devframes/json-render-ui`). The hub ships none by default.
    */
   renderers?: Record<string, DockRenderer>
+  /**
+   * Hub-wide override of the top-level dock-bar category ordering — a map of
+   * category id → ordering weight (lower sorts earlier), mirroring the shape
+   * of {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
+   *
+   * This is the OUTER bucket ordering: it governs every ungrouped entry's own
+   * `category` and every group's `category` (see
+   * {@link import('../types/docks').DevframeDockEntryBase.category}). It is
+   * distinct from {@link import('../types/docks').DevframeViewGroup.categoryOrder},
+   * which only reorders the IN-GROUP sub-categories of one specific group.
+   *
+   * Keys are merged over `DEFAULT_CATEGORIES_ORDER`, so the host app only
+   * lists the categories it wants to move; any category absent from the map
+   * keeps its default weight (falling back to `0`).
+   *
+   * @example
+   * ```ts
+   * // Surface `data` tools ahead of `app` tools, hub-wide.
+   * createDevframeClientHost({ categoryOrder: { data: 50 } })
+   * ```
+   */
+  categoryOrder?: Record<string, number>
 }
 
 export interface DevframeClientHost {
diff --git a/packages/hub/src/types/docks.ts b/packages/hub/src/types/docks.ts
index 5b02a4f..ac20b9b 100644
--- a/packages/hub/src/types/docks.ts
+++ b/packages/hub/src/types/docks.ts
@@ -375,6 +375,29 @@ export interface DevframeViewGroup extends DevframeDockEntryBase {
    * opens until a member is chosen.
    */
   defaultChildId?: string
+  /**
+   * Per-group override of the in-group sub-category ordering — a map of
+   * sub-category id → ordering weight (lower sorts earlier), mirroring the
+   * shape of {@link import('../constants').DEFAULT_CATEGORIES_ORDER}.
+   *
+   * A member's own {@link DevframeDockEntryBase.category} is reinterpreted as
+   * its IN-GROUP sub-category, and members are sub-divided and sorted by those
+   * sub-categories. By default that sort follows the hub-wide
+   * `DEFAULT_CATEGORIES_ORDER`; set this to reorder the sub-categories **inside
+   * this group only**, leaving the outer dock-bar ordering (and every other
+   * group) untouched.
+   *
+   * Keys are merged over the defaults, so you only list the sub-categories you
+   * want to move; any sub-category absent from the map keeps its default weight
+   * (falling back to `0`).
+   *
+   * @example
+   * ```ts
+   * // In the "nuxt" group, surface `app` tools before `framework` internals.
+   * { type: 'group', id: 'nuxt', categoryOrder: { app: -200 } }
+   * ```
+   */
+  categoryOrder?: Record<string, number>
 }
 
 /**
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 519f3a9..416b488 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -21,6 +21,7 @@ export interface DevframeClientHostOptions {
   clientType?: DockClientType;
   loadClientScripts?: boolean;
   renderers?: Record<string, DockRenderer>;
+  categoryOrder?: Record<string, number>;
 }
 export interface DockClientScriptContext extends DocksContext {
   current: DockEntryState;