FlowPad components and shells

This page enumerates every Matrix component shipped in @open-matrix/flowpad. Each entry lists the tag name (the custom-element registration), the actor class, the shell class, and the bus contract.

Pattern B reminder

Every component is a pair:

Shell (extends MatrixActorHtmlElement) ── owns DOM
   wraps
Actor (extends MatrixActor)            ── owns logic/state

Communication between them is bus-only (CQRS). The shell never calls actor methods directly.

Top-level

<flowpad-app>

Field	Value
Actor	FlowpadApp (src/FlowpadApp.ts)
Shell	FlowpadAppShell (src/shell/FlowpadAppShell.ts)
Mount	The page mount (e.g., flowpad-page)
Children	db, flow-runner, security-realm, topic-claims, lisp, scheme, bootstrap, vlm-router, vlm-join, vlm-atomizer, vlm-eval, vlm-node-0..4

Accepts: runFlow, runFromCode, selectExample, setTargetMount, loadExample, clearResults, snapshot.tree.oracle. Emits: flowStarted, executionPlanned, flowCompleted, flowError, exampleLoaded.

<flowpad-control>

Field	Value
Actor	FlowpadControl (components/FlowpadControl.ts)
Shell	FlowpadControlShell
Description	Header bar showing the current label and mount address. Each pane that wants its own labelled frame wraps itself in <flowpad-control>.

Accepts: setLabel { label }, ping. Emits: labelChanged { label }, pong { mount }.

Workspace components

<pipeline-editor>

Field	Value
Actor	PipelineEditor (components/PipelineEditor.ts)
Shell	PipelineEditorShell

Accepts: setCode { code }, getCode, clear, focus, setMode { mode }, requestRun { code, mode? }. Emits: codeChanged { code }, runRequested { code, mode }, modeChanged { mode }, focusRequested.

The shell auto-detects mode (Flow vs LISP) on every input and pushes that back to the actor. Ctrl+Enter triggers requestRun. The shell holds a single <textarea id="codeArea"> in shadow DOM and tracks DOM-wired state with _domWired (Pattern A's anti-pattern of double-wiring is deliberately prevented).

<results-panel>

Field	Value
Actor	ResultsPanel (components/ResultsPanel.ts)
Shell	ResultsPanelShell

Accepts: addResult { data, type?, label?, query? }, removeResult { id }, clearResults. Emits: resultAdded { id, mount, type, label? }, resultRemoved { id }, resultsCleared { count }.

Each result becomes a real Matrix child at ./results.result-N. The class of each child depends on the result shape (DataResultActor, TableResultActor, ErrorResultActor, or TreeViewer-class).

<execution-status>

Field	Value
Actor	ExecutionStatus (components/ExecutionStatus.ts)
Shell	ExecutionStatusShell

Accepts: setStatus { state, message? }. Emits: statusChanged { state, message }.

The shell reads the data-runtime-root, data-authority-root, data-platform-root, data-target-source, data-target-kind, data-requested-root, data-target-unavailable-reason attributes from the host element. When any of those change, it emits HOSTED_RUNTIME_TARGET_CHANGED_EVENT and re-renders the topology tag.

<transport-log>

Field	Value
Actor	TransportLog (components/TransportLog.ts)
Shell	TransportLogShell

Accepts: addEntry { timestamp, direction, topic, payload }, clear. Emits: entryClicked { index }, entryAdded { entry, removedFirst }, cleared.

The actor caps its log at a fixed length and removes the oldest entry when the cap is reached (removedFirst: true lets the shell DOM-update without a full re-render). The shell colour-codes entries by direction.

Sidebar components

<flowpad-sidebar>

Field	Value
Actor	FlowpadSidebar (components/sidebar/FlowpadSidebar.ts) — extends MatrixActorHtmlElement (sidebar uses the no-actor variant)
Children	packages (<flowpad-package-browser>), actors (<flowpad-actor-tree>), examples (<flowpad-example-list>)

Accepts: setCatalog, setTree, setSelectedNode, setExamples, clearExamples, setStatus. Emits: filterChanged, collapseToggled, refreshRequested, nodeSelected, nodeToggled, exampleSelected, packageActorSelected, packageSelected.

The sidebar acts as a bridge: it re-emits its children's events (onNodeSelectedFromActors → emit('nodeSelected')) and forwards parent-bound commands to the right child.

<flowpad-actor-tree>

Accepts: setTree { roots, status? }, setSelectedNode { mount? }, setStatus { status }. Emits: nodeSelected { mount, componentClass }, refreshRequested, nodeToggled { mount, expanded }.

Type-dot colour rule (FlowpadActorTree.ts:335-346):

Component class includes	Dot
daemon	blue
service, eval, runner, coordinator, atomizer, router, bootstrap, domain, projection, llm, mock	green
control, editor, panel, viewer, shell, app, element	purple
Anything else	grey

<flowpad-package-browser>

Accepts: setCatalog { packages, entries, loading?, error? }, setFilter { filter }. Emits: packageSelected { packageName, mounts, types }, actorSelected { mount }.

<flowpad-example-list>

Accepts: setExamples { examples, actorMount?, actorClass? }, setSelectedExample { key? }, clear. Emits: exampleSelected { endpointMount, exampleIndex, operation, payload, label, rawCode? }.

Layout primitives (re-exported from @open-matrix/core)

The package re-registers three layout primitives so they're available without importing core directly:

• <mx-split> — the resizable two-pane container used everywhere (MxSplitShell from @open-matrix/core/framework/components).
• <mx-dock> — tabbed dock used at the bottom of the workspace.
• <mx-theme> — design-token sink that listens for $tokens ops and applies them as CSS custom properties.

Result viewers (re-registered from @open-matrix/core/flow/viewers)

Registered for clarity at the bottom of index.ts:

• <data-viewer> — DataViewerShell
• <tree-viewer> — TreeViewerShell
• <table-viewer> — TableViewerShell
• <error-viewer> — ErrorViewerShell

These are the same viewers ResultsPanel mounts as result children.

VLM visualisation

• <vlm-visualization> — VLMVisualizationShell from src/vlm/VLMVisualization.ts. Renders distributed LISP execution across the bootstrap nodes.

See also

• Pipeline editor
• Actor integration and IR pipeline
• Component API

Source: projects/matrix-3/packages/flowpad/src/index.ts:36-101 is the authoritative custom-element registration list.