Package manifest (matrix.json)

projects/matrix-3/packages/flowpad/matrix.json is the package's authoritative manifest. It describes how Host Service and the gateway integrate FlowPad. The full file as of this writing:

json

{
  "name": "@open-matrix/flowpad",
  "version": "0.2.6",
  "description": "FlowPad — Matrix interactive data flow visualization",
  "runtime": {
    "language": "typescript",
    "entry": "dist/index.html"
  },
  "webapp": {
    "distDir": "dist",
    "entry": "index.html",
    "appName": "flowpad",
    "displayName": "FlowPad",
    "icon": "📋",
    "navOrder": 40,
    "description": "Interactive actor data-flow workspace",
    "shells": ["platform", "edge"]
  },
  "components": [],
  "permissions": {
    "fsPolicy": "none"
  }
}

Field reference

`name`

Type: string. The fully-qualified package name. Must match package.json name.

`version`

Type: semver string. Must match package.json version. The host's package store keys on <name>/<version>, so an inconsistent value here lands the package at the wrong path.

`description`

Type: string. Free-form one-liner. Surfaced by system.catalog and the package browser.

`runtime`

Sub-field	Value	Meaning
`runtime.language`	`"typescript"`	The runtime kind. The runner uses this to select a loader.
`runtime.entry`	`"dist/index.html"`	What the runner serves when started. For a webapp this is the HTML entry point.

`webapp`

This whole block tells the gateway how to mount the package as a browser-served app.

Sub-field	Value	Meaning
`webapp.distDir`	`"dist"`	Directory served as the static root.
`webapp.entry`	`"index.html"`	File served at `/apps/<appName>/`.
`webapp.appName`	`"flowpad"`	URL path component. The page is reachable at `/apps/flowpad/`.
`webapp.displayName`	`"FlowPad"`	Human label. Used by the platform/edge shells to label nav entries.
`webapp.icon`	`"📋"`	Emoji or short string shown in nav.
`webapp.navOrder`	`40`	Sort order in the nav. Lower numbers come first. (Director is 30, FlowPad 40, Smithers 50, Inference Settings 60.)
`webapp.description`	`"Interactive actor data-flow workspace"`	Tooltip / link card text.
`webapp.shells`	`["platform", "edge"]`	Which top-level shells render this app. Both are accepted.

`components`

Type: array. Value: [].

This is what makes FlowPad a pure browser package. There are no headless actors that auto-mount when the runtime starts. Compare with Smithers, which lists SmithersSupervisor (autoStart) plus three child types here.

`permissions`

Sub-field	Value	Meaning
`permissions.fsPolicy`	`"none"`	The runner is not allowed to touch the filesystem.

There are no network, subprocess, or env flags — the runtime has no need for them because FlowPad only runs in the browser.

Relationship with `package.json`

package.json and matrix.json carry overlapping fields by design — the workspace uses package.json for build/dev commands, and the runtime uses matrix.json for product behaviour.

Field	`package.json`	`matrix.json`
`name`	`@open-matrix/flowpad`	`@open-matrix/flowpad` (must match)
`version`	`0.2.6`	`0.2.6` (must match)
`files`	`["dist", "dist-path.js", "matrix.json", "README.md", "LICENSE"]`	n/a
`scripts`	`build`, `test`, `dev`, `preview`, `type-check`	n/a
`devDependencies`	`@open-matrix/core`, `tsx`, `vite`	n/a
build target	n/a	`runtime.entry`, `webapp.distDir/entry`

Conformance

The pre-merge gate (scripts/ci/premerge-local.sh) checks that:

matrix.json parses and has name, version, webapp (for browser packages).
webapp.entry exists in webapp.distDir/.
webapp.appName matches the URL path used by other packages that link here.

A change to any of these fields requires a coordinated change to the gateway's static-route registration and any sibling package that hard-codes the URL.

Adding a headless component (hypothetical)

If you wanted to add a server-side actor — e.g., a flow runner that survived between page loads — you would add an entry like:

json

"components": [
  {
    "type": "FlowpadServerRunner",
    "export": "FlowpadServerRunner",
    "mount": "flowpad",
    "autoStart": true,
    "surface": "headless",
    "accepts": ["RunFlow", "$introspect"],
    "emits": ["flowpad.started", "flowpad.completed"]
  }
]

…and ship the matching class in dist/index.js. Today the package does not do this — FlowPad's flow runner lives only in the browser as a child of FlowpadApp.

Package manifest (matrix.json) ​

Field reference ​

name ​

version ​

description ​

runtime ​

webapp ​

components ​

permissions ​

Relationship with package.json ​

Conformance ​

Adding a headless component (hypothetical) ​

See also ​