feat(patina): rebuild resonance detector, simplify controls, new look

Patina 0.2.0. The old detector compared raw FFT bins with a one-octave
dB mean, so every harmonic of a tonal sound looked like a resonance and
real harsh bumps were barely touched. The new detector:

- averages power over each log band and smooths it over time
- joins harmonic tops into an envelope, smoothed by Sharpness
- compares it with a robust, tilt-aware local line fit that ignores
  empty regions and cannot be lifted by the bump itself

Six overlapping controls become Depth, Sharpness and Selectivity; focus
points now read "up cuts more, down protects". The analysis window is
halved to 2048 samples (about 43 ms delay). Behaviour tests cover plain
harmonic tones, resonant bumps, narrow rings, level independence,
flicker on noise and high sample rates.

Both editors get a dark metallic look with #FF0160 as the single
accent colour; screenshots and docs are updated. Projects saved with
Patina 0.1 load the new controls at their defaults.

docs/patina/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Patina changelog
 
+## 0.2.0
+
+- Rebuild the detector so it finds resonant bumps instead of cutting individual
+  harmonics: band-averaged power, temporal smoothing, a harmonic-top envelope,
+  and a robust tilt-aware reference.
+- Replace six overlapping controls with Depth, Sharpness, and Selectivity.
+  Focus points now read the same way everywhere: up cuts more, down protects.
+- Halve the analysis window to 2048 samples at 44.1/48 kHz (about 43 ms delay).
+- Show the detector envelope and reference on the plot.
+- New dark metallic look with a single accent colour, shared with Rivet.
+- Breaking: projects saved with 0.1 load the new controls at their defaults.
+
 ## 0.1.0
 
 - Introduce Patina, formerly Resonance Compressor, as an independent mixing effect.

docs/patina/README.md

@@ -1,10 +1,11 @@
 # Patina
 
 Patina smooths a sound’s rough surface without erasing its character. Formerly
-**Resonance Compressor**; current version **0.1.0**.
+**Resonance Compressor**; current version **0.2.0**.
 
-A mixing effect for controlling local spectral peaks while retaining the intended
-sound. Independently designed in Rust; no claim of matching Soothe or Quance.
+A mixing effect that finds harsh, ringing regions as they happen and pulls them
+down, while plain harmonic tone passes. Independently designed in Rust; no claim
+of matching Soothe or Quance.
 
 ![Patina](assets/editor.png)
 
@@ -19,40 +20,60 @@ redistributed packages.
 
 ## Work with it
 
-Loop a troublesome passage in context. Restrict Low/High frequency, then adjust
-Amount and Max cut. Sensitivity is a prominence threshold: lower catches more.
-Neighborhood defines the spectral reference; Cut width smooths the attenuation.
-Attack and Release smooth gain changes; Transient guard briefly relaxes cuts.
+Three controls decide what happens:
 
-Double-click the plot to add one of four focus points. Positive sensitivity
-makes the detector more eager; negative values protect the region by raising
-the threshold. Drag a point, wheel to change width, or use its numeric fields.
-Range boundary handles constrain where processing may act. Focus is detector
-weighting, not a static EQ boost and not an absolute protection guarantee.
+- **Depth** is the largest cut, in dB. 0 dB does nothing.
+- **Sharpness** sets what counts as a resonance. Low values follow broad,
+  smooth bumps (honk, boxiness). High values target narrow rings and whistles.
+- **Selectivity** sets how far a bump must stand out before it is cut. Low
+  values treat any bump; high values treat only the worst.
+
+Start with Depth around 6 dB. Raise Selectivity until only the harsh parts show
+cuts, then use Delta to hear what is removed. Restrict Low/High frequency to keep
+the source’s body out of reach. Attack and Release set how quickly cuts grow and
+recover; Transient guard briefly relaxes cuts on attacks to keep punch.
+
+Double-click the plot to add one of four focus points. Drag a point up to cut
+more in that region, down to protect it. Wheel changes its width. Range handles
+on the plot drag the processing limits.
+
+On the plot, the grey fill is the measured input. The bright line is what the
+detector hears (its smoothed spectral envelope); the dim line is what it expects
+there. Accent-coloured cuts appear where the bright line rises above the dim one
+by more than Selectivity allows. The blue curve is the focus/protect shape.
 
