Connect FLTK shell to JACK engine controls and status

docs/ARCHITECTURE.md

@@ -43,3 +43,12 @@ the optional JACK implementation drives that same realtime engine.
 Only acknowledged retired plans are reclaimed during processing. Backend close
 synchronizes callbacks before reclaiming remaining plans. See decision 0004
 for the release/acquire protocol, bounded resource retention and recovery.
+
+## GUI backend ownership
+
+The Phase 3 window owns one C backend handle and serializes all control calls
+on the GUI thread. A GUI timer reads snapshots and collects retired resources;
+no audio callback calls FLTK. Successful window close first closes the JACK
+client (synchronizing callbacks), then removes the GUI timer and hides the
+window. Failed close leaves both handle and window available for retry. View
+switching is GUI state only; editors have no domain mutations yet. See GUI.md.

docs/AUDIO_ENGINE.md

@@ -131,5 +131,6 @@ internal realtime guarantees depend on the installed implementation/server.
 Validation commands and results are recorded in BUILD.md and the integration
 test README. Current limitations: mono input/output, no parameter ramping or
 crossfaded graph changes, no realtime meter bridge, no automatic reconnect,
-no physical-device or long-duration endurance qualification. GUI controls and
-status display are Phase 3; the GUI remains a placeholder shell.
+no physical-device or long-duration endurance qualification. Phase 3 connects
+the FLTK shell to backend controls and status; see GUI.md. Its editors remain
+placeholders and the GUI submits no playback graph yet.

docs/BUILD.md

@@ -17,8 +17,8 @@ make gui
 `all` builds the static C library and startup check. `test` runs the existing
 core/offline tests, concurrent plan-handoff stress, JACK fault injection
 (when JACK headers are available), and the startup check. `debug` builds and tests separately in
-`build/debug`. `gui` builds the existing placeholder shell; it does not produce
-audio. Generated files remain under `build` and header changes trigger rebuilds.
+`build/debug`. `gui` builds the FLTK shell with backend controls and status.
+The shell starts a silent engine and never connects physical ports. Generated files remain under `build` and header changes trigger rebuilds.
 Compiler, flags, `BUILD_DIR`, `PKG_CONFIG`, `FLTK_CONFIG`, and installation
 `PREFIX` can be overridden through Make variables. C uses C99; GUI uses C++17.
 
@@ -76,8 +76,24 @@ fault-injection tests cover those notification paths. No packages installed
 or system/device configuration changed. Sanitizers are not enabled in the live
 callback qualification run.
 
+## Phase 3 verification
+
+```sh
+make clean all test gui debug test-gui test-gui-jack
+```
+
+`test-gui` needs Xvfb and `xvfb-run`, uses a fake C backend and requires no JACK
+server. `test-gui-jack` needs a running server; it creates no physical routes.
+Both passed, including repeated active-client close and reconnect. The GUI also
+builds without JACK metadata and reports unsupported backend support at startup.
+A live keyboard/visual smoke run passed under Xvfb. Clang ASan/UBSan GUI tests
+passed with a suppression limited to the installed fontconfig library's
+exit-time font allocations; see tests/integration/README.md for the distinction
+and command. No compiler warnings remain with GCC or Clang. Core/backend tests
+pass with unsuppressed ASan/UBSan. No packages or system configuration changed.
+
 ## Next milestone
 
-Phase 3 connects the FLTK shell to the backend C API for engine controls,
-status/error reporting and clean shutdown. Physical playback and endurance,
-project persistence and sequencing remain unverified/unimplemented as applicable.
+Phase 4 implements the modular graph editor and submits validated graph edits
+through the C API. Physical playback/endurance, project persistence and
+sequencing remain unverified/unimplemented as applicable.

docs/GUI.md

@@ -16,3 +16,49 @@ from project mutation. Never call FLTK from the audio thread.
 Visual direction: compact, high-contrast, restrained dark interface. Avoid
 excessive animation and modal configuration. Recreate broad usability ideas,
 not energyXT's exact artwork or proprietary resources.
+
+## Phase 3 shell
+
+The shell opens JACK on startup through `xtc_backend.h`. It never accesses
+backend structures, processes samples, creates domain objects, or calls JACK
+itself. All backend control calls run on the GUI thread; FLTK is never called
+from an audio callback. No server is started and no audio ports are connected
+by the GUI. With no graph submitted, the running backend produces silence.
+
+- **Play / F5:** start the engine. **Stop / F8:** deactivate it. **Space:** toggle.
+  These are engine controls, not timeline playback or transport positioning.
+- **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; no project editing is implied.
+- **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.
+
+The indicator shows disconnected, ready, running, server lost, format changed
+or process-error states. The status line shows rate, actual block size, mono
+layout, processed block count, xruns and process result. Command errors remain
+visible until a successful control action; periodic refresh does not erase them.
+A GUI-owned 100 ms timer reads atomic snapshots and collects retired plans.
+Label text changes only when needed. The timer is removed before successful
+close and again by the window destructor. No GUI locks are held across control
+calls. Operations such as opening JACK can briefly block the GUI; there is no
+worker/control-thread framework in this initial shell.
+
+MainWindow owns the backend handle and FLTK owns the window's children. The
+destructor also attempts cleanup on exceptional event-loop exit; if JACK close
+itself fails then, it reports to stderr and retains the callback context until
+process exit. Normal close/reconnect paths permit retry and release ownership
+only after successful close. The entry point catches C++ exceptions before
+process exit. Backend operations return C error codes throughout.
+
+Tests: `make test-gui` runs real widgets/callbacks/timers against a fake C backend
+under Xvfb, including control errors, startup without JACK, partially initialized
+handles, server/format notifications, view switching, retrying close, and timer
+removal. `make test-gui-jack` additionally requires a running JACK-compatible
+server, tests repeated start/stop, reconnect and active-client close, and creates
+no routes. Physical playback is outside this shell. See BUILD.md and the
+integration test README for sanitizer limitations and keyboard smoke results.

docs/ROADMAP.md

@@ -26,12 +26,18 @@ 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; no GUI engine integration until Phase 3.
+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. Editors and
+project-file actions remain placeholders; engine runs in silence. 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.