refactor(devframe,hub): plain ctx.staticConfig + split DevframeDockPreferences

Applies review feedback:

- `ctx.configs` (the `DevframeConfigsHost` with `contribute`/`resolve`) is
  now `ctx.staticConfig` — a plain, non-reactive `Partial<DevframeConnectionConfigsRegistry>`
  object mutated at setup time. Drops the host class and its test; the
  instance shell serializes the object straight into `ConnectionMeta.configs`.
- The hub-wide dock-bar preferences (`categoryOrder` / `maxVisibleItems` /
  `defaultMode` / `defaultPosition`) move off the per-entry `DevframeDockDefaults`
  into a dedicated `DevframeDockPreferences` type, declared on the new
  `DevframeDefinition.dockPreferences`. `installDevframe` aggregates it into
  `ctx.staticConfig.dock`; the hub's `configs.dock` registry key now points at
  `DevframeDockPreferences` (the `DevframeDockConfig` alias is gone).

Built with the help of an agent.

Author: antfubot

docs/guide/devframe-definition.md

@@ -113,7 +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
+  staticConfig: Partial<DevframeConnectionConfigsRegistry> // this context's own ConnectionMeta.configs
 
   scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
 }
@@ -133,7 +133,7 @@ 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.
+`ctx.staticConfig` is this context's own `ConnectionMeta.configs` — static, boot-time data delivered once through the connection handshake every client already performs, and read-only from the browser. It's a plain, **non-reactive** object: write it during `setup(ctx)`, never during the session (it's serialized once, after setup). 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' {
@@ -142,7 +142,7 @@ declare module 'devframe/types' {
   }
 }
 
-ctx.configs.contribute('my-plugin', () => ({ featureFlag: true }))
+ctx.staticConfig['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.

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

@@ -3,7 +3,6 @@ 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'
@@ -45,7 +44,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
     diagnostics: undefined!,
     agent: undefined!,
     services: undefined!,
-    configs: undefined!,
+    staticConfig: {},
     scope: undefined!,
   } as unknown as DevframeNodeContext
 
@@ -56,7 +55,6 @@ 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/context.ts

@@ -589,14 +589,13 @@ 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
+    // Whatever `setup(ctx)` wrote to `ctx.staticConfig` during
+    // `options.init(api)` — e.g. a hub aggregating each installed devframe's
+    // own dock-bar preferences — is in by now; bake it into the meta
+    // `options.mount` (and every host that re-serves this same meta at
+    // another base) publishes.
+    if (Object.keys(ctx.staticConfig).length > 0)
+      meta.configs = ctx.staticConfig
 
     await options.mount?.(ctx, meta, api)
 

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

@@ -65,13 +65,21 @@ export interface DevframeNodeContext {
    */
   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}.
+   * This context's own {@link ConnectionMeta.configs} — static, boot-time
+   * config a host publishes once through the connection handshake and every
+   * client reads read-only. A plain, **non-reactive** object: mutate it
+   * during `setup(ctx)` (a plugin sets its keys, a hub aggregates across
+   * every installed devframe), never during the session — it's serialized
+   * once, after setup, and changing it afterwards reaches no client.
+   *
+   * ```ts
+   * ctx.staticConfig.dock = {
+   *   ...ctx.staticConfig.dock,
+   *   categoryOrder: { ...ctx.staticConfig.dock?.categoryOrder, ...myOrder },
+   * }
+   * ```
    */
-  // TODO: call it `ctx.staticConfig`, and have it a plain object. No need for complex host here.
-  // Just mention that it's not reactive and should be updated only at setup time, not during the session.
-  configs: DevframeConfigsHost
+  staticConfig: Partial<DevframeConnectionConfigsRegistry>
   /**
    * Create a namespace-scoped view of this context. The returned
    * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
@@ -246,30 +254,3 @@ 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/devframe/src/node/instance-shell.ts

@@ -262,30 +262,34 @@ export interface DevframeDockDefaults {
   badge?: string
   /** Id of the dock group this entry collapses under, if any. */
   groupId?: string
-  // TODO: `categoryOrder` / `maxVisibleItems` / `defaultMode` / `defaultPosition` are not per-entry attributes, but global hub-wide preferences. They should be moved to a separate `DevframeDockPreferences` type and surfaced in the connection meta, not on the entry itself.
+}
+
+/**
+ * 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 {
   /**
-   * 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
+   * 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>
   /**
-   * 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.
+   * 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 — 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.
+   * 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'
   /**
@@ -344,6 +348,15 @@ 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/devframe/src/types/context.ts

@@ -178,11 +178,13 @@ describe('initHub', () => {
     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', categoryOrder: { app: -40 }, maxVisibleItems: 4 },
+      dock: { category: 'app' },
+      dockPreferences: { categoryOrder: { app: -40 }, maxVisibleItems: 4 },
     }
     const beta: DevframeDefinition = {
       ...makeFrame('beta'),
-      dock: { category: 'web', categoryOrder: { app: -60, web: 300 }, defaultMode: 'edge' },
+      dock: { category: 'web' },
+      dockPreferences: { categoryOrder: { app: -60, web: 300 }, defaultMode: 'edge' },
     }
 
     const hub = initHub({

packages/devframe/src/types/devframe.ts

@@ -1,4 +1,4 @@
-import type { DevframeConfigsHost, DevframeDefinition, DevframeDuplicationStrategy } from 'devframe/types'
+import type { DevframeDefinition, DevframeDuplicationStrategy } from 'devframe/types'
 import type { DevframeHubContext } from '../context'
 import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -8,17 +8,6 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { DevframeDocksHost } from '../host-docks'
 import { installDevframe } from '../install-devframe'
 
-/** Minimal stand-in for `createHostContext`'s real `DevframeConfigsHostImpl`. */
-function createConfigsHost(): DevframeConfigsHost {
-  const values: Record<string, any> = {}
-  return {
-    contribute: (key, updater) => {
-      values[key] = updater(values[key])
-    },
-    resolve: () => values,
-  }
-}
-
 function createContext(): DevframeHubContext {
   const storageDir = mkdtempSync(join(tmpdir(), 'devframe-hub-install-'))
   const context = {
@@ -30,7 +19,8 @@ function createContext(): DevframeHubContext {
     views: {
       hostStatic: () => {},
     },
-    configs: createConfigsHost(),
+    // `createHostContext` seeds this plain object; the fake mirrors it.
+    staticConfig: {},
   } as unknown as DevframeHubContext
   context.docks = new DevframeDocksHost(context)
   // `createHubContext` wires this; the hand-built fake context here does the
@@ -109,19 +99,19 @@ describe('ctx.install', () => {
     })
   })
 
