@denaudio/den 0.0.0-stage → 0.1.0

package/dist/performance.d.ts

@@ -0,0 +1,61 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+import { type VoicePolicyConfig } from './voice-policy.js';
+export interface PitchGlideConfig {
+    sampleRate: number;
+}
+export interface PitchGlideControls {
+    /** MIDI-note semitones, clamped [-128,255]. */
+    target: Node<'f32'>;
+    /** [0,30] seconds; rounded to nearest sample and latched on target change. */
+    seconds: Node<'f32'>;
+    /** Level-sensitive: follow target immediately, consuming its current value. */
+    reset: Node<'bool'>;
+    /** Level-sensitive immediate target following, e.g. a nonlegato retrigger. */
+    snap: Node<'bool'>;
+}
+/** Constant-time linear glide in musical pitch. Call once per sample. */
+export declare const pitchGlide: import("@unworklet/core").SubgraphDecl<[config: PitchGlideConfig], {
+    tick(c: PitchGlideControls): Node<"f32">;
+}>;
+export interface TuningControls {
+    note: Node<'f32'>;
+    transpose: Node<'f32'>;
+    cents: Node<'f32'>;
+    a4: Node<'f32'>;
+}
+/** Finite controls, bounded 12-TET conversion, one final frequency ceiling. */
+export declare function tunedFrequency(c: TuningControls, maxFrequency: number): Node<"f32">;
+export interface PerformancePolicyConfig extends VoicePolicyConfig {
+    /** Poly default/max 4; mono must be 1. */
+    capacity?: number;
+    /** Default/max 8; counts physically-held AND pedal-held identities. */
+    heldCapacity?: number;
+}
+/** Native MIDI expression + bounded sustain ledger over the unchanged allocator.
+ * MIDI remains quantum-boundary FIFO. All performance state is transient.
+ * See docs/performance.md for duplicate, overflow, CC and DSP-clear semantics.
+ */
+export declare const performancePolicy: import("@unworklet/core").SubgraphDecl<[config: PerformancePolicyConfig], {
+    capacity: number;
+    heldCapacity: number;
+    reset: (when?: Node<"bool">) => void;
+    overflowed: () => Node<"bool">;
+    bindMidi(input: MidiInputHandle): void;
+    voices: {
+        read(): {
+            channelPressure: Node<"f32">;
+            polyPressure: Node<"f32">;
+            bend: Node<"f32">;
+            timbre: Node<"f32">;
+            sustain: Node<"bool">;
+            active: Node<"bool">;
+            gate: Node<"bool">;
+            note: Node<"i32">;
+            channel: Node<"i32">;
+            velocity: Node<"f32">;
+        };
+        takeRetrigger(): Node<"bool">;
+        takeReset(): Node<"bool">;
+        releaseFinished(done: Node<"bool">): void;
+    }[];
+}>;

package/dist/performance.js

