refactor(hub,hub-ui): dockPreferences as a createUi() option; DevframeHubUi.setup(ctx)

Dock-bar preferences (categoryOrder / maxVisibleItems / defaultMode /
defaultPosition) are reference-UI rendering concerns, not per-devframe
declarations — move them off `DevframeDefinition.dockPreferences` (removed
from core, along with the `DevframeDockPreferences` type and the hub's
`configs.dock` aggregation) into `createUi({ dockPreferences })`, published
under `ConnectionMeta.configs.ui.dockPreferences` alongside `branding` and
`embeddedVisibility`.

Also replace the `DevframeHubUi.configs` producer with a `setup(ctx)` hook:
the UI slot now publishes its config through the generic `ctx.staticConfig`
(`createUi()`'s setup writes `ctx.staticConfig.ui = { branding, ... }`), so
the hub's mount handler no longer special-cases a `ui` merge.

Built with the help of an agent.

Author: antfubot

docs/guide/build-your-own-hub-ui.md

@@ -16,7 +16,7 @@ interface DevframeHubUi {
   viewer?: { distDir: string } // a standalone SPA served at the hub base
   embedded?: { entry: string } // a self-contained bootstrap at <base>embedded.js
   assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
-  configs?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
+  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
 }
 ```
 
@@ -25,14 +25,13 @@ prebuilt assets: the viewer SPA is built with relative asset paths, and the
 embedded entry is one self-contained ES module that mounts your dock into any
 host page.
 
-`configs` publishes whatever you return verbatim as
-`ConnectionMeta.configs.ui` — the reference UI's `createUi({ branding })` uses
-it to deliver `{ branding }`, read by the dock from the one connection
-handshake it already performs, rather than a separate fetched file. The hub
-never interprets this object; it's a policy-free pass-through to your own
-client code. It's the read-only counterpart to `assets`: reach for `configs`
-for small, structured, boot-time config, and `assets` for arbitrary served
-files.
+`setup(ctx)` runs once during hub init — write your static, boot-time config
+to `ctx.staticConfig`, which is serialized into `ConnectionMeta.configs` and
+read by the client from the one connection handshake it already performs. The
+reference UI's `createUi({ branding })` uses it to set
+`ctx.staticConfig.ui = { branding, … }`; the hub never interprets what you
+write. It's the structured, read-only counterpart to `assets` (arbitrary
+served files).
 
 ## The client contracts
 

docs/guide/hub-initiate.md

@@ -57,23 +57,26 @@ interface DevframeHubUi {
   viewer?: { distDir: string } // a standalone SPA served at the namespace root
   embedded?: { entry: string } // a prebuilt bootstrap served at <base>embedded.js
   assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
-  configs?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
+  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
 }
 ```
 
-`@devframes/hub-ui`'s `createUi()` is the reference implementation: a standalone viewer plus the floating dock — one `<script type="module" src="/__devframes/embedded.js">` tag in the host page and the dock mounts itself. A viewer product supplies a different object to the same slot and reuses all the infrastructure.
+`@devframes/hub-ui`'s `createUi()` is the reference implementation: a standalone viewer plus the floating dock — one `<script type="module" src="/__devframes/embedded.js">` tag in the host page and the dock mounts itself. A viewer product supplies a different object to the same slot and reuses all the infrastructure. Its `setup(ctx)` publishes the reference UI's config to `ctx.staticConfig.ui`, which rides `ConnectionMeta.configs.ui` to the client.
 
-`createUi()` takes a few options: `branding` (rebrand the reference UI — logo, product name, primary color) and `embeddedVisibility` for the floating dock's reveal policy:
+`createUi()` takes a few options:
+
+- **`branding`** — rebrand the reference UI (logo, product name, primary color).
+- **`dockPreferences`** — dock-bar rendering: `categoryOrder`, floating-dock `maxVisibleItems`, and the first-run `defaultMode` (`'float'` / `'edge'`) and `defaultPosition`.
+- **`embeddedVisibility`** — the floating dock's reveal policy:
+  - `'normal'` (default) — the dock is shown immediately.
+  - `'passive'` — the dock starts hidden with a console hint; `Shift+Alt+D` reveals it, and the reveal persists per-origin so later sessions start shown.
+  - `'hidden'` — the dock starts hidden; `Shift+Alt+D` reveals it for the current session only.
 
 ```ts
-createUi({ embeddedVisibility: 'passive' })
+createUi({ embeddedVisibility: 'passive', dockPreferences: { defaultMode: 'edge' } })
 ```
 
-- `'normal'` (default) — the dock is shown immediately.
-- `'passive'` — the dock starts hidden with a console hint; `Shift+Alt+D` reveals it, and the reveal persists per-origin so later sessions start shown.
-- `'hidden'` — the dock starts hidden; `Shift+Alt+D` reveals it for the current session only.
-
-Both ride `ConnectionMeta.configs.ui` to the client. Like the float/edge dock mode, `embeddedVisibility` seeds a user-overridable preference — the visitor's own reveal/hide wins from then on.
+Each seeds a user-overridable preference — the config sets the default, the visitor's own choice (reveal/hide, float/edge, …) wins from then on.
 
 ## Renderer modules
 

packages/devframe/src/types/devframe.ts

@@ -264,41 +264,6 @@ export interface DevframeDockDefaults {
   groupId?: string
 }
 
-/**
- * A devframe's opinion about the **hub-wide** dock bar — not attributes of
- * its own synthesized entry, but preferences the hub aggregates across every
- * installed devframe and publishes once via `ConnectionMeta.configs.dock`.
- * Declared on {@link DevframeDefinition.dockPreferences}. Standalone adapters
- * (`cli` / `spa` / `build`) ignore this entirely.
- */
-export interface DevframeDockPreferences {
-  /**
-   * The top-level dock-bar **category** ordering. Every installed devframe's
-   * `categoryOrder` is shallow-merged into one aggregate (last-installed wins
-   * per key) and merged beneath `DEFAULT_CATEGORIES_ORDER`. A host page's own
-   * `createDevframeClientHost({ categoryOrder })` still overrides it.
-   */
-  categoryOrder?: Record<string, number>
-  /**
-   * Preferred inline-item capacity for the floating dock bar before entries
-   * overflow. The last installed devframe declaring it wins; an explicit
-   * `layout` prop passed to the dock UI still overrides it. Edge mode ignores
-   * this by design — it shows every entry with no capacity cutoff.
-   */
-  maxVisibleItems?: number
-  /**
-   * Seeds a first-run visitor's dock mode. Only applies when the visitor has
-   * no stored dock preference yet; never overwrites one who already moved
-   * their dock. The last installed devframe declaring it wins.
-   */
-  defaultMode?: 'float' | 'edge'
-  /**
-   * Seeds a first-run visitor's dock position, same override semantics as
-   * {@link defaultMode}.
-   */
-  defaultPosition?: 'left' | 'right' | 'top' | 'bottom'
-}
-
 export interface DevframeSpaOptions {
   base?: string
   /**
@@ -348,15 +313,6 @@ export interface DevframeDefinition {
    * @see {@link DevframeDockDefaults}
    */
   dock?: DevframeDockDefaults
-  /**
-   * This devframe's opinion about the hub-wide dock bar (category ordering,
-   * float-mode capacity, first-run mode/position). Consulted only by the hub
-   * install path, which aggregates it across every installed devframe into
-   * `ConnectionMeta.configs.dock`; standalone adapters ignore it.
-   *
-   * @see {@link DevframeDockPreferences}
-   */
-  dockPreferences?: DevframeDockPreferences
   /**
    * Mount path override. Defaults depend on the adapter:
    * `/` for standalone (`cli` / `spa` / `build`), `/__<id>/` for hosted

packages/hub-ui/src/client/dock-preferences.ts

@@ -0,0 +1,26 @@
+/**
+ * The reference UI's dock-bar rendering preferences, set via
+ * `createUi({ dockPreferences })` and published as
+ * `ConnectionMeta.configs.ui.dockPreferences`. Read by the embedded dock and
+ * the standalone viewer at boot.
+ *
+ * Like the float/edge dock mode, these seed user-overridable state — the
+ * config sets the default, the visitor's own choice wins from then on.
+ */
+export interface DevframeDockPreferences {
+  /**
+   * The top-level dock-bar **category** ordering — a map of category id →
+   * ordering weight (lower sorts earlier), merged beneath
+   * `DEFAULT_CATEGORIES_ORDER`.
+   */
+  categoryOrder?: Record<string, number>
+  /**
+   * Preferred inline-item capacity for the floating dock bar before entries
+   * overflow. Edge mode ignores it — it shows every entry with no cutoff.
+   */
+  maxVisibleItems?: number
+  /** Seeds a first-run visitor's dock mode (float vs edge). */
+  defaultMode?: 'float' | 'edge'
+  /** Seeds a first-run visitor's dock position. */
+  defaultPosition?: 'left' | 'right' | 'top' | 'bottom'
+}

packages/hub-ui/src/client/embedded/index.ts

@@ -40,21 +40,21 @@ async function mountDock(): Promise<void> {
     simpleAuth: false,
   })
 
-  // The hub's aggregated dock-bar preferences (declared by installed
-  // devframes), delivered once via the connection handshake we just
-  // performed — fixed for the life of this server, never re-fetched.
-  const dockConfig = rpc.connectionMeta.configs?.dock
+  // The reference UI's dock-bar preferences (`createUi({ dockPreferences })`),
+  // delivered once via the connection handshake we just performed — fixed for
+  // the life of this server, never re-fetched.
+  const dockPreferences = rpc.connectionMeta.configs?.ui?.dockPreferences
 
   const defaultStore = DEFAULT_DOCK_PANEL_STORE()
   const state = useLocalStorage<DockPanelStorage>(
     'devframes-dock-state',
     {
       ...defaultStore,
-      // Seed a first-run visitor's mode/position from the hub's declared
+      // Seed a first-run visitor's mode/position from the configured
       // defaults — `useLocalStorage`'s own `mergeDefaults` already limits
       // this to a visitor with no stored preference yet.
-      ...(dockConfig?.defaultMode ? { mode: dockConfig.defaultMode } : {}),
-      ...(dockConfig?.defaultPosition ? { position: dockConfig.defaultPosition } : {}),
+      ...(dockPreferences?.defaultMode ? { mode: dockPreferences.defaultMode } : {}),
+      ...(dockPreferences?.defaultPosition ? { position: dockPreferences.defaultPosition } : {}),
     },
     { mergeDefaults: true },
   )
@@ -71,7 +71,7 @@ async function mountDock(): Promise<void> {
   const { DockEmbedded } = await import('../components/DockEmbedded')
   dockEl = new DockEmbedded({
     context,
-    ...(dockConfig?.maxVisibleItems !== undefined ? { layout: { maxVisibleItems: dockConfig.maxVisibleItems } } : {}),
+    ...(dockPreferences?.maxVisibleItems !== undefined ? { layout: { maxVisibleItems: dockPreferences.maxVisibleItems } } : {}),
   }) as unknown as HTMLElement
   // Inline on the host element — beats the generated `:host` ramp defaults and
   // inherits through the shadow tree. The embedded bootstrap never touches the

packages/hub-ui/src/client/state/context.ts

@@ -353,10 +353,10 @@ export async function createDocksContext(
 
   // Settings store, `settings`, and `getWhenContext` are established earlier
   // (right before `switchEntry`) — its group→member resolution needs them.
-  // `categoryOrderOverride` folds in every installed devframe's own declared
-  // `dock.categoryOrder`, aggregated hub-wide and delivered once via the
-  // connection handshake (`ConnectionMeta.configs.dock.categoryOrder`).
-  const categoryOrderOverride = rpc.connectionMeta.configs?.dock?.categoryOrder
+  // `categoryOrderOverride` folds in the reference UI's configured
+  // `dockPreferences.categoryOrder` (`createUi({ dockPreferences })`),
+  // delivered once via the connection handshake.
+  const categoryOrderOverride = rpc.connectionMeta.configs?.ui?.dockPreferences?.categoryOrder
   const groupedEntries = computed(() => {
     return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true, categoryOrderOverride })
   })

packages/hub-ui/src/index.ts

@@ -1,16 +1,22 @@
 import type { DevframeHubUi } from '@devframes/hub/initiate'
+import type { DevframeDockPreferences } from './client/dock-preferences'
 import type { EmbeddedVisibility } from './client/embedded/visibility'
 import type { DevframeBranding } from './client/state/branding'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+export type { DevframeDockPreferences } from './client/dock-preferences'
 export type { EmbeddedVisibility } from './client/embedded/visibility'
 export type { DevframeBranding } from './client/state/branding'
 
 declare module 'devframe/types' {
   interface DevframeConnectionConfigsRegistry {
-    ui: { branding?: DevframeBranding, embeddedVisibility?: EmbeddedVisibility }
+    ui: {
+      branding?: DevframeBranding
+      embeddedVisibility?: EmbeddedVisibility
+      dockPreferences?: DevframeDockPreferences
+    }
   }
 }
 
@@ -57,6 +63,13 @@ export interface CreateUiOptions {
    * dock only; the standalone viewer is an explicit visit and always shows.
    */
   embeddedVisibility?: EmbeddedVisibility
+  /**
+   * Dock-bar rendering preferences — category ordering, floating-dock
+   * inline-item capacity, and the first-run float/edge mode and position.
+   * Published as `ConnectionMeta.configs.ui.dockPreferences`; each seeds a
+   * user-overridable preference the visitor's own choice then wins.
+   */
+  dockPreferences?: DevframeDockPreferences
 }
 
 /**
@@ -85,9 +98,15 @@ export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
     ...(options.embedded !== false
       ? { embedded: { entry: join(client, 'embedded.js') } }
       : {}),
-    configs: () => ({
-      branding: options.branding || {},
-      ...(options.embeddedVisibility ? { embeddedVisibility: options.embeddedVisibility } : {}),
-    }),
+    // Publish the reference UI's config through the generic `ctx.staticConfig`
+    // — it rides the connection handshake to every mounted frame and the
+    // standalone viewer as `ConnectionMeta.configs.ui`.
+    setup(ctx) {
+      ctx.staticConfig.ui = {
+        branding: options.branding || {},
+        ...(options.embeddedVisibility ? { embeddedVisibility: options.embeddedVisibility } : {}),
+        ...(options.dockPreferences ? { dockPreferences: options.dockPreferences } : {}),
+      }
+    },
   }
 }

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

@@ -157,10 +157,9 @@ describe('createDevframeClientHost', () => {
     host.dispose()
   })
 
-  it('merges categoryOrder from connectionMeta.configs.dock beneath DEFAULT_CATEGORIES_ORDER, and the host option beneath that', async () => {
+  it('merges the host-page categoryOrder option beneath DEFAULT_CATEGORIES_ORDER', async () => {
     const { rpc, states } = createStubRpc()
-    ;(rpc as any).connectionMeta = { backend: 'websocket', configs: { dock: { categoryOrder: { app: -200, web: 10 } } } }
-    const host = await createDevframeClientHost({ rpc, categoryOrder: { web: 999 } })
+    const host = await createDevframeClientHost({ rpc, categoryOrder: { app: -200, web: 999 } })
 
     states.get('devframe:docks')!.push([
       iframeEntry('app-entry', { category: 'app' }),
@@ -169,7 +168,7 @@ describe('createDevframeClientHost', () => {
     ])
 
     expect(host.context.docks.categoryOrder).toMatchObject({ app: -200, web: 999, framework: -100 })
-    // `app` (-200, from connectionMeta) now sorts ahead of `framework` (-100, default).
+    // `app` (-200, from the option) now sorts ahead of `framework` (-100, default).
     expect(host.context.docks.groupedEntries.map(([cat]) => cat)).toEqual(['app', 'framework', 'web'])
     host.dispose()
   })

packages/hub/src/client/host.ts

@@ -78,11 +78,9 @@ export interface DevframeClientHostOptions {
    * 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` and every installed
-   * devframe's own declared `dock.categoryOrder` (see
-   * `ConnectionMeta.configs.dock.categoryOrder`) — this option sorts last
-   * and wins, so the host app only lists the categories it wants to move;
-   * any category absent from the map keeps its otherwise-resolved weight.
+   * 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.
    *
    * @example
    * ```ts
@@ -138,13 +136,10 @@ export async function createDevframeClientHost(
   const frameNavAdapters = new Map<string, () => void>()
   const loadScriptsEnabled = options.loadClientScripts ?? true
 
-  // Resolved once at boot, fixed for the session: default table, overridden
-  // by every installed devframe's own declared preference (delivered once
-  // via the connection handshake), overridden again by this host page's own
-  // explicit option.
+  // Resolved once at boot, fixed for the session: the default table overridden
+  // by this host page's own explicit option.
   const categoryOrder: Record<string, number> = {
     ...DEFAULT_CATEGORIES_ORDER,
-    ...rpc.connectionMeta?.configs?.dock?.categoryOrder,
     ...options.categoryOrder,
   }
 

packages/hub/src/node/__tests__/initiate.test.ts

@@ -174,42 +174,32 @@ describe('initHub', () => {
     }
   })
 
-  it('assembles ConnectionMeta.configs from the ui slot and every installed devframe\'s dock preferences', async () => {
+  it('serves whatever the ui slot\'s setup(ctx) writes to ctx.staticConfig as ConnectionMeta.configs', async () => {
     const wsPort = await getPort({ port: 18225, host: '127.0.0.1' })
-    const alpha: DevframeDefinition = {
-      ...makeFrame('alpha', makeDist('<!doctype html><title>frame a</title>')),
-      dock: { category: 'app' },
-      dockPreferences: { categoryOrder: { app: -40 }, maxVisibleItems: 4 },
-    }
-    const beta: DevframeDefinition = {
-      ...makeFrame('beta'),
-      dock: { category: 'web' },
-      dockPreferences: { categoryOrder: { app: -60, web: 300 }, defaultMode: 'edge' },
-    }
+    const alpha = makeFrame('alpha', makeDist('<!doctype html><title>frame a</title>'))
 
     const hub = initHub({
       base: DEVFRAMES_HUB_BASE,
       auth: false,
       host: '127.0.0.1',
       ws: { port: wsPort },
-      devframes: [alpha, beta],
-      ui: { configs: () => ({ branding: { productName: 'Test Hub' } }) },
+      devframes: [alpha],
+      ui: {
+        setup(ctx) {
+          ;(ctx.staticConfig as Record<string, unknown>).ui = { branding: { productName: 'Test Hub' } }
+        },
+      },
     })
 
     try {
       await hub.ready
       const origin = 'http://localhost:5173'
 
-      // The hub's own meta…
+      // The hub's own meta carries what the ui slot published…
       const hubMeta = await (await hub.handler(new Request(`${origin}/__devframes/__connection.json`))).json()
-      expect(hubMeta.configs).toEqual({
-        ui: { branding: { productName: 'Test Hub' } },
-        // Last-installed devframe (`beta`) wins the `app` scalar key; `web`
-        // only `beta` declared; `maxVisibleItems` only `alpha` declared.
-        dock: { categoryOrder: { app: -60, web: 300 }, maxVisibleItems: 4, defaultMode: 'edge' },
-      })
+      expect(hubMeta.configs).toEqual({ ui: { branding: { productName: 'Test Hub' } } })
 
-      // …and every per-frame meta carries the identical aggregate.
+      // …and every per-frame meta carries the identical document.
       const frameMeta = await (await hub.handler(new Request(`${origin}/__devframes/alpha/__connection.json`))).json()
       expect(frameMeta.configs).toEqual(hubMeta.configs)
     }
@@ -218,7 +208,7 @@ describe('initHub', () => {
     }
   })
 
-  it('omits ConnectionMeta.configs entirely when neither the ui slot nor any devframe declares anything', async () => {
+  it('omits ConnectionMeta.configs entirely when the ui slot writes nothing', async () => {
     const wsPort = await getPort({ port: 18226, host: '127.0.0.1' })
     const hub = initHub({ base: DEVFRAMES_HUB_BASE, auth: false, host: '127.0.0.1', ws: { port: wsPort }, devframes: [makeFrame('alpha')] })