feat(devframe,hub,hub-ui): static connection-meta configs + plugin-declared dock layout

Add ConnectionMeta.configs — an augmentable, boot-time, read-only-from-the-
browser config channel, distinct from the mutable/shared-state-synced
ctx.settings and devframe:user-settings. Each key is contributed via
declaration merging against DevframeConnectionConfigsRegistry.

Ports vitejs/devtools#515 (plugin-declared dock ordering, layout, and
window defaults) on top of it: DevframeDockDefaults gains categoryOrder,
maxVisibleItems, defaultMode, and defaultPosition. The hub aggregates them
across every installed devframe (last-installed wins per scalar,
categoryOrder shallow-merged) into ConnectionMeta.configs.dock, folded
into the dock bar's category sort, the floating dock's inline-item
capacity, and a first-run visitor's mode/position seed.

hub-ui's branding moves off the ad-hoc branding.json asset route onto
configs.ui.branding, delivered through the one connection handshake the
dock already performs instead of a separate fetch. createUi({ branding })
keeps its existing signature.

Built with the help of an agent.

Author: antfubot

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

@@ -16,6 +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
+  settings?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
 }
 ```
 
@@ -24,6 +25,15 @@ 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.
 
+`settings` 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 `settings`
+for small, structured, boot-time config, and `assets` for arbitrary served
+files.
+
 ## The client contracts
 
 A viewer renders from the hub's shared state and drives it through

docs/guide/hub-initiate.md

@@ -56,6 +56,8 @@ The hub is headless — `DevframeHubUi` is pure data, and whoever fills it decid
 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
+  settings?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
 }
 ```
 

examples/hub-hono-minimal/src/app.ts

