6.hub-api.md

title	Hub API
navigation	icon i-lucide-layout-dashboard
description	Lookup tables for the hub: subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the client runtime, the client context, and dock entry types.

Lookup tables for @devframes/hub: its node-side subsystems and its browser-side client runtime. Each section links the guide page that teaches the concept.

Hub subsystems

What DevframeHubContext adds to DevframeNodeContext: Hub.

Subsystem	API	Purpose
ctx.docks	register / update / values / activate	Dock entries (iframes, launchers, custom-render) and groups; activate(dockId, params?) sets the active dock (Cross-iframe dock activation).
ctx.terminals	register / startChildProcess / startPtySession	Aggregate terminal sessions, streaming output (Terminals).
ctx.messages	add / update / remove / clear	Server-side toast/notification queue (FIFO, capped at 1000).
ctx.commands	register / execute / list	Hierarchical command palette with keybindings and when clauses.

Launcher fields

The optional launcher fields that make a type: 'launcher' dock entry a live process controller: Process-control launchers.

Field	Purpose
command	Bound command id; out-of-process hub UI providers dispatch via hub:commands:execute (register a handler via ctx.commands).
terminalSessionId	Tracked session id; a "view in terminal" action calls hub:docks:activate with the terminals dock id and { sessionId }.
digest	Latest progress line, shown inline; patch via docks.update().

Duplication strategies

The duplicationStrategy values deciding what happens when a devframe shares an already-mounted id: Duplicate devframes.

Strategy	Behavior
'warn' (default)	Keep the first, drop the later, emit DF8105.
'silent'	Drop the later one without warning.
'throw'	Throw DF8105.
'duplicate'	Every instance coexists under a disambiguated dock id (my-tool, my-tool-2, …).

Dock categories

DEFAULT_CATEGORIES_ORDER (from @devframes/hub, /node, /client, /constants) names the default dock-rail buckets: The dual role of category.

Category	Weight	Typical use
framework	-100	Framework internals.
default	0	Uncategorized.
app	100	App tools.
ui	150	Components, styling.
data	250	State, storage, queries.
web	300	Network, platform, a11y.
performance	350	Profiling, metrics.
advanced	400	Power-user tools.
docs	500	Documentation.
~builtin	1000	Built-in views; always last.

Hub UI protocol

The shared-state keys and RPC methods a hub UI provider renders from: The hub UI protocol.

Channel	Type	What it carries
devframe:docks shared state	DevframeDockEntry[]	Every registered dock entry.
devframe:commands shared state	DevframeServerCommandEntry[]	Serializable command list (handlers stripped).
devframe:user-settings shared state	DevframeDocksUserSettings	Persisted project-scope hub settings.
devframe:docks:active shared state	DevframeDocksActiveState	Most recent dock activation request.
hub:commands:execute RPC	(id, ...args) => unknown	Server-side command dispatch.
hub:docks:activate RPC	({ dockId, params? }) => void	Switch the active dock.

Hub namespace routes

What initHub() serves under its base: The namespace.

Path	Serves
/	the ui.viewer SPA, or index document when headless
<id>/	each devframe's SPA + own __connection.json → shared socket
embedded.js	the ui.embedded bootstrap (404 if none)
__connection.json	meta for the shared RPC socket
__ws	WebSocket upgrade route
__index.json	machine-readable index: mounted devframes, endpoints
__client-imports.js	dock client-script import map for hub UI providers
__mcp	aggregate MCP endpoint over the tool registry (mcp: 'auto' default: mounted once agent tools exist)

buildHub options

The options of buildHub() from @devframes/hub/build: Static builds. devframes, services, rpcDeclarations, configure, ui, renderers, name, version, cwd, and getStorageDir carry the same contracts as their initHub counterparts.

Option	Purpose
outDir	Output directory for the hub subtree; corresponds to base at serve time (build base: '/__devframes/' into dist/__devframes). A mount served outside the hub base (a devframe SPA or asset dir kept as a sibling of it) is written to this directory's parent (the deploy root) by its absolute path.
base	Mount base baked into every absolute URL the build emits. Default /__devframes/.
context	An already-mounted DevframeHubContext to bake instead of devframes (the build counterpart of initHub({ context })); reads ctx.frames and ctx.views.buildStaticDirs. Mutually exclusive with devframes.
clean	Remove outDir before writing. Default true; set false to bake beside an app's own build output.
pretty	Pretty-print RPC dump JSON shards. Default false (minified).

Client runtime options

The options of createDevframeClientRuntime(): The client runtime.

Option	Description
rpc	An already-connected DevframeRpcClient; when omitted, created via connectDevframe(connect).
connect	Forwarded to connectDevframe when rpc is omitted (e.g. baseURL).
clientType	'standalone' (default) owns the page; 'embedded' runs inside a user app alongside a panel.
loadClientScripts	Import and run dock client scripts (default true).
renderers	Dock renderers registered at boot, keyed by dock type; local wins over the hub's renderer manifest.

Client context properties

The properties of DevframeClientContext: The client context.

Property	Description
rpc	The RPC client: server/client functions, shared state.
clientType	'embedded' (inside the user app) or 'standalone' (independent hub page).
docks	entries, selected, groupedEntries, switchEntry(), toggleEntry(), getStateById(), register() / update() for client-only docks.
panel	Current state, local events, session, position, size, and drag/resize state for the dock panel.
commands	Command palette: register(), execute(), getKeybindings(), paletteOpen, paletteScopeId, openPalette(atCommandId?). Passing an id opens the palette drilled into that command's children (Activating a group).
renderers	Dock-renderer registry: register(), get(), has(), mount(entry, container). Routes a dock type to a renderer (local boot or the hub's manifest; local wins). mount() resolves a status: mounted (with dispose), missing-renderer, or load-error (with error).
when	The when-clause context.
connection	Live connection status: status, error, events.

Dock client script fields

Which ClientScriptEntry field carries an entry's client script, and when it runs: Dock client scripts.

Entry kind	Field	Runs
action	action	when the dock button is activated
custom-render	renderer	to render the entry's panel
iframe	clientScript (optional)	alongside the iframe panel, inside the host page

Frame-nav messages

The origin-locked postMessage protocol on devframe:frame-nav: Shared-iframe soft navigation.

Message	Direction	Meaning
ready / manifest	iframe → host page	tab list ({ tabs, current }), on load and change
navigate	host page → iframe	show a view ({ tabId, navTarget }); the SPA routes client-side
navigated	iframe → host page	the SPA navigated internally; the hub UI provider highlights the dock

Dock entry types

The built-in variants of the open dock union (DevframeDockEntryRegistry, @devframes/hub/types) a hub UI provider renders: Build Your Own Hub UI.

Type	The hub UI provider renders
iframe	the entry's url in a kept-alive iframe (per frameId when shared); honor subTabs soft nav; show the existing address bar with addressBar: true, or configure Back, Reload, and Open externally by passing an addressBar object
action	a dock-rail button; activating runs its client script
custom-render	a container its client script mounts into
launcher	a launch call-to-action reflecting launcher.status
group	one dock-rail button collapsing its member entries
~builtin	your native views (settings, feeds) for reserved ids