@denaudio/den 0.0.0-stage → 0.2.0

package/dist/wavetable-bands.js

@@ -0,0 +1,145 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+import { readWavetableCycle } from './wavetable-read.js';
+function layout(length, count) {
+    if (!Number.isInteger(length) || length < 16 || length > 4096 || !Number.isInteger(Math.log2(length)) ||
+        !Number.isInteger(count) || count < 1 || count > 16)
+        throw new RangeError('banded wavetable requires power-of-two frameLength 16..4096 and frameCount 1..16');
+    const harmonics = [];
+    for (let h = length / 2 - 1; h >= 1; h = Math.floor(h / 2))
+        harmonics.push(h);
+    const required = length * count * harmonics.length;
+    if (required > 65536)
+        throw new RangeError('all wavetable bands must fit 65536 samples');
+    return { harmonics, required };
+}
+// Host-only radix-2 FFT. This runs before native ingress, never in audio processing.
+function transform(real, imag, inverse) {
+    const size = real.length;
+    for (let n = 1, j = 0; n < size; n++) {
+        let bit = size >> 1;
+        for (; j & bit; bit >>= 1)
+            j ^= bit;
+        j ^= bit;
+        if (n < j) {
+            const r = real[n], im = imag[n];
+            real[n] = real[j];
+            imag[n] = imag[j];
+            real[j] = r;
+            imag[j] = im;
+        }
+    }
+    for (let width = 2; width <= size; width *= 2) {
+        for (let base = 0; base < size; base += width)
+            for (let k = 0; k < width / 2; k++) {
+                const angle = (inverse ? 2 : -2) * Math.PI * k / width, c = Math.cos(angle), s = Math.sin(angle);
+                const a = base + k, b = a + width / 2;
+                const tr = c * real[b] - s * imag[b], ti = s * real[b] + c * imag[b];
+                real[b] = real[a] - tr;
+                imag[b] = imag[a] - ti;
+                real[a] += tr;
+                imag[a] += ti;
+            }
+    }
+    if (inverse)
+        for (let n = 0; n < size; n++) {
+            real[n] /= size;
+            imag[n] /= size;
+        }
+}
+/** Prepare harmonic-truncated pitch bands outside the audio callback. No per-band
+ * normalization, resampling, loader, or provenance/license assumption is added.
+ * Reject nonfinite input or reconstruction that overflows float32. DC, phase and
+ * retained harmonic gain are preserved within FFT/float32 roundoff. */
+export function prepareWavetableBands({ frames }) {
+    const frameCount = frames.length, frameLength = frames[0]?.length ?? 0;
+    const { harmonics, required } = layout(frameLength, frameCount);
+    for (const frame of frames) {
+        if (!(frame instanceof Float32Array) || frame.length !== frameLength || frame.some(x => !Number.isFinite(x))) {
+            throw new RangeError('wavetable frames must be equal-length finite Float32Arrays');
+        }
+    }
+    const data = new Float32Array(required);
+    const real = new Float64Array(frameLength), imag = new Float64Array(frameLength);
+    const r = new Float64Array(frameLength), im = new Float64Array(frameLength);
+    for (let frame = 0; frame < frameCount; frame++) {
+        real.set(frames[frame]);
+        imag.fill(0);
+        transform(real, imag, false);
+        for (let band = 0; band < harmonics.length; band++) {
+            r.fill(0);
+            im.fill(0);
+            const limit = harmonics[band];
+            r[0] = real[0];
+            // Explicit conjugate pairs guarantee a real table despite FFT roundoff.
+            for (let h = 1; h <= limit; h++) {
+                r[h] = (real[h] + real[frameLength - h]) / 2;
+                im[h] = (imag[h] - imag[frameLength - h]) / 2;
+                r[frameLength - h] = r[h];
+                im[frameLength - h] = -im[h];
+            }
+            transform(r, im, true);
+            const offset = (band * frameCount + frame) * frameLength;
+            for (let n = 0; n < frameLength; n++) {
+                const value = Math.fround(r[n]);
+                if (!Number.isFinite(value))
+                    throw new RangeError('prepared wavetable exceeds finite float32 PCM range');
+                data[offset + n] = value;
+            }
+        }
+    }
+    return { data, frameLength, frameCount, harmonicLimits: Object.freeze(harmonics) };
+}
+function bounded(value, high) {
+    return select(value.eq(value), f64(value), f64(0)).clamp(0, high);
+}
+/** Four periodic cycle interpolations: frame morph in neighboring pitch bands.
+ * Fetches eight integer resident reads so tiny local fractions survive offsets.
+ * Static harmonic truncation is not a brickwall reconstruction filter and does
+ * not remove interpolation images or bandwidth from modulation/reset/asset edits. */
+export const bandedWavetableSource = defineSubgraph((config) => {
+    const { sampleRate, sample, frameLength, frameCount, phaseCycles = 0 } = config;
+    const { harmonics, required } = layout(frameLength, frameCount);
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('banded wavetable sampleRate must be in [8000,192000] Hz');
+    if (!Number.isInteger(sample.capacity) || sample.capacity < required || sample.capacity > 65536)
+        throw new RangeError('all wavetable bands must fit resident capacity');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    const phaseScale = 2 ** 1020, controlScale = 2 ** 128;
+    const phase = state.f64(phaseCycles * phaseScale).named('scaledPhase'), revision = state.i32(-1).named('revision');
+    const current = state.f64(phaseCycles * phaseScale).named('scaledCurrentPhase');
+    const scan = state.f64(0).named('scaledFrame'), pitch = state.f64(0).named('scaledFrequency'), band = state.f64(0).named('scaledBand');
+    const frameLo = state.i32(0).named('frameLo'), frameHi = state.i32(0).named('frameHi');
+    const bandLo = state.i32(0).named('bandLo'), bandHi = state.i32(0).named('bandHi');
+    const starts = Array.from({ length: 4 }, (_, i) => state.i32(0).named(`start${i}`));
+    return { tick(c) {
+            current.write(select(c.reset.or(sample.revision().eq(revision.read()).not()), f64(phaseCycles * phaseScale), phase.read()));
+            scan.write(bounded(c.frame, frameCount - 1).mul(controlScale));
+            pitch.write(bounded(c.frequencyHz, .45 * sampleRate).mul(controlScale));
+            const frequency = pitch.read().div(controlScale), frame = scan.read().div(controlScale), p = current.read().div(phaseScale);
+            // Nonoverlapping transitions: the bright H band has zero weight by .45*sr/H.
+            let position = f64(0);
+            for (const h of harmonics.slice(0, -1)) {
+                const start = .225 * sampleRate / h;
+                position = position.add(frequency.sub(start).div(start).clamp(0, 1));
+            }
+            band.write(position.mul(controlScale));
+            const b = band.read().div(controlScale), frameMix = frame.sub(frame.floor()), bandMix = b.sub(b.floor());
+            frameLo.write(i32(frame.floor()));
+            frameHi.write(frameLo.read().add(1).min(frameCount - 1));
+            bandLo.write(i32(b.floor()));
+            bandHi.write(bandLo.read().add(1).min(harmonics.length - 1));
+            starts[0].write(bandLo.read().mul(frameCount).add(frameLo.read()).mul(frameLength));
+            starts[1].write(bandLo.read().mul(frameCount).add(frameHi.read()).mul(frameLength));
+            starts[2].write(bandHi.read().mul(frameCount).add(frameLo.read()).mul(frameLength));
+            starts[3].write(bandHi.read().mul(frameCount).add(frameHi.read()).mul(frameLength));
+            const values = starts.map(start => readWavetableCycle(sample, p, start.read(), frameLength));
+            const a = f64(values[0]).mul(f64(1).sub(frameMix)).add(f64(values[1]).mul(frameMix));
+            const z = f64(values[2]).mul(f64(1).sub(frameMix)).add(f64(values[3]).mul(frameMix));
+            const missing = sample.length().lt(required);
+            const output = select(missing, f32(0), f32(a.mul(f64(1).sub(bandMix)).add(z.mul(bandMix))));
+            phase.write(p.add(frequency.div(sampleRate)).frac().mul(phaseScale));
+            revision.write(sample.revision());
+            return { output, missing };
+        } };
+});

