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)	inside the host page on first activation

ClientScriptEntry.eager defaults to false. Set it to true on an iframe clientScript or an action to initialize it after RPC trust, before dock activation. A custom-render renderer needs its mounted panel, so it always initializes on activation regardless of eager. Setup is cached per RPC connection and dock; action clicks execute on every activation.

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. Each entry's icon takes any of the icon values.

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