refactor(devframe,hub,hub-ui): generic ctx.configs API, drop host-page branding channels

Follows up on review feedback:

- Adds ctx.configs (DevframeConfigsHost) as a core devframe context
  primitive — the generic API for contributing to a context's own
  ConnectionMeta.configs, resolved once (instance-shell) after every
  contributor has run and baked into the served meta for every host
  adapter, not just the hub. Contributors own their own merge semantics
  via an (current) => next updater.
- installDevframe now calls ctx.configs.contribute('dock', ...) instead
  of a docks-specific contributeDockConfig; dockConfig/contributeDockConfig
  are removed from DevframeDocksHost — dock-bar config aggregation isn't
  a docks-registry concern.
- DevframeHubUi.settings renamed to configs, matching the
  ConnectionMeta.configs.ui wire shape it feeds.
- hub-ui's resolveBranding drops the host-page override channels
  (window.__DEVFRAME_BRANDING__, <script data-*>, ?query params) —
  ConnectionMeta already has its own cross-realm propagation, so
  branding needs no globals or query params of its own.

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
-  settings?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
+  configs?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
 }
 ```
 
@@ -25,12 +25,12 @@ 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
+`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 `settings`
+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.
 

docs/guide/devframe-definition.md

@@ -113,6 +113,7 @@ interface DevframeNodeContext {
   diagnostics: DevframeDiagnosticsHost
   agent: DevframeAgentHost // experimental
   services: DevframeServicesHost // typed cross-plugin service registry
+  configs: DevframeConfigsHost // contribute to this context's own ConnectionMeta.configs
 
   scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
 }
@@ -130,6 +131,22 @@ ctx.services.whenAvailable('my-plugin:sources', (sources) => {
 })
 ```
 
+### Static connection configs
+
+`ctx.configs` builds up `ConnectionMeta.configs` — static, boot-time data delivered once through the connection handshake every client already performs, and never mutated again. Contrast it with `ctx.scope(id).settings`, which is mutable and synced bidirectionally over shared-state RPC for the life of the session.
+
+```ts
+declare module 'devframe/types' {
+  interface DevframeConnectionConfigsRegistry {
+    'my-plugin': { featureFlag: boolean }
+  }
+}
+
+ctx.configs.contribute('my-plugin', () => ({ featureFlag: true }))
+```
+
+`updater` receives whatever's been contributed to that key so far (or `undefined` on the first contribution), so multiple contributors sharing a key — a hub aggregating each installed devframe's own preference, for example — own their own merge semantics (overwrite, shallow-merge a record, …) rather than the host imposing one.
+
 ### Storage scopes
 
 `ctx.host.getStorageDir(scope)` places persisted state in one of three classes:
@@ -152,6 +169,7 @@ Each devframe-level host has a dedicated page:
 - [Shared State](./shared-state) — `ctx.rpc.sharedState`
 - [Diagnostics](./diagnostics) — `ctx.diagnostics`
 - [Agent-Native](./agent-native) — `ctx.agent`
+- [Cross-Plugin Services](./services) — `ctx.services`
 
 ## Browser setup
 

docs/guide/hub-initiate.md

@@ -57,7 +57,7 @@ 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
+  configs?: () => Record<string, unknown> // static config, published as ConnectionMeta.configs.ui
 }
 ```
 

packages/devframe/src/node/__tests__/host-configs.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { DevframeConfigsHostImpl } from '../host-configs'
+
+describe('devframeConfigsHost', () => {
+  it('resolves empty before any contribution', () => {
+    const configs = new DevframeConfigsHostImpl()
+    expect(configs.resolve()).toEqual({})
+  })
+
+  it('passes undefined to the updater on the first contribution for a key', () => {
+    // The registry is empty in the core package (augmented by consumers like
+    // `@devframes/hub`), so the test drives `contribute`/`resolve` untyped.
+    const configs = new DevframeConfigsHostImpl() as any
+    configs.contribute('dock', (current: any) => {
+      expect(current).toBeUndefined()
+      return { maxVisibleItems: 4 }
+    })
+    expect(configs.resolve()).toEqual({ dock: { maxVisibleItems: 4 } })
+  })
+
+  it('threads the current value into each subsequent contribution for the same key', () => {
+    const configs = new DevframeConfigsHostImpl() as any
+    configs.contribute('dock', () => ({ categoryOrder: { app: -40 } }))
+    configs.contribute('dock', (current: any) => ({
+      categoryOrder: { ...current.categoryOrder, web: 300 },
+    }))
+    expect(configs.resolve()).toEqual({ dock: { categoryOrder: { app: -40, web: 300 } } })
+  })
+
+  it('keeps contributions to different keys independent', () => {
+    const configs = new DevframeConfigsHostImpl() as any
+    configs.contribute('dock', () => ({ maxVisibleItems: 4 }))
+    configs.contribute('ui', () => ({ branding: { productName: 'Test' } }))
+    expect(configs.resolve()).toEqual({
+      dock: { maxVisibleItems: 4 },
+      ui: { branding: { productName: 'Test' } },
+    })
+  })
+})

packages/devframe/src/node/context.ts

@@ -3,6 +3,7 @@ import type { DevframeHost, DevframeNodeContext, DevframeScopedNodeContext } fro
 import { diagnostics as rpcDiagnostics } from '../rpc/diagnostics'
 import { diagnostics as devframeDiagnostics } from './diagnostics'
 import { DevframeAgentHost } from './host-agent'
+import { DevframeConfigsHostImpl } from './host-configs'
 import { DevframeDiagnosticsHost } from './host-diagnostics'
 import { RpcFunctionsHostImpl } from './host-functions'
 import { DevframeServicesHostImpl } from './host-services'