@@ -39,9 +39,9 @@ export const hub: HubInstance = globalRef.__hubHonoMinimal ??= initHub({
     createAssetsDevframe({ watch: false }),
   ],
   // Rebrand the reference UI to Hono's own orange — one field, no CSS:
-  // `createUi`'s `branding` option publishes `branding.json`, which the dock
-  // fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+  // which the dock reads at connect time and feeds into `--devframe-primary`
+  // (see `@devframes/hub-ui`'s `primary-ramp.css`).
   ui: createUi({ branding: { primaryColor: '#e36002', productName: 'Devframes on Hono' } }),
   // Gate with devframe's interactive OTP (the default). The hub prints a
   // 6-digit code + magic link on startup, and the reference UI's authorization

examples/hub-next-minimal/src/client/hub.ts

@@ -73,9 +73,10 @@ async function loadHub(): Promise<HubInstance> {
   // `@devframes/next/hub` runs the socket on a side-car (Next routes can't
   // accept WS upgrades). This host overrides the default UI slot to rebrand
   // the reference viewer to Next.js/Vercel's monochrome black — one field, no
-  // CSS: `createUi`'s `branding` option publishes `branding.json`, which the
-  // dock fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // CSS: `createUi`'s `branding` option publishes
+  // `ConnectionMeta.configs.ui.branding`, which the dock reads at connect
+  // time and feeds into `--devframe-primary` (see `@devframes/hub-ui`'s
+  // `primary-ramp.css`).
   return createNextDevframeHub({
     devframes,
     ui: (hubUi.createUi as typeof CreateUi)({ branding: { primaryColor: '#000000', productName: 'Devframes on Next.js' } }),

examples/hub-nitro-minimal/hub.ts

@@ -42,9 +42,9 @@ export const hub: HubInstance = globalRef.__hubNitroMinimal ??= initHub({
     createAssetsDevframe({ watch: false }),
   ],
   // Rebrand the reference UI to Nitro's own pink/red — one field, no CSS:
-  // `createUi`'s `branding` option publishes `branding.json`, which the dock
-  // fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+  // which the dock reads at connect time and feeds into `--devframe-primary`
+  // (see `@devframes/hub-ui`'s `primary-ramp.css`).
   ui: createUi({ branding: { primaryColor: '#ff2056', productName: 'Devframes on Nitro' } }),
   // Gate with devframe's interactive OTP (the default). The hub prints a
   // 6-digit code + magic link on startup, and the reference UI's authorization

examples/hub-rsbuild-minimal/rsbuild.config.ts

@@ -77,9 +77,10 @@ export default defineConfig({
         base,
         devframes: builtinDevframes,
         // Rebrand the reference UI to Rsbuild's own orange — one field, no
-        // CSS: `createUi`'s `branding` option publishes `branding.json`,
-        // which the dock fetches at boot and feeds into `--devframe-primary`
-        // (see `@devframes/hub-ui`'s `primary-ramp.css`).
+        // CSS: `createUi`'s `branding` option publishes
+        // `ConnectionMeta.configs.ui.branding`, which the dock reads at
+        // connect time and feeds into `--devframe-primary` (see
+        // `@devframes/hub-ui`'s `primary-ramp.css`).
         ui: createUi({ branding: { primaryColor: '#ff5e00', productName: 'Devframes on Rsbuild' } }),
         // Serve the reference json-render frontend as a prebuilt renderer
         // module — the one-liner that makes `'json-render'` docks render in

examples/hub-vite-minimal/vite.config.ts

@@ -67,10 +67,10 @@ export default defineConfig({
       quiet: true,
       devframes: builtinDevframes,
       // Rebrand the reference UI to Vite's own purple — one field, no CSS:
-      // `createUi`'s `branding` option publishes `branding.json`, which the
-      // dock fetches at boot and feeds into `--devframe-primary` (see
-      // `@devframes/hub-ui`'s `primary-ramp.css`). Passing `ui` overrides the
-      // default `createUi()` the plugin would otherwise use.
+      // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+      // which the dock reads at connect time and feeds into `--devframe-primary`
+      // (see `@devframes/hub-ui`'s `primary-ramp.css`). Passing `ui` overrides
+      // the default `createUi()` the plugin would otherwise use.
       ui: createUi({ branding: { primaryColor: '#646cff', productName: 'Devframes on Vite' } }),
       // Serve the reference json-render frontend as a prebuilt renderer
       // module — the one-liner that makes `'json-render'` docks render in

packages/devframe/src/types/context.ts

@@ -205,4 +205,36 @@ export interface ConnectionMeta {
    * token same-origin until the requesting origin has been verified.
    */
   viewerOriginToken?: string
+  /**
+   * Static, host-declared configuration — baked in once at connect time and
+   * fixed for the life of the server (e.g. a hub's UI rebrand, or its
+   * aggregated dock-bar layout preferences). Read-only from the browser: a
+   * client only ever reads `rpc.connectionMeta.configs`, never writes to it.
+   *
+   * Contrast this with {@link DevframeSettingsRegistry} (`ctx.scope(ns).settings`)
+   * and a hub's `devframe:user-settings` shared-state key — both are
+   * mutable, user-editable, and synced bidirectionally over RPC for the
+   * life of the session. `configs` is the opposite: one-way, immutable,
+   * decided by whoever assembled the server.
+   *
+   * Each key is owned by one package, contributed via declaration merging:
+   *
+   * ```ts
+   * declare module 'devframe/types' {
+   *   interface DevframeConnectionConfigsRegistry {
+   *     'my-key': { some: 'shape' }
+   *   }
+   * }
+   * ```
+   */
+  configs?: Partial<DevframeConnectionConfigsRegistry>
 }
+
+/**
+ * Augmentation point for {@link ConnectionMeta.configs}. Empty by default —
+ * a package that wants to publish static, boot-time config through the
+ * connection handshake augments this interface with its own key (see
+ * {@link ConnectionMeta.configs} for the pattern). `@devframes/hub`
+ * augments it with `dock`; `@devframes/hub-ui` augments it with `ui`.
+ */
+export interface DevframeConnectionConfigsRegistry {}

packages/devframe/src/types/devframe.ts

@@ -262,6 +262,36 @@ export interface DevframeDockDefaults {
   badge?: string
   /** Id of the dock group this entry collapses under, if any. */
   groupId?: string
+  /**
+   * This devframe's opinion about the top-level dock-bar **category**
+   * ordering, hub-wide — not an attribute of this entry itself. Every
+   * installed devframe's `categoryOrder` is shallow-merged into one
+   * aggregate (last-installed wins per key), delivered once via
+   * `ConnectionMeta.configs.dock.categoryOrder` and merged beneath
+   * `DEFAULT_CATEGORIES_ORDER`. A host page's own
+   * `createDevframeClientHost({ categoryOrder })` still overrides it.
+   */
+  categoryOrder?: Record<string, number>
+  /**
+   * This devframe's preferred inline-item capacity for the floating dock
+   * bar before entries overflow — hub-wide, not an attribute of this entry.
+   * 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 — hub-wide, not an attribute of
+   * this entry. 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 {

packages/hub-ui/src/client/components/DockEmbedded.ts

@@ -1,5 +1,6 @@
 import type { DocksContext } from '@devframes/hub/client'
 import type { VueElementConstructor } from 'vue'
+import type { DockLayout } from './dock/dock-layout'
 import { defineCustomElement } from 'vue'
 import css from '../.generated/css'
 import Component from './dock/DockEmbedded.vue'
@@ -12,6 +13,7 @@ export const DockEmbedded = defineCustomElement(
   },
 ) as VueElementConstructor<{
   context: DocksContext
+  layout?: Partial<DockLayout>
 }>
 
 customElements.define('devframes-dock-embedded', DockEmbedded)