M1: multiband width, Auto Mono Safety, Haas Mode, correlation meter, broadened tests, manual

[yves-vogl]

Summary

Completes the M1 — DSP completion & test coverage milestone and prepares Firmament for a v0.1.0 tag.

DSP (issue #1, "Complete and refine the DSP")

• Multiband width: independent Low Width (0-200%, default 0%) scales the Side signal's low band (below Bass Mono Freq), while Width now governs the high band whenever the crossover is engaged. Low Width's default reproduces the v0.1 "bass mono forces the low band to silence" behaviour exactly (verified in tests/MultibandWidthTests.cpp).
• Auto Mono Safety: an optional, correlation-driven Side attenuation that reins in the stereo image when the input goes strongly out-of-phase. Only ever scales Side, so it can never break the L + R == 2 * Mid mono-sum invariant.
• Correlation/phase meter (DSP): a running, leaky-integrated (200 ms) input-correlation estimate, exposed via FirmamentEngine::getCorrelationValue() / FirmamentAudioProcessor::getCorrelationMeterValue(). Drives Auto Mono Safety internally.
• Haas Mode: an optional post-M/S-decode Right-channel delay (0-40 ms, juce::dsp::DelayLine), off by default - a deliberate, clearly-documented exception to the mono-sum invariant, since delaying one channel relative to the other is fundamentally incompatible with an exact sum guarantee.
• PluginEditor extended with knobs/toggles for every new parameter (still the plain v0.1-style editor - custom LookAndFeel is M3).

Notable finding, corrected in docs: juce::dsp::LinkwitzRileyFilter's dual-output low+high bands sum to a flat-magnitude allpass, not an exact reconstruction of the input - this is JUCE 8.0.14's own documented behaviour, confirmed empirically during development. The original v0.1 "Bass Mono" feature was never affected (it only ever discards the low band rather than re-summing), but a pre-existing doc comment overclaimed exact reconstruction; corrected in docs/architecture.md and FirmamentEngine.h/.cpp before it could mislead future multiband work.

Deferred / explicitly out of scope

• A visible correlation/phase meter widget in the GUI - the DSP value is fully computed, tested, and exposed (getCorrelationMeterValue()), but the visual meter component itself belongs to the M3 "Custom GUI / LookAndFeel" issue ("Add metering where relevant to the plugin"), not M1. Not closing that issue.
• 3+ band multiband width - the M1 issue text didn't specify band count; a 2-band (low/high) split reusing the existing single crossover was chosen as the safe, minimal-risk interpretation. A finer multiband split (e.g. low/mid/high) is a reasonable follow-up but not required here.
• No bus-layout changes were made (no sidechain input added) - out of scope for this issue and correctly not attempted.

Tests (issue #2, "Broaden test coverage")

Grew the suite from 24 to 49 Catch2 test cases:

• SampleRateSweepTests.cpp - unity round-trip, latency, and finiteness across the full 44.1-192 kHz range, plus a mid-session sample-rate-change test.
• BusConfigTests.cpp - direct isBusesLayoutSupported() accepted/rejected coverage (mono/stereo in, stereo out, surround/mono-out/disabled rejections) plus full-signal-path smoke tests with every M1 stage engaged.
• LongRunStabilityTests.cpp - ~1000-block randomised-automation and ~500-block sustained-worst-case NaN/Inf stability sweeps.
• Extended RobustnessTests.cpp's extreme-value and rapid-automation tests to cover every new parameter.
• Dedicated coverage per M1 feature: MultibandWidthTests.cpp, AutoMonoSafetyTests.cpp, CorrelationMeterTests.cpp, HaasModeTests.cpp.
• ParameterTests.cpp/StateTests.cpp updated for the 4 new parameters (count, defaults, ranges, state round-trip).

All existing v0.1 null/reference/mono-collapse/latency tests remain green and unmodified in intent (only extended with new parameters at their v0.1-equivalent defaults).

Documentation

• New docs/manual.md - full user manual (what Firmament is, where it sits in a symphonic-metal chain, signal flow, complete 7-parameter reference, mixing tips).
• docs/architecture.md - updated diagram/sections for the new signal path, plus the LinkwitzRileyFilter documentation correction above.
• README.md - expanded feature list, added a parameter table, corrected the roadmap table to match the actual GitHub milestones.
• CLAUDE.md - updated Status/DSP sections.
• CHANGELOG.md - moved Unreleased content into a new [0.1.0] - 2026-07-14 section.

Test evidence (local, Debug, macOS arm64)

export CPM_SOURCE_CACHE="$HOME/.cache/CPM"
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target Tests Firmament_Standalone --parallel 3
ctest --test-dir build --output-on-failure

• Tests and Firmament_Standalone build cleanly (no warnings from new code).
• ctest: 100% tests passed, 49/49, ~8s total.

CMake project VERSION is already 0.1.0 (project(Firmament VERSION 0.1.0 ...), JUCE 8.0.14's juce_add_plugin inherits PROJECT_VERSION when no explicit VERSION is passed - confirmed via JUCEUtils.cmake), so no version bump was needed.

Closes #1
Closes #2