@denaudio/den 0.0.0-stage → 0.2.0

package/dist/prepared-convolution.js

@@ -0,0 +1,104 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { spectralDispatchPeriod, spectralFft, spectralForEach } from './spectral-fft.js';
+import { PREPARED_BLOCK as B, PREPARED_FFT_SIZE as N, PREPARED_PARTITIONS as P, PREPARED_VALUES as VALUES, validatePreparedConvolutionConfig } from './convolution-spectrum.js';
+export { prepareConvolutionSpectrum } from './convolution-spectrum.js';
+/** Fixed B128/P64 prepared-spectrum mono convolution candidate.
+ * Correctness/gain bounds require an unchanged packet from host preparation.
+ * Caller owns native CAPACITY_16 ingress with payloadCapacity 131072 bytes.
+ * Copy/scan runs in native dispatch, so preload with audible playback gated off.
+ */
+export const preparedConvolution = defineSubgraph((config) => {
+    validatePreparedConvolutionConfig(config);
+    const dispatchPeriod = spectralDispatchPeriod(B, config.renderQuantumSize);
+    const coefficients = state.buffer.f32({ size: VALUES }).expose({ name: 'coefficients', snapshot: 'persistent' });
+    const history = state.buffer.f64({ size: B }).expose({ name: 'historyScaled', snapshot: 'persistent' });
+    const previous = state.buffer.f64({ size: VALUES }).expose({ name: 'previousSpectraScaled', snapshot: 'persistent' });
+    const mixedReal = state.buffer.f64({ size: N }).expose({ name: 'mixedRealScaled', snapshot: 'transient' });
+    const mixedImag = state.buffer.f64({ size: N }).expose({ name: 'mixedImagScaled', snapshot: 'transient' });
+    const overlap = state.buffer.f64({ size: N }).expose({ name: 'overlapScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor'), spectrumCursor = state.i32(0).named('spectrumCursor');
+    const validSamples = state.i32(0).named('validSamples'), validBlocks = state.i32(0).named('validBlocks');
+    const pendingReset = state.bool(true).named('pendingReset');
+    const loaded = state.bool(false).named('loaded'), rejected = state.bool(false).named('rejected');
+    const revision = state.i32(0).named('revision');
+    const malformed = state.bool(false).expose({ name: 'malformed', snapshot: 'transient' });
+    const sumReal = state.f64(0).expose({ name: 'sumRealScaled', snapshot: 'transient' });
+    const sumImag = state.f64(0).expose({ name: 'sumImagScaled', snapshot: 'transient' });
+    const fft = instantiate(spectralFft, { size: N }, { name: 'fft' });
+    const scale = 2 ** 128;
+    return {
+        /** Module-specific native event payload; this is not a host loader/ack. */
+        load(packet) {
+            coefficients.copyFrom(packet.spectrum);
+            const length = packet.spectrum.length;
+            const header = packet.formatVersion.eq(1).and(packet.blockSize.eq(B)).and(packet.partitions.eq(P));
+            const complete = header.and(packet.impulseFrames.gte(1)).and(packet.impulseFrames.lte(B * P)).and(packet.impulseFrames.floor().eq(packet.impulseFrames))
+                .and(packet.declaredValues.eq(VALUES)).and(length.eq(VALUES));
+            const unload = header.and(packet.impulseFrames.eq(0)).and(packet.declaredValues.eq(0)).and(length.eq(0));
+            malformed.write(false);
+            spectralForEach(P, p => spectralForEach(N, k => {
+                const index = p.mul(N).add(k).mul(2), re = coefficients.read(index), im = coefficients.read(index.add(1));
+                malformed.write(malformed.read().or(re.eq(re).not()).or(im.eq(im).not()).or(re.abs().gt(4)).or(im.abs().gt(4)));
+            }));
+            loaded.write(complete.and(malformed.read().not()));
+            rejected.write(loaded.read().not().and(unload.not()));
+            revision.write(revision.read().add(1));
+            validSamples.write(0);
+            validBlocks.write(0);
+            pendingReset.write(true);
+        },
+        /** Once per sample, inside stride-1 forSample with its native scheduler.
+         * Finite normalized input[-1,1]. Reset discards its sample and keeps the IR.
+         * Reload clears prior tail but accepts the next sample after its handler.
+         */
+        tick(input, reset, everyNSamples) {
+            const invalidate = reset.or(loaded.read().not());
+            validSamples.write(select(invalidate, i32(0), validSamples.read()));
+            validBlocks.write(select(invalidate, i32(0), validBlocks.read()));
+            pendingReset.write(pendingReset.read().or(invalidate));
+            // Keep B-sample frame phase in the persistent cursor. A fresh native
+            // scheduler must also align after snapshots taken inside a B-sample hop.
+            everyNSamples(dispatchPeriod, () => {
+                const frameDue = cursor.read().mod(B).eq(0);
+                const frame = fft.transform(n => select(n.lt(B).and(validSamples.read().gte(i32(B).sub(n))), history.read(cursor.read().add(n).mod(B)), f64(0)), () => f64(0), false);
+                spectralForEach(N, k => {
+                    const index = spectrumCursor.read().mul(N).add(k).mul(2);
+                    previous.write(index, select(frameDue, frame.real(k), previous.read(index)));
+                    previous.write(index.add(1), select(frameDue, frame.imag(k), previous.read(index.add(1))));
+                });
+                spectralForEach(N, k => {
+                    sumReal.write(0);
+                    sumImag.write(0);
+                    spectralForEach(P, p => {
+                        const x = spectrumCursor.read().add(P).sub(p).mod(P).mul(N).add(k).mul(2);
+                        const h = p.mul(N).add(k).mul(2);
+                        const xr = select(validBlocks.read().gte(p), previous.read(x), f64(0));
+                        const xi = select(validBlocks.read().gte(p), previous.read(x.add(1)), f64(0));
+                        // Mask malformed/unloaded coefficient bytes before multiplication.
+                        const hr = f64(select(loaded.read(), coefficients.read(h), f32(0)));
+                        const hi = f64(select(loaded.read(), coefficients.read(h.add(1)), f32(0)));
+                        sumReal.write(sumReal.read().add(xr.mul(hr).sub(xi.mul(hi))));
+                        sumImag.write(sumImag.read().add(xr.mul(hi).add(xi.mul(hr))));
+                    });
+                    mixedReal.write(k, sumReal.read());
+                    mixedImag.write(k, sumImag.read());
+                });
+                const result = fft.transform(n => mixedReal.read(n), n => mixedImag.read(n), true);
+                spectralForEach(N, n => {
+                    const index = cursor.read().add(n).mod(N);
+                    const prior = overlap.read(index);
+                    overlap.write(index, select(frameDue, select(pendingReset.read(), f64(0), prior).add(result.real(n)), prior));
+                });
+                spectrumCursor.write(select(frameDue, spectrumCursor.read().add(1).mod(P), spectrumCursor.read()));
+                validBlocks.write(select(frameDue, validBlocks.read().add(1).min(P - 1), validBlocks.read()));
+                pendingReset.write(pendingReset.read().and(frameDue.not()));
+            });
+            const output = select(invalidate.or(pendingReset.read()), f32(0), f32(overlap.read(cursor.read()).div(scale)));
+            overlap.write(cursor.read(), f64(0));
+            history.write(cursor.read().mod(B), f64(select(invalidate, f32(0), input)).mul(scale));
+            cursor.write(cursor.read().add(1).mod(N));
+            validSamples.write(select(invalidate, i32(0), validSamples.read().add(1).min(B)));
+            return { output, loaded: loaded.read(), rejected: rejected.read(), revision: revision.read() };
+        },
+    };
+});

package/dist/resident-recorder.d.ts

@@ -0,0 +1,28 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+export interface ResidentTakeRecorderConfig {
+    /** Mono take capacity, 1..65,536 frames. Separate fixed load/record buffers. */
+    capacity: number;
+    /** Rate of the incoming signal/processor, 8,000..192,000 Hz. No resampling. */
+    sampleRate: number;
+}
+export interface ResidentTakeRecorderControls {
+    input: Node<'f32'>;
+    /** Append one frame per tick; false pauses. Capacity stops recording without wrapping. */
+    record: Node<'bool'>;
+    /** Level-sensitive logical clear, with priority over record. Not secure erasure. */
+    reset: Node<'bool'>;
+}
+export interface ResidentTakeRecorder {
+    /** Existing resident reader/load contract. Load replaces the take; later recording appends. */
+    readonly sample: ResidentSample;
+    tick(controls: ResidentTakeRecorderControls): {
+        written: Node<'bool'>;
+        full: Node<'bool'>;
+        length: Node<'i32'>;
+    };
+}
+/** Native finite take/pause/resume writer for catalog §3. Exact binary scaling
+ * retains finite f32 input below core's scalar-store floor. No overdub, circular
+ * overwrite, gain, device input, transport, or realtime guarantee. */
+export declare const residentTakeRecorder: import("@unworklet/core").SubgraphDecl<[config: ResidentTakeRecorderConfig], ResidentTakeRecorder>;

package/dist/resident-recorder.js

@@ -0,0 +1,68 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const READ_POSITION_SCALE = 2 ** 192;
+const PCM_SCALE = 2 ** 128;
+const F32_MAX = 3.4028234663852886e38;
+/** Native finite take/pause/resume writer for catalog §3. Exact binary scaling
+ * retains finite f32 input below core's scalar-store floor. No overdub, circular
+ * overwrite, gain, device input, transport, or realtime guarantee. */
+export const residentTakeRecorder = defineSubgraph((config) => {
+    const { capacity, sampleRate } = config;
+    if (!Number.isInteger(capacity) || capacity < 1 || capacity > 65536)
+        throw new RangeError('take capacity must be an integer in [1,65536]');
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('sampleRate must be in [8000,192000] Hz');
+    // Event ingress keeps its original f32 bytes; appended PCM is scaled into
+    // f64 so even the smallest nonzero f32 survives core's 1e-30 store floor.
+    // One boundary chooses the loaded prefix or recorded suffix. No conversion
+    // loop/copy or additional runtime is required when replacing a take.
+    const loadedPCM = state.buffer.f32({ size: capacity }).expose({ name: 'loadedPCM', snapshot: 'persistent' });
+    const recordedPCM = state.buffer.f64({ size: capacity + 1 }).expose({ name: 'recordedPCM', snapshot: 'persistent' });
+    const length = state.i32(0).named('length'), revision = state.i32(0).named('revision');
+    const loadedPrefixLength = state.i32(0).named('loadedPrefixLength');
+    const readPosition = state.f64(0).expose({ name: 'readPosition', snapshot: 'transient' });
+    const sample = {
+        capacity, sourceSampleRate: sampleRate,
+        load(data) {
+            loadedPCM.copyFrom(data);
+            length.write(data.length.clamp(0, capacity));
+            loadedPrefixLength.write(data.length.clamp(0, capacity));
+            revision.write(revision.read().add(1));
+        },
+        length() { return length.read(); },
+        revision() { return revision.read(); },
+        // Match residentSample's published interpolation, clipping and invalid-tap
+        // policy without changing the existing module or consumer interfaces.
+        read(position, start, end, loop) {
+            const lo = start.clamp(0, capacity - 1), hi = end.clamp(0, capacity).min(length.read());
+            const valid = hi.gt(lo);
+            const safe = select(position.eq(position), position, f64(lo)).clamp(-2147483648, 2147483647);
+            const span = f64(hi.sub(lo).max(1)), relative = safe.sub(f64(lo));
+            const wrapped = relative.sub(relative.div(span).floor().mul(span)).add(f64(lo));
+            readPosition.write((loop ? wrapped : safe.clamp(f64(lo), f64(hi.sub(1).max(lo)))).mul(READ_POSITION_SCALE));
+            const p = readPosition.read().div(READ_POSITION_SCALE);
+            const whole = i32(p.floor()).clamp(0, capacity - 1), fraction = p.sub(f64(whole));
+            const next = loop ? select(whole.add(1).gte(hi), lo, whole.add(1)) : whole.add(1).min(hi.sub(1).max(lo));
+            const second = next.clamp(0, capacity - 1), prefix = loadedPrefixLength.read();
+            const rawA = select(whole.lt(prefix), f64(loadedPCM.read(whole)), recordedPCM.read(whole).div(PCM_SCALE));
+            const rawB = select(second.lt(prefix), f64(loadedPCM.read(second)), recordedPCM.read(second).div(PCM_SCALE));
+            const a = select(rawA.eq(rawA).and(rawA.abs().lte(F32_MAX)), rawA, f64(0));
+            const b = select(rawB.eq(rawB).and(rawB.abs().lte(F32_MAX)), rawB, f64(0));
+            return select(valid, f32(a.add(b.sub(a).mul(fraction))), f32(0));
+        },
+    };
+    return { sample, tick(c) {
+            const before = length.read();
+            const written = c.record.and(c.reset.not()).and(before.lt(capacity));
+            const index = select(written, before, i32(capacity));
+            const finite = c.input.eq(c.input).and(c.input.abs().lte(F32_MAX));
+            // select evaluates both branches. Inactive writes touch only a private
+            // sentinel, never existing exposed PCM. Signed zero stores as positive zero.
+            recordedPCM.write(index, select(written.and(finite), f64(c.input).mul(PCM_SCALE), f64(0)));
+            // Commit bytes before making the additional frame visible to a later reader.
+            length.write(select(c.reset, i32(0), before.add(select(written, i32(1), i32(0)))));
+            loadedPrefixLength.write(select(c.reset, i32(0), loadedPrefixLength.read()));
+            revision.write(revision.read().add(select(c.reset, i32(1), i32(0))));
+            const current = length.read();
+            return { written, full: current.eq(capacity), length: current };
+        } };
+});

package/dist/resident-time-stretch.d.ts

@@ -0,0 +1,46 @@
+import { type EveryNSamples, type Node } from '@unworklet/core';
+import type { ResidentSample } from './sample.js';
+export interface ResidentTimeStretchConfig {
+    /** Pass ctx.renderQuantumSize; aligns native dispatch with snapshot boundaries. */
+    renderQuantumSize: number;
+    /** Match ctx.sampleRate; integer 8000..192000. */
+    sampleRate: number;
+    /** Resident sourceSampleRate must also be an integer in [8000,192000]. */
+    sample: ResidentSample;
+    /** Fixed synthesis hop. Window length is twice this value; default 256. */
+    hopSamples?: 128 | 256;
+    /** Integer source-frame offsets searched, independently of source rate.
+     * Zero disables alignment. Default 64; compare 64 points per candidate. */
+    searchFrames?: 0 | 8 | 16 | 32 | 64 | 128;
+}
+export interface ResidentTimeStretchControls {
+    gate: Node<'bool'>;
+    /** Level-sensitive request. Starts at the next global hop boundary while
+     * gate stays high. Held trigger restarts each hop; it can click. */
+    trigger: Node<'bool'>;
+    /** Silences/cancels now. Does not rephase the global hop clock. */
+    reset: Node<'bool'>;
+    /** Output duration / original duration, [0.5,2], latched at actual launch.
+     * Invalid values reject that launch. Changes need a fresh trigger. */
+    durationScale: Node<'f32'>;
+    /** Grain-local pitch multiplier, [0.5,2], latched at actual launch. */
+    pitchRatio: Node<'f32'>;
+}
+/** Fixed-capacity mono resident WSOLA variant. Native 64-point squared-error
+ * alignment and complementary linear overlap; no normalization or clipping.
+ * True independent duration/pitch controls, with bounded search/transient and
+ * interpolation/alias limitations. Call once in stride-1 forSample, passing
+ * that loop's everyNSamples. Native snapshots continue only the same schema.
+ */
+export declare const residentTimeStretch: import("@unworklet/core").SubgraphDecl<[config: ResidentTimeStretchConfig], {
+    tick(c: ResidentTimeStretchControls, everyNSamples: EveryNSamples): {
+        output: Node<"f32">;
+        active: Node<"bool">;
+        position: Node<"f32">;
+        ended: Node<"bool">;
+        pending: Node<"bool">;
+        rejected: Node<"bool">;
+        missing: Node<"bool">;
+        selectedOffset: Node<"i32">;
+    };
+}>;

package/dist/resident-time-stretch.js

@@ -0,0 +1,136 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+import { spectralDispatchPeriod, spectralForEach } from './spectral-fft.js';
+// Exact binary internal scaling protects tiny waveform differences from the
+// native 1e-30 scalar-store scrub. Even opposite finite f32 extrema produce
+// a 64-term squared score below 2**649, far inside finite f64 range.
+const SCALE = 2 ** 192;
+/** Fixed-capacity mono resident WSOLA variant. Native 64-point squared-error
+ * alignment and complementary linear overlap; no normalization or clipping.
+ * True independent duration/pitch controls, with bounded search/transient and
+ * interpolation/alias limitations. Call once in stride-1 forSample, passing
+ * that loop's everyNSamples. Native snapshots continue only the same schema.
+ */
+export const residentTimeStretch = defineSubgraph((config) => {
+    const { sample, sampleRate, hopSamples: H = 256, searchFrames: S = 64 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isInteger(sample.sourceSampleRate) || sample.sourceSampleRate < 8000 || sample.sourceSampleRate > 192000 ||
+        ![128, 256].includes(H) || ![0, 8, 16, 32, 64, 128].includes(S)) {
+        throw new RangeError('residentTimeStretch requires integer sampleRate/sourceSampleRate [8000,192000], hopSamples 128/256 and searchFrames 0/8/16/32/64/128');
+    }
+    const dispatchPeriod = spectralDispatchPeriod(H, config.renderQuantumSize);
+    const active = state.bool(false).named('active'), pending = state.bool(false).named('pending');
+    const ended = state.bool(false).named('ended'), rejected = state.bool(false).named('rejected');
+    const previousGate = state.bool(false).named('previousGate'), revision = state.i32(-1).named('revision');
+    const clock = state.i32(0).named('clock'), age = state.i32(0).named('age'), total = state.i32(0).named('total');
+    const sourceLength = state.i32(0).named('sourceLength'), pitchStep = state.f64(1).named('pitchStep');
+    const current = state.f64(0).named('currentStart'), previous = state.f64(0).named('previousStart');
+    const first = state.bool(true).named('first'), offset = state.i32(0).named('selectedOffset');
+    const reference = state.buffer.f64({ size: 64 }).expose({ name: 'referenceScaled', snapshot: 'transient' });
+    const score = state.f64(0).expose({ name: 'scoreScaled', snapshot: 'transient' });
+    const bestScore = state.f64(0).expose({ name: 'bestScoreScaled', snapshot: 'transient' });
+    const bestOffset = state.i32(0).expose({ name: 'bestOffset', snapshot: 'transient' });
+    const launching = state.bool(false).expose({ name: 'launching', snapshot: 'transient' });
+    const oldValue = state.f64(0).expose({ name: 'oldValueScaled', snapshot: 'transient' });
+    const wet = state.f64(0).expose({ name: 'wetScaled', snapshot: 'transient' });
+    // Each PCM endpoint outside [0,length) is zero, including fractional reads
+    // straddling either boundary. Clamp indices BEFORE calling the shared reader.
+    const readScaled = (position) => {
+        const whole = position.floor(), fraction = position.sub(whole), end = sample.length();
+        const a = f64(sample.read(whole.clamp(0, f64(end.sub(1).max(0))), i32(0), end, false));
+        oldValue.write(select(whole.gte(0).and(whole.lt(f64(end))), a, f64(0)).mul(SCALE));
+        const next = whole.add(1);
+        const b = f64(sample.read(next.clamp(0, f64(end.sub(1).max(0))), i32(0), end, false));
+        return oldValue.read().mul(f64(1).sub(fraction)).add(select(next.gte(0).and(next.lt(f64(end))), b, f64(0)).mul(SCALE).mul(fraction));
+    };
+    // Exact rational ceil(L * R * D / Rs) for integer rates and finite f32 D.
+    // A=L*R<2**34 and K=D*2**24<=2**25. Split the >53-bit A*K product:
+    // hi*K<2**43 and lo*K<2**41 are exact integers. Numerator / 2**16 is
+    // represented by its integer part and a 16-bit remainder. The nearest
+    // approximate integer q is either floor(exact) or ceil(exact), since the
+    // absolute arithmetic error is far below 0.5. Exact comparison with
+    // q*Rs*256 then returns the true ceil without an epsilon adjustment.
+    const durationFrames = (duration) => {
+        const a = f64(sample.length()).mul(sampleRate), k = f64(duration).mul(2 ** 24);
+        const hi = a.div(65536).floor(), loProduct = a.sub(hi.mul(65536)).mul(k);
+        const integerPart = hi.mul(k).add(loProduct.div(65536).floor()), remainder = loProduct.mod(65536);
+        const q = a.mul(f64(duration)).div(sample.sourceSampleRate).add(.5).floor();
+        const target = q.mul(sample.sourceSampleRate).mul(256);
+        const greater = integerPart.gt(target).or(integerPart.eq(target).and(remainder.gt(0)));
+        return i32(q.add(select(greater, f64(1), f64(0))));
+    };
+    return {
+        tick(c, everyNSamples) {
+            const missing = sample.length().eq(0), changed = sample.revision().eq(revision.read()).not();
+            const clear = c.reset.or(changed).or(missing);
+            active.write(active.read().and(clear.not()).and(c.gate));
+            pending.write(pending.read().and(clear.not()).and(c.gate));
+            ended.write(ended.read().and(clear.not()));
+            rejected.write(rejected.read().and(c.reset.not()));
+            age.write(select(clear, i32(0), age.read()));
+            total.write(select(clear, i32(0), total.read()));
+            sourceLength.write(select(clear, i32(0), sourceLength.read()));
+            const request = c.trigger.or(c.gate.and(previousGate.read().not())).and(c.gate).and(c.reset.not()).and(missing.not());
+            pending.write(pending.read().or(request));
+            // Native scheduler counters are not snapshotted. This period divides H
+            // and the actual quantum, so every block-atomic restore realigns dispatch.
+            // The persistent clock carries H phase; off-phase searches do not commit.
+            everyNSamples(dispatchPeriod, () => {
+                const due = clock.read().eq(0), attempt = due.and(pending.read()).and(c.gate).and(c.reset.not());
+                const valid = c.durationScale.gte(.5).and(c.durationScale.lte(2)).and(c.pitchRatio.gte(.5)).and(c.pitchRatio.lte(2));
+                launching.write(attempt.and(valid).and(missing.not()));
+                const launch = launching.read();
+                pending.write(pending.read().and(attempt.not()));
+                rejected.write(select(attempt, valid.not(), rejected.read()));
+                age.write(select(launch, i32(0), age.read()));
+                total.write(select(launch, durationFrames(select(valid, c.durationScale, f32(1))), total.read()));
+                sourceLength.write(select(launch, sample.length(), sourceLength.read()));
+                pitchStep.write(select(launch, f64(c.pitchRatio).mul(sample.sourceSampleRate / sampleRate), pitchStep.read()));
+                active.write(active.read().or(launch));
+                ended.write(ended.read().and(launch.not()));
+                const nominal = f64(age.read()).mul(f64(sourceLength.read())).div(f64(total.read().max(1)));
+                const priorTail = current.read().add(pitchStep.read().mul(H));
+                spectralForEach(64, j => reference.write(j, readScaled(priorTail.add(f64(j).mul(H / 64).mul(pitchStep.read())))));
+                const compare = (candidate) => {
+                    score.write(0);
+                    spectralForEach(64, j => {
+                        const value = readScaled(nominal.add(f64(candidate)).add(f64(j).mul(H / 64).mul(pitchStep.read())));
+                        const difference = value.sub(reference.read(j));
+                        score.write(score.read().add(difference.mul(difference)));
+                    });
+                };
+                compare(i32(0));
+                bestScore.write(score.read());
+                bestOffset.write(0);
+                if (S > 0)
+                    spectralForEach(S * 2, j => {
+                        const distance = j.div(2).add(1), candidate = select(j.mod(2).eq(0), distance, distance.mul(-1));
+                        compare(candidate);
+                        const improve = score.read().lt(bestScore.read());
+                        bestOffset.write(select(improve, candidate, bestOffset.read()));
+                        bestScore.write(select(improve, score.read(), bestScore.read()));
+                    });
+                const commit = due.and(active.read());
+                previous.write(select(commit, select(launch, f64(0), priorTail), previous.read()));
+                current.write(select(commit, select(launch, f64(0), nominal.add(f64(bestOffset.read()))), current.read()));
+                offset.write(select(commit, select(launch, i32(0), bestOffset.read()), offset.read()));
+                first.write(select(commit, launch, first.read()));
+            });
+            const exhausted = active.read().and(age.read().gte(total.read()));
+            ended.write(ended.read().or(exhausted));
+            active.write(active.read().and(exhausted.not()));
+            const playing = active.read();
+            const local = f64(clock.read()).mul(pitchStep.read()), blend = f64(clock.read()).div(H);
+            // Capture the first read because resident.read uses a shared transient.
+            wet.write(readScaled(previous.read().add(local)));
+            const incoming = readScaled(current.read().add(local));
+            const mixed = select(first.read(), incoming, wet.read().mul(f64(1).sub(blend)).add(incoming.mul(blend)));
+            const output = select(playing, f32(mixed.div(SCALE)), f32(0));
+            const position = f32(f64(age.read().min(total.read())).mul(f64(sourceLength.read())).div(f64(total.read().max(1))));
+            age.write(select(playing, age.read().add(1), age.read()));
+            clock.write(clock.read().add(1).mod(H));
+            previousGate.write(c.gate.and(c.reset.not()));
+            revision.write(sample.revision());
+            return { output, active: playing, position, ended: ended.read(), pending: pending.read(), rejected: rejected.read(), missing, selectedOffset: offset.read() };
+        },
+    };
+});

package/dist/resonator.d.ts

@@ -0,0 +1,32 @@
+import { type Node } from '@unworklet/core';
+export interface ResonatorMode {
+    frequencyHz: number;
+    decaySeconds: number;
+    gain: number;
+}
+export interface ModalResonatorConfig {
+    sampleRate: number;
+    modes: readonly ResonatorMode[];
+}
+/** Fixed stable two-pole modes. Decay is amplitude T60 in seconds. */
+export declare const modalResonator: import("@unworklet/core").SubgraphDecl<[config: ModalResonatorConfig], {
+    /** Excitation clamps to [-1,1]. Reset clears each mode before current excitation. */
+    tick(input: Node<"f32">, reset: Node<"bool">): Node<"f32">;
+}>;
+export interface TunedCombConfig {
+    sampleRate: number;
+    minFrequencyHz: number;
+}
+export interface TunedCombControls {
+    input: Node<'f32'>;
+    frequencyHz: Node<'f32'>;
+    feedback: Node<'f32'>;
+    /** One-pole memory coefficient in [0,1]; 0 bypasses damping, 1 freezes it. */
+    damping: Node<'f32'>;
+    reset: Node<'bool'>;
+}
+/** Fractional moving-delay resonator. Interpolation and damping change tuning/decay. */
+export declare const tunedComb: import("@unworklet/core").SubgraphDecl<[config: TunedCombConfig], {
+    /** Normalize excitation by (1-|feedback|) before storage; return the raw tap. */
+    tick(c: TunedCombControls): Node<"f32">;
+}>;

package/dist/resonator.js

@@ -0,0 +1,63 @@
+import { defineSubgraph, f32, f64, instantiate, select, state } from '@unworklet/core';
+import { delayReadhead } from './delay-readhead.js';
+function maximumFrequency(sampleRate) {
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('resonator sampleRate must be in [8000,192000] Hz');
+    return 0.45 * sampleRate;
+}
+/** Fixed stable two-pole modes. Decay is amplitude T60 in seconds. */
+export const modalResonator = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    if (config.modes.length < 1 || config.modes.length > 16)
+        throw new RangeError('modalResonator requires 1–16 modes');
+    const scale = 2 ** 128; // Keep valid f32 subnormal tails above upstream scalar-state flush.
+    const modes = config.modes.map((mode, i) => {
+        if (!Number.isFinite(mode.frequencyHz) || mode.frequencyHz < 20 || mode.frequencyHz > maximum ||
+            !Number.isFinite(mode.decaySeconds) || mode.decaySeconds < 0.005 || mode.decaySeconds > 30 ||
+            !Number.isFinite(mode.gain) || Math.abs(mode.gain) > 16)
+            throw new RangeError('invalid mode frequency, T60 or gain');
+        const omega = 2 * Math.PI * mode.frequencyHz / config.sampleRate;
+        const radius = Math.exp(-Math.LN10 * 3 / (mode.decaySeconds * config.sampleRate));
+        return { gain: mode.gain, a1: 2 * radius * Math.cos(omega), a2: -radius * radius, b: Math.sin(omega),
+            first: state.f64(0).named(`mode${i}First`), second: state.f64(0).named(`mode${i}Second`) };
+    });
+    const normalization = modes.reduce((sum, mode) => sum + Math.abs(mode.gain), 0) || 1;
+    return {
+        /** Excitation clamps to [-1,1]. Reset clears each mode before current excitation. */
+        tick(input, reset) {
+            let sum = f64(0);
+            for (const mode of modes) {
+                const first = select(reset, f64(0), mode.first.read().div(scale));
+                const second = select(reset, f64(0), mode.second.read().div(scale));
+                const next = f64(input).clamp(-1, 1).mul(mode.b).add(first.mul(mode.a1)).add(second.mul(mode.a2));
+                mode.second.write(first.mul(scale));
+                mode.first.write(next.mul(scale));
+                sum = sum.add(next.mul(mode.gain / normalization));
+            }
+            return f32(sum);
+        },
+    };
+});
+/** Fractional moving-delay resonator. Interpolation and damping change tuning/decay. */
+export const tunedComb = defineSubgraph((config) => {
+    const maximum = maximumFrequency(config.sampleRate);
+    if (!Number.isFinite(config.minFrequencyHz) || config.minFrequencyHz < 20 || config.minFrequencyHz > maximum) {
+        throw new RangeError('comb minFrequencyHz must be in [20,.45*sampleRate]');
+    }
+    const line = instantiate(delayReadhead, { sampleRate: config.sampleRate, maxDelaySeconds: 1 / config.minFrequencyHz }, { name: 'line' });
+    const history = state.f64(0).named('dampingHistory');
+    const scale = 2 ** 128;
+    return {
+        /** Normalize excitation by (1-|feedback|) before storage; return the raw tap. */
+        tick(c) {
+            const frequency = f64(c.frequencyHz).clamp(config.minFrequencyHz, maximum);
+            const feedback = f64(c.feedback).clamp(-0.999, 0.999), damping = f64(c.damping).clamp(0, 1);
+            const tap = line.read(f32(f64(1).div(frequency)), c.reset);
+            const previous = select(c.reset, f64(0), history.read().div(scale));
+            const filtered = f64(tap.output).mul(f64(1).sub(damping)).add(previous.mul(damping));
+            history.write(filtered.mul(scale));
+            tap.write(f32(f64(c.input).mul(f64(1).sub(feedback.abs())).add(filtered.mul(feedback))));
+            return tap.output;
+        },
+    };
+});

