@denaudio/den 0.0.0-stage → 0.1.0

package/dist/windowed-pitch-shift.d.ts

@@ -0,0 +1,34 @@
+import { type Node } from '@unworklet/core';
+export interface WindowedPitchShiftConfig {
+    /** Match the enclosing processor's ctx.sampleRate; integer 8000..192000. */
+    sampleRate: number;
+    /** Fixed delay sweep width, even integer 32..16384; default 2048.
+     * A head's cycle lasts windowSamples / abs(1-ratio) output samples.
+     * This is not a fixed-duration grain or an STFT frame. */
+    windowSamples?: number;
+}
+export interface WindowedPitchShiftControls {
+    /** Input-time speed [0.5,2]. Invalid values retain the last valid ratio,
+     * or 1 on reset. Finite endpoints are accepted without epsilon. */
+    ratio: Node<'f32'>;
+    /** Level retrigger: use phase zero now, preserving history. Can click.
+     * Held retrigger pins the current read to the initial midpoint delay. */
+    retrigger: Node<'bool'>;
+    /** Priority over retrigger. Silence/discard this sample, invalidate history,
+     * and hold phase zero. A valid ratio is still accepted during reset. */
+    reset: Node<'bool'>;
+}
+/** Bounded mono two-window moving-readhead pitch effect. Call once per sample.
+ * Finite f32 input required. Complementary triangular weights and linear reads
+ * are convex: no implicit gain, feedback, dry/wet mix or bypass. Initially,
+ * ratio 1 is a (1+windowSamples/2)-sample delay; unity after modulation may comb.
+ * Read ages are [1,windowSamples+1]; no single latency for shifting audio.
+ * Linear interpolation aliases, and windows can color/cancel/modulate audio.
+ * No formant preservation, general time stretching or realtime guarantee.
+ */
+export declare const windowedPitchShift: import("@unworklet/core").SubgraphDecl<[config: WindowedPitchShiftConfig], {
+    tick(input: Node<"f32">, c: WindowedPitchShiftControls): {
+        output: Node<"f32">;
+        ratioRejected: Node<"bool">;
+    };
+}>;

package/dist/windowed-pitch-shift.js