-  it('contributes categoryOrder/maxVisibleItems/defaultMode/defaultPosition to ctx.configs instead of the entry', async () => {
+  it('writes dockPreferences to ctx.staticConfig.dock, not the synthesized entry', async () => {
     const ctx = createContext()
     await ctx.install(makeDevframe({
-      dock: {
-        category: 'app',
+      dock: { category: 'app' },
+      dockPreferences: {
         categoryOrder: { app: -40 },
         maxVisibleItems: 4,
         defaultMode: 'edge',
         defaultPosition: 'left',
       },
     }))
 
-    expect(ctx.configs.resolve().dock).toEqual({
+    expect(ctx.staticConfig.dock).toEqual({
       categoryOrder: { app: -40 },
       maxVisibleItems: 4,
       defaultMode: 'edge',
@@ -136,23 +126,23 @@ describe('ctx.install', () => {
     expect(entry.category).toBe('app')
   })
 
-  it('leaves ctx.configs untouched when a devframe declares no dock-bar preferences', async () => {
+  it('leaves ctx.staticConfig untouched when a devframe declares no dock preferences', async () => {
     const ctx = createContext()
     await ctx.install(makeDevframe({ dock: { category: 'app' } }))
-    expect(ctx.configs.resolve().dock).toBeUndefined()
+    expect(ctx.staticConfig.dock).toBeUndefined()
   })
 
   it('shallow-merges categoryOrder across two devframes, last wins per scalar field', async () => {
     const ctx = createContext()
     await ctx.install(makeDevframe({
-      dock: { categoryOrder: { app: -40, web: 300 }, maxVisibleItems: 4, defaultMode: 'edge' },
+      dockPreferences: { categoryOrder: { app: -40, web: 300 }, maxVisibleItems: 4, defaultMode: 'edge' },
     }))
     await ctx.install(makeDevframe({
       id: 'demo-2',
-      dock: { categoryOrder: { app: -60, advanced: -50 }, maxVisibleItems: 10 },
+      dockPreferences: { categoryOrder: { app: -60, advanced: -50 }, maxVisibleItems: 10 },
     }))
 
-    expect(ctx.configs.resolve().dock).toEqual({
+    expect(ctx.staticConfig.dock).toEqual({
       categoryOrder: { app: -60, web: 300, advanced: -50 },
       maxVisibleItems: 10,
       defaultMode: 'edge',

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

@@ -534,7 +534,7 @@ export function initHub(options: InitHubOptions): HubInstance {
 
     mount(ctx, meta) {
       // `meta.configs` already carries whatever every installed devframe
-      // contributed via `ctx.configs` (e.g. aggregated dock-bar preferences
+      // wrote to `ctx.staticConfig` (e.g. aggregated dock-bar preferences
       // under `dock`) — add the UI slot's own opaque config (e.g. branding)
       // under `ui`, without interpreting it, staying policy-free about what
       // "ui" means.