@@ -0,0 +1,241 @@
+import { bool, defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { voicePolicy } from './voice-policy.js';
+// Native scalar writes flush tiny values. Scale musical pitch state so every
+// finite f32 target survives; this is storage encoding, not a new noise floor.
+const PITCH_SCALE = 2 ** 128;
+/** Constant-time linear glide in musical pitch. Call once per sample. */
+export const pitchGlide = defineSubgraph((config) => {
+    if (!Number.isInteger(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000) {
+        throw new RangeError('pitchGlide sampleRate must be an integer in [8000,192000]');
+    }
+    const live = state.bool(false).named('live');
+    const value = state.f64(0).named('valueScaled');
+    const target = state.f64(0).named('targetScaled');
+    const remaining = state.i32(0).named('remaining');
+    return { tick(c) {
+            const destination = f64(c.target.clamp(-128, 255)).mul(PITCH_SCALE);
+            const changed = destination.eq(target.read()).not();
+            const immediate = c.reset.or(c.snap).or(live.read().not());
+            const frames = i32(f64(c.seconds.clamp(0, 30)).mul(config.sampleRate).add(0.5).floor());
+            remaining.write(select(immediate, i32(0), select(changed, frames, remaining.read())));
+            const count = remaining.read();
+            const output = select(immediate.or(count.lte(1)), destination, value.read().add(destination.sub(value.read()).div(f64(count.max(1)))));
+            value.write(output);
+            target.write(destination);
+            remaining.write(count.sub(1).max(0));
+            live.write(true);
+            return f32(output.div(PITCH_SCALE));
+        } };
+});
+/** Finite controls, bounded 12-TET conversion, one final frequency ceiling. */
+export function tunedFrequency(c, maxFrequency) {
+    if (!Number.isFinite(maxFrequency) || maxFrequency <= 0 || maxFrequency > 3.4028234663852886e38) {
+        throw new RangeError('maxFrequency must be positive and representable as finite f32');
+    }
+    const semitones = f64(c.note.clamp(-128, 255)).sub(69)
+        .add(f64(c.transpose.clamp(-48, 48))).add(f64(c.cents.clamp(-1200, 1200)).div(100));
+    // Both pow and exp use an approximate f32 bridge in core 0.4.1.
+    // |semitones| <= 257: exp(x/32), |x/32| < .465, degree 12,
+    // then five squarings. The bounded remainder stays below f32 rounding.
+    const x = semitones.mul(Math.LN2 / (12 * 32));
+    let factorial = 1;
+    const inverse = [1];
+    for (let n = 1; n <= 12; n++) {
+        factorial *= n;
+        inverse.push(1 / factorial);
+    }
+    let ratio = f64(inverse[12]);
+    for (let n = 11; n >= 0; n--)
+        ratio = ratio.mul(x).add(inverse[n]);
+    for (let n = 0; n < 5; n++)
+        ratio = ratio.mul(ratio);
+    return f32(f64(c.a4.clamp(220, 880)).mul(ratio).min(maxFrequency));
+}
+/** Native MIDI expression + bounded sustain ledger over the unchanged allocator.
+ * MIDI remains quantum-boundary FIFO. All performance state is transient.
+ * See docs/performance.md for duplicate, overflow, CC and DSP-clear semantics.
+ */
+export const performancePolicy = defineSubgraph((config) => {
+    const size = config.capacity ?? (config.mode === 'mono' ? 1 : 4);
+    const heldSize = config.heldCapacity ?? 8;
+    if (!Number.isInteger(size) || size < 1 || size > 4)
+        throw new RangeError('performance capacity must be an integer in [1,4]');
+    if (!Number.isInteger(heldSize) || heldSize < size || heldSize > 8)
+        throw new RangeError('performance heldCapacity must be between capacity and 8');
+    const policy = instantiate(voicePolicy, { ...config, capacity: size, heldCapacity: heldSize }, { name: 'allocator' });
+    const ints = (name, length) => state.buffer.i32({ size: length }).expose({ name, snapshot: 'transient' });
+    const floats = (name, length) => state.buffer.f32({ size: length }).expose({ name, snapshot: 'transient' });
+    // Dense ages (1..heldSize), not an ever-increasing event counter.
+    const age = ints('heldAge', heldSize), key = ints('heldKey', heldSize), channel = ints('heldChannel', heldSize), down = ints('heldDown', heldSize);
+    const pedal = ints('pedal', 16), bend = floats('bend', 16), pressure = floats('channelPressure', 16), timbre = floats('timbre', 16);
+    const polyPressure = floats('polyPressure', size), trigger = ints('trigger', size), clear = ints('clear', size);
+    const oldKey = ints('oldKey', size), oldChannel = ints('oldChannel', size), scratch = ints('scratch', 3);
+    const previousIdentity = state.i32(-1).expose({ name: 'previousIdentity', snapshot: 'transient' });
+    const overflow = state.bool(false).expose({ name: 'overflow', snapshot: 'transient' });
+    const validChannel = (ch) => ch.gte(0).and(ch.lte(15));
+    const validKey = (note, ch) => validChannel(ch).and(note.gte(0)).and(note.lte(127));
+    const safeChannel = (ch) => ch.clamp(0, 15);
+    function newestIdentity() {
+        scratch.write(0, -1);
+        scratch.write(1, 0);
+        for (let n = 0; n < heldSize; n++) {
+            const newer = age.read(n).gt(scratch.read(1));
+            scratch.write(0, select(newer, i32(n), scratch.read(0)));
+            scratch.write(1, select(newer, age.read(n), scratch.read(1)));
+        }
+    }
+    function beforeChange() {
+        if (config.mode === 'mono') {
+            newestIdentity();
+            previousIdentity.write(scratch.read(0));
+        }
+        policy.voices.forEach((voice, n) => { const v = voice.read(); oldKey.write(n, v.note); oldChannel.write(n, v.channel); });
+    }
+    function afterChange() {
+        if (config.mode === 'mono')
+            newestIdentity();
+        const identityChanged = config.mode === 'mono' ? scratch.read(0).gte(0).and(scratch.read(0).eq(previousIdentity.read()).not()) : bool(false);
+        policy.voices.forEach((voice, n) => {
+            const v = voice.read(), retrigger = voice.takeRetrigger();
+            trigger.write(n, select(retrigger, i32(1), trigger.read(n)));
+            polyPressure.write(n, select(retrigger.or(identityChanged).or(v.active.not()).or(v.note.eq(oldKey.read(n)).not()).or(v.channel.eq(oldChannel.read(n)).not()), f32(0), polyPressure.read(n)));
+        });
+    }
+    function remove(index, when) {
+        const old = age.read(index);
+        for (let n = 0; n < heldSize; n++)
+            age.write(n, select(when.and(age.read(n).gt(old)), age.read(n).sub(1), age.read(n)));
+        age.write(index, select(when, i32(0), age.read(index)));
+        key.write(index, select(when, i32(0), key.read(index)));
+        channel.write(index, select(when, i32(0), channel.read(index)));
+        down.write(index, select(when, i32(0), down.read(index)));
+    }
+    function oldest(ch, note, physicallyDown, matchKey) {
+        scratch.write(0, 0);
+        scratch.write(1, heldSize + 1);
+        for (let n = 0; n < heldSize; n++) {
+            const candidate = age.read(n).gt(0).and(age.read(n).lt(scratch.read(1))).and(channel.read(n).eq(ch))
+                .and(physicallyDown ? down.read(n).gt(0) : down.read(n).eq(0)).and(matchKey ? key.read(n).eq(note) : bool(true));
+            scratch.write(0, select(candidate, i32(n), scratch.read(0)));
+            scratch.write(1, select(candidate, age.read(n), scratch.read(1)));
+        }
+    }
+    function noteOff(note, ch, when = bool(true)) {
+        oldest(ch, note, true, true);
+        const index = scratch.read(0), found = when.and(validKey(note, ch)).and(scratch.read(1).lte(heldSize));
+        const release = found.and(pedal.read(safeChannel(ch)).eq(0));
+        down.write(index, select(found, i32(0), down.read(index)));
+        policy.noteOff(select(release, note, i32(-1)), ch);
+        remove(index, release);
+    }
+    function flush(ch) {
+        for (let n = 0; n < heldSize; n++) {
+            oldest(ch, i32(0), false, false);
+            const index = scratch.read(0), found = validChannel(ch).and(scratch.read(1).lte(heldSize));
+            policy.noteOff(select(found, key.read(index), i32(-1)), ch);
+            remove(index, found);
+        }
+    }
+    function noteOn(note, ch, velocity) {
+        noteOff(note, ch, velocity.eq(0));
+        scratch.write(0, 0);
+        scratch.write(1, 0);
+        scratch.write(2, 0);
+        for (let n = heldSize - 1; n >= 0; n--) {
+            const free = age.read(n).eq(0);
+            scratch.write(0, select(free, i32(n), scratch.read(0)));
+            scratch.write(1, select(free, i32(1), scratch.read(1)));
+            scratch.write(2, scratch.read(2).add(select(free, i32(0), i32(1))));
+        }
+        const index = scratch.read(0), enabled = validKey(note, ch).and(velocity.gt(0)).and(velocity.lte(127));
+        const accept = enabled.and(scratch.read(1).gt(0));
+        overflow.write(overflow.read().or(enabled.and(accept.not())));
+        age.write(index, select(accept, scratch.read(2).add(1), age.read(index)));
+        key.write(index, select(accept, note, key.read(index)));
+        channel.write(index, select(accept, ch, channel.read(index)));
+        down.write(index, select(accept, i32(1), down.read(index)));
+        policy.noteOn(select(accept, note, i32(-1)), ch, velocity);
+    }
+    function allSoundOff(ch) {
+        policy.voices.forEach((voice, n) => {
+            const affected = voice.read().active.and(voice.read().channel.eq(ch));
+            clear.write(n, select(affected, i32(1), clear.read(n)));
+            trigger.write(n, select(affected, i32(0), trigger.read(n)));
+        });
+        policy.allSoundOff(ch);
+        for (let n = 0; n < heldSize; n++)
+            remove(i32(n), age.read(n).gt(0).and(channel.read(n).eq(ch)));
+        const safe = safeChannel(ch);
+        pedal.write(safe, select(validChannel(ch), i32(0), pedal.read(safe)));
+    }
+    function control(ch, controller, value) {
+        const safe = safeChannel(ch), valid = validChannel(ch).and(value.gte(0)).and(value.lte(127));
+        const sustain = valid.and(controller.eq(64)), resetControllers = valid.and(controller.eq(121));
+        const notesOff = valid.and(controller.eq(123)), soundOff = valid.and(controller.eq(120));
+        pedal.write(safe, select(resetControllers, i32(0), select(sustain, select(value.gte(64), i32(1), i32(0)), pedal.read(safe))));
+        bend.write(safe, select(resetControllers, f32(0), bend.read(safe)));
+        pressure.write(safe, select(resetControllers, f32(0), pressure.read(safe)));
+        timbre.write(safe, select(resetControllers, f32(0), select(valid.and(controller.eq(74)), f32(value).div(127), timbre.read(safe))));
+        policy.voices.forEach((voice, n) => polyPressure.write(n, select(resetControllers.and(voice.read().channel.eq(ch)), f32(0), polyPressure.read(n))));
+        for (let n = 0; n < heldSize; n++)
+            down.write(n, select(notesOff.and(channel.read(n).eq(ch)), i32(0), down.read(n)));
+        const release = resetControllers.or(sustain.and(value.lt(64))).or(notesOff.and(pedal.read(safe).eq(0)));
+        flush(select(release, ch, i32(-1)));
+        allSoundOff(select(soundOff, ch, i32(-1)));
+    }
+    function reset(when = bool(true)) {
+        policy.reset(when);
+        for (let n = 0; n < heldSize; n++) {
+            age.write(n, select(when, i32(0), age.read(n)));
+            key.write(n, select(when, i32(0), key.read(n)));
+            channel.write(n, select(when, i32(0), channel.read(n)));
+            down.write(n, select(when, i32(0), down.read(n)));
+        }
+        for (let ch = 0; ch < 16; ch++) {
+            pedal.write(ch, select(when, i32(0), pedal.read(ch)));
+            bend.write(ch, select(when, f32(0), bend.read(ch)));
+            pressure.write(ch, select(when, f32(0), pressure.read(ch)));
+            timbre.write(ch, select(when, f32(0), timbre.read(ch)));
+        }
+        for (let n = 0; n < size; n++) {
+            polyPressure.write(n, select(when, f32(0), polyPressure.read(n)));
+            trigger.write(n, select(when, i32(0), trigger.read(n)));
+            clear.write(n, select(when, i32(1), clear.read(n)));
+        }
+        overflow.write(select(when, false, overflow.read()));
+    }
+    return {
+        capacity: size, heldCapacity: heldSize, reset,
+        overflowed: () => overflow.read().or(policy.overflowed()),
+        bindMidi(input) {
+            input.onEvent('noteOn', e => { beforeChange(); noteOn(e.note, e.channel, e.velocity); afterChange(); });
+            input.onEvent('noteOff', e => { beforeChange(); noteOff(e.note, e.channel); afterChange(); });
+            input.onEvent('cc', e => { beforeChange(); control(e.channel, e.controller, e.value); afterChange(); });
+            input.onEvent('pitchBend', e => {
+                const ch = safeChannel(e.channel), value = f32(e.value).sub(8192);
+                bend.write(ch, select(validChannel(e.channel).and(e.value.gte(0)).and(e.value.lte(16383)), value.div(select(e.value.lt(8192), f32(8192), f32(8191))), bend.read(ch)));
+            });
+            input.onEvent('channelPressure', e => {
+                const ch = safeChannel(e.channel);
+                pressure.write(ch, select(validChannel(e.channel).and(e.pressure.gte(0)).and(e.pressure.lte(127)), f32(e.pressure).div(127), pressure.read(ch)));
+            });
+            input.onEvent('aftertouch', e => {
+                policy.voices.forEach((voice, n) => {
+                    const v = voice.read(), match = v.active.and(v.channel.eq(e.channel)).and(v.note.eq(e.note)).and(e.pressure.gte(0)).and(e.pressure.lte(127));
+                    polyPressure.write(n, select(match, f32(e.pressure).div(127), polyPressure.read(n)));
+                });
+            });
+        },
+        voices: policy.voices.map((voice, n) => ({
+            read() {
+                const v = voice.read(), ch = safeChannel(v.channel);
+                return { ...v, channelPressure: select(v.active, pressure.read(ch), f32(0)),
+                    polyPressure: select(v.active, polyPressure.read(n), f32(0)), bend: select(v.active, bend.read(ch), f32(0)),
+                    timbre: select(v.active, timbre.read(ch), f32(0)), sustain: v.active.and(pedal.read(ch).gt(0)) };
+            },
+            takeRetrigger() { const value = trigger.read(n).gt(0); trigger.write(n, 0); return value; },
+            takeReset() { const value = clear.read(n).gt(0); clear.write(n, 0); return value; },
+            releaseFinished(done) { voice.releaseFinished(done); },
+        })),
+    };
+});

package/dist/pitch-quantizer.d.ts

@@ -0,0 +1,26 @@
+import { type Node } from '@unworklet/core';
+export interface PitchQuantizerConfig {
+    /** 1..128 finite offsets in [0,12), in semitones. Copied, f32-rounded, sorted. */
+    pitchClasses: readonly number[];
+    /** Fixed Schmitt margin in semitones, f32-rounded in [0,12]. Default 0. */
+    hysteresis?: number;
+}
+export interface PitchQuantizerOutput {
+    /** Selected octave*12 + pitch class, rounded to f32. */
+    pitch: Node<'f32'>;
+    /** Index into the sorted, f32-rounded pitchClasses. */
+    degree: Node<'i32'>;
+    /** Octave multiplier; pitch=12*octave+pitchClasses[degree]. Not an octave label. */
+    octave: Node<'i32'>;
+}
+/**
+ * Audio-rate, octave-periodic nearest pitch, not audio pitch detection or MIDI
+ * output. Call once per sample. NaN becomes 0; other inputs clamp to +/-16384.
+ * f64 computational distance ties choose the lower pitch. A positive margin
+ * retains the previous degree inside its expanded adjacent-midpoint interval,
+ * including both endpoints. Reset (level-sensitive) and first call snap to
+ * nearest immediately. Zero margin always uses nearest, including tie policy.
+ */
+export declare const pitchQuantizer: import("@unworklet/core").SubgraphDecl<[config: PitchQuantizerConfig], {
+    tick(input: Node<"f32">, reset: Node<"bool">): PitchQuantizerOutput;
+}>;

package/dist/pitch-quantizer.js

@@ -0,0 +1,88 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+// Native 0.4.1 scalar state flushes tiny values. f32 controls/offsets scaled
+// by this exact power of two remain well above that floor, including 2^-149.
+const SCALE = 2 ** 128;
+/**
+ * Audio-rate, octave-periodic nearest pitch, not audio pitch detection or MIDI
+ * output. Call once per sample. NaN becomes 0; other inputs clamp to +/-16384.
+ * f64 computational distance ties choose the lower pitch. A positive margin
+ * retains the previous degree inside its expanded adjacent-midpoint interval,
+ * including both endpoints. Reset (level-sensitive) and first call snap to
+ * nearest immediately. Zero margin always uses nearest, including tie policy.
+ */
+export const pitchQuantizer = defineSubgraph((config) => {
+    if (!Array.isArray(config.pitchClasses) || config.pitchClasses.length < 1 || config.pitchClasses.length > 128) {
+        throw new RangeError('pitchClasses requires 1..128 offsets');
+    }
+    // Array.from visits sparse holes too; every supplied slot must be valid.
+    const degrees = Array.from(config.pitchClasses, value => {
+        if (!Number.isFinite(value) || value < 0 || value >= 12 || Math.fround(value) >= 12) {
+            throw new RangeError('pitch class must be finite in [0,12), including after f32 rounding');
+        }
+        return Math.fround(value) || 0;
+    }).sort((a, b) => a - b);
+    if (degrees.some((value, n) => n > 0 && value === degrees[n - 1])) {
+        throw new RangeError('pitch classes must be distinct after f32 rounding');
+    }
+    const requestedMargin = config.hysteresis ?? 0;
+    if (!Number.isFinite(requestedMargin) || requestedMargin < 0 || requestedMargin > 12) {
+        throw new RangeError('hysteresis must be finite in [0,12] semitones');
+    }
+    const margin = Math.fround(requestedMargin);
+    const degree = state.i32(0).named('degree');
+    const octave = state.i32(0).named('octave');
+    const initialized = state.bool(false).named('initialized');
+    const nearestDegree = state.i32(0).named('nearestDegree');
+    const nearestOctave = state.i32(0).named('nearestOctave');
+    const nearestPitch = state.f64(0).named('nearestPitchScaled');
+    const nearestDistance = state.f64(0).named('nearestDistanceScaled');
+    const candidateOctave = state.i32(0).named('candidateOctave');
+    const candidatePitch = state.f64(0).named('candidatePitchScaled');
+    const candidateDistance = state.f64(0).named('candidateDistanceScaled');
+    const takeCandidate = state.bool(false).named('takeCandidate');
+    const update = state.bool(false).named('update');
+    return { tick(input, reset) {
+            // Unlike min/max alone, the explicit NaN branch gives a portable policy.
+            const x = f64(select(input.eq(input), input, f32(0)).clamp(-16384, 16384));
+            nearestDistance.write(f64(32768 * SCALE));
+            nearestPitch.write(f64(32768 * SCALE));
+            for (let n = 0; n < degrees.length; n++) {
+                // Compare both bracketing octaves by their actual f64 distances.
+                // A midpoint shortcut is not equivalent near zero: e.g. +/-6 have
+                // equal rounded distances from an f32 subnormal, so lower must win.
+                candidateOctave.write(i32(x.sub(degrees[n]).div(12).floor()));
+                for (let adjacent = 0; adjacent < 2; adjacent++) {
+                    if (adjacent > 0)
+                        candidateOctave.write(candidateOctave.read().add(1));
+                    candidatePitch.write(f64(candidateOctave.read()).mul(12).add(degrees[n]).mul(SCALE));
+                    candidateDistance.write(x.mul(SCALE).sub(candidatePitch.read()).abs());
+                    takeCandidate.write(candidateDistance.read().lt(nearestDistance.read()).or(candidateDistance.read().eq(nearestDistance.read()).and(candidatePitch.read().lt(nearestPitch.read()))));
+                    nearestDegree.write(select(takeCandidate.read(), i32(n), nearestDegree.read()));
+                    nearestOctave.write(select(takeCandidate.read(), candidateOctave.read(), nearestOctave.read()));
+                    nearestPitch.write(select(takeCandidate.read(), candidatePitch.read(), nearestPitch.read()));
+                    nearestDistance.write(select(takeCandidate.read(), candidateDistance.read(), nearestDistance.read()));
+                }
+            }
+            if (margin === 0) {
+                update.write(bool(true));
+            }
+            else {
+                let lower = f64(0), upper = f64(0);
+                for (let n = 0; n < degrees.length; n++) {
+                    const previous = n === 0 ? degrees[degrees.length - 1] - 12 : degrees[n - 1];
+                    const next = n === degrees.length - 1 ? degrees[0] + 12 : degrees[n + 1];
+                    lower = select(degree.read().eq(n), f64((previous + degrees[n]) / 2 - margin), lower);
+                    upper = select(degree.read().eq(n), f64((degrees[n] + next) / 2 + margin), upper);
+                }
+                const base = f64(octave.read()).mul(12);
+                update.write(reset.or(initialized.read().not()).or(x.lt(base.add(lower))).or(x.gt(base.add(upper))));
+            }
+            degree.write(select(update.read(), nearestDegree.read(), degree.read()));
+            octave.write(select(update.read(), nearestOctave.read(), octave.read()));
+            initialized.write(bool(true));
+            let selected = f64(degrees[0]);
+            for (let n = 1; n < degrees.length; n++)
+                selected = select(degree.read().eq(n), f64(degrees[n]), selected);
+            return { pitch: f32(f64(octave.read()).mul(12).add(selected)), degree: degree.read(), octave: octave.read() };
+        } };
+});

package/dist/prepared-convolution.d.ts

@@ -0,0 +1,22 @@
+import { type EveryNSamples, type MessageGraphPayload, type Node } from '@unworklet/core';
+import { type PreparedConvolutionConfig, type PreparedConvolutionPacket } from './convolution-spectrum.js';
+export { prepareConvolutionSpectrum, type PreparedConvolutionConfig, type PreparedConvolutionPacket } 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 declare const preparedConvolution: import("@unworklet/core").SubgraphDecl<[config: PreparedConvolutionConfig], {
+    /** Module-specific native event payload; this is not a host loader/ack. */
+    load(packet: MessageGraphPayload<PreparedConvolutionPacket>): void;
+    /** 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: Node<"f32">, reset: Node<"bool">, everyNSamples: EveryNSamples): {
+        output: Node<"f32">;
+        loaded: Node<"bool">;
+        rejected: Node<"bool">;
+        revision: Node<"i32">;
+    };
+}>;

package/dist/prepared-convolution.js

@@ -0,0 +1,99 @@
+import { defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+import { 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 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));
+            everyNSamples(B, () => {
+                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, frame.real(k));
+                    previous.write(index.add(1), frame.imag(k));
+                });
+                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);
+                    overlap.write(index, select(pendingReset.read(), f64(0), overlap.read(index)).add(result.real(n)));
+                });
+                spectrumCursor.write(spectrumCursor.read().add(1).mod(P));
+                validBlocks.write(validBlocks.read().add(1).min(P - 1));
+                pendingReset.write(false);
+            });
+            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 };
+        } };
+});