@denaudio/den 0.0.0-stage → 0.2.0

package/docs/delay-settings.md

@@ -0,0 +1,111 @@
+# Chorus and rhythmic delay candidates
+
+Two plain configuration/value objects use the existing `delayFx` engine. They add
+no DSP, serializer, parameter registry, runtime, or UI. `chorusSettings` and
+`rhythmicDelaySettings` are exported by `@denaudio/den/delay-settings`. Values map directly to existing engine inputs / AudioParams. Supply
+`sampleRate` from the processor context, and spread the config to select a different
+fixed capacity before construction. Two seconds is a candidate allocation, not a
+product limit. Tone mode and stereo phase are construction configuration.
+
+| Setting | Time | Motion | Feedback / tone | Linear wet mix |
+| --- | --- | --- | --- | --- |
+| Chorus | 18 ms both channels | 0.65 Hz, ±3 ms; opposite phase | 0 / flat | 0.45 |
+| Rhythmic delay | 120 BPM; dotted eighth left (375 ms), quarter right (500 ms) | disabled | 0.48 / 3200 Hz low-pass in feedback, Q=0.5 | 0.35 |
+
+Chorus aims for slow stereo widening with audible pitch motion and dry/wet comb
+coloration. Mono sources are explicitly duplicated; averaging the stereo output
+can alter that coloration. Rhythmic delay aims for interleaved repeats that darken
+with each pass. The first echo is unfiltered. Neither candidate has listening
+approval. Changing source or controls uses the engine's existing inputs; changing
+config requires reconstruction. Settings objects are compile-time readonly data,
+not runtime-frozen objects or saved state.
+
+## Acoustic behavior
+
+Times and tempo jump immediately: a moving readhead can click and change pitch;
+there is no crossfade or smoothing. Continuous chorus modulation deliberately
+changes pitch. Rate zero holds phase; depth zero removes modulation. The 15–21 ms
+chorus range fits the proposed capacity. At 30 BPM the rhythmic right tap reaches
+the two-second boundary exactly. Requests beyond configured capacity or BPM
+30–300 are rejected as unity dry, not silently changed into another rhythm.
+Modulation is bounded to the engine limits, with clipping reported separately.
+
+Stopping input preserves repeats. Bypass emits unity dry, blocks new input to
+history, and lets the internal tail decay; unbypass can expose it. Reset clears
+history/filter/phase immediately and may click. No output normalization or limiter
+is applied. Use headroom when feeding correlated dry and delayed signals.
+
+## Verification and reproduction
+
+Run `npm ci`, `npm run check`, `npm test`, then
+`node scripts/render-delay-settings.mjs` after building. Candidate plotting uses
+Python with NumPy and Matplotlib (no package/lock change); its versions are recorded.
+Generated files remain under ignored `artifacts/delay-settings/`. Run generation
+from the exact reviewed commit; `sourceDirty` and hashes disclose provisional runs.
+
+Dedicated tests cover both settings at 44.1/48/96 kHz with an unbounded written
+sample timeline and independent direct-form bilinear biquad using `Math.tan`.
+They verify mono duplication/opposite phase, zero-depth/same-phase collapse,
+chorus quarter-cycle rate/depth with a closed-form ramp, rhythmic impulse positions
+and integrated second-echo gain, tail, abrupt edits, capacity/tempo rejection,
+modulation clipping, bypass/reset and silent-instance isolation. A shifted oracle
+must fail. The 44.1-kHz left tap is fractional; the second repeat starts at twice
+the earlier interpolation tap, not floor(twice the ideal delay).
+
+Normal candidate renders use a 5e-6 absolute sample tolerance and exact status bits.
+The 50-ms-depth stress case uses a separately calculated float-time rounding
+budget: two time ULPs times sample rate, the input's maximum adjacent slope and
+wet mix, divided by `(1-feedback)^2`, plus 2e-6. This accounts for the bounded sine
+approximation and ideal sine straddling rounding ties; it is not a golden update.
+The independent oracle rounds the 50-ms clamp constant to float32. Engine source
+is unchanged. Packed settings are rendered in an isolated installed tarball at
+all three offline rates. The existing engine browser gate remains 48 kHz only.
+
+## Listening packet
+
+Four short candidates: each setting's base sound and an edited version. Each has
+raw float32 stereo input/output WAVs and a static waveform with the same time and
+amplitude axes. The WAV encoder/decoder must round-trip samples exactly. Source
+stops at two seconds; the rest exposes the tail. Edited clips change rate/depth
+or tempo/feedback at 1.5 s, bypass at 3 s, unbypass at 3.5 s, and reset at 4.5 s.
+The manifest contains every setting, sample-indexed edit, deterministic input
+formula and actual input file, source/dependency hashes, rate/length, raw audio
+hashes, waveform hashes, peak values and independent numerical errors. There is
+no MIDI or random source. No loudness-matched derivative is included.
+
+These are **initial reference CANDIDATES**, with no approved old audio or golden.
+Human approval must name the source/settings/audio hashes in a separate record;
+any sound-affecting update requires regeneration. Code checks alone do not approve
+tone, widening, repeat balance, edit clicks or bypass/unbypass feel. The shared
+frontend now exposes both settings in the integrated sound/FX candidate. Existing
+owner feedback is recorded in [initial acceptance](initial-acceptance.md), separately
+from the generated manifests and exact-hash golden approval.
+
+The checked-in `delay-settings-candidate.json` is the small provenance manifest
+for source commit `ace4deafaf41f8c4336df7fdb532bbac10a6be42`. Audio and images are
+excluded from Git. Regenerate them with the command above into `artifacts/`, the
+repository's existing CI artifact-upload path. The recorded audio remains
+CANDIDATE, even when the mechanical checks pass. A documentation-only commit does
+not invalidate the recorded source/file hashes.
+
+For focused review, after `npm ci && npm run build` run:
+
+```sh
+npm run check
+npx vitest run tests/delay-settings.spec.ts
+node --test tests/delay-settings-packed.test.mjs
+```
+
+The dedicated packed check installs the tarball into a separate locked consumer
+and tests both settings at 44.1/48/96 kHz. Its package and verification files are
+also written under `artifacts/delay-settings/`. Candidate audio generation is an
+explicit local step; the current workflow does not automatically run the plotting
+script. Publishing the listening packet through CI requires the integration
+owner's existing artifact workflow; no preview/deployment settings are changed here.
+
+After integrating main `91c45c5c58ea4c2cb0a30bcbdf84dc56097ed0cd`, both settings
+and their numerical tests remain unchanged. The shared filter update is inherited
+from main. All four regenerated input WAVs, raw output WAVs and static waveform
+images match the previous candidate hashes exactly; this is reproducibility
+evidence, not listening approval. The manifest records the new source commit and
+filter source hash.

