Warm up or distort a sound with a Saturation node (#323)

A sound FX had no way to bend a sound. The Saturation node pushes it
into a curve, from warmth to a hard distortion, on a voice or a bus.

- Eight types, each a fixed curve made once: Soft (tanh), Cubic, Hard
  clip, Tube, Fuzz, Foldback, Sine fold and Rectify. The issue asked
  for as many as useful.
- Drive (0 to 48 dB) is a gain in front of the curve. The curve spans
  256 times full scale, so the drive glides like any gain.
- Output and Auto-gain blend as on the Compressor. Auto-gain brings a
  sine at -12 dBFS back to the RMS it came in with.
- Tone is a low-pass after the curve, 1 kHz at 0 to 20 kHz at 1, as
  recommended in the plan. A 10 Hz high-pass takes out the DC the
  lopsided types make.
- Mix blends with the dry sound. The 4x oversampling is 192 samples
  late in Chrome, so the dry way is held back as far. The node counts
  as late by that much for voices, Mixes and buses.
- A test hook gives e2e the auto-gain at a drive.

Tests:
- Unit saturation (new) 5, soundfx 51 (2 new), sound-library 101
  (1 new), green.
- Counter-checks, each turns tests red: no hold-back of the dry way
  (1), the level without auto-gain (2).
- e2e 34 (melektaus-atx): ALL PASSED, 79 checks (1 new). Chrome
  offline: 192 samples late at 48 and at 44.1 kHz. Half dry at 1125 Hz
  0.00 dB. A sine at -12 dBFS driven 24 dB into Soft comes out at
  0.00 dB with full auto-gain.
- The gate runs once on the last commit of this series.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/viewport/sound-library.test.ts

@@ -19,6 +19,7 @@ import type { MixBus } from '../../src/core/music/mixer';
 import type { SequencePlay } from '../../src/core/music/playbacks';
 import type { ScheduledNote } from '../../src/core/music/Scheduler';
 import type { PitchOptions } from '../../src/viewport/fxWorklet';
+import { saturationCurve } from '../../src/core/soundfx/saturation';
 import { SoundLibrary, stageNodes } from '../../src/viewport/SoundLibrary';
 
 /** What a test wants to hear: a chain whose pitch, where it is not 0, is a Pitch typed in. */
@@ -2358,4 +2359,30 @@ describe('the stages of #318 to #328', () => {
     ]);
     expect(library.busLatency('mix:c')).toBeCloseTo(0.006, 9);
   });
+
+  it('saturates through a curve oversampled 4x, the sound itself held back beside it (#323)', () => {
+    const context = fakeContext() as unknown as BaseAudioContext;
+    const made = stageNodes(context, {
+      kind: 'saturate',
+      curve: 'tube',
+      drive: 12,
+      tone: 5000,
+      level: 0.5,
+      mix: 0.25,
+    });
+    expect(shapers[0]!.curve).toBe(saturationCurve('tube'));
+    expect((shapers[0] as unknown as { oversample: string }).oversample).toBe('4x');
+    expect(filters.map((f) => [f.type, f.frequency.value])).toEqual([
+      ['highpass', 10],
+      ['lowpass', 5000],
+    ]);
+    expect(delays.map((d) => d.delayTime.value)).toEqual([0.004]);
+    expect(made.knobs.map((k) => [k.target, k.even])).toEqual([
+      [10 ** (12 / 20) / 256, 'ratio'],
+      [5000, 'ratio'],
+      [0.5, 'ratio'],
+      [0.25, 'value'],
+      [0.75, 'value'],
+    ]);
+  });
 });