feat(plugins): qualify host VST3 chains and refresh the DAW gallery (phase 89)

docs/KNOWN_LIMITATIONS.md

@@ -112,3 +112,20 @@ Do not unload/replace modules during playback; candidate plans are prepared off
 the callback and old instances are reclaimed on the control thread. Missing
 references remain inspectable without loading; failed GUI preparation retains
 the current project. Save a backup for applications limited to v11 or earlier.
+
+
+### Track insert chains (Phases 80–89)
+
+Track chains contain at most eight mono effects. Modern adapters require zero
+reported latency, use default configuration and do not provide native plugin
+windows, parameter editing or opaque state persistence. A bounded VST3 output
+parameter sink retains the final notification per parameter per block (64
+parameters); these notifications are not recorded or exposed as controls.
+Track edits stop transport before candidate preparation. Bus inserts and tracks
+with both audio assets and MIDI reject preparation. Unassigned live sine
+monitoring stays on the master input. Stereo insert layouts, latency
+compensation, sandboxed scanning and gapless live insert edits remain future
+work. Internal history resets on discontinuities; third-party history follows
+the existing host contract. Presets retain absolute plugin references, so
+compatible binaries must be installed at the same paths on another machine.
+The smaller optional inspector's visibility is session-local.

docs/PROJECT_FORMAT.md

@@ -1,4 +1,4 @@
-# Project format v16 (reads v1–v15)
+# Project format v17 (reads v1–v17)
 
 Phases 5–31 use a bounded text format implemented in C99 without a parser library.
 The extension is `.xtc`. File operations run exclusively on the control thread.
@@ -426,3 +426,39 @@ followed by `MARKER tick hex_name` records. Count is 0..128; ticks must be stric
 increasing and at most MAX_TICK. Names use the existing bounded UTF-8 hex encoding.
 Versions 1–15 migrate to an empty marker list. Older builds reject version 16.
 Markers are copied by snapshots and history; the tick is their stable key.
+
+
+## Version 17: per-track insert chains
+
+After MARKERS/MARKER and before END, the writer emits a chain for every track,
+in dense track order. Earlier versions migrate to empty chains with unity gain.
+Floats use the existing eight-digit IEEE binary32 hex encoding; strings use the
+existing bounded UTF-8/byte hex encoding, with `-` for an empty identity.
+
+```text
+CHAINS track_count
+CHAIN track_id slot_count output_gain_bits
+INSERT enabled wet_bits format descriptor_index unique_id inputs tempo hex_label
+MODULE hex_absolute_binary_path
+IDENTITY hex_stable_identifier_or_dash
+CONTROLS control_count
+CONTROL port value_bits
+PARAMETERS point_count
+PARAM tick port step value_bits
+```
+
+Each CHAIN has exactly slot_count INSERT blocks. CONTROLS/PARAMETERS determine
+the subsequent CONTROL/PARAM record counts, including zero. Slots are ordered,
+at most eight, and accept mono non-instrument effects only. Enabled is 0/1,
+wet is finite 0–1, output gain finite 0–4; inputs must be 1. The format values
+are LADSPA=0, CLAP=1, VST2=2, VST3=3 and Internal=4. Existing plugin specification
+validation applies, including descriptor/identity/port/automation bounds and
+20,000–300,000 milli-BPM. Bus chains must be empty. No sample reference is
+permitted on an effect. Duplicate, missing, reordered or excessive chain
+records, malformed strings and nonfinite values reject the whole load.
+
+Loading and dependency inspection only validate metadata; no plugin module
+is opened. Enabled plugins are verified when a render plan is prepared. Chain
+preset files reuse this schema with exactly one non-bus track and no clips or
+instrument. Track insert APIs are declared in `xtc_plugin.h`; see
+[TRACK_INSERTS.md](TRACK_INSERTS.md) for playback restrictions and workflows.

docs/ROADMAP.md

@@ -2015,12 +2015,40 @@ Implemented: selected insert wet amount (0–1) and chain output gain (0–4) co
 Load compatible installed host VST3 effects in real track chains, capture screenshots, update usage documentation and qualify integration, persistence and real-time boundaries.
 
 ### Tasks and acceptance criteria
