FlowPad package boundaries

@open-matrix/flowpad is intentionally narrow. It owns the editor, the run loop, the panes, and a small set of in-page services. Everything else is a workspace dependency or a runtime mount it talks to over the bus.

What lives inside the package

projects/matrix-3/packages/flowpad/src/ (entire tree):

src/
├── FlowpadApp.ts                 # The MatrixActor; orchestrates examples + run loop
├── index.ts                      # Re-exports + customElements.define for every shell
├── index.html                    # The mount point
├── components/                   # Pane components (each is actor + shell pair)
│   ├── PipelineEditor.ts         # Editor with auto Flow/LISP detection
│   ├── ResultsPanel.ts           # Results manager — adds children per result
│   ├── ExecutionStatus.ts        # Status bar + topology summary
│   ├── TransportLog.ts           # Log of bus messages observed in the page
│   ├── FlowpadControl.ts         # Header strip / labelled frame
│   ├── addressing.ts             # resolveMountAddress() helper
│   └── sidebar/                  # FlowpadSidebar + ActorTree + PackageBrowser + ExampleList
├── shell/                        # FlowpadAppShell + projectCatalog + transport-indicator
├── dsl/                          # parseFlowDSL + DSL_EXAMPLES + query-catalog + validateExamples
├── runtime/                      # queryPipeline.ts — IR + executeCanonicalIR
├── services/                     # In-page service actors (MockDb, FlowRunner, SecurityRealm, TopicClaim)
├── projects/                     # Six bundled "projects" (database, federation, lisp, security, serialization, vlm)
├── template/                     # flowpad.template.ts — the page HTML
├── styles/                       # flowpad.styles.ts
├── config/defaults.ts            # FLOWPAD_DEFAULTS
└── vlm/                          # VLM visualization shell

That is the boundary: anything not in this tree is somebody else's package.

What FlowPad imports from elsewhere

package.json declares a single workspace devDependency (projects/matrix-3/packages/flowpad/package.json:42-46):

json

"devDependencies": {
  "@open-matrix/core": "workspace:*",
  "tsx": "^4.15.6",
  "vite": "^6.0.0"
}

Inside src/, FlowPad imports from @open-matrix/core/... deeply. The cross-package imports are limited to:

@open-matrix/core/core/MatrixActor — base class for all actors.
@open-matrix/core/framework/MatrixActorHtmlElement — base for the shells.
@open-matrix/core/framework/components/index — MxSplit, MxDock, MxTheme.
@open-matrix/core/flow/FlowBuilder — fluent builder used by runFlow.
@open-matrix/core/flow/viewers — DataViewer, TableViewer, TreeViewer, ErrorViewer (the result viewers ResultsPanel mounts as children).
@open-matrix/core/engine/remoting/RequestReply — used by _executeRemoteCall.
@open-matrix/core/engine/core/IMatrixContext — context type.
@open-matrix/core/serialization — five-representation parity (HTML / Fluent / JSON / S-expr / Topics).
@open-matrix/core/lisp — the canonical LISP/Scheme/VLM evaluators (LispEval, SchemeEval, BootstrapNode, parseSExpr, etc.).
@open-matrix/core/browser/HostedRuntimeRecovery and HostedRuntimeTarget — the page reads its target authority root from the host element.

Note: Rule 9 of CLAUDE.md forbids cross-package ../../ imports. FlowPad obeys this — every cross-package reference is an @open-matrix/core/... subpath that goes through the package's declared exports.

What FlowPad does NOT own

These are common confusions. They are not part of @open-matrix/flowpad:

Director, Smithers, Chat, Inference Settings, Matrix Web, Matrix Edge. These are sibling packages. FlowPad neither launches them nor loads code from them.
Host-service supervision. FlowPad has no daemon. The retired daemon path is forbidden product surface; FlowPad's lifecycle is the browser's.
Auth. FlowPad does not perform login; it accepts an authority root passed in by the page bootstrap and uses whatever credentials the surrounding shell already established.
Bundled NATS. The transport is provided by the surrounding page (browser WebSocket to the Host's /nats-ws for federated mode, or InMemory for standalone test pages). See transport-indicator.ts.
The 1270-line dsl/examples.ts body is bundled, but the runtime "projects" (src/projects/database/, lisp/, security/, serialization/, vlm/, federation/) are loaded at runtime by shell/projectCatalog.ts from dist/projects/<id>/manifest.json. That means the catalog can be replaced by an external package or a user-supplied root URL without rebuilding FlowPad.

Project catalog and external roots

projectCatalog.ts (projects/matrix-3/packages/flowpad/src/shell/projectCatalog.ts:115-166) accepts multiple ProjectCatalogRootConfig entries. The default is the bundled root:

const DEFAULT_PROJECT_ROOT: ProjectCatalogRootConfig = {
  id: 'flowpad-projects',
  label: 'FlowPad Projects',
  baseUrl: new URL('./projects/', FLOWPAD_BASE_URL_STR).toString(),
  projectIds: ['database', 'federation', 'lisp', 'security', 'serialization', 'vlm'],
  source: 'bundled',
};

Additional roots — matrix (the package authority's system.catalog) or user (a user-supplied URL serving the same manifest contract) — can be passed to loadProjectCatalog to surface their packages and examples in the FlowPad sidebar without code changes.

Versioning and shipping

@open-matrix/flowpad ships its compiled browser bundle in dist/ plus dist-path.js (an export entry that other packages can use to find the on-disk path of FlowPad's assets). The webapp block in matrix.json tells the gateway how to mount it: appName=flowpad, served as /apps/flowpad/, with displayName=FlowPad and navOrder=40.

FlowPad package boundaries ​

What lives inside the package ​

What FlowPad imports from elsewhere ​

What FlowPad does NOT own ​

Project catalog and external roots ​

Versioning and shipping ​