@denaudio/den 0.0.0-stage → 0.2.0

package/docs/mpe-expression.md

@@ -0,0 +1,65 @@
+# Bounded lower-zone expression candidate
+
+Status: CANDIDATE. `mpeExpression` is an expression-routing primitive for a manually configured MIDI 1.0 lower zone. It is not a complete MPE receiver, MPE compliance certification, a voice allocator, a pedal implementation, a MIDI runtime or an instrument.
+
+## Entry and values
+
+The public entry is `@denaudio/den/mpe-expression`, exporting `mpeExpression`, `MpeExpressionConfig` and `MpeExpressionVoice`.
+
+Instantiate `mpeExpression({ memberChannels, memberBendRange, masterBendRange })` once. `memberChannels` is a fixed integer 1..15, default 15. Native channels are zero-based: master channel 0 (musician-facing channel 1), member channels 1..N (musician-facing channels 2..N+1). Bind once to the same existing `event.midi({from:'main',name:...})` handle as `performancePolicy` or `voicePolicy`. Multiple native handlers share the port; the module neither wraps nor resends MIDI.
+
+Pass an allocator voice's unchanged `active` and `channel` fields to `read(voice)`. The returned `inZone` is true only for an active member channel. Every numeric output is zero for inactive voices, master-channel notes, channels outside the configured zone or invalid channel indices. A clamped internal buffer index never turns an invalid channel into a valid member.
+
+- `memberBend` and `masterBend`: normalized -1..1. MIDI bend 8192 is exactly zero; 0 is -1 and 16383 is +1. The negative half divides by 8192 and positive half by 8191.
+- `bendSemitones`: member normalized bend times `memberBendRange`, plus master normalized bend times `masterBendRange`. Ranges are symmetric semitones, finite 0..96, construction-fixed, with defaults 48 and 2 respectively. Addition uses f64 intermediates and one final f32 conversion. No clipping or note-frequency conversion is applied here.
+- `memberPressure` and `masterPressure`: channel-pressure bytes normalized 0..127 to 0..1, initially zero. These are separate lanes. A composition chooses how they affect sound and whether to combine them.
+- `memberTimbre` and `masterTimbre`: CC74 bytes normalized 0..127 to 0..1, initially 64/127. The default is the exact MIDI byte center, approximately 0.503937, not 0.5. Raw timbre is not intrinsically bipolar. These are separate lanes with no invented timbre destination or combination law.
+
+Use `bendSemitones` exactly once in the pitch path. When composing with `performancePolicy`, do not also add its `bend`, which represents the same member-channel message. Add any independently desired tuning/transpose controls separately. Pressure/timbre from the existing policy also represent the same incoming bytes and must not be accidentally applied twice. No pitch smoothing is provided.
+
+## Notes, tails, steals and pedals
+
+The existing allocation policy alone owns note-on/off, velocity-zero note-on, duplicate pairing, held identities, overflow, voice stealing, mono priority, gate/retrigger, pedal and release completion. This module does not filter notes admitted by that policy. A composition wanting member-only sound must use `inZone` to gate its output; master/out-of-zone notes can still consume allocator slots.
+
+Expression is channel state, not a per-note identifier or voice-slot cache. It can be set before note-on and persists after note-off. Every active voice carrying that member channel observes the current channel expression, including multiple same-key identities and release tails. Reusing a member channel while an old tail remains means both the new note and old tail receive later changes. A stolen physical slot immediately reads its replacement's channel; the stolen identity's later note-off retains the original allocator semantics. A free slot emits zero expression. Notes, note-offs, steals, CC120, CC123 and release completion do not themselves reset expression.
+
+With `performancePolicy`, member-channel CC64 sustain continues to work as documented there. Master-channel CC64 is NOT propagated to members. Master CC120 and CC123 also do not become zone-wide panic/all-notes-off. Their handling remains the original allocator's channel-local behavior. This intentionally limited primitive is unsuitable as a drop-in full MPE pedal receiver.
+
+## Reset, timing and snapshots
+
+CC121 resets only the addressed master/member expression state to bend center, pressure zero and timbre byte 64. Master CC121 resets the master lanes only. It does not reset every member. The original allocator/performance policy independently handles that same CC according to its own contract, including its different legacy timbre default. This module's outputs are authoritative for its expression path.
+
+`reset(true)` resets every expression channel; `reset(false)` does nothing. Reset is level-sensitive and does not clear notes, stop audio, raise pedals, generate retriggers, or reset DSP. A composition's full panic must explicitly call the allocation policy reset and clear its envelopes/oscillators as appropriate. Call expression reset after native dispatch if reset should win over MIDI in the same quantum.
+
+All state is native transient integer state and is excluded from the snapshot. A **fresh-instance** restore (including `renderOffline` into a new driver) starts from centered bend, zero pressure and timbre byte 64. Native 0.4.1 **in-place** `node.restore()` only overlays saved slots: it leaves the current expression, notes and pedals unchanged. It neither recalls excluded gestures from the blob nor clears current ones. For a cold in-place restore, use the composition's existing explicit reset for expression, allocation policy and DSP after restoring; let at least one quantum render before fresh notes. Expression-only reset cannot clear notes or silence an orphan envelope. A composition must also clear persistent voice DSP whenever its note identity is absent.
+
+Native unworklet 0.4.1 dispatch is FIFO before each 128-sample process quantum. Multiple messages in a quantum coalesce to the final state. A nominal sample-129 event affects boundary 128. No sample-accurate scheduling, new transport or hardware MIDI claim is made.
+
+## Deliberate exclusions
+
+No upper zone, dynamic zone/RPN negotiation, RPN bend-range updates, MIDI-CI/MIDI 2.0, polyphonic key-pressure interpretation, master-pedal propagation, external MIDI host/device verification or per-note release-tail freezing is implemented. Unsupported messages are ignored by this expression primitive, while other handlers on the native input retain their own behavior.
+
+The MIDI Association's [MPE overview](https://midi.org/midi-polyphonic-expression-mpe-specification-adopted) explains member-channel expression and zone-wide master control. The primitive implements only the manually configured expression subset documented above. The broader catalog's full MPE gap remains open.
+
+## Evidence
+
+The 35 focused tests use byte fixtures with an independent ordinary-object state model at 44.1, 48 and 96 kHz. They cover master/member isolation and bend addition, endpoint/center values, duplicate FIFO pairing, steals and stale note-offs, channel reuse/tails, per-member sustain, explicitly absent master pedal/panic propagation, channel-local CC121, expression-only versus composition-wide reset, empty transient snapshots, unsupported controllers/RPN, native handler registration order and all 15 members.
+
+The packed consumer gate requires strict public-subpath TypeScript, native MIDI/envelope/oscillator rendering at the three offline rates, independent pitch/amplitude equations, zero scrubbed samples, snapshot silence and fresh-note safety. Maximum configured member count is storage coverage, not 15-voice allocation or real-time clearance. No browser, hardware, listening approval or approved golden follows from offline evidence.
+
+The diagnostic composition routes pitch as note plus `bendSemitones`, then applies separate tuning controls. Its amplitude is velocity times a linear envelope times (0.5 + 0.25 member pressure + 0.25 master pressure) times (0.5 + 0.25 member timbre + 0.25 master timbre), with output gain 0.2. This is an explicit test routing, not a standardized MPE sound or preset. The initial packed proof reports zero pitch/level error, maximum audio error below 3.3e-8 and four-voice chord error below 7.7e-8. The four-voice/eight-identity/15-member composition is 719,110 WASM bytes with 65,536 bytes of memory, unchanged over 256 driver blocks. These are functional/fixed-memory results, not deadline clearance. Exact-head package/source/lock hashes and CANDIDATE status are retained in the generated manifest and result pair.
+
+## Retained live-restore finding
+
+The first integrated browser probe on `ed061ca` expected a centered fresh note
+after in-place restore, but observed 187.5 Hz rather than 375 Hz: the current master
+bend of −12 semitones was correctly retained by the native overlay. The fresh-
+driver offline test had not exercised this lifecycle. The corrected browser
+contract separately checks continued held notes/current expression, silence
+when the current note was already released, inherited master expression on a
+new member note, and centered fresh-note audio only after explicit composition
+reset has rendered. This diagnostic composition also tests reset-before-restore
+when a quantum has completed first: its inactive-voice guards clear the restored
+persistent envelope/oscillator tail. General compositions should use the explicit
+reset-after-restore sequence above unless their own ordering is verified. DSP
+statements and upstream restoration are unchanged.