-- [ ] Implement the described workflow with validated errors and safe ownership.
-- [ ] Pass relevant core and/or GUI tests.
-- [ ] Document behavior and limitations; commit this phase separately.
+- [x] Implement the described workflow with validated errors and safe ownership.
+- [x] Pass relevant core and/or GUI tests.
+- [x] Document behavior and limitations; commit this phase separately.
 
 ### Implementation status
-Planned.
+Implemented: installed host ZamEQ2, ZamAutoSat and ZamDelay VST3 effects load together, render finite nonzero output and export a non-silent WAV. A bounded VST3 output-parameter sink fixes host assertion logging; the fixture verifies notification/reset/capacity behavior. Actual format labels and scrollable compact insert graphs are verified. All 52 prior screenshots were refreshed and five real compact/VST3 captures added. Full core/reliability, four-format insert GUI, full effect/instrument GUI matrix, JACK lifecycle, ASan/UBSan core and focused/full GUI, static analysis and both staged install layouts passed. See TRACK_INSERTS.md and screenshots/README.md for exact limits and reproduction.
+
+---
+
+### Integrated validation for Phases 80–89
+
+All ten phases have separate tested implementation commits. Verification used
+`make BUILD_DIR=build/audio-editor all test test-reliability gui`,
+`test-gui-track-fx`, the full `test-gui`, `test-gui-modern-plugins`,
+`test-gui-instruments`, `test-gui-plugins` and `test-gui-jack` targets,
+`analyze`, `test-install` and `test-install-layout`. Clang ASan/UBSan core,
+allocation guards and focused/full GUI checks passed using only the existing
+system Fontconfig leak suppression. The normal GCC build is warning-free;
+Clang/FLTK emits the existing redundant-instrumentation warning.
+
+The opt-in `XTC_TEST_HOST_VST3=1` core check loaded the installed Zam VST3
+binaries, rendered their serial MIDI-track chain and validated non-silent WAV
+export. The screenshot tool refreshed the complete prior gallery; its
+`XTC_CAPTURE_HOST_VST3=1` mode captured the real loaded chain, identity view,
+parallel branches, compact workspace and creation menu. Metadata-only CLI
+inspection tests cover insert dependencies, malformed/overflow records,
+nonfinite values, missing modules and v16 migration without executing modules.
+
+No dependency was added. Writer format is 17, reads 1–17. Inserts remain bounded
+mono effects with zero reported latency, control-thread edits and no native
+plugin editors or modern parameter/state persistence. Bus/hybrid inserts reject
+preparation. These tests qualify host ownership and the named configurations;
+physical hardware, arbitrary third-party plugins and feature parity with mature
+DAWs are not claimed. See TRACK_INSERTS.md and KNOWN_LIMITATIONS.md.
 
 ---
 

docs/TRACK_INSERTS.md

@@ -65,3 +65,30 @@ Edits are prepared and undoable, with finite range validation. Internal sync
 parameters follow project tempo. This is mono amplitude blending; stereo track
 insert layouts, latency compensation and gapless live insert edits are future
 work. Editing stops transport before preparing the replacement plan.
+
+The CLI `xtc-check --inspect project.xtc` lists insert format, slot order,
+bypass/wet settings and missing binary references without loading plugins.
+VST3 processing supplies a fixed output-parameter sink (64 IDs, final point per
+ID/block) for plugins that emit meter/parameter notifications; notifications are
+not recorded or exposed as controls.
+
+Host qualification on 2026-11-06 used the installed Linux x86_64 ZamEQ2,
+ZamAutoSat and ZamDelay VST3 binaries under `/usr/lib/vst3`. All three were
+prepared together, rendered with nonzero finite output and exported to WAV.
+This verifies those default mono configurations, not arbitrary plugins or
+physical hardware. The repository fixtures cover LADSPA, CLAP, VST2 and VST3
+insert adoption and VST3 output notification bounds. Internal-plan allocation
+failure and callback guards, sanitizers, GUI/JACK lifecycle and install checks
+cover host ownership and cleanup.
+
+Reproduce focused verification with:
+
+```sh
+make BUILD_DIR=build/audio-editor test-track-fx test-gui-track-fx
+XTC_TEST_HOST_VST3=1 ./build/audio-editor/test_track_fx
+```
+
+The host opt-in requires the three named Zam bundles; the normal tests use
+internal devices and controlled fixtures. The screenshot tool's
+`XTC_CAPTURE_HOST_VST3=1` mode captures those real host plugins; see
+[screenshots/README.md](../screenshots/README.md).