feat(hub): add builtinDocks option to gate built-in dock entries

Add an optional `builtinDocks` field to `CreateHubContextOptions` so a host
can suppress individual synthesized built-in dock entries (`~terminals`,
`~messages`, `~settings`). Each flag defaults to present; passing `false`
omits that entry from every path that reads `DevframeDocksHost.values()`.

Omitting the option keeps all three built-ins, so existing hosts are
unaffected.

Author: antfubot

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

@@ -30,6 +30,18 @@ describe('createHubContext shared state', () => {
       '~settings',
     ])
   })
+
+  it('suppresses built-ins gated off via builtinDocks', async () => {
+    const context = await createHubContext({
+      cwd: process.cwd(),
+      mode: 'build',
+      host: createHost(),
+      builtinDocks: { terminals: false, messages: false },
+    })
+
+    const docks = await context.rpc.sharedState.get<DevframeDockEntry[]>('devframe:docks')
+    expect(docks.value().map(dock => dock.id)).toEqual(['~settings'])
+  })
 })
 
 describe('startHttpAndWs remote endpoint metadata', () => {

packages/hub/src/node/__tests__/host-docks.test.ts

@@ -16,6 +16,10 @@ function createContext(): DevframeHubContext {
       resolveOrigin: () => 'http://localhost:5173',
       getStorageDir: () => storageDir,
     },
+    // Minimal stubs so the built-in `~terminals`/`~messages` getters
+    // (`when`/`badge`) can be evaluated without a full context.
+    terminals: { sessions: new Map() },
+    messages: { entries: new Map() },
   } as unknown as DevframeHubContext
 }
 
@@ -189,3 +193,48 @@ describe('devframeDockHost grouping', () => {
     })).toThrow('Dock with id "ghost" is not registered and cannot be updated')
   })
 })
+
+describe('devframeDockHost built-in gating', () => {
+  it('includes all three built-ins by default', () => {
+    const host = new DevframeDocksHost(createContext())
+    const ids = host.values().map(entry => entry.id)
+    expect(ids).toEqual(['~terminals', '~messages', '~settings'])
+  })
+
+  it('treats an empty builtinDocks map as all-enabled', () => {
+    const host = new DevframeDocksHost(createContext(), {})
+    const ids = host.values().map(entry => entry.id)
+    expect(ids).toEqual(['~terminals', '~messages', '~settings'])
+  })
+
+  it('omits the built-ins gated with `false`, keeping the rest', () => {
+    const host = new DevframeDocksHost(createContext(), { terminals: false, messages: false })
+    const ids = host.values().map(entry => entry.id)
+    expect(ids).toEqual(['~settings'])
+  })
+
+  it('keeps an explicitly-enabled built-in and drops an omitted-as-false sibling', () => {
+    const host = new DevframeDocksHost(createContext(), { terminals: true, settings: false })
+    const ids = host.values().map(entry => entry.id)
+    expect(ids).toEqual(['~terminals', '~messages'])
+  })
+
+  it('keeps user views ahead of gated built-ins', () => {
+    const host = new DevframeDocksHost(createContext(), { messages: false, settings: false })
+    host.register({
+      type: 'iframe',
+      id: 'app:overview',
+      title: 'Overview',
+      icon: 'ph:gauge-duotone',
+      url: '/__app/',
+    })
+
+    const ids = host.values().map(entry => entry.id)
+    expect(ids).toEqual(['app:overview', '~terminals'])
+  })
+
+  it('drops every built-in when includeBuiltin is false, regardless of gating', () => {
+    const host = new DevframeDocksHost(createContext(), { terminals: true, messages: true, settings: true })
+    expect(host.values({ includeBuiltin: false })).toEqual([])
+  })
+})

packages/hub/src/node/context.ts

@@ -1,7 +1,7 @@
 import type { CreateHostContextOptions } from 'devframe/node'
 import type { DevframeHost, DevframeNodeContext } from 'devframe/types'
 import type { DevframeCommandsHost } from '../types/commands'
-import type { DevframeDocksHost } from '../types/docks'
+import type { BuiltinDocksOptions, DevframeDocksHost } from '../types/docks'
 import type { JsonRenderer, JsonRenderSpec } from '../types/json-render'
 import type { DevframeMessagesHost } from '../types/messages'
 import type { DevframeTerminalsHost } from '../types/terminals'
@@ -57,7 +57,19 @@ export interface DevframeHubContext extends DevframeNodeContext {
   createJsonRenderer: (spec: JsonRenderSpec) => JsonRenderer
 }
 