@@ -44,6 +45,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
     diagnostics: undefined!,
     agent: undefined!,
     services: undefined!,
+    configs: undefined!,
     scope: undefined!,
   } as unknown as DevframeNodeContext
 
@@ -54,6 +56,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
   context.views = viewsHost
   context.diagnostics = diagnosticsHost
   context.services = new DevframeServicesHostImpl()
+  context.configs = new DevframeConfigsHostImpl()
 
   // Agent host must be constructed after `rpcHost` so it can subscribe
   // to `onChanged` — it auto-discovers RPC functions flagged with

packages/devframe/src/node/host-configs.ts

@@ -0,0 +1,22 @@
+import type { DevframeConfigsHost, DevframeConnectionConfigsRegistry } from 'devframe/types'
+
+/**
+ * Backs `ctx.configs` (see `types/context.ts` for the contract). Values
+ * accumulate in memory for the life of the context — `resolve()` is read
+ * once, after every contributor has run, to build the served
+ * `ConnectionMeta.configs`.
+ */
+export class DevframeConfigsHostImpl implements DevframeConfigsHost {
+  private readonly values: Partial<DevframeConnectionConfigsRegistry> = {}
+
+  contribute<K extends keyof DevframeConnectionConfigsRegistry>(
+    key: K,
+    updater: (current: DevframeConnectionConfigsRegistry[K] | undefined) => DevframeConnectionConfigsRegistry[K],
+  ): void {
+    this.values[key] = updater(this.values[key])
+  }
+
+  resolve(): Partial<DevframeConnectionConfigsRegistry> {
+    return this.values
+  }
+}

packages/devframe/src/node/instance-shell.ts

@@ -589,6 +589,15 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
       ...(result.mcp ? { mcp: result.mcp } : {}),
     }
 
+    // Every contribution (`ctx.configs.contribute(...)`) made during
+    // `options.init(api)` — e.g. a hub aggregating each installed
+    // devframe's own dock-bar preferences — is in by now; bake the
+    // resolved configs into the meta `options.mount` (and every host that
+    // re-serves this same meta at another base) publishes.
+    const configs = ctx.configs.resolve()
+    if (Object.keys(configs).length > 0)
+      meta.configs = configs
+
     await options.mount?.(ctx, meta, api)
 
     // A pinned origin means the banner and registry record needn't wait for a

packages/devframe/src/types/context.ts

@@ -64,6 +64,12 @@ export interface DevframeNodeContext {
    * absorb setup-order differences between provider and consumer.
    */
   services: DevframeServicesHost
+  /**
+   * The API for contributing to this context's own {@link ConnectionMeta.configs}
+   * — static, boot-time config a host publishes once and never mutates
+   * again. See {@link DevframeConfigsHost}.
+   */
+  configs: DevframeConfigsHost
   /**
    * Create a namespace-scoped view of this context. The returned
    * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
@@ -238,3 +244,30 @@ export interface ConnectionMeta {
  * augments it with `dock`; `@devframes/hub-ui` augments it with `ui`.
  */
 export interface DevframeConnectionConfigsRegistry {}
+
+/**
+ * The API for building up {@link ConnectionMeta.configs} — every registered
+ * key merges from whatever contributes to it (a plugin's own `setup(ctx)`,
+ * a hub aggregating across every installed devframe, …) into the one
+ * document a host publishes once and serves for the life of the server.
+ *
+ * `updater` receives whatever's been contributed to `key` so far (or
+ * `undefined` on the first contribution) and returns the new value — the
+ * contributor owns its own merge semantics (overwrite, shallow-merge a
+ * record, …), not this host.
+ *
+ * ```ts
+ * ctx.configs.contribute('dock', (current = {}) => ({
+ *   ...current,
+ *   categoryOrder: { ...current.categoryOrder, ...myCategoryOrder },
+ * }))
+ * ```
+ */
+export interface DevframeConfigsHost {
+  contribute: <K extends keyof DevframeConnectionConfigsRegistry>(
+    key: K,
+    updater: (current: DevframeConnectionConfigsRegistry[K] | undefined) => DevframeConnectionConfigsRegistry[K],
+  ) => void
+  /** Everything contributed so far — what a host publishes as `ConnectionMeta.configs`. */
+  resolve: () => Partial<DevframeConnectionConfigsRegistry>
+}

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

@@ -59,13 +59,10 @@ async function mountDock(): Promise<void> {
   )
 
   // Resolve branding before the dock exists so the primary color and logo are
-  // in place on the first paint. Read from `ConnectionMeta.configs.ui.branding`
-  // (already fetched above), then overridden by any host-page channel.
+  // in place on the first paint. Read from `ConnectionMeta.configs.ui.branding`,
+  // carried by the connection we just established above.
   const { resolveBranding, applyPrimaryColor } = await import('../state/branding')
-  const branding = resolveBranding({
-    mode: 'embedded',
-    branding: rpc.connectionMeta.configs?.ui?.branding,
-  })
+  const branding = resolveBranding(rpc.connectionMeta.configs?.ui?.branding)
 
   const { createDocksContext } = await import('../state/context')
   const context = await createDocksContext('embedded', rpc, state)

packages/hub-ui/src/client/standalone/main.ts

@@ -34,10 +34,7 @@ async function main(): Promise<void> {
   // `ConnectionMeta.configs.ui.branding`, carried by the connection we just
   // established above.
   const { resolveBranding, applyPrimaryColor, applyDocumentHead } = await import('../state/branding')
-  const branding = resolveBranding({
-    mode: 'standalone',
-    branding: rpc.connectionMeta.configs?.ui?.branding,
-  })
+  const branding = resolveBranding(rpc.connectionMeta.configs?.ui?.branding)
   applyDocumentHead(document, branding)
 
   const { createDocksContext } = await import('../state/context')