The editor uses Next.js 16, React 19, React Flow, Tailwind CSS 4, Lucide icons, and the repository's shadcn-style primitives. app owns routing and page composition, components owns UI, data owns registry and project definitions, utils owns verification, simulation, and package behavior, and tests owns Node contract tests and Playwright workflows.
The root route is a local project home. Project routes use /projects/{projectId}. Durable project records, binary assets, and global editor preferences live in the versioned baudbound-editor IndexedDB database behind data/storage repositories. Do not add normal localStorage or sessionStorage persistence. The only localStorage access is the one-time panel-preference migration, which deletes legacy values after its IndexedDB transaction commits.
Project identity is immutable and separate from editable settings. Exports reuse the stored UUID and creation timestamp so the runner can recognize later packages as revisions of the same script. Import conflicts must offer open, replace, or independent-copy behavior explicitly.
Project routes coordinate one writable tab through BroadcastChannel. Takeover is denied while the owner is dirty, stale owners expire after missed heartbeats, and IndexedDB revision checks remain the final protection against stale writes. Save transactions must preserve the previous committed revision on failure and keep the current document available for package-export recovery.
Node definitions under data/nodes/definitions own display metadata, category, configuration fields, outputs, risk, capabilities, and supportedTargetRuntimes. The registry assembles definitions for palette, inspector, verification, help, schema generation, and package export.
Do not create a second platform-compatibility list. Absence of supportedTargetRuntimes means all targets. Restrictions must be explicit on the definition. Contract tests ensure the runner recognizes the same executable node types and capabilities.
Use existing shadcn-style UI primitives, Lucide icons, and established inspector field components. Keep operational screens compact and responsive, avoid nested cards and horizontal page scrolling, and verify behavior at desktop and narrow window sizes.
The help modal intentionally provides concise registry-derived reference material. The public wiki contains long-form documentation and is linked from the modal navigation.
After definition changes, regenerate node schemas, inspect the diff, run unit/type/lint/build checks, and exercise package export plus runner validation.
data/nodes/definitions/{triggers,control,actions}.actionType, label, description, group, defaults, config fields, execution ports, runtime outputs, risk, permission/capability derivation, fallibility, and target restrictions.data/nodes/registry.ts. Do not duplicate its fields in another catalog.program.schema.json references.Run:
pnpm schemas:generate
pnpm schemas:check
pnpm test
The export path takes current project state, sanitizes node config, verifies graph and target rules, derives declared access, separates executable program.json from editor.json, writes manifest assets and secret declarations, and creates the ZIP archive. The runner later repeats security and semantic checks independently.
Asset IDs and package paths must remain stable and normalized. Secret values never enter package state. Comments, positions, dimensions, and edge style remain editor metadata and cannot affect runner execution. Edge execution_order is executable program data. It must remain unique and consecutive for every source node and source handle.
Package compatibility is cross-language. Prefer additive changes with explicit defaults. Breaking changes require a format or language version decision before implementation.
For a node-contract change:
The runner must validate packages offline from committed or compiled contracts. Do not introduce runtime schema downloads.
Change package format version when old runners cannot safely parse the archive/document contract. Change script language version when the same valid graph would execute with incompatible semantics. An additive optional field with a safe default may require neither, but the decision must be explicit and tested against older fixtures.
The release gate is pnpm verify:release from the editor repository root.