package/dist/wavetable-read.d.ts

@@ -0,0 +1,6 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+/** Construction helper, not a resident/runtime API. Keep the cycle-local fraction
+ * separate from the absolute integer offset so tiny phase contributions survive
+ * at nonzero frames/bands even against the full finite float32 PCM range. */
+export declare function readWavetableCycle(sample: ResidentSample, phase: Node<'f64'>, start: Node<'i32'>, length: number): Node<'f32'>;

package/dist/wavetable-read.js

@@ -0,0 +1,11 @@
+import { f32, f64, i32 } from '@unworklet/core';
+/** Construction helper, not a resident/runtime API. Keep the cycle-local fraction
+ * separate from the absolute integer offset so tiny phase contributions survive
+ * at nonzero frames/bands even against the full finite float32 PCM range. */
+export function readWavetableCycle(sample, phase, start, length) {
+    const position = phase.mul(length), whole = i32(position.floor()), fraction = position.sub(f64(whole));
+    const a = sample.read(f64(start.add(whole)), start, start.add(length), false);
+    const b = sample.read(f64(start.add(whole.add(1).mod(length))), start, start.add(length), false);
+    // Convex weighting avoids cancellation in a+(b-a)*fraction near the endpoint.
+    return f32(f64(a).mul(f64(1).sub(fraction)).add(f64(b).mul(fraction)));
+}

