xtc/docs/ROADMAP.md

# Roadmap

## Phase 0 — Baseline
Inspect repository/toolchain, verify Makefile and minimal executable, document
dependencies. No system changes without permission.

Baseline implementation: headless startup/shutdown executable, core tests,
separate debug build, optional FLTK shell build, and header dependencies.
See [BUILD.md](BUILD.md) for toolchain, commands, licensing and limitations.

## Phase 1 — C core and offline processing
Graph data structures, validation, cycle detection, topological ordering,
preallocated buffers, test oscillator, gain and offline render tests.

Implemented: mono ports, transactional cycle rejection, independent compiled
plans, precomputed input routing, oscillator/gain/meter/output, deterministic
variable-block tests and lifecycle/error coverage. See AUDIO_ENGINE.md for API
limits and compatibility behavior.

## Phase 2 — Real-time backend
Choose and implement a Linux backend. Document callback semantics, start/stop,
device errors, shutdown, and safe graph publication.

Implemented: optional JACK-compatible mono backend, explicit audio port routing,
format/xrun/loss status, start/stop/reopen, and bounded pending/retired plan
handoff using lock-free atomics. Hardware-independent failure/concurrency tests
and a 30-second software-loopback run pass. See decision 0004 and AUDIO_ENGINE.md.
Physical hardware playback/endurance and live server-loss recovery remain
unverified; GUI engine controls are implemented in Phase 3.

## Phase 3 — FLTK shell
Main window, transport controls, view switching, backend status, clean startup
and shutdown through the C API.

Implemented: dark FLTK shell, Play/Stop/Reconnect, view/menu shortcuts, backend
state/format/xrun/process status, persistent command errors, timer-based refresh
and retirement collection, and callback-safe close/retry. Mock-backend GUI tests
and live GUI/JACK start/stop/reconnect/close tests pass under Xvfb. Sequencer,
mixer and project-file actions remain placeholders; initial graph is silent. See GUI.md.

## Phase 4 — Modular editor
Draw nodes/ports/edges; create, move and connect nodes; reject invalid edges;
safely submit edits to the C core.

Implemented: scrollable node/port/wire canvas; add/select/move/delete nodes;
drag connections, select/delete wires, and show invalid-edit feedback. C owns
stable IDs, read-only snapshots and transactional edits. Exact accepted graph
snapshots are submitted to the backend; prepared/queued/active state is exposed
through revision acknowledgements. Core/render, GUI rollback, mouse smoke and
live adoption tests pass. See GUI.md and AUDIO_ENGINE.md. Preset parameters,
mono-only processing, fixed canvas and no persistence/undo/zoom remain limits.

## Phase 5 — Project and sequencer
Versioned persistence, stable IDs, tracks, clips, timeline, selection, zoom,
scrolling, and transport synchronization.

Implemented: bounded version-1 project persistence with transactional loads and
temporary-file/fsync/rename saves; stable track/clip/node IDs; silent regions;
track and region creation/deletion, selection, move/trim, timeline zoom/scroll;
sample-counted playhead, pause/resume and stopped seek. Project/graph arrangement
roundtrips, malformed-input, GUI rollback/gesture and live transport tests pass.
See PROJECT_FORMAT.md and GUI.md. Constant tempo/4/4, silent metadata regions,
no undo, asset playback, MIDI or persisted GUI layout are explicit limits.

## Phase 6 — Audio clips and recording
Audio import/playback, recording through bounded buffers, missing-asset
handling, no file I/O in callbacks.

Implemented: bounded PCM16/24/32 and float32 WAV import (mono/stereo downmix),
preloaded overlap-summed clip plans with linear rate conversion, and an audio
source node using ordinary graph routing. A lock-free SPSC ring transfers JACK
input to a control-thread WAV writer; Stop finalizes and adds successful takes.
Version 2 metadata stores external asset references and reads v1. Missing assets
remain silent with reporting and manual relinking. Core, callback, GUI and live
software record/save/reopen/play acceptance tests pass. See AUDIO_FILES.md for
memory/format limits, overflow recovery and deferred physical-device validation.
No new dependency or callback I/O was introduced.

## Phase 7 — MIDI and instrument
MIDI input/events/clips, simple internal instrument, note-off/panic handling,
then a basic piano roll.

Implemented: bounded source-relative note events with stable IDs; sample-offset
JACK MIDI input; a velocity-scaled sine instrument and separate graph source;
panic, note-off, stop and seek handling; and a piano roll for drawing, moving,
resizing and deleting notes. Version 3 saves notes and reads v1/v2 projects.
Core, fault-injection, GUI and live software MIDI/save/reopen/play tests pass.
Acceptance uses drawn notes; MIDI recording and SMF import are deferred.
See MIDI.md for capacities, immediate note-off, routing and hardware limits.

## Phase 8 — Mixer and editing
Gain/pan, meters, mute/solo, automation, undo/redo, keyboard workflow.

Implemented: selectable per-track channel strips with gain/pan and mute/solo;
stereo graph/JACK output and output peak meters; editable gain/pan automation
lanes with sample interpolation; bounded 32-edit C snapshot undo/redo and mixer
keyboard controls. Format v4 persists mixing/automation and reads v1–v3.
Core, GUI rollback/gesture/history and live stereo software playback tests pass.
See MIXER.md for routing, mono compatibility, pan law, history behavior and limits.
Track inserts/sends, live fader adoption, MIDI capture, per-track meters and
advanced automation remain deferred. No project-file editing is needed for the
implemented composition/mixing workflow.

## Phase 9 — Extensibility and release
Native node API, evaluate plugin hosting, licensing review, packaging,
installation tests, performance and recovery tests.

Do not skip phases without documenting why and preserving acceptance criteria.