package/docs/musical-clock-seek-boundary.md

@@ -0,0 +1,31 @@
+# Musical clock seek boundary correction
+
+A native entry probe found that negative tiny finite f32 requests such as -2^-60
+and -2^-149 could round to exactly `steps` when wrapped in f64. The old clock
+emitted an invalid `step === steps`, `phase === 0` on that seek sample and stored
+zero position afterward. This violated the existing `[0,steps)` contract.
+
+The repair clamps only the rounded wrapped position to the immediately preceding
+f64 below `steps`, computed at construction as
+`steps - 2**(ceil(log2(steps))-53)`. Already-valid wrapped f64 positions retain their
+values; no extra f32 seek quantization, state slot, rate change, or API is added.
+Exact positive/negative integer boundaries still wrap to their correct step;
+negative tiny seeks remain within the final step, with public phase capped below
+one under the existing f32 phase contract. This cannot recover precision already
+lost when an input f32 was created, and is not arbitrary-precision transport.
+
+`tests/probes/musical-controls-clock-boundary.mjs` preserves a repeatable native
+probe. The pre-repair source SHA256 was
+`5b9c35ef1ecc9b00d97c649c645179dc25560d81d17b74788e2dd8293c1f6dcd`.
+The original output for both -2^-149 and -2^-60 was `(step,phase)=(1,0),(3,0),
+(64,0)` for cycles of 1, 3, and 64, in free and tempo mode, with zero position
+state at the final seek. The original source, f32 input/output bytes and snapshot
+were retained separately before the repair.
+
+`tests/musical-clock-seek.spec.ts` uses exact BigInt f32 units and a bit-adjacent
+f64 upper bound as its independent oracle. It covers every fixed step count
+1..64, free/tempo modes and extreme tempo divisions, positive/negative integer
+neighbors, the input clamp endpoints, tiny negative normal/subnormal requests,
+actual native stored position, and identical same-schema snapshot continuation.
+Existing modulation/arpeggiator regressions remain required. All native evidence
+is CANDIDATE; runtime remains NOT_CLEARED.