package/docs/dependency-findings.md

@@ -0,0 +1,58 @@
+# unworklet compatibility findings
+
+The current checks use registry-installed **0.6.0** packages and the checked-in
+locks. The initial 0.4.1 findings are retained below as historical context; fixes
+are checked against their correct behavior rather than preserving upstream bugs.
+No unworklet source or package internals are patched.
+
+| Issue | 0.4.1 observation | 0.6.0 regression check and remaining constraint |
+| --- | --- | --- |
+| [#78](https://github.com/yuichkun/unworklet/issues/78) | A pre-render snapshot stored gain 0 instead of initial 0.5; suspended edits stored the last rendered value. | Real Chromium snapshots retain initial 0.5 and a suspended edit to 0.25. Rendering verifies 0.5 → 0.25 → restored 0.5 at 44.1/48/96 kHz. |
+| [#79](https://github.com/yuichkun/unworklet/issues/79) | Restoring f32(1) into a same-name i32 slot yielded the reinterpreted bits 1065353216. | The incompatible slot is skipped and keeps its initial i32 value 7. den promises identical-schema/rate continuation; deliberate type changes still need a reviewed migration. |
+| [#96](https://github.com/yuichkun/unworklet/issues/96) | duration=896/48000 executed 8 blocks instead of 7. | Exact 896- and 256-sample durations execute 7 and 2 default quanta. |
+| [#98](https://github.com/yuichkun/unworklet/issues/98) | Unity DC measured 6.021 dB. | Unity DC measures 0 dB; the helper rejects the doubled-gain expectation. Direct sample comparisons remain independent checks. |
+| [#104](https://github.com/yuichkun/unworklet/issues/104) | A default config `{name:'default'}` swallowed `{name:'x'}`, producing 7 instead of 1. | **Still reproduced.** Required config plus a separate explicit instance name renders 1; den continues to use this form. |
+| [#106](https://github.com/yuichkun/unworklet/issues/106) | A lang type import under TS 5.9.3 ESNext failed with Volar TS2416. | Both ES2023 and ESNext pass strict checking with `skipLibCheck:false`. The consumer keeps ES2023 without a declaration shim. |
+
+The 0.5.0 and 0.6.0 [upstream changelog](https://github.com/yuichkun/unworklet/blob/v0.6.0/CHANGELOG.md)
+describes the snapshot, duration, gain, declaration and compilation changes.
+`tests/dependency.spec.ts` and the packed browser entry test independently check
+the paths above. `expectAudioMatches` accepts an independently calculated
+one-sample memory and rejects an intentionally incorrect answer. No audio golden
+is regenerated or approved by these tests.
+
+Reviewed but not independently reproduced here: #95 (snapshot matcher name reuse)
+and #97 (integer WAV golden scale). This gate uses float WAV output and direct
+sample assertions. Build/HMR reuse (#100/#101/#102), arbitrary schema migrations,
+SIMD, DevTools and other APIs remain outside this fixture's coverage.
+
+## Browser sample rate and render quantum
+
+The packed entry consumer renders at **44100, 48000 and 96000 Hz** through the
+public `?worklet` import and `createNode`. At non-default rates, unworklet 0.6.0
+compiles in its generated Web Worker for the actual AudioContext. The test checks
+real output, live gain changes and snapshot restoration at each rate, and records
+the actual rate and quantum in the browser evidence. Offline sample-rate coverage
+is recorded separately; it is not substituted for browser evidence.
+
+A processor compiled directly, including the playground's compiler worker, must
+receive `{ sampleRate: context.sampleRate, renderQuantumSize:
+context.renderQuantumSize ?? 128 }`. Its runtime metadata and schema hash must
+come from that compile result. The playground browser gate separately checks
+44.1/48/96 kHz with 32/128/256-sample quanta. Fixed-length DSP buffer traversal uses
+`forIndex`; FFT lengths and sample-based hop periods are not render quanta.
+See the [spectral contract](spectral.md) for snapshot dispatch behavior.
+
+These tests establish the listed contexts and operations, not arbitrary device
+performance or realtime deadline clearance. Cross-rate snapshot continuation and
+human sound approval remain outside this gate.
+
+## Tooling security
+
+Vite remains pinned to **7.3.6** in the package and isolated consumers. The former
+7.3.1 pin was affected by
+[GHSA-p9ff-h696-f583](https://github.com/vitejs/vite/security/advisories/GHSA-p9ff-h696-f583)
+and other reported advisories. The gate serves a production preview on
+`127.0.0.1`; it does not expose a development server to the network. Locks retain
+the patched esbuild dependency. Root and consumer audit results are checked after
+installation.

package/docs/deployment-status.md

@@ -0,0 +1,37 @@
+# Code playground deployment
+
+The previous public UI was deleted and its production routes and asset URLs
+verified absent before this replacement was started. The new root is an
+English, code-first playground. It is a work-in-progress Preview until the
+replacement PR's exact-head browser, review and CI gates are accepted.
+
+The production command remains `npm run build:site`, with output `site-dist/`
+and no Vercel project, access, authentication, domain or security-setting
+changes. The builder packs the current repository source, installs the isolated
+`playground/` consumer from its lockfile, checks its types and exhaustive public
+export/example coverage, and replaces the public output with its built files.
+Actual package, declaration and example hashes are emitted in `provenance.json`.
+
+`/catalog.html`, `/audition.html`, `/diagnostics.html`, `/playground.html` and
+former asset paths remain absent. No old product page is redirected or hidden
+behind the editor. The only public application route is `/`, with `?module=`
+selecting a bundled example without autoplay.
+
+Library/DSP sources, exports and history are preserved. Historical browser
+surfaces remain test fixtures only. `tests/site-fixture-build.mjs` builds them
+outside public output, preserving all earlier numerical, native state, MIDI,
+keyboard/touch and interrupted-audio assertions. The production build never
+calls that fixture helper.
+
+`tests/site-removal.test.mjs` poisons the public directory with old routes and
+assets and verifies they are physically removed. `tests/site.test.mjs` tests the
+actual packed replacement: Monaco assistance, editable sources, native audio,
+Run/Stop/retry/cancellation, navigation/search and mobile layout. Its dedicated
+Preview job runs a bounded generator/effect slice for early feedback; full
+entry runs every example. Screenshots and manifests retain the exact source
+and packed-package identity. Browser checks and listening approval are separate.
+
+All development commands (`build:consumer`, `build:integration`, `build:catalog`
+and the manual realtime probe) use isolated temporary output.
+`buildConsumer({stageSite: true})` is rejected before packing/installing.
+Only `build:site` owns public `site-dist`.

package/docs/drive.md

@@ -0,0 +1,152 @@
+# Drive, fixed waveshapers, and reduction
+
+Status: **CANDIDATE**. This implements catalog §7's fixed curves and a separate
+intentional reduction effect. It is not an approved sound or a claim of matching
+another product. Import `drive` and `reduction` from `@denaudio/den/drive`.
+
+## Contract
+
+Both are mono `defineSubgraph` modules, instantiated with an immutable config
+containing the enclosing processor's `sampleRate` in [8000, 192000] Hz. Call each
+instance exactly once per audio sample. Their state is fixed, independently named,
+and handled by unworklet 0.4.1's existing snapshot mechanism. No parameter,
+snapshot, routing, loader, or test framework is introduced.
+
+`drive` config additionally requires `curve: 'hard' | 'soft' | 'asymmetric' |
+'fold'`. `quality: 'direct' | 'adaa'` defaults to `'adaa'`. `dcBlockHz` defaults to
+0 (off); its finite range is [0, 200] Hz. Invalid config throws at construction.
+
+`tick(input, gain, mix, reset)` takes three f32 nodes and a bool reset. Input is
+clamped to [-8,8], gain is a **linear multiplier** in [0,32], and mix is [0,1].
+There is no automatic loudness compensation. NaNs become 0; infinities saturate
+to the appropriate bound. These policies also apply to the dry path. Nonzero wet
+gain is not a promise that output loudness matches the input.
+
+Reset clears histories **before processing the current sample**. Construction
+also starts with zero histories. In ADAA mode, the first interval is therefore
+from zero to the current driven input. Quality and curve are construction choices,
+not runtime switching controls; same-schema snapshot continuation is tested.
+Changing quality, curve, or DC configuration and migrating a snapshot is not
+supported by this module's contract. The host must construct a fresh graph and
+choose its own audible transition if changing those choices.
+
+All audio-rate gain changes are interpreted as changes in the driven signal
+`x[n] = gain[n] * input[n]`; ADAA integrates between consecutive driven values.
+There is no hidden gain smoothing. Arbitrary fast modulation can still generate
+sidebands/aliasing. Mix is audio-rate and immediate.
+
+## Transfer curves and their antiderivatives
+
+The driven input is bounded to [-256,256]. Let `S(x)` be the clipped cubic:
+
+- For |x| <= 1: `S(x) = 1.5*x - 0.5*x^3`
+- Outside: `S(x) = sign(x)`
+
+Its continuous first antiderivative, with F(0)=0, is `0.75*x^2 - 0.125*x^4`
+inside [-1,1], and `|x| - 0.375` outside.
+
+- `hard`: clamp(x,-1,1); primitive `x^2/2` inside and `|x|-1/2` outside.
+- `soft`: S(x); unity positive endpoint, small-signal slope 1.5.
+- `asymmetric`: S(x) for x >= 0, and S(2*x)/2 for x < 0. Its primitive is F(x)
+  on the positive side and F(2*x)/4 on the negative side. Output range [-0.5,1].
+  This curve can create DC from a zero-mean input; the optional blocker is useful.
+- `fold`: triangular folding with period 4 and values 0,1,0,-1,0 at inputs
+  0,1,2,3,4. Let t=(x+1) modulo 4 in [0,4). Output is `1-|t-2|`; its continuous,
+  periodic primitive is `t^2/2-t+1/2` for t <= 2 and `3*t-t^2/2-7/2` otherwise.
+
+Direct quality samples these curves without AA. ADAA computes
+`(F(x[n])-F(x[n-1]))/(x[n]-x[n-1])` using f64 arithmetic. For a difference <=1e-5,
+it uses the curve at the interval midpoint, protecting even the unselected
+division because unworklet selects evaluate both branches. The maximum slope
+of these curves is 1.5, so the midpoint replacement error is bounded by
+`1.5*|difference|/4 <= 3.75e-6`, including a knot crossing. Smooth cubic interiors
+have a second-order error. This is a difference criterion, not an exclusion of
+quiet audio. Histories use exact power-of-two scaling to retain recoverable f32
+subnormals through unworklet's <1e-30 state-write flush.
+
+### AA and dry-path tradeoff
+
+First-order ADAA is appropriate here because these are **fixed memoryless curves**
+with continuous analytic primitives. It is not a generic wrapper around arbitrary
+nonlinear/stateful circuits, oversampling, or a guarantee of bandlimited output.
+No claim is made about an inner oversampled state/sample-rate API.
+
+For a linear portion, ADAA is a two-sample average: half-sample group delay and
+gain `cos(pi*f/sampleRate)` below Nyquist, with a zero at Nyquist. Its dry path is
+the same two-sample average, preventing a dry/wet mismatch in the linear region.
+It is **not transparent bypass** at mix=0. Direct quality has an undelayed dry path.
+There is no integer lookahead or block buffering. Nonlinear high-frequency
+behavior is not equivalent to a constant fractional delay; heavy folding can
+lose substantial fundamental energy. The tests record both absolute folded
+energy and fundamental amplitude, without loudness normalization hiding this.
+
+### Optional DC blocker
+
+The wet path only uses `y[n]=w[n]-w[n-1]+p*y[n-1]`, where
+`p=exp(-2*pi*dcBlockHz/sampleRate)`. Zero disables its state and processing.
+This adds phase shift and a slightly above-unity high-frequency gain; it is not
+an alias-removal filter. Mix=0 stays on the mode's dry path. Reset clears both
+blocker histories. Step decay, actual digital corner response, and snapshot
+continuation are tested. Sudden resets/mix changes are not click-free promises.
+
+## Intentional bit/sample reduction
+
+`reduction.tick(input, bits, holdSamples, mix, reset)` clamps input to [-1,1]. Bits
+are floored in [2,24], and holdSamples are floored in [1,4096]. NaN defaults are
+input=0, bits=24, holdSamples=1, mix=0; infinities saturate. These are fixed-size
+state controls, not allocations.
+
+With L=2^(bits-1), quantization is nearest signed PCM with exactly 2^bits levels:
+`clamp(floor(x*L+0.5),-L,L-1)/L`. Ties round toward positive infinity; the maximum
+is 1-1/L, the minimum is -1, and silence is exact zero. The positive/negative
+endpoint asymmetry is intentional and documented rather than a gain bug.
+
+Capture happens on the first sample, reset sample, or when the current hold ends.
+Bits and period changes take effect **at the next capture**, not mid-hold. A
+period of N emits that captured value for exactly N samples. The dry path has
+no delay and mix changes immediately. There is no antialias filter: quantization
+and sample holding intentionally add distortion and aliasing. It is unsuitable
+for transparent sample-rate conversion. Same-schema snapshots retain both held
+audio and remaining count.
+
+## Evidence and limits
+
+`tests/drive.spec.ts` covers 44.1/48/96 kHz with independent scalar curves and
+segmented Simpson quadrature (not copied primitives), both sides of curve knots,
+near-equal input, extreme drive, signed quantizer levels, hold timing/control
+changes, impulses, reset boundaries, independent instances, tiny state, graph
+NaN/infinity controls without output scrubbing, and exact snapshot continuation.
+It also checks cubic THD/IMD coefficients, optional DC step/corner response, and
+the mode's dry-path phase/gain behavior. A bypass counterexample fails the oracle.
+
+Alias fixtures are 8192-frame coherent sines at bins 997 and 1709, amplitude 3,
+after a full warmup period. Projection removes DC and only harmonics below
+Nyquist. Across the four curves the observed first-order ADAA reduction in
+remaining folded RMS is **7.96–9.47 dB** relative to direct quality, exceeding
+the unchanged >=6 dB test requirement. Rates use the same normalized frequencies;
+these are specific synthetic fixtures, not universal audible-quality guarantees.
+At bin 1709, heavy folding's fundamental falls from approximately 0.5015 to 0.0939
+while folded RMS falls from 0.5535 to 0.1889. Choose direct quality when that
+intentional aggressive high-frequency behavior is wanted; compare candidates.
+
+`tests/drive-packed.test.mjs` installs a tarball into a locked isolated consumer,
+checks public `/drive` declarations, renders all curves/qualities and reduction,
+applies independent numerical checks, and records source/audio/package hashes.
+All generated audio and manifests remain **CANDIDATE**, requiring separate human
+approval. The lane has no local browser/realtime performance proof.
+
+Bounded user-editable piecewise-linear curves are now a separate
+[curve-shaper candidate](curve-shaper.md). Remaining work: higher-order ADAA, verified
+oversampling wrappers, configurable multistage coloration engines, performance
+and listening comparison. Composing several current instances is possible but
+does not establish an oversampling or multistage-quality guarantee.
+
+Method reference: Werner & Azelborn, [Antialiasing Piecewise Polynomial
+Waveshapers, DAFx 2023](https://www.dafx.de/paper-archive/2023/DAFx23_paper_61.pdf).
+This implementation derives the four simple primitives above and validates them
+independently; no reference implementation or vendor audio was copied.
+
+The separate [fixed oversampled drive](oversampled-drive.md) candidate now covers
+a bounded 2×/4× memoryless composition. Its filtered dry path, FIR precursors,
+32-sample bulk delay and high-treble loss are explicit; this does not add general
+arbitrary-graph oversampling or higher-order ADAA to this module.

package/docs/dual-head-delay.md

@@ -0,0 +1,131 @@
+# Dual-head delay-time transitions — candidate contract
+
+`dualHeadDelay` at `@denaudio/den/dual-head-delay` is an additive mono delay
+primitive. The initial `delayReadhead`, Delay/Chorus, tempo policy and existing
+sounds are unchanged. This candidate supports bounded delay-time transitions by
+crossfading two fixed delay offsets. It is not a pitch shifter or time stretcher.
+
+## API and construction
+
+```ts
+const delay = instantiate(dualHeadDelay, {
+  sampleRate: ctx.sampleRate,
+  maxDelaySeconds: 2,
+  transitionSamples: 256,
+}, { name: 'transitionDelay' });
+// Exactly once per sample:
+const { output, transitioning, timingRejected } = delay.tick(input, timeSeconds, reset);
+```
+
+For same-sample feedback or processing before history is written:
+
+```ts
+const tap = delay.read(timeSeconds, reset);
+tap.write(input.add(tap.output.mul(0.5)));
+output.write(tap.output);
+```
+
+Use exactly one `tick`, or one `read` followed by one call to that read's `write`,
+per sample per instance. The object and closure exist at graph construction only.
+No allocation occurs on the audio thread. Audio and seconds are f32 nodes; reset
+and both diagnostics are boolean nodes. Input audio must be finite. No parameter,
+state, routing or loader framework is introduced; use native unworklet 0.4.1 APIs.
+
+Construction requires integer `sampleRate` in 8000..192000, matching the enclosing
+processor, capacity from one sample through eight seconds (default two seconds),
+and integer `transitionSamples` in 2..65536 (default 256). These are tested candidate
+implementation bounds, not general product or real-time capacity claims. Allocation
+is one fixed f64 history of `ceil(sampleRate * maxDelaySeconds) + 2` values, plus
+scalar state. At the maximum eight seconds/192 kHz this is 1,536,002 history
+values, or 12,288,016 history bytes. The measured packed four-output fixture uses
+12,320,768 bytes of native WASM memory at that capacity, unchanged across its
+allocation/tiny-signal smoke. There is no resize or dynamic per-request buffer.
+
+## Timing and rapid requests
+
+Times are accepted within the f32-representable endpoints
+`[f32(1/sampleRate), f32(maxDelaySeconds)]`. Conversion to sample offset uses f64,
+with only endpoint rounding clamped to the exact capacity. Invalid finite times,
+NaN and infinities are rejected, `timingRejected=true`, and the last valid request
+is retained. They do not silently replace an unavailable musical time with a
+clamped rhythm. A fresh or reset instance with an invalid time starts at one sample.
+
+The first sample, and every reset sample, captures the valid current request
+immediately, without a startup fade. Later distinct accepted delays start a fade
+only when the previous fade is finished. For a transition starting at sample `s`
+with length `L`, the current output is
+
+`(1 - a) * x[n - oldDelay] + a * x[n - newDelay]`,
+where `a = (n - s)/(L - 1)` for `s <= n < s + L`.
+
+The request sample is old-only; sample `s+L-1` is new-only. Both delay offsets stay
+fixed for that whole fade. `transitioning` is true on all L samples, including
+both endpoints. An unchanged accepted delay causes no fade. A change while fading
+updates a single latest-valid-request slot; it never moves either active head,
+interrupts the fade, or starts a third head. After the fade ends, the most recent
+accepted request starts another fade on the next sample if it differs from the
+settled target. A request back to the old delay therefore completes the outward
+fade before returning. A request back to the active target removes a stale queued
+request. Invalid requests leave this queue alone. This bounded coalescing policy
+can skip intermediate automation values.
+
+An idle change reaches its requested endpoint L-1 samples after its request. A
+request during an existing fade may wait for that fade and a second full fade;
+newer requests may supersede it. Continuous modulation has no exact tracking or
+uniform control-latency guarantee. This is a control transition duration, not an
+additional audio lookahead delay. Audio is always read before the current input
+is written, so the minimum audio delay is one sample; there is no zero-delay dry
+feedthrough.
+
+## Interpolation, gain, phase and tails
+
+Each fixed head linearly interpolates its two adjacent source samples. For offset
+`k+f`, this is `(1-f)*x[n-k] + f*x[n-k-1]`. The interpolation response is
+`(1-f)+f*exp(-j*w)` apart from integer delay; the half-sample case reaches zero at
+Nyquist. The transition is a linear amplitude crossfade rather than equal power.
+All four source weights are nonnegative and sum to one, so finite input extrema
+are not exceeded by this primitive. Correlated in-phase heads retain unity gain;
+uncorrelated heads dip in energy at the midpoint, and opposite-phase heads can
+cancel. The two times can create comb filtering, transient smearing, duplicated
+or skipped content, and modulation sidebands. A sine maintains its original
+frequency at each fixed head, but the overlapping signal need not maintain its
+amplitude or phase during a transition. No arbitrary-modulation Doppler-free,
+antialiasing, click-free, seamless or ideal pitch-preservation claim is made.
+
+There is no internal feedback, dry/wet, bypass, limiter or gain compensation.
+Callers compose those explicitly. An undelayed dry mix combs against the wet delay;
+both branches have no implicit alignment. Convex dry/wet preserves the primitive's
+input peak bound. Feedback changes that bound: for a constant magnitude feedback
+below one, the history can be bounded by inputPeak/(1-abs(feedback)); external
+filtering, gain, clipping and modulation are the caller's responsibility. The
+read-before-write API adds no extra circulation sample beyond the selected delay.
+
+Stopping input lets stored source samples finish. Without feedback, no stored
+contribution survives beyond `ceil(sampleRate*maxDelaySeconds)` samples after the
+last nonzero input, even through requests. A transition can expose earlier history
+or spread an impulse across both heads, so its tail is not a single echo. External
+feedback extends the tail. Reset cancels transitions and logically invalidates all
+prior history before the read; the current input is then the first new sample.
+Held reset remains silent. Reset can click and is not a bypass or memory-erasure API.
+
+## Numerical state and verification boundary
+
+History is multiplied by exact `2**128` before f64 storage and divided after the
+weighted read. This avoids native buffer scrubbing of tiny valid f32 samples and
+keeps full-range finite f32 weighted sums inside f64. It does not recover a result
+below f32's representable range. Stable named state records history, cursor, valid
+count, initialized state, current/target/queued delays and remaining fade samples.
+Snapshot continuation requires the same schema, sample rate, capacity and fade
+length. Logical reset does not physically wipe old snapshot bytes.
+
+The dedicated tests compare native rendering with an independent unbounded source
+timeline and absolute-time transition schedule, plus analytic impulse, sinusoidal,
+phase/cancellation and feedback assertions. They cover rapid changes, invalid
+controls, minimum/maximum and fractional wraps, reset, instance isolation,
+full-range and tiny finite audio, and in-flight snapshot continuation at 44.1/48/96
+kHz. The isolated packed consumer uses the public subpath, strict declarations,
+native parameter edits and actual rendering. Audio remains CANDIDATE, not an
+approved golden. Local cost reports are diagnostic only: an initial 96 kHz run observed a
+4.655 ms warm quantum against a 1.333 ms nominal budget. Host jitter and cold
+execution are not hidden by median timings. No browser, hardware
+real-time deadline, general pitch/time processing or listening approval follows.