Hub API
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 |