-Cyan shows spectral input energy, coral the attenuation, violet detector focus.
-The left scale is calibrated per-bin spectral power; the right scale is cut dB.
 Delta plays delayed dry minus wet before output trim. Use it to inspect changes,
 then return to normal monitoring to decide whether the music improved.
 Mix is a linear blend of aligned signals. Bypass keeps the same latency.
 Use Output for matched-level comparison. Spectral attenuation is not a limiter:
 sample peaks can increase even when frequency gains never exceed unity.
 
-Four starting presets and A/B comparison help explore alternatives. All controls
-are visible. The instrument-style sidebar holds Amount, Mix, and Output; the
-spectrum includes filled energy traces, cut overlays, meter rails, and range
-handles, using the plugin’s cyan/coral/violet palette. Host parameters and window
-size persist; Delta does not. The editor supports numeric entry, keyboard focus, and direct graph editing.
+Four presets and A/B comparison help explore alternatives. Host parameters and
+window size persist; Delta does not.
+
+## How detection works
+
+1. Each analysis frame is grouped into 512 log-spaced bands. Each band holds the
+   mean power of the FFT bins it covers, smoothed over time (about 5 ms rise,
+   40 ms fall) so cuts hold on a stable ring instead of flickering.
+2. Neighbouring peaks are joined in dB, so the gaps between harmonics do not count
+   as the expected level. A plain harmonic tone reads as a smooth envelope.
+3. The envelope is smoothed across frequency by the Sharpness width.
+4. The reference is a robust local straight-line fit over 2–3 octaves: spectral
+   tilt is expected, bumps cannot raise their own reference, and empty regions
+   (below a fundamental, beyond a filter cutoff) are ignored.
+5. Envelope minus reference, above the Selectivity threshold, becomes the cut,
+   limited by Depth, smoothed with Attack/Release, and linked across stereo.
 
 ## Timing and limits
 
-Mixing only: 4096-sample analysis windows at 44.1/48 kHz, 8192 at 88.2/96 kHz,
-16384 at 176.4/192 kHz, with eight overlaps. Delay is one window, about 85–93 ms.
+Mixing only: 2048-sample analysis windows at 44.1/48 kHz, 4096 at 88.2/96 kHz,
+8192 at 176.4/192 kHz, with eight overlaps. Delay is one window, about 43–46 ms.
 The plugin reports it for host compensation. Supported layouts are mono and
 linked stereo; supported rates are those six standard rates.
 
 The engine uses complex RustFFT with supplied scratch buffers, WOLA reconstruction,
-a log-frequency prominence detector, bounded soft-knee cuts, and temporal/frequency
+the envelope/reference detector above, bounded soft-knee cuts, and temporal
 smoothing. Original bin phases are retained. This is not a minimum-phase filter
 bank, a live monitoring effect, a limiter, or an automatic separation of tone and
 unwanted resonance. No external sidechain, Learn, M/S, or pitch detector in v0.1.
@@ -88,15 +109,17 @@ Judge through real patches with matched listening levels: preserve vowel motion,
 snare punch, bass body, and stereo placement. Synthetic tests do not establish
 artistic usefulness.
 
-Local benchmark: AMD Ryzen 7 PRO 3700U, optimized build, stereo 48 kHz, FFT
-4096/hop 512: five seconds processed in 0.233 seconds (about 4.7% of one
-core in that run). This is not a worst-case multi-instance guarantee.
+Local benchmark, optimized build, stereo 48 kHz, FFT 2048/hop 256: five seconds
+processed in about 0.35–0.45 seconds (7–9% of one core on a laptop CPU). This is
+not a worst-case multi-instance guarantee.
 
 
 ## Existing projects and source layout
 
-The CLAP ID `io.storyboard.resonance-compressor`, parameter IDs, and state
-format are unchanged. Replace the former plugin file with `Patina.clap` and
+The CLAP ID `io.storyboard.resonance-compressor` is unchanged. Version 0.2
+replaces Amount, Sensitivity, Max cut, Neighborhood, Cut width, and Knee with
+Depth, Sharpness, and Selectivity, so projects saved with 0.1 load those
+controls at their defaults. Replace the former plugin file with `Patina.clap` and
 rescan; avoid two scanned copies with the same ID. Host project recall still
 needs verification in FL Studio.
 

docs/rivet/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Rivet changelog
 
+## Unreleased
+
+- New dark metallic look with a single accent colour, shared with Patina.
+
 ## 0.3.0
 
 - Introduce the Rivet name and a dedicated product source/documentation tree.