@@ -0,0 +1,51 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const SCALE = 2 ** 128;
+/** Bounded mono two-window moving-readhead pitch effect. Call once per sample.
+ * Finite f32 input required. Complementary triangular weights and linear reads
+ * are convex: no implicit gain, feedback, dry/wet mix or bypass. Initially,
+ * ratio 1 is a (1+windowSamples/2)-sample delay; unity after modulation may comb.
+ * Read ages are [1,windowSamples+1]; no single latency for shifting audio.
+ * Linear interpolation aliases, and windows can color/cancel/modulate audio.
+ * No formant preservation, general time stretching or realtime guarantee.
+ */
+export const windowedPitchShift = defineSubgraph((config) => {
+    const { sampleRate, windowSamples = 2048 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isInteger(windowSamples) || windowSamples < 32 || windowSamples > 16384 || windowSamples % 2 !== 0) {
+        throw new RangeError('windowedPitchShift requires integer sampleRate [8000,192000] and even windowSamples [32,16384]');
+    }
+    const size = windowSamples + 3;
+    // Exact binary scaling avoids native tiny-state scrubbing, retaining all
+    // finite f32 inputs without threatening f64 overflow at either endpoint.
+    const history = state.buffer.f64({ size }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor'), valid = state.i32(0).named('valid');
+    const phase = state.f64(0).named('phaseScaled'), ratio = state.f64(1).named('ratio');
+    const wet = state.f64(0).expose({ name: 'wetScaled', snapshot: 'transient' });
+    return {
+        tick(input, c) {
+            const accepted = c.ratio.gte(0.5).and(c.ratio.lte(2));
+            ratio.write(select(accepted, f64(c.ratio), select(c.reset, f64(1), ratio.read())));
+            phase.write(select(c.reset.or(c.retrigger), f64(0), phase.read()));
+            const p = phase.read().div(SCALE), other = select(p.gte(0.5), p.sub(0.5), p.add(0.5));
+            const weight = f64(1).sub(p.mul(2).sub(1).abs());
+            const write = select(c.reset, i32(0), cursor.read()), available = select(c.reset, i32(0), valid.read());
+            const at = (position) => {
+                const delay = position.mul(windowSamples).add(1), whole = i32(delay.floor()), fraction = delay.sub(f64(whole));
+                const relative = write.sub(whole), recentIndex = select(relative.lt(0), relative.add(size), relative);
+                const olderIndex = select(recentIndex.eq(0), i32(size - 1), recentIndex.sub(1));
+                const recent = select(available.gte(whole), history.read(recentIndex), f64(0));
+                const older = select(available.gt(whole), history.read(olderIndex), f64(0));
+                return recent.mul(f64(1).sub(fraction)).add(older.mul(fraction));
+            };
+            // Materialize before advancing phase or overwriting the ring. Using the
+            // exact complement guarantees unit DC gain at every crossfade position.
+            wet.write(at(p).mul(weight).add(at(other).mul(f64(1).sub(weight))));
+            history.write(write, f64(select(c.reset, f32(0), input)).mul(SCALE));
+            cursor.write(select(c.reset, i32(0), write.add(1).mod(size)));
+            valid.write(select(c.reset, i32(0), available.add(1).min(size)));
+            const next = p.add(f64(1).sub(ratio.read()).div(windowSamples));
+            phase.write(select(c.reset, f64(0), next.sub(next.floor()).mul(SCALE)));
+            return { output: f32(wet.read().div(SCALE)), ratioRejected: accepted.not() };
+        },
+    };
+});

package/docs/catalog-audition.md

@@ -0,0 +1,76 @@
+# Catalog A/B audition
+
+This is a historical **test-only** browser fixture. It is no longer included in
+`npm run build:site` or publicly deployed. `tests/site-fixture-build.mjs` stages
+the original pages in a temporary directory so the existing browser and
+navigation assertions remain executable. Its three isolated consumers install
+identical packed den bytes with locked dependencies. The original DSP settings
+are unchanged. `npm run build:catalog` remains a standalone development fixture.
+
+## Four candidate materials
+
+The page imports the already reviewed `/musical-examples` processors, complete
+A/B parameter maps and original asset builders without rewriting or normalizing
+them. See [musical examples](musical-examples.md) for independent three-rate
+pitch, envelope, tail, headroom, repeat and snapshot evidence.
+
+- Glass dyad: two independently held 220/330 Hz wavetable voices, original
+  three-frame cycle bank, soft-glass and brighter-harmonic maps.
+- FM/modal hit: fixed 220 Hz FM voice with three resonant modes. Gate rise
+  strikes once; a new strike clears the previous tail.
+- Grain cloud: two seeded grains over original 4096-frame PCM, forward/reverse
+  maps. Release stops new grains and lets current windows finish.
+- Shaped echo: soft ADAA, Q0.5 low-pass and stereo repeats. This page supplies a
+  native 220 Hz sine at amplitude 0.25 with a 10 ms gain time constant. This
+  explicit audition source is separate from the effect's unchanged settings.
+
+The visible master ranges from 0 to 1 and defaults to **1.00×**. There is no
+hidden additional attenuation, normalization, limiter or per-example leveling.
+Start with low device volume. Stereo waveforms use a fixed −1..+1 scale; the
+visible peak is an observed analyser window, not proof of all-frame headroom or
+all-device deadline clearance. The browser is deliberately restricted to 48 kHz.
+
+## Interaction and cleanup
+
+No AudioContext is constructed on page load. Start creates a fresh context and
+native node with all gates off. Asset-backed candidates send the original PCM
+through the existing native event, then inspect native snapshot length and
+buffer-head values before enabling the play controls. The displayed SHA256
+identifies the complete submitted asset; the receipt check itself checks loaded
+length and the inspected head, not a full buffer hash. Snapshot acknowledgement
+has a 10-second bound and is cancelled immediately by Stop.
+
+Select materials and A/B maps while stopped. Pointer capture supports separate
+fingers. Global A/S/Space shortcuts apply outside interactive controls. Focus a
+play button and hold Enter/Space to play it; assistive/virtual click activation
+holds for 180 ms and releases. Focused Stop, Clear, Release, sliders and links
+keep their native keyboard behavior. Blur releases held intents.
+
+Release drops gates and leaves tails. Clear drops gates and source excitation,
+holds the native reset for 40 ms, and leaves the context ready. Stop releases,
+fades the master for 20 ms and disposes/closes audio. Visibility loss and
+navigation close immediately. Generation/cancellation checks keep late resume,
+compilation or preload completion from reviving an old session. No microphone,
+external MIDI, loader, parameter, snapshot or routing framework is added.
+
+## Provenance and verification boundary
+
+The build records packed-package integrity plus the Git commit and dirty state
+when the checkout is available. A Vercel build without Git may use the documented
+`VERCEL_GIT_COMMIT_SHA` system value; otherwise it explicitly says unavailable.
+No project access or environment settings are changed, and no other environment
+values are exposed. Browser assets display CANDIDATE and Runtime NOT_CLEARED.
+
+`tests/catalog-audition.test.mjs` serves the actual combined test-fixture bytes. The
+hosted browser gate must exercise all eight A/B selections, native asset receipt,
+actual stereo unity/half-gain residuals, finite/headroom windows, release/tail,
+clear/stop and route preservation. The independent lifecycle helper observes
+native contexts/worklets and introduces resume/WASM/snapshot barriers; it checks
+cancellation, retry, keyboard/touch behavior, fatal errors and navigation. Mobile
+and desktop screenshots and a source/package manifest are retained. The earlier
+offline tests remain the full-frame numerical/headroom/continuation evidence.
+
+Local compilation/staging is not a browser pass. Hosted exact-head CI and review
+must pass before integration. No new human listening approval or golden
+promotion is inferred from automated checks. Historical intermittent runtime
+failures remain open.

package/docs/catalog-filters.md

@@ -0,0 +1,125 @@
+# Catalog filters: clean responses, EQ, formants and crossover
+
+These are additive CANDIDATE modules. The initial `filter`, instrument, sound
+settings and Delay FX are unchanged. No framework, dependency upgrade, dynamics
+processing, automatic normalization or approved golden is added.
+
+## Public entries and contract
+
+All modules are unworklet `defineSubgraph` declarations. Instantiate with immutable
+`sampleRate`, use `Node<f32>` signals/controls and `Node<bool>` reset, and call each
+instance exactly once per sample. Each instance owns independent fixed histories.
+Construction accepts finite rates 8000–192000 Hz; numeric fixtures exercise
+44100/48000/96000 Hz. Browser worklet compilation remains 48000 Hz only.
+
+- `@denaudio/den/state-variable-filter`: `stateVariableFilter({sampleRate})`.
+  `tick(input, cutoffHz, q, reset)` returns simultaneous `lowpass`, `bandpass`,
+  `highpass`, `notch`, `allpass`. Cutoff clamps to [20,min(20000,.45*sampleRate)] Hz,
+  Q to [.5,10]. Bandpass is normalized to unity at its center; low/high resonance
+  can exceed unity. This is a linear trapezoidal SVF, not a nonlinear ladder or
+  character model. It uses one two-integrator history for all five responses.
+- `@denaudio/den/biquad-eq`: `biquadEq({sampleRate,mode})`, with construction mode
+  `peaking`, `lowShelf` or `highShelf`. `tick(input,cutoffHz,q,gainDb,reset)` uses
+  the same cutoff/Q limits and gain [-24,24] dB. Shelves have fixed monotonic
+  slope S=1; their Q argument is intentionally unused. The peaking filter's gain
+  is the gain at center; shelf gain at center is half the requested dB, with full
+  shelf gain at DC or Nyquist. No hidden makeup gain is used.
+- `@denaudio/den/formant-bank`: `formantBank({sampleRate,bands})`, with 1–8 fixed
+  `{frequencyHz,q,gain}` bands. Construction validates frequency within the cutoff
+  range, Q [.5,10], finite gain [-1,1]. `tick(input,frequencyRatio,resonanceScale,reset)`
+  applies linear frequency/Q factors, each clamped to [.25,4], then each filter's
+  final cutoff/Q bounds. Parallel unity-peak bandpasses are summed with their
+  specified gains. There is no normalization, vowel-recognition claim, speech
+  synthesizer, or implicit voice. Negative gain is an explicit phase inversion.
+- `@denaudio/den/crossover`: `crossover({sampleRate})`.
+  `tick(input,cutoffHz,reset)` returns `{low,high}` from fourth-order
+  Linkwitz–Riley branches: two cascaded second-order Butterworth responses each.
+  A shared first-stage SVF supplies LP/HP, followed by separate LP/HP stages.
+  At fixed cutoff, both outputs are -6.0206 dB at crossover and their positive-
+  polarity sum has unity magnitude. The sum is an allpass: it is not zero phase,
+  original PCM, a linear-phase FIR, or latency compensation.
+
+Inputs and controls must be finite. These blocks do not clamp or sanitize audio,
+apply bypass, or guarantee arbitrary modulation is stable. The tests cover
+specified per-sample sweeps; fixed-parameter transfer-function guarantees must
+not be transferred to arbitrary coefficient jumps. Host callers choose their
+musical control trajectories and explicit dry/wet/bypass path. Reset clears
+history before the current input, so it may produce a waveform discontinuity.
+There is no click-free-reset claim. When input stops, IIR tails decay normally.
+
+## Numeric and state choices
+
+Internal audio histories are f64. unworklet 0.4.1 flushes scalar state writes with
+magnitude below 1e-30, so these new modules store audio histories scaled by exact
+`2**128` and divide by the same power on read. This preserves subnormal f32 signal
+history without extra scale rounding. The scaled full finite f32 range remains
+well within f64. Bounded nonzero coefficient scratch values are overwritten
+before every use. No audio intermediate is cached merely to shorten a graph.
+The initial filter's existing state/schema is not changed or migrated.
+
+The half-angle tangent uses the existing reviewed bounded polynomial formulation.
+EQ amplitude uses a degree-16 exponential polynomial on the explicitly bounded
+±24 dB domain. Both SVF and EQ use a TPT two-integrator realization; EQ mixes its band/low
+responses to match the RBJ static formulas. Peaking uses damping 1/(Q*A),
+low shelf scales the tuning by 1/sqrt(A), and high shelf by sqrt(A), where
+A=10^(gainDb/40). Independent impulse oracles use trigonometric RBJ coefficients
+and direct form I. Snapshots use the existing same-processor/schema/rate contract.
+
+## Verification and provenance
+
+`tests/catalog-filters.spec.ts` has 49 cases covering:
+
+- all five SVF response impulses, Q/cutoff endpoints and comparison with the
+  unchanged initial low-pass at three rates (absolute sample error <2e-6)
+- three EQ modes across gain/cutoff endpoints; unity at 0 dB, center/shelf gains;
+  independent impulse error <1e-5
+- LR4 cascade references, half-amplitude/in-phase split at crossover, sampled
+  frequency magnitude-flat sum, and an explicit rejection of identity-PCM claims
+- independent weighted formant-band sums and center shifts
+- reset, uninterrupted same-schema snapshot continuation, lower clamps,
+  controlled per-sample modulation, finite output and zero scrubbed samples
+- tiny/subnormal histories at 1e-35 and 1e-39, measured against independent
+  references after scaling for inspection
+- invalid construction rate/band count/frequency/Q/gain rejection
+- adversarial 10/100/1000 Hz cutoff sweeps at Q=10 and +24 dB across all three
+  EQ modes/rates; zero scrubs and a fixed conservative peak ceiling reject
+  runaway state without implying a universal headroom limit
+
+The isolated packed consumer exercises all four public subpaths, strict NodeNext
+checking, actual five-output worklet construction, three-rate offline impulse
+renders, repeated PCM identity and independent references. Its per-run artifacts
+link source/package/lock hashes, complete controls, source impulse, rates, raw
+planar f32/WAV, fixed ±1 static waveforms, measured peaks/errors and build/WASM
+hashes. The browser stage checks real 48 kHz processing, reset and native snapshot
+restoration; it must pass on hosted exact-head CI before integration. Local
+browser availability failures remain failed/unverified stages, never a pass.
+No generated impulse WAV is human-approved musical audio or a golden baseline.
+
+## Formula sources and boundaries
+
+The multimode SVF follows the linear trapezoidal circuit solution described in
+[Andrew Simper's SVF note](https://www.cytomic.com/files/dsp/SvfLinearTrapOptimised2.pdf).
+Cytomic's [technical-paper page](https://cytomic.com/technical-papers/) states its
+shared algorithmic knowledge is public domain. EQ response formulas are checked
+against the [W3C/RBJ Audio EQ Cookbook](https://www.w3.org/TR/audio-eq-cookbook/).
+This is an original implementation from mathematical formulas, not bundled
+third-party source. The crossover is the explicit cascade construction above;
+formants are an explicit parallel bank, not a borrowed commercial preset.
+
+Nonlinear character filters, comb resonators, dynamic multiband processing and
+vowel presets are separate catalog work. No universal real-time capacity,
+all-device stability, transparent changing-cutoff reconstruction, or human
+listening approval is established by these tests.
+
+## Rejected implementation retained in history
+
+The rejected `tests/fixtures/eq-before-tpt.ts` (from the first local catalog
+commit `4235a0a`) retains the time-varying transposed direct-form II EQ.
+Independent review found peaking-state amplification to peak 23939.65 at
+44.1 kHz with a normalized 0.1 sine, Q=10, +24 dB and 100 Hz logarithmic cutoff
+modulation; 1 kHz modulation overflowed/scrubbed. Static impulse agreement did
+not detect this. That realization is rejected and preserved as a non-shipping counterexample
+fixture. A regression confirms it scrubs under the same input that the TPT
+replacement handles with zero scrubs. The reproductions are now mandatory regressions;
+no threshold was raised to accept the rejected behavior. This correction changes
+only the unmerged new catalog EQ, not the existing initial candidate's DSP.

package/docs/catalog-modulation-fx.md

@@ -0,0 +1,220 @@
+# Modulation, stereo delay and algorithmic reverb candidates
+
+Status: **CANDIDATE**. These are composable DSP modules, not human-approved sounds,
+finished room/plate emulations, or a browser real-time performance guarantee.
+The catalog source is [sections 8 and 10](https://www.notion.so/3ef449b4e81d817db1acf1fff48779b3).
+
+Public entries:
+
+- `@denaudio/den/modulation-fx`: `flanger`, `phaser` and their config/control types
+- `@denaudio/den/stereo-delay`: `pingPongDelay`, `multiTapDelay`, `StereoDelayConfig`,
+  `PingPongControls`, `DelayMixControls`, `DelayTap`, `MultiTapDelayConfig`
+- `@denaudio/den/reverb`: `algorithmicReverb`, `AlgorithmicReverbConfig`, `ReverbControls`
+
+All use existing `defineSubgraph` / `instantiate` and state/snapshot mechanisms.
+No loader, routing, serialization, parameter, or test framework is added.
+Keep unworklet at 0.4.1. The root entry does not re-export these candidate modules.
+
+## Shared entry contract
+
+Instantiate during graph construction with `sampleRate: ctx.sampleRate`; rates are
+integer Hz in [8000, 192000]. Call each instance's `tick` exactly once per sample.
+Audio and continuous controls are `Node<'f32'>`, reset/bypass are `Node<'bool'>`.
+Inputs and controls must be finite. Numerical tests use nominal audio within
+[-1, 1]; extreme near-overflow f32 input is not a supported operating level.
+There is no output limiter and wet/feedback paths can exceed unity.
+
+`mix` is linear dry/wet in [0, 1], clamped at the endpoints. A zero mix continues
+feeding/advancing the effect. Bypass emits unity dry, stops new input to the wet
+network, and continues its existing tail. Re-enabling it reveals that continuing
+tail. Bypass does not save CPU. Reset clears effective history **before** the
+current input is processed. Holding reset continually clears history. Reset and
+bypass together suppress new wet input; reset alone accepts the current input.
+
+No implicit parameter smoothing or click-free bypass is claimed. Abrupt controls
+can create discontinuities. The caller owns musical modulation and smoothing.
+Persistent histories use the existing snapshot path; tests cover exact same-rate,
+same-schema continuation. Cross-rate snapshots and changed construction schemas
+are not asserted compatible. unworklet scalar writes flush values below 1e-30;
+very small tails therefore differ from ideal infinite-precision equations.
+
+## Flanger
+
+`flanger(config).tick(left, right, controls)` is stereo-in/stereo-out and returns
+`left`, `right`, `timingRejected`, `modulationClipped`.
+
+Construction controls:
+
+- `maxDelaySeconds`: fixed per-channel capacity, one sample through 0.02 seconds;
+  default 0.02
+- `stereoPhaseCycles`: finite relative right LFO phase; default 0.5
+
+Sample controls: `delaySeconds`, `depthSeconds`, `rateHz`, `feedback`, `mix`,
+`bypass`, `reset`. Base time must lie in [one sample, capacity]. Invalid time emits
+dry, stops new wet input, and preserves the prior valid internal time (or minimum
+time on reset), reporting `timingRejected`. Depth and rate inherit existing delay
+bounds: depth [0, 0.05] seconds, rate [0, 20] Hz; the resulting moving head is clipped
+to the declared short capacity and reports `modulationClipped`.
+Feedback is positive, clamped to [0, 0.95].
+
+This intentionally reuses `delayFx`, `delayReadhead` and the existing LFO. Flat
+feedback and short delay create the comb response: with a static integer delay D,
+wet transfer is z^-D / (1 - feedback*z^-D). At zero feedback and 50% mix, the first
+notch is at sampleRate/(2D). Tests check complex frequency response, not merely a
+renamed chorus preset. Wet latency is the selected delay; dry has no added delay.
+Linear interpolation attenuates high frequencies and moving delay produces
+Doppler pitch changes. There is no through-zero or negative-feedback mode.
+
+## Phaser
+
+`phaser(config).tick(input, controls)` returns one mono sample. Compose independent
+instances, or use different modulation trajectories, for stereo.
+
+- `stages`: fixed 2, 4, 6 or 8 first-order allpasses; default 4
+- `frequencyHz`: common per-stage -90 degree frequency, clamped to
+  [20, 0.45*sampleRate]
+- `feedback`: signed previous-sample wet feedback, clamped to [-0.95, 0.95]
+- `mix`, `bypass`, `reset`: shared behavior above
+
+With a = (tan(pi*f/fs)-1)/(tan(pi*f/fs)+1), a static stage has transfer
+(a + z^-1)/(1 + a*z^-1). Stages are normalized lattice sections:
+y = a*x + b*s; next_s = b*x - a*s; b = sqrt(1-a*a). The scattering matrix is
+orthogonal, so even changing a every sample cannot create energy in that isolated
+section. The bounded sine/cosine polynomial uses f64 arithmetic, followed by f64
+coefficient, signal, history and feedback staging. This does not promise absence
+of modulation sidebands, perceptual artifacts, or numerical error.
+
+Static wet magnitude is unity; dry/wet cancellation produces the phaser notches.
+At 100% wet it is an allpass phase effect, not an EQ notch bank. There is direct
+feedthrough, no lookahead, and exactly one sample in the explicit feedback path.
+A normalized realization is deliberate: a time-varying direct-form allpass does
+not inherit the same per-sample energy argument automatically.
+
+## Ping-pong delay
+
+`pingPongDelay(config).tick(left, right, controls)` returns stereo samples and
+`timingRejected`. `maxDelaySeconds` is fixed, one sample through 8 seconds;
+default 2. `timeSeconds` sets both channel delays and has the same invalid-request
+policy as the flanger base time. It is a moving, linearly interpolated head;
+there is no dual-head transition or internal tempo conversion.
+
+Feedback is signed and clamped to [-0.95, 0.95]. Both channels are read before
+either channel is written. The left wet output feeds the right input and vice
+versa. A left-only impulse appears on the left after D samples, right after 2D,
+left after 3D, with amplitudes 1, g, g². No extra sample enters this circulation.
+A duplicated mono input stays symmetric. A feedback filter is not part of this
+candidate; the existing `delayFx` provides filtered independent-channel repeats.
+
+## Multitap delay
+
+`multiTapDelay(config).tick(monoInput, controls)` returns `left`, `right`.
+Construction fixes 1–8 taps and the common `maxDelaySeconds` capacity (default 2,
+up to 8 seconds). Each tap has `delaySeconds`, `gainLeft`, `gainRight`. Times must
+fit [one sample, capacity]; signed gains must be finite and in [-1e6, 1e6].
+
+All gains share divisor max(1, sum(abs(left gains)), sum(abs(right gains))). This
+preserves signs, each channel's relative tap levels, and stereo ratios; it reduces
+absolute level when either sum exceeds unity. There is no per-tap auto gain or
+energy-based normalization. The post-normalization L1 sum in either channel is
+at most one, giving the mixed-tap feedback path a clear amplitude bound.
+
+Each tap reuses one independent `delayReadhead`, read once and written once per
+sample. This deliberately spends N fixed-capacity buffers instead of changing the
+existing readhead's single-read contract. Feedback is the average of the two wet
+channels, multiplied by signed gain [-0.95, 0.95], then added to mono input before
+all tap writes. Opposite-polarity stereo taps can cancel in this feedback sum.
+Dry mono input is copied to both channels. There is no runtime tap insertion,
+reordering or time control; rebuild for a different rhythmic pattern.
+
+## Small algorithmic reverb
+
+`algorithmicReverb(config).tick(left, right, { mix, bypass, reset })` returns
+stereo samples. The network has four fixed delays and a Hadamard/2 orthogonal
+feedback matrix. Reference delays are 29.7, 37.1, 41.1 and 43.7 ms, scaled and
+rounded to sample counts at construction.
+
+- `roomScale`: fixed [0.5, 2], default 1
+- `decaySeconds`: fixed low-frequency target RT60 [0.1, 10], default 1.5
+- `dampingHz`: fixed matched-z one-pole corner [20, 0.45*sampleRate], default
+  min(6000, 0.45*sampleRate)
+
+Each delay's loop gain is 10^(-3*delaySamples/(sampleRate*decaySeconds)). The damping
+pole exp(-2*pi*dampingHz/sampleRate) makes a convex one-pole lowpass, so high-band
+decay is shorter than the low-frequency target. Room, decay and damping are
+construction settings, **not runtime modulation controls**. Compute rate-relative
+settings from `ctx.sampleRate`, including during unworklet's eager 48 kHz capture.
+
+Input stereo is injected through two orthonormal Hadamard columns and wet stereo
+uses two other orthonormal projections. Hadamard diffusion occurs at every return;
+there are no extra input diffusers or hand-tuned early-reflection paths. Sparse
+initial reflections and metallic modes are possible. Increasing echo density and
+correct low-band decay do not establish a pleasant room/hall/plate sound.
+
+There is no predelay or processing lookahead. The first wet arrival is approximately
+29.7 ms*roomScale; dry is immediate. This is an acoustic network delay, not a host
+latency-compensation value. Four buffers use the existing readhead capacity rule,
+ceil(sampleRate*maxDelaySeconds)+2; floating-point ceiling can add a guard slot.
+Passing their times through the existing f32 seconds API introduces at most a small
+fractional-sample interpolation difference; the independent reference includes it.
+This implementation is damped, not a lossless network or freeze effect.
+
+No convolution, IR handling, FFT, shimmer, frequency shifter or preset engine is
+included. There is no claim of matching a commercial reverb or a physical room.
+
+## Verification and reproducibility
+
+Focused suites are `tests/catalog-modulation-fx.spec.ts` and
+`tests/catalog-reverb.spec.ts`, at 44.1, 48 and 96 kHz. They check independent
+complex comb/allpass responses, DC/Nyquist and cutoff extremes, lattice
+fast-modulation energy, signed ping-pong timing against a non-ring timeline,
+normalization/polarity/steady-state tap levels, reset/bypass/mix, fresh silence,
+exact same-schema continuation, stereo and mono behavior, FDN impulse/matrix
+references, bounded energy, echo-density growth and band-decay fits.
+
+The FDN 0.6 s decay fixture requires a low-band fitted RT60 between 0.45 and 0.75 s
+and high-band RT60 below 65% of low-band RT60. This explicitly allows finite-window
+and modal estimation differences; no test threshold is adjusted from an observed
+result. A separate 43.7-second offline fixture exercises maximum 10-second decay,
+sustained stereo excitation and a long tail. Every render requires finite outputs
+and zero reported scrubbed samples.
+
+`tests/catalog-modulation-packed.test.mjs` installs the actual tarball into a fresh
+consumer, checks public-entry types, renders WASM at all three rates, builds a Vite
+worklet bundle, and records CANDIDATE WAV files plus package/source hashes under
+`artifacts/catalog-modulation`. Building a worklet bundle is not browser execution.
+Exact-head CI/browser verification belongs to the integration gate. These tests do
+not measure hardware audio, scheduler deadlines, maximum voice count, or universal
+runtime performance. Listen to candidate material before musical approval.
+
+## Algorithm sources
+
+- Julius O. Smith, [delay-line interpolation](https://www.dsprelated.com/freebooks/pasp/Delay_Line_Signal_Interpolation.html)
+  and [allpass sections](https://www.dsprelated.com/freebooks/filters/Allpass_Filter_Sections.html):
+  background for the interpolation and static allpass transfer properties.
+- Sebastian J. Schlecht and Emanuel A. P. Habets,
+  [On Lossless Feedback Delay Networks](https://arxiv.org/abs/1606.07729): matrix
+  losslessness background. This candidate adds fixed losses and independent tests;
+  the paper is not evidence of this implementation's musical or runtime quality.
+
+Implementation is original TypeScript composition of den/unworklet primitives;
+no external DSP source code or audio assets were copied.
+
+
+## Review clarifications and boundary correction
+
+`decaySeconds` sets each FDN line's nominal loop-gain loss, not an exact measured
+RT60 or a hard 10-second tail ceiling. Damping suppresses high frequencies, but
+very low damping also adds loop-filter group delay and can lengthen low-band
+decay. Independent review at 48 kHz, roomScale 0.5, decaySeconds 10 and damping 20 Hz
+measured asymptotic stereo-energy RT60 of 14.8826 seconds (fit 5–15 seconds of a
+43.69-second impulse render, zero scrubs/nonfinite values). Independent
+matrix-pole analysis predicted 14.9275 seconds. This stable setting is retained
+with the correct interpretation, not described as a measured 10-second maximum.
+
+The catalog integration also corrects the shared read-head's one-sample
+construction boundary. At rates such as 8001 Hz, `sampleRate*(1/sampleRate)` can
+round below 1. Construction now checks the seconds value against the exact
+computed reciprocal first, then floors the already-valid product at one sample.
+The immediately smaller representable seconds value still rejects. Regression
+coverage checks new wrappers plus old/new audio, complete state and WASM parity
+for the original 44.1/48/96 kHz paths. No broader capacity rounding is introduced.