FlowPad

Appearance

FlowPad ​

What this is and why it exists ​

Matrix is docker-for-actors / npm-for-actors — a typed pub/sub/RPC substrate where every Feed, Service, and Component is an actor on a federated bus. FlowPad is one vertical built on top of that substrate. It is the closest thing the substrate has to a hands-on REPL: an in-browser workspace where a developer can compose a pipeline in Flow DSL or LISP/Scheme, dispatch it through the bus, and watch results, transport messages, and execution status update against live mounts.

Concretely, FlowPad ships as the @open-matrix/flowpad Package. The browser app — the <flowpad-app> custom element — lets the user wire Components together with flow().fromValue(...).viaRemote("./db", "Query")... style call chains, and execute them against actors mounted under the same authority root. The page is pure browser; FlowPad has no headless component.

Motivation ​

FlowPad exists because individual actors only become useful work once you can compose them — feed into transform into component into output, run live, and watch each step return real data. It gives developers and integrators a hands-on workspace for that composition: write a pipeline in Flow DSL or LISP, run it against the actors already mounted on your Host, and read the results, transport messages, and execution status without leaving the page. There is no scaffolding, no separate test harness, and no mock data; what you wire is what you run. Read these docs if you author actors and want to exercise their contracts interactively, or if you build data flows on top of mounts that other packages already provide.

Where this fits ​

  • Vertical, not substrate. Substrate concepts (actor, mount, bus, contract, registry) are documented in the substrate-side packages (docs-matrix, docs-sdk, docs-runtime-host). FlowPad sits on the substrate as a developer/integrator workspace.
  • Tier 1, browser surface. FlowPad runs in the user's browser and connects over WebSocket to the local Host's bus. There is no FlowPad daemon and no FlowPad backend Service; it composes whatever actors the bus already has.
  • Wedge: Compositional UI. This is the Compositional UI vertical from the thesis (Vertical C in THESIS.md Part 5). FlowPad is the developer-facing form of "find me a component, wire it up, run it"; Chat is the user-facing form.

Five-minute quickstart ​

bash
# Build FlowPad (and the Host wrapper if you don't already have it)
pnpm --filter @open-matrix/flowpad build
pnpm --filter hivecast build

# Install + start a Host
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs start --home /tmp/matrix-home

# Open the editor
#   http://127.0.0.1:3100/apps/flowpad/

# Verify the FlowPad mount and its eleven service children from the bus
matrix invoke flowpad-page $introspect '{}'
matrix invoke flowpad-page.scheme $introspect '{}'

Inside the editor, the example list (Basic Query, Filter & Map, Query Tree, Scheme Eval, Security Policy) shows pipelines you can run unchanged. They address children with relative mounts (./db, ./scheme, ./vlm-eval); the DSL resolves those against the calling page's mount root, so the same example works regardless of the mount FlowPad is deployed under.

Conceptual map ​

  • Overview — what FlowPad is, where it sits in the substrate's actor model, what the package owns vs imports.
  • User Guide — running flows, reading results, sidebar tour, settings.
  • Developer Guide — source layout, custom-element registration, the IR pipeline that compiles Flow DSL and LISP into the same Canonical Internal Representation.
  • Operations — installing the package into a Host, runtime startup, logs, troubleshooting.
  • Reference — manifest, component API, actor ops, configuration.

Cross-references ​

Note on terminology. The original draft TOC used boards/cards/links terminology. That terminology does not appear in code. The actual surfaces are Pipeline Editor, Results Panel, Transport Log, Execution Status, and the Sidebar (Actor Tree, Package Browser, Example List). The documentation tree has been realigned to match.

Source conventions: PORTABILITY-RULES.md.