Contributing
A repository map and a reading path for each kind of change.
Start here when changing Soundor itself. To build a plugin with published packages, use Getting started.
Read Setup, then Workflow and Conventions. Subsystem guides describe their purpose, source, operation, invariants and tests, and how to change them.
Repository map
flowchart TD
project["Plugin project"] --> toolchain["packages/: config, CLI, codegen"]
toolchain --> contract["Generated contract and UI bundle"]
contract --> juce["runtimes/juce-runtime: native host"]
contract --> web["runtimes/web-runtime: browser host"]
juce --> engine["runtimes/engine: C++ engine"]
react["packages/react: UI renderer"] --> contract
tests["packages/: simulated runtime and testing tools"] --> react
examples["examples/: plugins and snippets"] --> site["apps/website: docs and playground"]The package map gives dependency direction and
ownership. configs/ contains private TypeScript and bundler presets;
tools/benchmark/ measures the native runtime; .github/ owns CI and releases.
Where to start a change
| Change | Read first | Main source |
|---|---|---|
| A config option or generated type | Pipeline, ownership | packages/config/src/, packages/core/src/ |
| A CLI command or dev session | Pipeline, Runtime SDK | packages/cli/src/ |
| A new runtime | Build a runtime | packages/config/src/runtime.ts, packages/runtime-sdk/src/ |
| A shared UI or service behavior | Cross-runtime contract | Engine, web runtime, test runtime and React |
| Native layout, painting or JavaScript | Engine reference | runtimes/engine/include/, runtimes/engine/src/ |
| Native host integration | Embedding API | runtimes/juce-runtime/native/backend/juce/ |
| Accessibility | Contract, Apple bridges | Engine src/a11y/, web client ui/semantics.ts |
| React or application tests | React tests, test runtime | packages/react/, packages/react/testing/, packages/test-runtime/ |
| DevTools | Protocol, server, client | packages/devtools-*/ |
| Performance | Benchmarks | tools/benchmark/ |
| Docs, snippets or playground | Conventions | apps/website/, examples/snippets/ |
Follow a behavior across implementations
For a parameter change, start with config validation and generated declarations,
then trace its host representation and subscriptions through both runtimes. For
a React prop, start with its type and reconciler mapping, then follow the
soundor:ui node into native, browser and simulated implementations.
Choose tests for the boundary being changed. A simulated React test proves observable interactions; native tests prove engine behavior; browser tests prove DOM, layout and page integration. Workflow lists checks and generated files.