@denaudio/den 0.0.0-stage → 0.2.0

package/dist/instrument.js

@@ -0,0 +1,166 @@
+import { audioOutput, i32, defineProcessor, event, f32, forSample, instantiate, param, select, state } from '@unworklet/core';
+import { envelope } from './envelope.js';
+import { lfo, modulatePitch, modulateCutoff } from './lfo.js';
+import { oscillator } from './oscillator.js';
+import { filter } from './filter.js';
+import { voicePolicy } from './voice-policy.js';
+export { bassConfig, bassParameters, percussionConfig, percussionParameters, padConfig, padParameters } from './instrument-settings.js';
+/** Diagnostic initial AudioParam values, not an approved preset or a preset format. */
+export const diagnosticInstrumentParameters = {
+    gain: 0.15,
+    ampAttack: 0.005,
+    ampDecay: 0.08,
+    ampSustain: 0.7,
+    ampRelease: 0.15,
+    pitchAttack: 0,
+    pitchDecay: 0.1,
+    pitchSustain: 0,
+    pitchRelease: 0.1,
+    filterAttack: 0.01,
+    filterDecay: 0.15,
+    filterSustain: 0.2,
+    filterRelease: 0.15,
+    cutoff: 2500,
+    resonance: 0.707,
+    pitchEnvelopeDepth: 0,
+    filterEnvelopeDepth: 1,
+    lfoRate: 2,
+    lfoAmpDepth: 0,
+    lfoPitchDepth: 0,
+    lfoFilterDepth: 0,
+    bypass: 0,
+};
+/** MIDI input `midi`, stereo dual-mono output `main`, panic message `reset`.
+ * Capacities/mode/waveform/parts are construction choices; all musical controls
+ * use native AudioParams. See docs/instrument.md for timing and reset semantics.
+ */
+export function createInstrument(config) {
+    // Keep the tested compilation ceiling after the initial 32-voice graph
+    // exceeded the WASM function-size limit. This is not a real-time guarantee.
+    if ((config.capacity ?? (config.mode === 'mono' ? 1 : 4)) > 16) {
+        throw new RangeError('instrument capacity must be <= 16 (compiled graph limit)');
+    }
+    return defineProcessor(({ sampleRate }) => {
+        const policy = instantiate(voicePolicy, { ...config, capacity: config.capacity ?? (config.mode === 'mono' ? 1 : 4) }, { name: 'voices' });
+        const output = audioOutput({ channels: 2, name: 'main' });
+        const midi = event.midi({ from: 'main', name: 'midi' });
+        // A persisted marker paired with a transient marker distinguishes restore
+        // from a pristine instance even when MIDI already reactivated a voice.
+        const rendered = state.bool(false).named('rendered');
+        const live = state.bool(false).expose({ name: 'live', snapshot: 'transient' });
+        const panic = state.bool(false).expose({ name: 'panic', snapshot: 'transient' });
+        const voiceControls = state.buffer.bool({ size: 3 * policy.capacity }).expose({ name: 'voiceControls', snapshot: 'transient' });
+        const deferredRetrigger = state.buffer.bool({ size: policy.capacity }).expose({ name: 'deferredRetrigger', snapshot: 'transient' });
+        const completed = state.buffer.bool({ size: policy.capacity }).expose({ name: 'completed', snapshot: 'transient' });
+        const cleared = state.buffer.bool({ size: policy.capacity }).expose({ name: 'cleared', snapshot: 'transient' });
+        const tuning = state.buffer.f32({ size: 128 }).expose({ name: 'tuning', snapshot: 'transient' });
+        const modulation = instantiate(lfo, { sampleRate }, { name: 'lfo' });
+        // Materialize intermediate signals: 0.4.1 analysis recursively expands DAGs.
+        // Only cache musical exponents: below the state flush threshold (1e-30),
+        // their octave ratio already rounds to exactly 1. Do not cache final audio,
+        // where a finite sub-threshold result must survive downstream gain.
+        const depths = state.buffer.f32({ size: 2 * policy.capacity }).expose({ name: 'depths', snapshot: 'transient' });
+        const signals = state.buffer.f32({ size: 4 * policy.capacity + 1 }).expose({ name: 'signals', snapshot: 'transient' });
+        const gain = param.f32({ default: diagnosticInstrumentParameters.gain, min: 0, max: 1, automationRate: 'a-rate' }).named('gain');
+        const ampAttack = param.f32({ default: diagnosticInstrumentParameters.ampAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('ampAttack');
+        const ampDecay = param.f32({ default: diagnosticInstrumentParameters.ampDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('ampDecay');
+        const ampSustain = param.f32({ default: diagnosticInstrumentParameters.ampSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('ampSustain');
+        const ampRelease = param.f32({ default: diagnosticInstrumentParameters.ampRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('ampRelease');
+        const pitchAttack = param.f32({ default: diagnosticInstrumentParameters.pitchAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchAttack');
+        const pitchDecay = param.f32({ default: diagnosticInstrumentParameters.pitchDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchDecay');
+        const pitchSustain = param.f32({ default: diagnosticInstrumentParameters.pitchSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('pitchSustain');
+        const pitchRelease = param.f32({ default: diagnosticInstrumentParameters.pitchRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('pitchRelease');
+        const filterAttack = param.f32({ default: diagnosticInstrumentParameters.filterAttack, min: 0, max: 30, automationRate: 'a-rate' }).named('filterAttack');
+        const filterDecay = param.f32({ default: diagnosticInstrumentParameters.filterDecay, min: 0, max: 30, automationRate: 'a-rate' }).named('filterDecay');
+        const filterSustain = param.f32({ default: diagnosticInstrumentParameters.filterSustain, min: 0, max: 1, automationRate: 'a-rate' }).named('filterSustain');
+        const filterRelease = param.f32({ default: diagnosticInstrumentParameters.filterRelease, min: 0, max: 30, automationRate: 'a-rate' }).named('filterRelease');
+        const cutoff = param.f32({ default: diagnosticInstrumentParameters.cutoff, min: 20, max: 20000, automationRate: 'a-rate' }).named('cutoff');
+        const resonance = param.f32({ default: diagnosticInstrumentParameters.resonance, min: 0.5, max: 10, automationRate: 'a-rate' }).named('resonance');
+        const pitchEnvelopeDepth = param.f32({ default: diagnosticInstrumentParameters.pitchEnvelopeDepth, min: -24, max: 24, automationRate: 'a-rate' }).named('pitchEnvelopeDepth');
+        const filterEnvelopeDepth = param.f32({ default: diagnosticInstrumentParameters.filterEnvelopeDepth, min: -8, max: 8, automationRate: 'a-rate' }).named('filterEnvelopeDepth');
+        const lfoRate = param.f32({ default: diagnosticInstrumentParameters.lfoRate, min: 0, max: 20, automationRate: 'a-rate' }).named('lfoRate');
+        const lfoAmpDepth = param.f32({ default: diagnosticInstrumentParameters.lfoAmpDepth, min: 0, max: 1, automationRate: 'a-rate' }).named('lfoAmpDepth');
+        const lfoPitchDepth = param.f32({ default: diagnosticInstrumentParameters.lfoPitchDepth, min: -24, max: 24, automationRate: 'a-rate' }).named('lfoPitchDepth');
+        const lfoFilterDepth = param.f32({ default: diagnosticInstrumentParameters.lfoFilterDepth, min: -8, max: 8, automationRate: 'a-rate' }).named('lfoFilterDepth');
+        const bypass = param.f32({ default: diagnosticInstrumentParameters.bypass, min: 0, max: 1, automationRate: 'a-rate' }).named('bypass');
+        const parts = policy.voices.map((_, index) => ({
+            amp: instantiate(envelope, { sampleRate }, { name: `amp${index}` }),
+            pitch: instantiate(envelope, { sampleRate }, { name: `pitch${index}` }),
+            tone: instantiate(envelope, { sampleRate }, { name: `tone${index}` }),
+            oscillator: instantiate(config.oscillator ?? oscillator, { sampleRate, waveform: config.waveform ?? 'sine' }, { name: `oscillator${index}` }),
+            filter: instantiate(config.filter ?? filter, { sampleRate }, { name: `filter${index}` }),
+        }));
+        midi.onEvent('noteOn', e => policy.noteOn(e.note, e.channel, e.velocity));
+        midi.onEvent('noteOff', e => policy.noteOff(e.note, e.channel));
+        midi.onEvent('cc', e => {
+            // Capture ownership before CC120 frees/reassigns voices. A subsequent note
+            // in this quantum starts cold, even when it reuses the same physical slot.
+            policy.voices.forEach((voice, n) => cleared.write(n, cleared.read(n).or(e.controller.eq(120).and(voice.read().channel.eq(e.channel)))));
+            // These policy methods have no conditional argument. CC routing uses the
+            // policy's validated channel guard for unsupported controller messages.
+            policy.allNotesOff(select(e.controller.eq(123), e.channel, i32(-1)));
+            policy.allSoundOff(select(e.controller.eq(120), e.channel, i32(-1)));
+        });
+        event({ from: 'main', name: 'reset' }).onReceive(() => panic.write(true));
+        return { process() {
+                // Reset wins over MIDI delivered in the same block. Its DSP pulse is only
+                // the first sample; subsequent blocks may accept fresh notes normally.
+                policy.reset(panic.read());
+                for (let note = 0; note < 128; note++)
+                    tuning.write(note, 440 * 2 ** ((note - 69) / 12));
+                forSample(i => {
+                    const reset = panic.read();
+                    signals.write(4 * policy.capacity, modulation.tick(lfoRate.at(i), reset, f32(0)));
+                    let sum = f32(0);
+                    policy.voices.forEach((voice, n) => {
+                        const v = voice.read();
+                        voiceControls.write(n * 3, reset.or(rendered.read().and(live.read().not())).or(v.active.not()).or(cleared.read(n)));
+                        voiceControls.write(n * 3 + 1, v.gate.and(voiceControls.read(n * 3).not()));
+                        voiceControls.write(n * 3 + 2, voice.takeRetrigger().or(deferredRetrigger.read(n)));
+                        const clear = voiceControls.read(n * 3), gate = voiceControls.read(n * 3 + 1), trigger = voiceControls.read(n * 3 + 2);
+                        // CC120 can suppress the note's first sample. Keep its reset pulse
+                        // until the first audible sample, so oscillator phase starts at zero.
+                        deferredRetrigger.write(n, clear.and(trigger).and(v.active).and(v.gate));
+                        const p = parts[n];
+                        const common = { gate, retrigger: trigger, reset: clear };
+                        const amp = p.amp.tick({ ...common, attack: ampAttack.at(i), decay: ampDecay.at(i), sustain: ampSustain.at(i), release: ampRelease.at(i) });
+                        const pitch = p.pitch.tick({ ...common, attack: pitchAttack.at(i), decay: pitchDecay.at(i), sustain: pitchSustain.at(i), release: pitchRelease.at(i) });
+                        const tone = p.tone.tick({ ...common, attack: filterAttack.at(i), decay: filterDecay.at(i), sustain: filterSustain.at(i), release: filterRelease.at(i) });
+                        signals.write(n * 4, pitch.level);
+                        signals.write(n * 4 + 1, tone.level);
+                        const wave = signals.read(4 * policy.capacity);
+                        // Combine depths in musical units before the single destination clamp.
+                        const semitones = signals.read(n * 4).mul(pitchEnvelopeDepth.at(i)).add(wave.mul(lfoPitchDepth.at(i)));
+                        const octaves = signals.read(n * 4 + 1).mul(filterEnvelopeDepth.at(i)).add(wave.mul(lfoFilterDepth.at(i)));
+                        depths.write(n * 2, semitones);
+                        depths.write(n * 2 + 1, octaves);
+                        signals.write(n * 4 + 2, modulatePitch(tuning.read(v.note.max(0)), f32(1), depths.read(n * 2), 0.45 * sampleRate));
+                        signals.write(n * 4 + 3, modulateCutoff(cutoff.at(i), f32(1), depths.read(n * 2 + 1), Math.min(20000, 0.45 * sampleRate)));
+                        // Preserve recoverable finite values across custom parts and amp gain.
+                        // Native state writes flush tiny values, so these paths stay expressions.
+                        const oscillation = p.oscillator.tick(signals.read(n * 4 + 2), clear.or(trigger));
+                        const filtered = p.filter.tick(select(clear, f32(0), oscillation), signals.read(n * 4 + 3), resonance.at(i), clear.or(trigger));
+                        // Unipolar tremolo: depth 0 is unity; depth 1 spans 0..1.
+                        const tremolo = f32(1).sub(lfoAmpDepth.at(i).mul(f32(1).sub(wave)).mul(0.5));
+                        const sample = select(v.active.and(clear.not()), filtered.mul(amp.level).mul(v.velocity).mul(tremolo), f32(0));
+                        sum = sum.add(sample);
+                        completed.write(n, amp.done);
+                        cleared.write(n, 0);
+                    });
+                    const result = select(bypass.at(i).gte(0.5).or(reset), f32(0), sum.mul(gain.at(i)));
+                    output.ch(0).at(i).write(result);
+                    output.ch(1).at(i).write(result);
+                    panic.write(false);
+                    rendered.write(true);
+                    live.write(true);
+                });
+                // MIDI is drained only before process(). Once the amp reaches zero it
+                // stays done for the rest of this block. Free completed allocations here,
+                // before the next MIDI dispatch, instead of doing O(voices²) rank updates
+                // on every sample. Audio termination remains on the exact envelope sample.
+                policy.voices.forEach((voice, n) => voice.releaseFinished(completed.read(n)));
+            } };
+    });
+}
+/** Diagnostic default: four voices, configurable at construction. */
+export const instrument = createInstrument({ mode: 'poly' });

package/dist/lfo.d.ts

@@ -0,0 +1,19 @@
+import { type Node } from '@unworklet/core';
+export interface LfoConfig {
+    sampleRate: number;
+}
+/**
+ * Free-running sine source; tick once per sample. Rate is clamped to [0,20] Hz.
+ * Output uses the current phase, then advances by rate/sampleRate. Rate zero
+ * holds phase; changing rate never resets phase. Reset emits the supplied phase
+ * on that sample and advances from it. Reset phase is in cycles, wrapped to [0,1).
+ * f64 phase prevents a small rate from stalling against a large f32 phase.
+ * Finite inputs required. No implicit note reset, depth, smoothing or routing.
+ */
+export declare const lfo: import("@unworklet/core").SubgraphDecl<[config: LfoConfig], {
+    tick(rate: Node<"f32">, reset: Node<"bool">, resetPhase: Node<"f32">): Node<"f32">;
+}>;
+/** Destination-unit depth, with final bounds enforced by the destination. */
+export declare function modulatePitch(baseHz: Node<'f32'>, signal: Node<'f32'>, semitones: Node<'f32'>, maxHz: number): Node<"f32">;
+export declare function modulateCutoff(baseHz: Node<'f32'>, signal: Node<'f32'>, octaves: Node<'f32'>, maxHz: number): Node<"f32">;
+export declare function modulateDelay(baseSeconds: Node<'f32'>, signal: Node<'f32'>, depthSeconds: Node<'f32'>, minSeconds: number, maxSeconds: number): Node<"f32">;

package/dist/lfo.js

@@ -0,0 +1,55 @@
+import { defineSubgraph, f32, f64, select, state } from '@unworklet/core';
+/**
+ * Free-running sine source; tick once per sample. Rate is clamped to [0,20] Hz.
+ * Output uses the current phase, then advances by rate/sampleRate. Rate zero
+ * holds phase; changing rate never resets phase. Reset emits the supplied phase
+ * on that sample and advances from it. Reset phase is in cycles, wrapped to [0,1).
+ * f64 phase prevents a small rate from stalling against a large f32 phase.
+ * Finite inputs required. No implicit note reset, depth, smoothing or routing.
+ */
+export const lfo = defineSubgraph((config) => {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 1) {
+        throw new RangeError('lfo sampleRate must be a positive integer');
+    }
+    const phase = state.f64(0).named('phase');
+    return {
+        tick(rate, reset, resetPhase) {
+            const requested = f64(resetPhase);
+            const current = select(reset, requested.sub(requested.floor()), phase.read());
+            const next = current.add(f64(rate.clamp(0, 20)).div(config.sampleRate));
+            phase.write(next.sub(next.floor()));
+            // Reflect cycles into [-1/4,1/4] before polynomial evaluation. The
+            // degree-13 sine remainder is <= (pi/2)^15 / 15! < 7e-10.
+            // unworklet 0.4.1 sin demotes f64 to its f32 degree-9 approximation;
+            // direct f64 arithmetic preserves slow phase changes and the error bound.
+            const centered = current.sub(select(current.gt(0.5), f64(1), f64(0)));
+            const folded = select(centered.gt(0.25), f64(0.5).sub(centered), select(centered.lt(-0.25), f64(-0.5).sub(centered), centered));
+            const x = folded.mul(2 * Math.PI), x2 = x.mul(x);
+            const polynomial = f64(1 / 6227020800).mul(x2).sub(1 / 39916800)
+                .mul(x2).add(1 / 362880).mul(x2).sub(1 / 5040)
+                .mul(x2).add(1 / 120).mul(x2).sub(1 / 6).mul(x2).add(1);
+            return f32(x.mul(polynomial)).clamp(-1, 1);
+        },
+    };
+});
+// The musical octave ratio has a bounded exponent [-8,8]. Evaluate exp(x/16)
+// through degree 8, then square four times: |x/16| <= ln(2)/2, giving < 5e-9
+// relative truncation error. This avoids 0.4.1's approximate f32 pow/log path.
+function octaveRatio(octaves) {
+    const x = f64(octaves).mul(Math.LN2 / 16);
+    const p = f64(1 / 40320).mul(x).add(1 / 5040).mul(x).add(1 / 720)
+        .mul(x).add(1 / 120).mul(x).add(1 / 24).mul(x).add(1 / 6)
+        .mul(x).add(0.5).mul(x).add(1).mul(x).add(1);
+    const p2 = p.mul(p), p4 = p2.mul(p2), p8 = p4.mul(p4);
+    return f32(p8.mul(p8));
+}
+/** Destination-unit depth, with final bounds enforced by the destination. */
+export function modulatePitch(baseHz, signal, semitones, maxHz) {
+    return baseHz.mul(octaveRatio(signal.clamp(-1, 1).mul(semitones.clamp(-24, 24)).div(12))).clamp(0, maxHz);
+}
+export function modulateCutoff(baseHz, signal, octaves, maxHz) {
+    return baseHz.mul(octaveRatio(signal.clamp(-1, 1).mul(octaves.clamp(-8, 8)))).clamp(20, maxHz);
+}
+export function modulateDelay(baseSeconds, signal, depthSeconds, minSeconds, maxSeconds) {
+    return baseSeconds.add(signal.clamp(-1, 1).mul(depthSeconds.clamp(0, 0.05))).clamp(minSeconds, maxSeconds);
+}

package/dist/live-buffer.d.ts

@@ -0,0 +1,39 @@
+import { type Node } from '@unworklet/core';
+export interface LiveSampleBufferConfig {
+    /** Fixed mono history capacity, 1..65,536 accepted writes. */
+    capacity: number;
+    /** Incoming processor rate, 8,000..192,000 Hz. No resampling. */
+    sampleRate: number;
+}
+export interface LiveSampleBufferControls {
+    input: Node<'f32'>;
+    /** Accept one frame per tick. False freezes history, including its ages. */
+    record: Node<'bool'>;
+    /** Level-sensitive logical clear, with priority over record. Not secure erasure. */
+    reset: Node<'bool'>;
+}
+export interface LiveSampleBufferRead {
+    output: Node<'f32'>;
+    /** True only for finite age in [0,length-1], including both interpolation taps. */
+    available: Node<'bool'>;
+}
+export interface LiveSampleBufferStatus {
+    written: Node<'bool'>;
+    full: Node<'bool'>;
+    length: Node<'i32'>;
+}
+export interface LiveSampleBuffer {
+    readonly capacity: number;
+    readonly sampleRate: number;
+    tick(controls: LiveSampleBufferControls): LiveSampleBufferStatus;
+    /** Age 0 is the latest accepted write at this statement position. Linear
+     * interpolation toward older writes; unavailable ages are silent, not wrapped. */
+    readAge(ageFrames: Node<'f64'>): LiveSampleBufferRead;
+    length(): Node<'i32'>;
+    /** Wrapping i32 mutation serial: one increment per accepted write or reset. */
+    revision(): Node<'i32'>;
+}
+/** Bounded rolling mono history with explicit accepted-write ages. Intentionally
+ * not a ResidentSample: rotating age coordinates must not silently change the
+ * meaning of existing sample-player/grain positions. No device or host ingress. */
+export declare const liveSampleBuffer: import("@unworklet/core").SubgraphDecl<[config: LiveSampleBufferConfig], LiveSampleBuffer>;

package/dist/live-buffer.js

@@ -0,0 +1,52 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const PCM_SCALE = 2 ** 128;
+const AGE_SCALE = 2 ** 192;
+const F32_MAX = 3.4028234663852886e38;
+/** Bounded rolling mono history with explicit accepted-write ages. Intentionally
+ * not a ResidentSample: rotating age coordinates must not silently change the
+ * meaning of existing sample-player/grain positions. No device or host ingress. */
+export const liveSampleBuffer = defineSubgraph((config) => {
+    const { capacity, sampleRate } = config;
+    if (!Number.isInteger(capacity) || capacity < 1 || capacity > 65536)
+        throw new RangeError('live buffer 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');
+    // Exact binary scaling preserves every finite f32, including subnormals,
+    // across core 0.4.1's 1e-30 scalar-store floor. The extra cell is private.
+    const pcm = state.buffer.f64({ size: capacity + 1 }).expose({ name: 'pcm', snapshot: 'persistent' });
+    const head = state.i32(0).named('head'), length = state.i32(0).named('length');
+    const revision = state.i32(0).named('revision');
+    const readAge = state.f64(0).expose({ name: 'readAge', snapshot: 'transient' });
+    return {
+        capacity, sampleRate,
+        tick(c) {
+            const written = c.record.and(c.reset.not());
+            const finite = c.input.eq(c.input).and(c.input.abs().lte(F32_MAX));
+            // select evaluates both branches. Paused/reset ticks touch the sentinel,
+            // not exposed history, and no clearing pass runs on reset.
+            pcm.write(select(written, head.read(), i32(capacity)), select(written.and(finite), f64(c.input).mul(PCM_SCALE), f64(0)));
+            head.write(select(c.reset, i32(0), select(written, head.read().add(1).mod(capacity), head.read())));
+            length.write(select(c.reset, i32(0), length.read().add(select(written, i32(1), i32(0))).min(capacity)));
+            revision.write(revision.read().add(select(written.or(c.reset), i32(1), i32(0))));
+            const current = length.read();
+            return { written, full: current.eq(capacity), length: current };
+        },
+        readAge(ageFrames) {
+            const count = length.read();
+            const available = ageFrames.gte(0).and(ageFrames.lte(f64(count.sub(1))));
+            // Keep invalid ages out of integer conversion and address arithmetic.
+            // Scale the cache before its native store so tiny valid fractions still
+            // contribute when adjacent samples span the full finite f32 range.
+            readAge.write(select(available, ageFrames, f64(0)).mul(AGE_SCALE));
+            const age = readAge.read().div(AGE_SCALE), whole = i32(age.floor());
+            const fraction = age.sub(f64(whole));
+            const older = whole.add(1).min(count.sub(1).max(0));
+            const newest = head.read().add(capacity - 1);
+            const a = pcm.read(newest.sub(whole).mod(capacity)).div(PCM_SCALE);
+            const b = pcm.read(newest.sub(older).mod(capacity)).div(PCM_SCALE);
+            return { output: select(available, f32(a.add(b.sub(a).mul(fraction))), f32(0)), available };
+        },
+        length() { return length.read(); },
+        revision() { return revision.read(); },
+    };
+});

package/dist/live-granular.d.ts

@@ -0,0 +1,41 @@
+import { type Node } from '@unworklet/core';
+import type { LiveSampleBuffer } from './live-buffer.js';
+export interface LiveGranularConfig {
+    /** Shared accepted-write history; its sampleRate must match the processor. */
+    history: LiveSampleBuffer;
+    /** Immutable first-free pool size, integer 1..8. */
+    maxGrains: number;
+}
+export interface LiveGranularControls {
+    /** Exactly the immediately preceding history.tick() status.written. */
+    written: Node<'bool'>;
+    /** The same reset passed to history.tick(); level-sensitive, highest priority. */
+    reset: Node<'bool'>;
+    /** One request per true sample; held true requests every sample. */
+    trigger: Node<'bool'>;
+    /** Onset age after the current write, in retained accepted-write frames. */
+    ageFrames: Node<'f32'>;
+    /** Signed frames toward newer source material per output sample, [-16,16]. */
+    rate: Node<'f32'>;
+    /** [0,2] seconds, rounded to frames with minimum 3. Zero is valid. */
+    durationSeconds: Node<'f32'>;
+}
+export interface LiveGranularResult {
+    output: Node<'f32'>;
+    /** Valid reads this sample, including both zero-weight window endpoints. */
+    activeGrains: Node<'i32'>;
+    launched: Node<'bool'>;
+    /** Valid request with a full pool; no stealing or queue. */
+    dropped: Node<'bool'>;
+    /** Invalid controls or unavailable onset. Does not interrupt existing grains. */
+    rejected: Node<'bool'>;
+    /** Existing grains whose current read became unavailable; excludes reset/EOF. */
+    expiredGrains: Node<'i32'>;
+}
+export interface LiveGranularSource {
+    tick(controls: LiveGranularControls): LiveGranularResult;
+}
+/** Fixed mono live-history grain reader. Call the writer, then this reader once
+ * per sample with the writer's written flag and shared reset. No density clock,
+ * source ownership, resampling filter, implicit safety margin or host ingress. */
+export declare const liveGranularSource: import("@unworklet/core").SubgraphDecl<[config: LiveGranularConfig], LiveGranularSource>;

package/dist/live-granular.js

@@ -0,0 +1,64 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+// Preserve small representable scalar values across core 0.4.1's 1e-30
+// state-store floor. This does not extend f64 precision at a large cursor.
+const SCALE = 2 ** 192;
+/** Fixed mono live-history grain reader. Call the writer, then this reader once
+ * per sample with the writer's written flag and shared reset. No density clock,
+ * source ownership, resampling filter, implicit safety margin or host ingress. */
+export const liveGranularSource = defineSubgraph((config) => {
+    const { history, maxGrains } = config;
+    if (!Number.isInteger(maxGrains) || maxGrains < 1 || maxGrains > 8)
+        throw new RangeError('liveGranularSource maxGrains must be an integer in [1,8]');
+    if (!Number.isInteger(history.capacity) || history.capacity < 1 || history.capacity > 65536 || !Number.isFinite(history.sampleRate) || history.sampleRate < 8000 || history.sampleRate > 192000)
+        throw new RangeError('liveGranularSource history requires capacity [1,65536] and sampleRate [8000,192000]');
+    const allocated = state.bool(false).expose({ name: 'allocated', snapshot: 'transient' });
+    const grains = Array.from({ length: maxGrains }, (_, n) => ({
+        active: state.bool(false).named(`grain${n}Active`),
+        index: state.i32(0).named(`grain${n}Index`),
+        duration: state.i32(3).named(`grain${n}Duration`),
+        age: state.f64(0).named(`grain${n}AgeScaled`),
+        rate: state.f64(0).named(`grain${n}RateScaled`),
+    }));
+    return { tick(c) {
+            const requested = c.trigger.and(c.reset.not());
+            const valid = c.ageFrames.gte(0).and(c.ageFrames.lte(history.capacity - 1))
+                .and(f64(c.ageFrames).lte(f64(history.length().sub(1))))
+                .and(c.rate.gte(-16)).and(c.rate.lte(16))
+                .and(c.durationSeconds.gte(0)).and(c.durationSeconds.lte(2));
+            const attempt = requested.and(valid);
+            // select is eager. Sanitize before conversion even on rejected requests.
+            const duration = i32(f64(select(valid, c.durationSeconds, f32(0))).mul(history.sampleRate).add(.5).floor()).clamp(3, Math.round(2 * history.sampleRate));
+            const onsetAge = f64(select(valid, c.ageFrames, f32(0))), onsetRate = f64(select(valid, c.rate, f32(0)));
+            allocated.write(false);
+            let sum = f64(0), count = i32(0), expired = i32(0);
+            for (const grain of grains) {
+                const activeBefore = grain.active.read().and(c.reset.not());
+                // Add the increment as one expression: (tinyAge + 1) - 1 would erase
+                // representable tiny onset fractions while continuously writing at rate 1.
+                const increment = select(c.written, f64(1), f64(0)).sub(grain.rate.read().div(SCALE));
+                const currentAge = grain.age.read().div(SCALE).add(increment);
+                const available = currentAge.gte(0).and(currentAge.lte(f64(history.length().sub(1))));
+                const existing = activeBefore.and(available);
+                expired = expired.add(select(activeBefore.and(available.not()), i32(1), i32(0)));
+                const alreadyAllocated = allocated.read();
+                const launch = attempt.and(alreadyAllocated.not()).and(existing.not());
+                allocated.write(alreadyAllocated.or(launch));
+                const active = existing.or(launch);
+                grain.index.write(select(c.reset.or(launch), i32(0), grain.index.read()));
+                grain.duration.write(select(c.reset, i32(3), select(launch, duration, grain.duration.read())));
+                grain.rate.write(select(c.reset, f64(0), select(launch, onsetRate.mul(SCALE), grain.rate.read())));
+                grain.age.write(select(active, select(launch, onsetAge, currentAge).mul(SCALE), f64(0)));
+                const index = grain.index.read(), length = grain.duration.read();
+                const window = f64(1).sub(f64(index).mul(2).div(f64(length.sub(1))).sub(1).abs()).max(0);
+                const read = history.readAge(grain.age.read().div(SCALE));
+                sum = sum.add(select(active, f64(read.output).mul(window), f64(0)));
+                count = count.add(select(active, i32(1), i32(0)));
+                grain.index.write(select(active, index.add(1), i32(0)));
+                // Natural completion is recorded now, before next sample's age validity.
+                grain.active.write(active.and(index.add(1).lt(length)));
+            }
+            const launched = allocated.read();
+            return { output: f32(sum.div(maxGrains)), activeGrains: count, launched,
+                dropped: attempt.and(launched.not()), rejected: requested.and(valid.not()), expiredGrains: expired };
+        } };
+});

package/dist/lookahead-limiter.d.ts

@@ -0,0 +1,31 @@
+import { type Node } from '@unworklet/core';
+export interface LookaheadLimiterConfig {
+    sampleRate: number;
+    /** Fixed integer latency/allocation, 0..2048 samples. No implicit default. */
+    lookaheadSamples: number;
+}
+export interface LookaheadLimiterControls {
+    /** Current-output sample ceiling in dBFS, clamped to [-120,0]; nonfinite -> 0. */
+    ceilingDb: Node<'f32'>;
+    /** Peak-detector release, 0..30 seconds; nonfinite -> 0. Attack is immediate. */
+    release: Node<'f32'>;
+    /** Invalidate all history before accepting this sample. */
+    reset: Node<'bool'>;
+}
+/** Bounded stereo-linked sample-peak limiter. Not a true-peak limiter. */
+export declare const lookaheadLimiter: import("@unworklet/core").SubgraphDecl<[config: LookaheadLimiterConfig], {
+    latencySamples: number;
+    latencySeconds: number;
+    /** Exactly once per sample. Dry outputs have the same fixed latency. */
+    tick(left: Node<"f32">, right: Node<"f32">, controls: LookaheadLimiterControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        dryLeft: Node<"f32">;
+        dryRight: Node<"f32">;
+        envelope: Node<"f32">;
+        windowPeak: Node<"f32">;
+        ceiling: Node<"f32">;
+        /** Diagnostic only: this f32 conversion may underflow for extreme audio. */
+        gain: Node<"f32">;
+    };
+}>;

package/dist/lookahead-limiter.js

@@ -0,0 +1,67 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { envelopeFollower } from './dynamics.js';
+const SCALE = 2 ** 128;
+function finite(input) {
+    return select(input.eq(input).and(input.abs().lte(3.4028234663852886e38)), input, f32(0));
+}
+/** Bounded stereo-linked sample-peak limiter. Not a true-peak limiter. */
+export const lookaheadLimiter = defineSubgraph((config) => {
+    const { sampleRate, lookaheadSamples: delay } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) {
+        throw new RangeError('lookaheadLimiter sampleRate must be an integer in [8000,192000]');
+    }
+    if (!Number.isInteger(delay) || delay < 0 || delay > 2048) {
+        throw new RangeError('lookaheadLimiter lookaheadSamples must be an integer in [0,2048]');
+    }
+    const size = delay + 1, capacity = 2 ** Math.ceil(Math.log2(size));
+    // Native buffer writes flush magnitudes below 1e-30. Exact binary scaling
+    // preserves every finite f32 value, including subnormals, without overflow.
+    const leftHistory = state.buffer.f64({ size }).expose({ name: 'leftScaled', snapshot: 'persistent' });
+    const rightHistory = state.buffer.f64({ size }).expose({ name: 'rightScaled', snapshot: 'persistent' });
+    const peaks = state.buffer.f64({ size: capacity * 2 }).expose({ name: 'peakTreeScaled', snapshot: 'persistent' });
+    const cursor = state.i32(0).named('cursor'), valid = state.i32(0).named('valid');
+    const follower = instantiate(envelopeFollower, { sampleRate, mode: 'peak' }, { name: 'detector' });
+    return {
+        latencySamples: delay,
+        latencySeconds: delay / sampleRate,
+        /** Exactly once per sample. Dry outputs have the same fixed latency. */
+        tick(left, right, controls) {
+            const write = select(controls.reset, i32(0), cursor.read());
+            const available = select(controls.reset, i32(0), valid.read()).add(1).min(size);
+            const l = f64(finite(left)).mul(SCALE), r = f64(finite(right)).mul(SCALE);
+            leftHistory.write(write, l);
+            rightHistory.write(write, r);
+            peaks.write(write.add(capacity), l.abs().max(r.abs()));
+            // At reset the valid leaves form an initially empty prefix. Sequential
+            // refill ensures each included sibling was rebuilt since that reset.
+            // Other siblings (including permanently unused leaves) are read as zero.
+            // Once full, all real leaves stay valid across arbitrary ring wraps.
+            for (let width = 2; width <= capacity; width *= 2) {
+                const block = write.div(width), first = block.mul(width), node = block.add(capacity / width);
+                const low = select(first.lt(available), peaks.read(node.mul(2)), f64(0));
+                const high = select(first.add(width / 2).lt(available), peaks.read(node.mul(2).add(1)), f64(0));
+                peaks.write(node, low.max(high));
+            }
+            const windowPeak = f32(peaks.read(1).div(SCALE));
+            const envelope = follower.tick(windowPeak, { attack: f32(0), release: controls.release, reset: controls.reset });
+            const ceiling = finite(controls.ceilingDb).clamp(-120, 0).mul(Math.LN10 / 20).exp();
+            const gain = select(envelope.gt(0), f64(ceiling).div(select(envelope.gt(0), f64(envelope), f64(1))).min(1), f64(1));
+            const read = write.add(1).mod(size);
+            const ready = available.eq(size);
+            const dryLeft = select(ready, leftHistory.read(read).div(SCALE), f64(0));
+            const dryRight = select(ready, rightHistory.read(read).div(SCALE), f64(0));
+            cursor.write(read);
+            valid.write(available);
+            return {
+                // Keep the gain f64 through multiplication: full-range f32 input at a
+                // -120dB ceiling would otherwise quantize its tiny gain to a few ulps.
+                left: f32(dryLeft.mul(gain)).clamp(ceiling.neg(), ceiling),
+                right: f32(dryRight.mul(gain)).clamp(ceiling.neg(), ceiling),
+                dryLeft: f32(dryLeft), dryRight: f32(dryRight),
+                envelope, windowPeak, ceiling,
+                /** Diagnostic only: this f32 conversion may underflow for extreme audio. */
+                gain: f32(gain),
+            };
+        },
+    };
+});

package/dist/loop-crossfade.d.ts

@@ -0,0 +1,28 @@
+import { type Node } from '@unworklet/core';
+import type { ResidentSample, SamplePlayerControls } from './sample.js';
+export interface CrossfadedLoopConfig {
+    sampleRate: number;
+    sample: ResidentSample;
+    /** Fixed source slice [startFrame,endFrame), intersected with loaded length. */
+    startFrame?: number;
+    endFrame?: number;
+    /** Source-frame overlap, 0..floor(slice length/2). Effective period is L-F,
+     * and forward playback starts at startFrame+F. Zero disables the overlap. */
+    crossfadeFrames: number;
+    /** Linear gate-off ramp in output samples; zero/one stops on first off sample. */
+    releaseFrames?: number;
+}
+/** One mono cyclic waveform with a unity-sum linear tail/head overlap. Shortens
+ * the source period from L to L-F; reverse traverses that same waveform backward.
+ * Not a dry-attack, time-stretching, antialiasing or arbitrary-content seam promise. */
+export declare const crossfadedLoopPlayer: import("@unworklet/core").SubgraphDecl<[config: CrossfadedLoopConfig], {
+    tick(c: SamplePlayerControls): {
+        output: Node<"f32">;
+        active: Node<"bool">;
+        position: Node<"f32">;
+        phase: Node<"f32">;
+        periodFrames: Node<"i32">;
+        crossfadeFrames: Node<"i32">;
+        missing: Node<"bool">;
+    };
+}>;