# modulation module

## Related source files

This directory contains guidance; implementations remain in the parent `Source/`
directory:

- `../ModulationMatrix.h`, `../ModulationMatrix.cpp`
- `../MacroControls.h`, `../MacroControls.cpp`
- `../RAVEButton.h`, `../RAVEButton.cpp`, which define `RaveController`

## Rules

- Use `bool` return codes for bounded inserts (`addConnection`, `addAssignment`).
- Require a cap on connection and assignment counts (`kMaxConnections`, `kMaxAssignments`).
- Serialise and restore state through `juce::ValueTree` so presets survive save and load.
- Never accept a `ModTarget::None` connection; reject it and return false.
- Use `ids::` for every APVTS parameter reference in RaveController.
- Keep the existing RAVEButton filenames unless a rename is explicitly in scope.

## GUI/audio state

The current public connection and assignment vectors are shared mutable state.
GUI writes can race with audio-thread iteration. A mutex taken only by the writer
does not protect an unlocked reader, and taking a blocking mutex in the audio
callback conflicts with the real-time requirements.

When fixing this path, publish a stable snapshot or use a bounded thread-safe
handoff. Keep allocation and snapshot reclamation off the audio thread. Validate
reader and writer lifetimes together, including preset and state restore.

If `addConnection` or `addAssignment` returns false, handle the failed insert.

This file refines the repository-root AGENT.md for the related sources.