package/docs/musical-controls-contract.md

@@ -0,0 +1,144 @@
+# Musical controls candidate contract
+
+This bounded additive lane defines `@denaudio/den/musical-controls`, with
+`curvedAdsr` and `musicalLfo`. Existing envelope, LFO, clock, and MSEG entries stay
+compatible. Package export wiring belongs to the integration owner. This document
+records the independently reviewed entry contract; execution evidence is separate.
+
+Both graphs use fixed state, instantiate once, and tick exactly once per sample.
+Sample rate is an integer in [8000,192000]. All dynamic numeric inputs are finite
+f32 values; NaN and infinity are outside this contract. Sample-rate/configuration changes
+require reconstruction; same-schema snapshots at the same configuration resume
+exactly. No routing, scheduler, MIDI/MPE/RPN, parameter, snapshot, or clock framework
+is added. Generated output remains CANDIDATE; runtime is NOT_CLEARED.
+
+## Curved ADSR
+
+`curvedAdsr({ sampleRate }).tick({ gate, retrigger, reset, attack, decay, sustain,
+release, attackBend, decayBend, releaseBend }) -> { level, done }`.
+
+Gate/retrigger/reset are bool nodes; all other inputs and level are f32 nodes;
+done is bool. Durations are seconds, clamped [0,30], then rounded to the nearest
+sample with half samples up after the f32 input conversion. Sustain clamps [0,1].
+Bends clamp [-1,1]. For a segment of N frames, step k uses t=k/N and
+C(t,b)=t+b*t*(1-t). b=0 is linear, -1 is t² (ease-in), +1 is 2t-t² (ease-out).
+The output is start+(target-start)*C(t,b), with exact endpoint assignment on step
+N. This shapes segment time, preserving the latched sustain target and the
+retrigger/release origin. It is not a post-warp of absolute ADSR amplitude.
+Bend zero specifies a linear curve, not byte identity with the legacy iterative
+envelope, because this module deliberately latches the last emitted f32 level.
+
+- Stages are idle, attack, decay, sustain, release. Idle/reset output zero and
+  done=true. Sustain, including sustain zero, has done=false.
+- A gate rise or high retrigger while gate is high begins attack from the last
+  emitted f32 level. Retrigger is level-sensitive; every high sample restarts.
+- Positive N-frame stages emit step 1 on their entry sample and their endpoint
+  on step N. Attack duration/bend latch on its entry. Decay duration/bend/target
+  latch on the preceding positive attack endpoint, with its first step on the
+  next sample. Release duration/bend latch on the gate-fall sample.
+- Zero attack reaches 1 and immediately enters decay on the same sample. A zero
+  decay then reaches sustain immediately. Zero decay following a positive attack
+  reaches sustain on the next sample. Zero release becomes idle immediately.
+- Gate-off wins over retrigger, releases from the last emitted level, and reaches
+  exact zero/done on release step N. Release from zero becomes done immediately.
+  A positive release origin can round to f32 zero before step N; that does not
+  make done true early. Completion uses the latched segment, not rounded output.
+- Reset wins over gate-off and retrigger, emits zero immediately, clears stage
+  state, and consumes the current gate. A held gate after reset needs a new gate
+  edge or retrigger. Held reset stays idle. Retrigger with gate=false is ignored.
+- Duration, target, and bend edits do not change an active segment. Sustain stage
+  follows the current clamped sustain input every sample. Such live sustain edits,
+  zero durations, and reset can intentionally jump; no implicit smoothing exists.
+- Segment state records exact i32 duration/elapsed values and scaled f64 start,
+  target, bend, and last-emitted level. Power-of-two scaling protects tiny finite
+  f32 values against core 0.4.1 scalar-state flushing. Output rounds to f32.
+
+Independent numerical oracles use the algebraically different Bernstein
+form C=(1+b)*t*(1-t)+t², closed-form event intervals, exact endpoint/done checks,
+manual retrigger/release origins, zero-stage precedence, latching counterexamples,
+maximum-duration sample probes, tiny controls, instance isolation, and identical
+same-schema snapshot continuation at 44.1/48/96 kHz. Assertions distinguish absolute-level warping, wrong endpoints, and incorrect
+latching from the specified behavior. The maximum-duration probes inspect the
+first 383 steps and native latched duration; they do not render a full 30 seconds.
+
+## Tempo/free multiwave LFO
+
+`musicalLfo({ sampleRate, mode, waveform, beatsPerCycle? }).tick({ rate, reset,
+seek, position, phaseOffset, hold }) -> { value, phase }`.
+
+`mode` is fixed `free` or `tempo`; `waveform` is fixed `sine`, `triangle`, `saw`,
+or `square`. `beatsPerCycle` defaults to 1 and accepts powers of two in [1/64,64]
+only in tempo mode; free mode requires 1. Rate/position/phaseOffset and outputs
+are f32; reset/seek/hold are bool.
+
+The implementation composes the existing `musicalClock` with one step per cycle,
+using stepsPerBeat=1/beatsPerCycle for tempo. Free rate is Hz clamped [0,20].
+Tempo rate is BPM clamped [0,1000]; frequency is BPM/(60*beatsPerCycle), up to
+1066 2/3 Hz at the smallest division. No frequency cap changes the tempo ratio.
+That extreme is above conventional LFO rates; use appropriate rates for the
+modulated destination. Position and phaseOffset are in cycles, each clamped to
+[-1048576,1048576]. Position matters only on a rising seek edge. This module
+inherits the existing clock's wrapping and the separately reviewed narrow repair
+in `docs/musical-clock-seek-boundary.md`: a wrapped value that rounds up to the
+cycle length is capped to its immediately preceding f64. Negative tiny seeks
+therefore stay in the last step; exact signed integer seeks reach zero. No extra
+f32 seek quantization is inserted before the clock.
+
+- The initial base phase is zero. Output uses current phase before integrating
+  this sample's rate. Changing rate preserves phase. Rate zero or hold=true stops
+  base-phase integration; the live offset still affects the waveform.
+- Reset pins the base phase to zero throughout a held reset and wins over seek.
+  Reset consumes seek level; a seek held across reset release needs a fresh edge.
+  Offset still applies while reset. The first reset-low sample emits base zero
+  and resumes integration unless held or rate zero.
+- Seek is rising-edge-sensitive, can move phase while held, and emits the sought
+  phase on that sample. A held seek does not pin or repeatedly restart phase.
+- The existing clock exposes a canonical f32 base phase (capped below 1). The
+  offset first loses its integer part by truncation toward zero, preserving its
+  signed fractional part. Shifted phase is wrap(f64(basePhase)+fractionalOffset),
+  rounded to f32 and capped at 1-2^-24, with exactly one wrap after the addition.
+  This preserves negative-tiny offsets at base zero as the upper capped phase;
+  large integral offsets do not erase tiny base phases by f64 addition.
+  Waveforms are evaluated at that public phase, deliberately retaining
+  the existing clock's f32 quantization. Very slow changes may be inaudible or
+  repeat while internal compensated/scaled clock state continues to advance.
+  This module does not promise full-f64 waveform phase or sub-ULP edge timing.
+- Sine: sin(2πp), using the bounded f64 polynomial already used by the legacy LFO.
+  Triangle: 4p for p<1/4; 2-4p for 1/4<=p<3/4; 4p-4 otherwise.
+  Saw: 2p-1. Square: +1 for p<1/2, -1 otherwise (50% duty, boundary is low).
+  Output is f32 in [-1,1]. Saw and square have explicit discontinuities; all are
+  naïve non-bandlimited waveforms, with no anti-aliasing or smoothing claims.
+- Offset/seek/reset can intentionally jump. Hold freezes the clock, not changing
+  offsets. No depth, destination-unit conversion, random waveform, or transport
+  synchronization beyond caller-supplied BPM is included.
+
+Independent oracles calculate phase from exact f32 input schedules or rational
+sample-index expressions, apply the declared public f32 rounding, and compare
+sine with Math.sin and other waves with independent piecewise formulas. Tests
+cover all waves, free/tempo ratios, quarter/half/wrap boundaries, signed offsets,
+phase seeks (including signed integer neighbors and a retained native raw-clock
+negative-tiny counterexample), held controls/precedence, tempo changes without restart, tiny-rate
+state survival despite public quantization, restore, bounds, and instance isolation
+at 44.1/48/96 kHz. Packed and hosted-browser acceptance belong to integration.
+
+## Verification boundary
+
+`tests/musical-controls.spec.ts` performs native numerical and snapshot checks,
+including 44.1/48/96 kHz control schedules and a 49,152-frame smallest-subnormal
+free-rate probe at 48 kHz. The clock repair has its own independent all-capacity
+regressions. Source typechecking is separate from packed-public-entry and hosted
+browser proof; those integration checks are owned by the integration lane.
+No human listening approval, approved golden, or runtime clearance is implied.
+
+`tests/musical-controls-packed.test.mjs` packs the real package, installs it into
+an isolated consumer with the pinned fixture lock, checks the actual public
+TypeScript declarations, renders independent ADSR/LFO references at three rates,
+and builds separate ADSR and four-wave LFO worklet/WASM artifacts. Its default
+and CI path uses fresh `npm ci`. The explicit local-only
+`DEN_MUSICAL_CONTROLS_REUSE_LOCKED_CONSUMER` alternative reuses an existing locked
+dependency tree while extracting the newly packed target into a private directory;
+it is rejected under CI and is not presented as fresh-install evidence. Reuse
+records and rechecks the donor tarball, lock, installed target and full dependency
+file identities. The native diagnostic includes input/output copies and reports
+cold/startup/warm timing, zero memory growth and scrubbing, without runtime
+clearance. Raw f32 evidence contains control signals, not an audio audition.