package/dist/reverb.d.ts

@@ -0,0 +1,27 @@
+import { type Node } from '@unworklet/core';
+export interface AlgorithmicReverbConfig {
+    sampleRate: number;
+    /** Fixed delay-time scale, [0.5, 2]. Default 1. Rebuild to change. */
+    roomScale?: number;
+    /** Nominal loop-gain loss time in seconds, [0.1, 10]. Default 1.5.
+     * Not an exact RT60 or hard tail-duration ceiling: very low damping adds
+     * loop group delay and can lengthen low-band decay. Rebuild to change. */
+    decaySeconds?: number;
+    /** Fixed one-pole loop lowpass corner, [20, 0.45*sampleRate]. Default min(6000, 0.45*sampleRate). */
+    dampingHz?: number;
+}
+export interface ReverbControls {
+    mix: Node<'f32'>;
+    /** Dry output, no new input; existing tail continues internally. */
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** Four-line Hadamard FDN candidate. Fixed capacities and coefficients, no FFT.
+ * Finite inputs required. No predelay; the shortest network delay precedes wet audio.
+ */
+export declare const algorithmicReverb: import("@unworklet/core").SubgraphDecl<[config: AlgorithmicReverbConfig], {
+    tick(inputLeft: Node<"f32">, inputRight: Node<"f32">, c: ReverbControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+    };
+}>;

package/dist/reverb.js

@@ -0,0 +1,52 @@
+import { defineSubgraph, f32, f64, instantiate, select, state } from '@unworklet/core';
+import { delayReadhead } from './delay-readhead.js';
+/** Four-line Hadamard FDN candidate. Fixed capacities and coefficients, no FFT.
+ * Finite inputs required. No predelay; the shortest network delay precedes wet audio.
+ */
+export const algorithmicReverb = defineSubgraph((config) => {
+    const { sampleRate, roomScale = 1, decaySeconds = 1.5 } = config;
+    const dampingHz = config.dampingHz ?? Math.min(6000, 0.45 * sampleRate);
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isFinite(roomScale) || roomScale < 0.5 || roomScale > 2 ||
+        !Number.isFinite(decaySeconds) || decaySeconds < 0.1 || decaySeconds > 10 ||
+        !Number.isFinite(dampingHz) || dampingHz < 20 || dampingHz > 0.45 * sampleRate) {
+        throw new RangeError('algorithmicReverb requires sample rate [8000,192000], roomScale [0.5,2], decaySeconds [0.1,10], dampingHz [20,0.45*sampleRate]');
+    }
+    // Incommensurate reference lengths (seconds), rounded to fixed sample counts.
+    const lengths = [0.0297, 0.0371, 0.0411, 0.0437].map(seconds => Math.round(seconds * roomScale * sampleRate));
+    const lines = lengths.map((length, i) => ({
+        delay: instantiate(delayReadhead, { sampleRate, maxDelaySeconds: length / sampleRate }, { name: `line${i}` }),
+        seconds: length / sampleRate,
+        gain: 10 ** (-3 * length / (sampleRate * decaySeconds)),
+        damping: state.f64(0).named(`damping${i}`),
+        wet: state.f64(0).expose({ name: `wet${i}`, snapshot: 'transient' }),
+    }));
+    // One-pole matched-z lowpass: convex combination, unity DC, no added resonance.
+    const pole = Math.exp(-2 * Math.PI * dampingHz / sampleRate);
+    // H/2 is orthogonal. These literal rows also keep generated work fixed.
+    const matrix = [[1, 1, 1, 1], [1, -1, 1, -1], [1, 1, -1, -1], [1, -1, -1, 1]];
+    return {
+        tick(inputLeft, inputRight, c) {
+            const heads = lines.map(line => line.delay.read(f32(line.seconds), c.reset));
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                line.wet.write(f64(heads[i].output));
+                line.damping.write(select(c.reset, f64(0), line.damping.read()).mul(pole).add(line.wet.read().mul(1 - pole)));
+            }
+            const damped = lines.map(line => line.damping.read().mul(line.gain));
+            const left = f64(select(c.bypass, f32(0), inputLeft)), right = f64(select(c.bypass, f32(0), inputRight));
+            for (let i = 0; i < lines.length; i++) {
+                const injection = left.add(right.mul(matrix[1][i])).mul(0.5);
+                const feedback = damped.reduce((sum, x, j) => sum.add(x.mul(matrix[i][j] * 0.5)), f64(0));
+                heads[i].write(f32(injection.add(feedback)));
+            }
+            const wetLeft = lines.reduce((sum, line, i) => sum.add(line.wet.read().mul(matrix[2][i] * 0.5)), f64(0));
+            const wetRight = lines.reduce((sum, line, i) => sum.add(line.wet.read().mul(matrix[3][i] * 0.5)), f64(0));
+            const mix = f64(c.mix).clamp(0, 1);
+            return {
+                left: select(c.bypass, inputLeft, f32(f64(inputLeft).mul(f64(1).sub(mix)).add(wetLeft.mul(mix)))),
+                right: select(c.bypass, inputRight, f32(f64(inputRight).mul(f64(1).sub(mix)).add(wetRight.mul(mix)))),
+            };
+        },
+    };
+});