-export interface CreateHubContextOptions extends CreateHostContextOptions {}
+export interface CreateHubContextOptions extends CreateHostContextOptions {
+  /**
+   * Gate the hub's synthesized built-in dock entries (`~terminals`,
+   * `~messages`, `~settings`). Each entry defaults to present; set one to
+   * `false` to suppress it — e.g. when mounting `@devframes/plugin-terminals`
+   * or `@devframes/plugin-messages`, which replace the built-in tabs.
+   *
+   * Omitting this option keeps all three built-ins.
+   *
+   * @default { terminals: true, messages: true, settings: true }
+   */
+  builtinDocks?: BuiltinDocksOptions
+}
 
 /**
  * Create a hub-level node context: wraps devframe's `createHostContext`,
@@ -75,7 +87,7 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
   })
   const context = baseContext as DevframeHubContext
 
-  const docks = new DocksHostImpl(context)
+  const docks = new DocksHostImpl(context, options.builtinDocks)
   const terminals = new TerminalsHostImpl(context)
   const messages = new MessagesHostImpl(context)
   const commands = new CommandsHostImpl(context)

packages/hub/src/node/host-docks.ts

@@ -1,6 +1,7 @@
 import type { DevframeNodeContext } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type {
+  BuiltinDocksOptions,
   DevframeDockEntry,
   DevframeDocksHost as DevframeDocksHostType,
   DevframeDockUserEntry,
@@ -92,6 +93,12 @@ export class DevframeDocksHost implements DevframeDocksHostType {
 
   constructor(
     public readonly context: DevframeHubContext,
+    /**
+     * Per-entry toggles for the synthesized built-in dock entries. An omitted
+     * (or `undefined`) flag keeps that built-in; only an explicit `false`
+     * suppresses it.
+     */
+    private readonly builtinDocks: BuiltinDocksOptions = {},
   ) {
 
   }
@@ -111,8 +118,11 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     includeBuiltin?: boolean
   } = {}): DevframeDockEntry[] {
     const context = this.context
-    const builtinDocksEntries: DevframeViewBuiltin[] = [
-      {
+    // An omitted flag keeps the built-in; only an explicit `false` drops it.
+    const { terminals = true, messages = true, settings = true } = this.builtinDocks
+    const builtinDocksEntries: DevframeViewBuiltin[] = []
+    if (terminals) {
+      builtinDocksEntries.push({
         type: '~builtin',
         id: '~terminals',
         title: 'Terminals',
@@ -121,8 +131,10 @@ export class DevframeDocksHost implements DevframeDocksHostType {
         get when() {
           return context.terminals.sessions.size === 0 ? 'false' : undefined
         },
-      },
-      {
+      })
+    }
+    if (messages) {
+      builtinDocksEntries.push({
         type: '~builtin',
         id: '~messages',
         title: 'Messages & Notifications',
@@ -132,15 +144,17 @@ export class DevframeDocksHost implements DevframeDocksHostType {
           const size = context.messages.entries.size
           return size > 0 ? String(size) : undefined
         },
-      },
-      {
+      })
+    }
+    if (settings) {
+      builtinDocksEntries.push({
         type: '~builtin',
         id: '~settings',
         title: 'Settings',
         category: '~builtin',
         icon: 'ph:gear-duotone',
-      },
-    ]
+      })
+    }
 
     return [
       ...Array.from(this.views.values(), view => this.projectView(view)),

packages/hub/src/types/docks.ts

@@ -14,6 +14,32 @@ export interface DevframeDocksHost {
   values: (options?: { includeBuiltin?: boolean }) => DevframeDockEntry[]
 }
 
+/**
+ * Per-entry toggles for the hub's synthesized built-in dock entries.
+ *
+ * Each flag defaults to `true` (the entry is present). Set one to `false` to
+ * suppress that built-in everywhere it would otherwise appear — useful when a
+ * host mounts a plugin that supersedes the built-in tab (e.g.
+ * `@devframes/plugin-terminals` replacing the `~terminals` entry).
+ */
+export interface BuiltinDocksOptions {
+  /**
+   * Include the built-in `~terminals` dock entry.
+   * @default true
+   */
+  terminals?: boolean
+  /**
+   * Include the built-in `~messages` dock entry.
+   * @default true
+   */
+  messages?: boolean
+  /**
+   * Include the built-in `~settings` dock entry.
+   * @default true
+   */
+  settings?: boolean
+}
+
 // Known categories the hub orders by default. Kits may pass their own
 // category ids; `(string & {})` keeps autocomplete on the known set while
 // allowing arbitrary string values.

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -16,6 +16,7 @@ export declare const defineHubRpcFunction: <NAME extends string, TYPE extends _$
 // #endregion
 
 // #region Other
+export { BuiltinDocksOptions }
 export { ClientScriptEntry }
 export { ConnectionMeta }
 export { CreateHubContextOptions }

tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts

@@ -23,11 +23,13 @@ export declare class DevframeCommandsHost implements DevframeCommandsHost$1 {
 }
 export declare class DevframeDocksHost implements DevframeDocksHost$1 {
   readonly context: DevframeHubContext;
+  private readonly builtinDocks;
   readonly views: DevframeDocksHost$1['views'];
   readonly events: DevframeDocksHost$1['events'];
   userSettings: SharedState<DevframeDocksUserSettings>;
   private readonly remoteDocks;
-  constructor(_: DevframeHubContext);
+  constructor(_: DevframeHubContext,
+  _?: BuiltinDocksOptions);
   init(): Promise<void>;
   values({
     includeBuiltin

tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js

@@ -16,11 +16,12 @@ export class DevframeCommandsHost {
 }
 export class DevframeDocksHost {
   context
+  builtinDocks
   views
   events
   userSettings
   remoteDocks
-  constructor(_) {}
+  constructor(_, _) {}
   async init() {}
   values(_) {}
   projectView(_) {}

tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts

@@ -2,6 +2,7 @@
  * Generated by tsnapi — public API snapshot of `@devframes/hub/types`
  */
 // #region Other
+export { BuiltinDocksOptions }
 export { ClientScriptEntry }
 export { ConnectionMeta }
 export { CreateHubContextOptions }