package/dist/wavetable.d.ts

@@ -0,0 +1,29 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+export interface WavetableConfig {
+    sampleRate: number;
+    /** Shared mono PCM. Concatenate complete cycles, without duplicate end samples. */
+    sample: ResidentSample;
+    /** Samples per cycle, integer4..4096. */
+    frameLength: number;
+    /** Fixed number of morph frames, integer1..16; total must fit resident capacity. */
+    frameCount: number;
+    /** Initial/reset phase in cycles, [0,1). */
+    phaseCycles?: number;
+}
+export interface WavetableControls {
+    /** Hz clipped to [0,.45*sampleRate], NaN becomes0. */
+    frequencyHz: Node<'f32'>;
+    /** Fractional frame index, clipped to [0,frameCount−1], NaN becomes0. */
+    frame: Node<'f32'>;
+    /** Level-sensitive phase reset. A resident revision also restarts phase. */
+    reset: Node<'bool'>;
+}
+/** Two periodic linear cycle interpolations and frame morph. No automatic bandlimit. */
+export declare const wavetableSource: import("@unworklet/core").SubgraphDecl<[config: WavetableConfig], {
+    tick(c: WavetableControls): {
+        output: Node<"f32">;
+        missing: Node<"bool">;
+    };
+}>;
+export { bandedWavetableSource, prepareWavetableBands, type BandedWavetableConfig, type PreparedWavetableBands, type WavetableBandsOptions } from './wavetable-bands.js';

package/dist/wavetable.js

@@ -0,0 +1,49 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+import { readWavetableCycle } from './wavetable-read.js';
+function integer(value, low, high, name) {
+    if (!Number.isInteger(value) || value < low || value > high)
+        throw new RangeError(`${name} must be an integer in [${low},${high}]`);
+}
+function bounded(value, high) {
+    return select(value.eq(value), f64(value), f64(0)).clamp(0, high);
+}
+/** Two periodic linear cycle interpolations and frame morph. No automatic bandlimit. */
+export const wavetableSource = defineSubgraph((config) => {
+    const { sampleRate, sample, frameLength, frameCount, phaseCycles = 0 } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('wavetable sampleRate must be in [8000,192000] Hz');
+    integer(sample.capacity, 4, 65536, 'resident capacity');
+    integer(frameLength, 4, 4096, 'frameLength');
+    integer(frameCount, 1, 16, 'frameCount');
+    const required = frameLength * frameCount;
+    if (required > sample.capacity)
+        throw new RangeError('wavetable frames must fit resident capacity');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    // Phase accepts f64 configuration, including Number.MIN_VALUE: scaling
+    // by 2^1020 keeps even that value above the native 1e-30 flush. Phase
+    // is always <1 before scaling, leaving >16x finite headroom. Morph is
+    // f32 input and only needs 2^128; neither scaled value touches PCM.
+    const scale = 2 ** 1020, frameScale = 2 ** 128;
+    const phase = state.f64(phaseCycles * scale).named('scaledPhase'), revision = state.i32(-1).named('revision');
+    // Native materialization bounds capture size even when resident.read expands
+    // its four wrap/validation paths. These are ordinary same-schema snapshot slots.
+    const current = state.f64(phaseCycles * scale).named('scaledCurrentPhase'), scan = state.f64(0).named('scaledFrame');
+    const lower = state.i32(0).named('lowerStart'), upper = state.i32(0).named('upperStart');
+    return { tick(c) {
+            const changed = sample.revision().eq(revision.read()).not();
+            current.write(select(c.reset.or(changed), f64(phaseCycles * scale), phase.read()));
+            scan.write(bounded(c.frame, frameCount - 1).mul(frameScale));
+            const frame = scan.read().div(frameScale), p = current.read().div(scale);
+            lower.write(i32(frame.floor()).mul(frameLength));
+            upper.write(i32(frame.floor()).add(1).min(frameCount - 1).mul(frameLength));
+            const a = readWavetableCycle(sample, p, lower.read(), frameLength);
+            const b = readWavetableCycle(sample, p, upper.read(), frameLength);
+            const missing = sample.length().lt(required), mix = frame.sub(frame.floor());
+            const output = select(missing, f32(0), f32(f64(a).mul(f64(1).sub(mix)).add(f64(b).mul(mix))));
+            phase.write(p.add(bounded(c.frequencyHz, .45 * sampleRate).div(sampleRate)).frac().mul(scale));
+            revision.write(sample.revision());
+            return { output, missing };
+        } };
+});
+export { bandedWavetableSource, prepareWavetableBands } from './wavetable-bands.js';

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.