Sidebar (actors, packages, examples)

The FlowPad sidebar is a nested-split panel on the left of the workspace. It is rendered by FlowpadSidebar (projects/matrix-3/packages/flowpad/src/components/sidebar/FlowpadSidebar.ts), which composes three child components:

<flowpad-sidebar>
  ├── <flowpad-package-browser id="packageBrowser">  ← installed packages
  └── <mx-split>
        ├── <flowpad-actor-tree id="actorTree">      ← live actor mounts
        └── <flowpad-example-list id="exampleList">  ← examples for selected actor

The whole sidebar has a header (title + collapse toggle) and a single shared filter input. Filtering the input sends setFilter to the package browser; the input value is also re-emitted as filterChanged for any other listener.

Package browser

FlowpadPackageBrowser (FlowpadPackageBrowser.ts) shows installed .matrix packages, each with its component mounts listed underneath. The data comes from FlowPad's package catalog (set via setCatalog from the surrounding shell). Two events come out:

Event	Payload	Meaning
`packageSelected`	`{ packageName, mounts, types }`	The user clicked a package row
`actorSelected`	`{ mount }`	The user clicked a single actor under a package

When you click a package row, the sidebar itself republishes packageSelected to the parent FlowpadAppShell, which can then update the example list to show example flows for that package's components.

Actor tree

FlowpadActorTree (FlowpadActorTree.ts) renders a hierarchical tree of discovered actors organised by root. Each row carries:

a toggle (▶ / ▼ / ⏳ for loading) to expand/collapse children;
a display label;
a coloured "type dot" — blue for daemons, green for services (Eval, Runner, Coordinator, Atomizer, Router, Bootstrap, Domain, Projection, LLM, Mock), purple for UI components, grey for unknown.

The tree's accepts (FlowpadActorTree.ts:21-27):

static accepts = {
  setTree: { roots: 'any', status: 'string?' },
  setSelectedNode: { mount: 'string?' },
  setStatus: { status: 'string' },
};

A Refresh button in the tree's toolbar emits refreshRequested on the bus. The owning shell catches that and re-discovers the actor topology.

Selecting a node emits nodeSelected with { mount, componentClass }. The sidebar republishes that as its own nodeSelected; the shell uses it to:

Set the editor's targetMount — so $TARGET resolves to the just-selected mount.
Repopulate the example list with examples that target this component's class.

Toggling a node emits nodeToggled so the tree's expansion state can be persisted by the shell.

Example list

FlowpadExampleList (FlowpadExampleList.ts) is a flat list of selectable example tiles. Its accepts:

static accepts = {
  setExamples: { examples: 'any', actorMount: 'string?', actorClass: 'string?' },
  setSelectedExample: { key: 'string?' },
  clear: {},
};

Each example carries enough context to be re-run — endpoint mount, op name, payload, label, and optionally the raw source code. Clicking emits exampleSelected:

{
  endpointMount: string,
  exampleIndex: number,
  operation: string,
  payload: any,
  label: string,
  rawCode?: string,
}

The shell forwards rawCode to the editor (setCode) so the user lands on the example's source. If rawCode is missing, the shell synthesises a one-stage flow: flow().fromValue(payload).viaRemote(endpointMount, operation).

Filter and collapse

The shared filter input is wired in FlowpadSidebar.onBootstrap (FlowpadSidebar.ts:150-163):

filterInput?.addEventListener('input', () => {
  const filter = filterInput.value;
  this.sendToChild('packages', 'setFilter', { filter });
  this.emit('filterChanged', { filter });
});

So the filter only narrows the package browser; the actor tree and example list show whatever the shell pushed into them. The collapse button toggles between the full sidebar layout and a slim "open" button on the workspace.

Sidebar event flow (summary)

mermaid

sequenceDiagram
    participant User
    participant Sidebar as FlowpadSidebar
    participant Tree as FlowpadActorTree
    participant Examples as FlowpadExampleList
    participant Shell as FlowpadAppShell

    User->>Tree: click an actor
    Tree-->>Sidebar: nodeSelected { mount, class }
    Sidebar-->>Shell: nodeSelected
    Shell->>Sidebar: setExamples { examples, actorMount, actorClass }
    Sidebar->>Examples: setExamples
    User->>Examples: click an example
    Examples-->>Sidebar: exampleSelected
    Sidebar-->>Shell: exampleSelected
    Shell->>PipelineEditor: setCode { code: rawCode or synthesised flow }

Sidebar (actors, packages, examples) ​

Package browser ​

Actor tree ​

Example list ​

Filter and collapse ​

Sidebar event flow (summary) ​