package/docs/musical-examples.md

@@ -0,0 +1,255 @@
+# Musical chains and original materials
+
+Status: **CANDIDATE**. Four small, editable unworklet compositions address original
+catalog groups 12 (concrete chains/blends) and 13 (sounds/configurations/materials).
+Their A/B variants form a separate future listening group. None inherits the
+initial five settings' listening feedback, golden status, or runtime clearance.
+No original instrument or delay setting is changed.
+
+## Public use and native controls
+
+Import the four processors, their plain parameter maps and host-side asset
+builders from `@denaudio/den/musical-examples`. `src/musical-materials.ts` is an
+implementation detail; no private `dist` import is needed. These are ordinary
+`defineProcessor` declarations, native a-rate AudioParams, one native `load`
+message per resident and existing same-schema state. There is no preset format,
+parameter registry, MIDI/voice allocator, loader, routing or second runtime.
+
+All processors emit stereo `main`. `shapedEcho` accepts mono audio input `main`.
+The other three have native gate controls. A host can drive those AudioParams
+from buttons, an existing keyboard/MIDI mapping or automation; this example does
+not implement or claim that host input layer. Gates are high at values >=.5.
+Supply finite controls inside the declared bounds. Native parameter descriptors
+are not a sanitizer for arbitrary offline arrays, NaN or infinities.
+
+Use the existing unworklet host API to create/connect/resume at **48 kHz** for
+browser use. This lane's evidence is offline at 44.1/48/96 kHz; it does not establish
+browser execution of these exact graphs, scheduling capacity, output-device
+playback or hardware latency. Existing Vite worklets remain 48-kHz-specific.
+
+### Preloading and cleanup
+
+`glassDyad` needs the complete `makeGlassDyadTable()` result: 384 mono f32 samples
+comprising three consecutive 128-sample cycles, without duplicate endpoints.
+`grainCloud` needs `makeGrainCloudSample()`: 4096 mono f32 frames at a declared
+source rate of 48 kHz. Generate these arrays on the host, send one native
+`load` message with `{ data }`, and keep gates down until the host has established
+the message's delivery boundary. The examples do not add an acknowledgement or
+loader. The deterministic offline fixtures deliver at quantum 0 and start gates
+at sample 128 or later. Live hosts must establish their own boundary rather than
+assuming that elapsed wall time proves delivery.
+
+Loading copies into the resident during native message dispatch; it is bounded,
+not a callback-free/zero-cost promise. Both inputs have capacity-16 message rings.
+Missing/unloaded assets are silent. The wavetable also stays silent if fewer than
+all 384 required frames are loaded. Replacing a table restarts both table phases
+but does not retrigger their existing amplitude envelopes. Grain replacement
+invalidates current grains; while gate stays high, new grains resume only on
+later scheduled onsets, not an implicit sample-player restart. Neither replacement
+crossfades. Keep gates down/reset for changes that must be inaudible.
+
+An empty `load` logically unloads the resident; it does not securely erase buffer
+bytes or old snapshots. Host disposal/disconnection uses existing unworklet APIs,
+not a den-specific cleanup method. Tests establish source completion/reset/unload
+silence, not browser-node destruction. Stop gates/input and leave time for the
+stated tails before disconnecting, or use reset for an immediate discontinuous mute.
+
+## A. Glass Dyad
+
+`glassDyad`, `glassDyadParameters`, `glassDyadBrightParameters`,
+`glassDyadConstruction`, `makeGlassDyadTable`.
+
+Two independently gated, independently tuned resident-wavetable voices share one
+small table. Each uses the existing linear ADSR: 12-ms attack, 200-ms decay to
+.65 sustain, 280-ms release. A fresh gate edge resets that voice's oscillator;
+frequency edits preserve phase. Linear stereo weights are .75/.25 for voice A
+and .25/.75 for B; this is not equal-power panning. Shared frame morph is linear.
+
+- A: 220/330 Hz, morph frame .25, final gain .2.
+- B: same notes/envelope/gain, initial morph 1.75 for a richer second/third harmonic.
+- Bounds: each frequency 55–1200 Hz; frame 0–2; final gain 0–.3.
+- Asset: frame weights `[.8]`, `[.6,.2]`, `[.4,.25,.15]` at harmonics 1–3.
+  The fixed absolute weight sum .8 bounds every table frame and interpolated read.
+  With both envelopes <=1 and per-channel pan weights summing to one, the ideal
+  per-channel output is <=.8 × gain, or .16 at the candidate gain. No limiter or
+  peak normalization is involved. Arbitrary replacement PCM invalidates this bound.
+- No block/lookahead delay. Sine phase-zero and the attack make the initial sample
+  zero; that is waveform/envelope behavior, not claimed hardware latency.
+- Gate-off reaches exact source silence within 280 ms (nearest f32-seconds frame
+  count). There is no extra FX tail. Reset consumes a held gate, so it stays
+  silent after reset release until a new gate edge.
+- Fixed resources: two oscillators/envelopes, one 1536-byte PCM buffer and a
+  24,576-byte ingress payload arena, plus native state/metadata/I/O.
+
+The synthetic frames have only three specified low harmonics, but interpolation,
+fast morph/frequency edits, reset and replacement are not guaranteed alias-free.
+There are no automatic mipmaps or general bandlimiting.
+
+## B. FM Modal Hit
+
+`fmModalHit`, `fmModalHitParameters`, `fmModalHitBellParameters`, `fmModalHitModes`.
+
+A fixed A3/220-Hz FM body is linearly blended with an impulse-excited modal bank.
+Gate rise latches strength, resets both FM phases, restarts the amplitude envelope,
+and clears the old modal history before injecting one strength-scaled impulse.
+This is intentional hard retrigger, not additive overlapping resonances. It keeps
+the modal contribution inside the independently proved unit-impulse bound.
+
+The FM amplitude has 1-ms attack, 180-ms decay to zero and 40-ms gate-off release.
+Its instantaneous deviation follows that envelope; modulation feedback is zero.
+Modes are 220 Hz/T60 .42 s/gain 1, 351 Hz/.24 s/.6 and 563 Hz/.15 s/.35, normalized
+by the fixed sum of absolute mode gains. The modal pitches do not move when the
+FM ratio/deviation changes.
+
+- A: strength .8, modulator/carrier ratio 1.5, deviation 100 Hz, modal blend .35,
+  final gain .22. B: ratio 2.75, deviation 170 Hz, modal blend .7.
+- Bounds: strength 0–1, ratio .5–4, deviation 0–180 Hz, modal blend 0–1, gain 0–.3.
+- Strength is latched per hit, while ratio/deviation/blend/gain are live controls.
+- The FM sine and normalized reset-per-hit modal impulse each stay within the
+  latched strength (small floating-point tolerance); their convex blend does too.
+  Candidate output bound is .8 × .22=.176. This reasoning does not apply to
+  arbitrary sustained modal excitation; this example injects a single impulse.
+- Modal response begins on the strike sample. No block/lookahead buffer is added.
+- Gate-off releases FM but does not truncate the modal tail. The slowest pole
+  envelope reaches -60 dB at .42 s after the last strike, and below -120 dB at
+  .84 s. Sampled peaks need not occur exactly there. This is an asymptotic tail,
+  not exact silence. Reset mutes immediately, consumes held gate and requires a
+  fresh edge to strike again. Hard repeated strikes may click.
+- Fixed resources: one two-operator FM source, one envelope and three modal modes.
+
+FM is positive-frequency/clamped FM, not through-zero FM or bandlimited FM. The
+candidate deviation stays below the carrier; more general modulation still has
+sidebands and no blanket alias-free guarantee.
+
+## C. Grain Cloud
+
+`grainCloud`, `grainCloudParameters`, `grainCloudReverseParameters`,
+`grainCloudConstruction`, `makeGrainCloudSample`.
+
+Two fixed grain slots read an original periodic tone cluster. The 4096-frame
+asset uses integer cycle counts 19/31/47 with weights .32/.17/.08, multiplied by
+`.55−.45*cos(2πn/4096)`. It is analytic material, not sampled or downloaded audio.
+The file's fixed formula and full PCM hashes are recorded in the evidence.
+
+- A: position 512, jitter 240 source frames, speed 1, duration 90 ms, density 16 Hz,
+  gain .28. B: position 2800, speed −.75, duration 120 ms, density 12 Hz.
+- Bounds: position/jitter 0–4095 source frames, speed −2–2, duration 20–150 ms,
+  density 0–20 Hz, final gain 0–.4.
+- Source metadata is always 48 kHz. Readers apply the source/host rate ratio at
+  44.1/48/96 kHz. Speed changes pitch and traversal; this is not time-stretching.
+- Park–Miller seed 1741, two triangular-windowed grains, looped resident reads.
+  Position/jitter/rate/duration latch at grain onset. A full pool drops onsets.
+  A/B nominal density×duration=1.44, leaving room under two simultaneous grains;
+  arbitrary declared-bound combinations can saturate the pool and drop events.
+- Table bound .57, windows<=1, sum divided by the two-slot capacity: ideal source
+  <=.57 and candidate final output <=.1596. This fixed divisor is explicit DSP,
+  not loudness normalization. Replacement PCM needs its own bound.
+- Gate rise starts an endpoint-zero grain, so the first sample is zero. There is
+  no block latency. Grain attacks are part of each triangular window.
+- Gate-off starts no further grains; exact silence follows within the largest
+  duration already latched, at most 150 ms. Reset clears grains and reseeds RNG.
+  Unlike Glass/Hit, a gate held high starts again on reset release. Empty unload
+  stays silent even under held gate.
+- Fixed resources: two grains, one 16,384-byte resident PCM buffer and a 262,144-byte
+  ingress payload arena, plus native state/metadata/I/O. Maximum 32-grain capacity
+  is deliberately not used and receives no deadline clearance from this example.
+
+## D. Shaped Echo
+
+`shapedEcho`, `shapedEchoParameters`, `shapedEchoDarkParameters`.
+
+Finite mono input with magnitude<=1 passes through the existing soft first-order
+ADAA drive, a Q=.5 TPT low-pass and the existing stereo ping-pong delay. The left
+delay input receives the filtered signal, the right receives half of it, making
+successive cross-feedback echoes exchange emphasis. A final explicit gain follows
+both output channels. The supplied input is a .4-bound, enveloped 220/660-Hz phrase.
+
+- A: drive 2.4, cutoff 1800 Hz, time 125 ms, feedback .25, wet blend .3, gain .2.
+  B: drive 4.5, cutoff 650 Hz, time 187.5 ms, wet blend .45; feedback/gain unchanged.
+- Bounds: drive 0–8, cutoff 100–4000 Hz, time 40–250 ms, feedback 0–.4, mix 0–.6,
+  gain 0–.25. Delay capacity is fixed250 ms per channel.
+- ADAA averages the nonlinear curve along adjacent driven samples. In its linear
+  regime that has a half-sample effective phase delay and high-frequency rolloff.
+  The module's own dry branch uses the same adjacent-sample alignment, although
+  this composition selects fully wet drive. This is not an integer half-sample
+  delay buffer or a constant broadband latency claim for a nonlinear signal.
+- The filter adds frequency-dependent phase/group delay. Echo dry/wet is an
+  intentional mixture of current filtered signal and delayed history; there is
+  no external parallel-path latency compensation. Delay timing is f32 seconds
+  and fractional linear interpolation. Time edits have moving-head/Doppler
+  behavior and can click. No pitch-preserving crossfade is claimed.
+- With fixed cutoff, the independent direct-form filter/echo oracle checks the
+  complete composition. Tests edit drive mid-phrase. The oracle intentionally
+  does not pretend that a static direct-form recurrence proves fast moving-TPT
+  coefficient equivalence. Wider modulation needs the module's own evidence and
+  renewed composition headroom checks.
+- The chosen .5 peak guard means >6.02 dB measured headroom for fixtures; it is not
+  a universal safety theorem for arbitrary controls/history. No limiter or hidden
+  normalization is inserted. Reports include output measurements and explicitly
+  inferred pre-final-gain peak, not a fabricated raw measurement.
+- At candidate feedback .25, each repeat's envelope falls by about 12.04 dB. Ten
+  repeats are below −120 dB relative to the first: 1.25/1.875 seconds at A/B times,
+  plus the source/filter tail. Feedback .4 and 250-ms times have longer decay.
+  Filter/feedback tails are asymptotic. Held reset mutes and clears history;
+  releasing it passes any currently present input through the cold chain.
+- Fixed resources: one ADAA source-history pair, one SVF, two 250-ms f32 delay
+  buffers (`2*(ceil(rate*.25)+2)*4` bytes) and native scalar state.
+
+## Reproducible numerical and listening evidence
+
+Run `npm ci`, `npm run check`, and the focused
+`npm exec -- vitest run tests/musical-examples.spec.ts --maxWorkers=1`.
+`node --test tests/musical-examples-packed.test.mjs` packs the real package,
+installs it in an isolated locked consumer and type-checks only the public entry.
+It renders 24 A/B cases across 44.1/48/96 kHz and writes a fresh timestamped
+`artifacts/musical-examples/` directory. Existing evidence is never overwritten.
+
+Each source/settings/tarball/lock/asset/expanded-parameter/input/PCM/WAV hash is
+recorded. Every WAV is unnormalized stereo 32f with the stated gain, and every
+render is repeated for bit-identical PCM. A variants at all three rates must
+continue bit-exactly after same-schema snapshot restoration, without reloading
+resident PCM and with the remaining host parameter timeline reapplied. Reset,
+held reset, fresh restart, missing/short/unloaded resident and source completion
+have separate regressions. Persistent DSP state does not save pending host
+automation or create a portable/cross-rate preset.
+
+Independent oracles use periodic linear interpolation plus piecewise closed-form
+envelopes, Math.sin FM and analytic modal impulse sums, BigInt seeded grain
+scheduling, and piecewise Simpson quadrature followed by a static bilinear filter
+and an unbounded echo timeline. Independent expectations are not recorded audio.
+Deliberately wrong audio, clipping and nonfinite output must fail the same guards.
+Every render requires zero scrubbed/nonfinite/clipped samples and peak<.5, useful
+nonzero output, and a final 100-ms tail peak<5e-6. Source finite-tail cases also
+require exact silence. Instantiation/WASM sizes are diagnostics, not loaded
+browser deadline measurements. No golden is generated or approved by these tests.
+
+For later grouped listening, use the eight 48-kHz WAVs in order Glass A/B, Hit A/B,
+Grain A/B, Echo A/B at a comfortable user-controlled playback level. Compare morph
+clarity/stereo balance, struck body versus bell ring, forward versus reverse grain
+motion, and bright versus dark echo articulation. Evaluate clicks and subjective
+quality separately from numerical correctness. Any sound-affecting edit requires
+new hashed audio. Human approval, if given later, must identify those exact hashes;
+it is not inferred from module acceptance or feedback on the original sounds.
+
+### Authored fixture measurements
+
+The initial three-rate packed run measured these maxima across each A/B pair:
+
+| Example | Maximum output peak | Minimum measured headroom | Maximum independent sample error |
+| --- | ---: | ---: | ---: |
+| Glass Dyad | .150429115 | 16.45 dB | 1.50e-8 |
+| FM Modal Hit | .155718207 | 16.15 dB | 2.24e-8 |
+| Grain Cloud | .064521916 | 23.81 dB | 1.87e-9 |
+| Shaped Echo | .183290541 | 14.74 dB | 1.50e-8 |
+
+All had zero nonfinite, clipped or scrubbed samples. Glass/grain final tails were
+exactly zero. The largest final 100-ms tail peak was 6.59e-8 for modal hit and
+2.22e-8 for echo. Paired variation must additionally have a difference-signal RMS
+above 10% of A's RMS; unequal hashes alone are insufficient to call a variation
+meaningful. This is a numerical distinction, not a subjective-quality score.
+
+At 48 kHz, instantiated native memory was 64/64/320/128 KiB respectively; WASM
+sizes were 23,272/48,172/8,904/34,874 bytes. These are fixed-graph allocation
+observations only. They neither measure native message-copy cost nor establish
+loaded worklet callback deadlines. Consult the exact-commit manifest/results when
+reproducing, rather than promoting these summary numbers to a wider guarantee.