Phase 5: Add project persistence and sequencer foundation

docs/GUI.md

@@ -26,17 +26,15 @@ from an audio callback. No server is started and no audio ports are connected
 by the GUI. The initially empty graph produces silence.
 
 - **Play / F5:** start the engine. **Stop / F8:** deactivate it. **Space:** toggle.
-  These are engine controls, not timeline playback or transport positioning.
+  These advance/pause the sample-counted playhead; regions are currently silent.
 - **Reconnect / F6:** close the old client and open a fresh stopped client.
   Use this after server loss or sample-rate changes. A failed close preserves
   the handle and reports the failure instead of opening another client.
 - **View menu / Ctrl+1, Ctrl+2, Ctrl+3:** switch between sequencer, mixer and
-  modular graph. Tabs provide the same view switching. Editors remain clearly
-  labeled placeholders for sequencer/mixer; Modular Graph is implemented below.
+  modular graph. Tabs provide the same view switching. The mixer remains a placeholder; graph and sequencer editors are described below.
 - **File / Quit / Ctrl+Q** or the window close button: close the backend and
   synchronize audio callbacks before hiding/destroying widgets. A failed close
-  leaves the window open for a retry. Unsupported New/Open/Save actions are
-  visibly disabled. About identifies the development milestone and version.
+  leaves the window open for a retry. New/Open/Save actions are described below. About identifies the development milestone and version.
 
 The indicator shows disconnected, ready, running, server lost, format changed
 or process-error states. The status line shows rate, actual block size, mono
@@ -78,10 +76,10 @@ to connect. Click a node or wire to select it (yellow outline/wire), then press
 Delete/Backspace or **Delete selection**. Deleting a node deletes its incident
 wires. Escape cancels a drag preview. Canvas scrollbars pan the view; positions
 are retained across edits/reconnect but not across application restart. There
-is no zoom, multiselection, undo, project persistence or external routing UI yet.
+is no graph zoom, multiselection, undo or external routing UI yet.
 The editor supports 64 nodes on a fixed 2000x4000 canvas.
 
-Every semantic action becomes a C graph command. The window owns the graph
+Every semantic action becomes a C graph command. The window owns a C project containing the graph
 handle and publishes the C-created candidate through the backend. Cycle,
 invalid-direction, duplicate connection, missing-port, capacity and backend
 failures are shown below the canvas; failed edits leave the graph unchanged.
@@ -99,3 +97,36 @@ audio thread. There is no automatic retry/hidden edit queue; users retry a
 rejected capacity edit. Plan replacement can reset oscillator phase and is not
 crossfaded. Render validation and active replacement tests are described in
 tests/integration/README.md.
+
+
+## Phase 5 projects and sequencer
+
+File/New (Ctrl+N), Open (Ctrl+O), Save (Ctrl+S), and Save As
+(Ctrl+Shift+S) use native file dialogs and the C persistence API. New/Open/Quit
+offer Cancel/Discard when semantic edits are unsaved; save first to retain them.
+Save As confirms overwrites. The title marks unsaved changes. Failed loads and
+backend submissions retain the old document. Loading parses before stopping
+audio; installing a valid candidate stops and resets transport before compiling
+and submitting. A later failure can leave the retained document stopped at zero.
+Opening/New resets graph layout; graph positions are not saved. See PROJECT_FORMAT.md.
+
+Sequencer offers Add track, Add region, Delete region/track, Zoom +/-. Select a
+track header to add a one-bar region there at the cursor. Select a region to
+delete it; deleting a selected track cascades to its regions. Delete also works
+with canvas focus. Drag a region body to move it in time or between tracks;
+drag either edge to trim within its original source bounds. Edits commit on
+release with 1/16-note snapping; Escape cancels. There is no drag preview, undo,
+multiselection, rename or tempo editor yet. Overlapping regions are permitted.
+
+The scrollable canvas expands to cover the arrangement plus a margin; zoom
+ranges from 24 to 384 pixels/quarter. Names, tempo and 4/4 meter are drawn.
+A ruler click seeks while stopped (or positions the cursor when disconnected).
+The 100 ms GUI refresh converts the backend's actual sample counter to ticks;
+it never integrates wall-clock time. Play resumes and Stop pauses. Reconnect,
+New and Open reset position. Regions contain no audio or MIDI and cannot
+produce sound yet; modular graph processing continues as before. The C model
+supports a constant tempo; a tempo map and scheduler are future work.
+
+Tests cover C-model/persistence boundaries, GUI move/trim gestures and zoom,
+save/reopen, failed load/submission rollback, sample-derived cursor updates,
+and live JACK playhead advance/pause.