@denaudio/den 0.0.0-stage → 0.2.0

package/dist/stereo-delay.d.ts

@@ -0,0 +1,45 @@
+import { type Node } from '@unworklet/core';
+export interface StereoDelayConfig {
+    sampleRate: number;
+    /** Fixed per-head capacity in seconds. Default 2; at most 8. */
+    maxDelaySeconds?: number;
+}
+export interface DelayMixControls {
+    /** Signed feedback, clamped to [-0.95, 0.95]. */
+    feedback: Node<'f32'>;
+    /** Linear dry/wet, clamped to [0, 1]. */
+    mix: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+export interface PingPongControls extends DelayMixControls {
+    /** Both channel delays. Invalid time requests emit dry and reject new input. */
+    timeSeconds: Node<'f32'>;
+}
+/** Stereo cross-feedback delay. Both heads are read before either current write. */
+export declare const pingPongDelay: import("@unworklet/core").SubgraphDecl<[config: StereoDelayConfig], {
+    tick(inputLeft: Node<"f32">, inputRight: Node<"f32">, c: PingPongControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        timingRejected: Node<"bool">;
+    };
+}>;
+export interface DelayTap {
+    /** Fixed delay, within the declared capacity. */
+    delaySeconds: number;
+    gainLeft: number;
+    gainRight: number;
+}
+export interface MultiTapDelayConfig extends StereoDelayConfig {
+    /** One to eight independent fixed-capacity heads. */
+    taps: readonly DelayTap[];
+}
+/** Mono-in, stereo-out tapped delay. Gains share a construction-time divisor
+ * max(1, sum(abs(left)), sum(abs(right))), preserving signs and stereo ratios.
+ */
+export declare const multiTapDelay: import("@unworklet/core").SubgraphDecl<[config: MultiTapDelayConfig], {
+    tick(input: Node<"f32">, c: DelayMixControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+    };
+}>;

package/dist/stereo-delay.js

@@ -0,0 +1,70 @@
+import { defineSubgraph, f32, f64, instantiate, select, state } from '@unworklet/core';
+import { delayReadhead } from './delay-readhead.js';
+function validate(config) {
+    const { sampleRate, maxDelaySeconds = 2 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 ||
+        !Number.isFinite(maxDelaySeconds) || maxDelaySeconds < 1 / sampleRate || maxDelaySeconds > 8) {
+        throw new RangeError('stereo delay requires integer sample rate [8000,192000] and capacity [one sample,8 seconds]');
+    }
+    return { sampleRate, maxDelaySeconds };
+}
+/** Stereo cross-feedback delay. Both heads are read before either current write. */
+export const pingPongDelay = defineSubgraph((config) => {
+    const validated = validate(config), minimum = Math.fround(1 / config.sampleRate);
+    const left = instantiate(delayReadhead, validated, { name: 'left' });
+    const right = instantiate(delayReadhead, validated, { name: 'right' });
+    const acceptedTime = state.f32(minimum).named('acceptedTime');
+    const wetLeft = state.f32(0).expose({ name: 'wetLeft', snapshot: 'transient' });
+    const wetRight = state.f32(0).expose({ name: 'wetRight', snapshot: 'transient' });
+    return {
+        tick(inputLeft, inputRight, c) {
+            const valid = c.timeSeconds.gte(minimum).and(c.timeSeconds.lte(Math.fround(validated.maxDelaySeconds)));
+            acceptedTime.write(select(valid, c.timeSeconds, select(c.reset, f32(minimum), acceptedTime.read())));
+            const l = left.read(acceptedTime.read(), c.reset), r = right.read(acceptedTime.read(), c.reset);
+            wetLeft.write(l.output);
+            wetRight.write(r.output);
+            const dryOnly = c.bypass.or(valid.not()), gain = c.feedback.clamp(-0.95, 0.95);
+            l.write(select(dryOnly, f32(0), inputLeft).add(wetRight.read().mul(gain)));
+            r.write(select(dryOnly, f32(0), inputRight).add(wetLeft.read().mul(gain)));
+            const mix = c.mix.clamp(0, 1);
+            return {
+                left: select(dryOnly, inputLeft, inputLeft.mul(f32(1).sub(mix)).add(wetLeft.read().mul(mix))),
+                right: select(dryOnly, inputRight, inputRight.mul(f32(1).sub(mix)).add(wetRight.read().mul(mix))),
+                timingRejected: valid.not(),
+            };
+        },
+    };
+});
+/** Mono-in, stereo-out tapped delay. Gains share a construction-time divisor
+ * max(1, sum(abs(left)), sum(abs(right))), preserving signs and stereo ratios.
+ */
+export const multiTapDelay = defineSubgraph((config) => {
+    const validated = validate(config);
+    if (!Array.isArray(config.taps) || config.taps.length < 1 || config.taps.length > 8 || config.taps.some(t => !Number.isFinite(t.delaySeconds) || t.delaySeconds < 1 / config.sampleRate || t.delaySeconds > validated.maxDelaySeconds ||
+        !Number.isFinite(t.gainLeft) || !Number.isFinite(t.gainRight) || Math.abs(t.gainLeft) > 1e6 || Math.abs(t.gainRight) > 1e6)) {
+        throw new RangeError('multiTapDelay needs 1–8 finite taps within capacity and gains within [-1e6,1e6]');
+    }
+    const divisor = Math.max(1, config.taps.reduce((s, t) => s + Math.abs(t.gainLeft), 0), config.taps.reduce((s, t) => s + Math.abs(t.gainRight), 0));
+    const taps = config.taps.map((t, i) => ({ ...t, gainLeft: t.gainLeft / divisor, gainRight: t.gainRight / divisor,
+        delay: instantiate(delayReadhead, validated, { name: `tap${i}` }) }));
+    const wetLeft = state.f64(0).expose({ name: 'wetLeft', snapshot: 'transient' });
+    const wetRight = state.f64(0).expose({ name: 'wetRight', snapshot: 'transient' });
+    const feed = state.f32(0).expose({ name: 'feed', snapshot: 'transient' });
+    return {
+        tick(input, c) {
+            const heads = taps.map(t => t.delay.read(f32(t.delaySeconds), c.reset));
+            // All output reads precede all writes. Each delay instance is consumed once.
+            wetLeft.write(heads.reduce((sum, h, i) => sum.add(f64(h.output).mul(taps[i].gainLeft)), f64(0)));
+            wetRight.write(heads.reduce((sum, h, i) => sum.add(f64(h.output).mul(taps[i].gainRight)), f64(0)));
+            const left = wetLeft.read(), right = wetRight.read();
+            feed.write(f32(f64(select(c.bypass, f32(0), input)).add(left.add(right).mul(0.5).mul(f64(c.feedback).clamp(-0.95, 0.95)))));
+            for (const h of heads)
+                h.write(feed.read());
+            const mix = f64(c.mix).clamp(0, 1), dry = f64(input).mul(f64(1).sub(mix));
+            return {
+                left: select(c.bypass, input, f32(dry.add(left.mul(mix)))),
+                right: select(c.bypass, input, f32(dry.add(right.mul(mix)))),
+            };
+        },
+    };
+});

package/dist/virtual-analog.d.ts

@@ -0,0 +1,26 @@
+import { type Node } from '@unworklet/core';
+export interface VirtualAnalogConfig {
+    sampleRate: number;
+    waveform: 'pulse' | 'triangle';
+    /** Initial/reset phase in cycles, [0,1). */
+    phaseCycles?: number;
+}
+export interface VirtualAnalogControls {
+    /** Hz, clipped to [0,.45*sampleRate]; NaN becomes zero. */
+    frequencyHz: Node<'f32'>;
+    /** Pulse high fraction [0,1], NaN becomes .5; ignored by triangle. */
+    duty: Node<'f32'>;
+    /** Level-sensitive: emit initial phase, then advance, on every true sample. */
+    reset: Node<'bool'>;
+}
+/** Alias-reduced pulse and triangle. Polynomial smoothing is not a brickwall filter. */
+export declare const virtualAnalogSource: import("@unworklet/core").SubgraphDecl<[config: VirtualAnalogConfig], {
+    tick(c: VirtualAnalogControls): Node<"f32">;
+}>;
+export interface SeededNoiseConfig {
+    seed?: number;
+}
+/** Park–Miller 48271 white-noise candidate; deterministic, not cryptographic. */
+export declare const seededNoise: import("@unworklet/core").SubgraphDecl<[config?: SeededNoiseConfig | undefined], {
+    tick(reset: Node<"bool">): Node<"f32">;
+}>;

package/dist/virtual-analog.js

@@ -0,0 +1,66 @@
+import { defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+function bounded(value, low, high, fallback) {
+    return select(value.eq(value), f64(value), f64(fallback)).clamp(low, high);
+}
+/** Alias-reduced pulse and triangle. Polynomial smoothing is not a brickwall filter. */
+export const virtualAnalogSource = defineSubgraph((config) => {
+    const { sampleRate, waveform, phaseCycles = 0 } = config;
+    if (!Number.isFinite(sampleRate) || sampleRate < 8000 || sampleRate > 192000)
+        throw new RangeError('VA sampleRate must be in [8000,192000] Hz');
+    if (waveform !== 'pulse' && waveform !== 'triangle')
+        throw new RangeError('unknown VA waveform');
+    if (!Number.isFinite(phaseCycles) || phaseCycles < 0 || phaseCycles >= 1)
+        throw new RangeError('phaseCycles must be in [0,1)');
+    // Exact power-of-two scaling avoids the native |state|<1e-30 flush,
+    // including f64 phaseCycles=Number.MIN_VALUE and smallest f32 Hz.
+    // Phase is wrapped below1 before scaling, with >16x finite headroom.
+    const scale = 2 ** 1020;
+    const phase = state.f64(phaseCycles * scale).named('scaledPhase');
+    return { tick(c) {
+            const step = bounded(c.frequencyHz, 0, .45 * sampleRate, 0).div(sampleRate);
+            const p = select(c.reset, f64(phaseCycles), phase.read().div(scale));
+            // Both select branches evaluate: the zero-Hz denominator must remain safe.
+            const width = select(step.gt(0), step, f64(1));
+            let output;
+            if (waveform === 'pulse') {
+                const duty = bounded(c.duty, 0, 1, .5);
+                // Rising-step residual for the unit-area triangular kernel [-1,1].
+                const blep = (q) => {
+                    const after = f64(1).sub(q.div(width)).max(0);
+                    const before = f64(1).sub(f64(1).sub(q).div(width)).max(0);
+                    return before.mul(before).sub(after.mul(after));
+                };
+                const relative = p.sub(duty), falling = relative.sub(relative.floor());
+                const raw = select(p.lt(duty), f64(1), f64(-1));
+                output = raw.add(select(step.gt(0), blep(p).sub(blep(falling)), f64(0)));
+            }
+            else {
+                const rampResidual = (distance) => {
+                    const t = f64(1).sub(distance.div(width)).max(0);
+                    return t.mul(t).mul(t).div(6);
+                };
+                const raw = f64(1).sub(p.sub(.5).abs().mul(4));
+                // Slope jumps +8 at phase0 and -8 at phase.5. Support <.5 cycle,
+                // so only phase0 needs the periodic image at phase1.
+                const correction = rampResidual(p).add(rampResidual(f64(1).sub(p)))
+                    .sub(rampResidual(p.sub(.5).abs())).mul(step).mul(8);
+                output = raw.add(select(step.gt(0), correction, f64(0)));
+            }
+            phase.write(p.add(step).frac().mul(scale));
+            return f32(output);
+        } };
+});
+/** Park–Miller 48271 white-noise candidate; deterministic, not cryptographic. */
+export const seededNoise = defineSubgraph((config = {}) => {
+    const { seed = 1 } = config;
+    if (!Number.isInteger(seed) || seed < 1 || seed > 2147483646)
+        throw new RangeError('noise seed must be an integer in [1,2147483646]');
+    const random = state.i32(seed).named('random');
+    return { tick(reset) {
+            const current = select(reset, i32(seed), random.read());
+            // Exact integer product in f64; i32 multiplication would overflow.
+            const next = i32(f64(current).mul(48271).mod(2147483647));
+            random.write(next);
+            return f32(f64(next).mul(2 / 2147483647).sub(1));
+        } };
+});

package/dist/voice-policy.d.ts

@@ -0,0 +1,37 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+/** Fixed construction capacities, not product-wide polyphony limits. */
+export interface VoicePolicyConfig {
+    mode: 'mono' | 'poly';
+    /** Poly default 16; mono must use one slot. Maximum 32 limits graph expansion. */
+    capacity?: number;
+    /** Held note-on identities (including stolen notes). Default 128, maximum 256. */
+    heldCapacity?: number;
+    /** Mono only: preserve gate without a retrigger when another held note takes priority. */
+    legato?: boolean;
+}
+/** Voice allocation only. MIDI transport, graph storage, and node control remain unworklet's. */
+export declare const voicePolicy: import("@unworklet/core").SubgraphDecl<[config: VoicePolicyConfig], {
+    capacity: number;
+    heldCapacity: number;
+    noteOn: (key: Node<"i32">, ch: Node<"i32">, vel: Node<"i32">) => void;
+    noteOff: (key: Node<"i32">, ch: Node<"i32">, when?: Node<"bool">) => void;
+    reset: (when?: Node<"bool">) => void;
+    allNotesOff: (ch: Node<"i32">) => void;
+    allSoundOff: (ch: Node<"i32">) => void;
+    overflowed: () => Node<"bool">;
+    /** Call once in declaration scope with an existing unworklet MIDI input. */
+    bindMidi(input: MidiInputHandle): void;
+    voices: {
+        read(): {
+            active: Node<"bool">;
+            gate: Node<"bool">;
+            note: Node<"i32">;
+            channel: Node<"i32">;
+            velocity: Node<"f32">;
+        };
+        /** One latched start/retrigger; read once per sample before invoking the envelope. */
+        takeRetrigger(): Node<"bool">;
+        /** Envelope completion may free only a released voice, never a newly held one. */
+        releaseFinished(done: Node<"bool">): void;
+    }[];
+}>;

package/dist/voice-policy.js

@@ -0,0 +1,245 @@
+import { bool, defineSubgraph, f32, i32, select, state } from '@unworklet/core';
+function capacity(value, maximum, name) {
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new RangeError(`${name} must be an integer in [1, ${maximum}]`);
+    }
+    return value;
+}
+/** Voice allocation only. MIDI transport, graph storage, and node control remain unworklet's. */
+export const voicePolicy = defineSubgraph((config) => {
+    if (config.mode !== 'mono' && config.mode !== 'poly')
+        throw new TypeError('mode must be mono or poly');
+    const size = capacity(config.capacity ?? (config.mode === 'mono' ? 1 : 16), 32, 'capacity');
+    const heldSize = capacity(config.heldCapacity ?? Math.max(128, size), 256, 'heldCapacity');
+    if (config.mode === 'mono' && size !== 1)
+        throw new RangeError('mono capacity must be 1');
+    if (heldSize < size)
+        throw new RangeError('heldCapacity must be at least capacity');
+    if (config.legato !== undefined && typeof config.legato !== 'boolean')
+        throw new TypeError('legato must be boolean');
+    const legato = config.legato ?? true;
+    const ints = (name, length) => state.buffer.i32({ size: length }).expose({ name, snapshot: 'transient' });
+    const note = ints('note', size);
+    const channel = ints('channel', size);
+    const velocity = state.buffer.f32({ size }).expose({ name: 'velocity', snapshot: 'transient' });
+    const age = ints('age', size); // zero means free, otherwise dense allocation order 1..size
+    const releaseAge = ints('releaseAge', size); // zero means held, otherwise release order
+    const owner = ints('owner', size); // held token 1..heldSize; zero means no key owns the release tail
+    const retrigger = ints('retrigger', size);
+    const heldNote = ints('heldNote', heldSize + 1);
+    const heldChannel = ints('heldChannel', heldSize + 1);
+    const heldVelocity = ints('heldVelocity', heldSize + 1);
+    // Intrusive held-key order: token 0 is a sentinel; valid tokens are 1..heldSize.
+    const occupied = ints('occupied', heldSize + 1);
+    const previous = ints('previous', heldSize + 1);
+    const next = ints('next', heldSize + 1);
+    const head = state.i32(0).expose({ name: 'head', snapshot: 'transient' });
+    const tail = state.i32(0).expose({ name: 'tail', snapshot: 'transient' });
+    // Materialize loop accumulators: unworklet 0.4.1 analysis recursively expands
+    // expression DAGs, so nested selects otherwise grow exponentially.
+    const scratch = ints('scratch', 4);
+    const overflow = state.bool(false).expose({ name: 'overflow', snapshot: 'transient' });
+    const validKey = (key, ch) => key.gte(0).and(key.lte(127)).and(ch.gte(0)).and(ch.lte(15));
+    const releaseCount = () => {
+        let count = i32(0);
+        for (let n = 0; n < size; n++)
+            count = count.add(select(releaseAge.read(n).gt(0), i32(1), i32(0)));
+        return count;
+    };
+    function releaseVoice(index, when) {
+        const shouldRelease = when.and(age.read(index).gt(0)).and(owner.read(index).gt(0));
+        const nextOrder = releaseCount().add(1);
+        owner.write(index, select(shouldRelease, i32(0), owner.read(index)));
+        releaseAge.write(index, select(shouldRelease, nextOrder, releaseAge.read(index)));
+    }
+    function freeVoice(index, when) {
+        const oldAge = age.read(index);
+        const oldRelease = releaseAge.read(index);
+        const enabled = when.and(oldAge.gt(0));
+        for (let n = 0; n < size; n++) {
+            const a = age.read(n);
+            const r = releaseAge.read(n);
+            age.write(n, select(enabled.and(a.gt(oldAge)), a.sub(1), a));
+            releaseAge.write(n, select(enabled.and(oldRelease.gt(0)).and(r.gt(oldRelease)), r.sub(1), r));
+        }
+        age.write(index, select(enabled, i32(0), age.read(index)));
+        releaseAge.write(index, select(enabled, i32(0), releaseAge.read(index)));
+        owner.write(index, select(enabled, i32(0), owner.read(index)));
+        note.write(index, select(enabled, i32(0), note.read(index)));
+        channel.write(index, select(enabled, i32(0), channel.read(index)));
+        velocity.write(index, select(enabled, f32(0), velocity.read(index)));
+        retrigger.write(index, select(enabled, i32(0), retrigger.read(index)));
+    }
+    function activate(index, token, when, trigger) {
+        const oldAge = age.read(index);
+        const oldRelease = releaseAge.read(index);
+        let count = i32(0);
+        for (let n = 0; n < size; n++)
+            count = count.add(select(age.read(n).gt(0), i32(1), i32(0)));
+        for (let n = 0; n < size; n++) {
+            const a = age.read(n);
+            const r = releaseAge.read(n);
+            age.write(n, select(when.and(oldAge.gt(0)).and(a.gt(oldAge)), a.sub(1), a));
+            releaseAge.write(n, select(when.and(oldRelease.gt(0)).and(r.gt(oldRelease)), r.sub(1), r));
+        }
+        age.write(index, select(when, select(oldAge.gt(0), count, count.add(1)), age.read(index)));
+        releaseAge.write(index, select(when, i32(0), releaseAge.read(index)));
+        owner.write(index, select(when, token, owner.read(index)));
+        note.write(index, select(when, heldNote.read(token), note.read(index)));
+        channel.write(index, select(when, heldChannel.read(token), channel.read(index)));
+        velocity.write(index, select(when, f32(heldVelocity.read(token)).div(127), velocity.read(index)));
+        retrigger.write(index, select(when.and(trigger), i32(1), retrigger.read(index)));
+    }
+    function monoPriority(when) {
+        const selected = tail.read();
+        const newest = selected;
+        const changed = owner.read(0).eq(selected).not();
+        const trigger = bool(!legato).or(owner.read(0).eq(0));
+        activate(i32(0), selected, when.and(newest.gt(0)).and(changed), trigger);
+        releaseVoice(0, when.and(newest.eq(0)));
+    }
+    function removeHeld(token, when) {
+        const before = previous.read(token);
+        const after = next.read(token);
+        next.write(before, select(when.and(before.gt(0)), after, next.read(before)));
+        previous.write(after, select(when.and(after.gt(0)), before, previous.read(after)));
+        head.write(select(when.and(head.read().eq(token)), after, head.read()));
+        tail.write(select(when.and(tail.read().eq(token)), before, tail.read()));
+        occupied.write(token, select(when, i32(0), occupied.read(token)));
+        previous.write(token, select(when, i32(0), previous.read(token)));
+        next.write(token, select(when, i32(0), next.read(token)));
+        heldNote.write(token, select(when, i32(0), heldNote.read(token)));
+        heldChannel.write(token, select(when, i32(0), heldChannel.read(token)));
+        heldVelocity.write(token, select(when, i32(0), heldVelocity.read(token)));
+    }
+    function noteOff(key, ch, when = bool(true)) {
+        scratch.write(0, 0);
+        scratch.write(1, head.read());
+        for (let n = 0; n < heldSize; n++) {
+            const token = scratch.read(0);
+            const cursor = scratch.read(1);
+            const match = token.eq(0).and(cursor.gt(0)).and(heldNote.read(cursor).eq(key)).and(heldChannel.read(cursor).eq(ch));
+            scratch.write(0, select(match, cursor, token));
+            scratch.write(1, next.read(cursor));
+        }
+        const token = scratch.read(0);
+        const found = when.and(validKey(key, ch)).and(token.gt(0));
+        removeHeld(token, found);
+        if (config.mode === 'mono')
+            monoPriority(found);
+        else
+            for (let n = 0; n < size; n++)
+                releaseVoice(n, found.and(owner.read(n).eq(token)));
+    }
+    function noteOn(key, ch, vel) {
+        noteOff(key, ch, vel.eq(0));
+        const enabled = validKey(key, ch).and(vel.gt(0)).and(vel.lte(127));
+        let token = i32(0);
+        let found = bool(false);
+        for (let n = heldSize; n >= 1; n--) {
+            const free = occupied.read(n).eq(0);
+            token = select(free, i32(n), token);
+            found = found.or(free);
+        }
+        const accept = enabled.and(found);
+        overflow.write(overflow.read().or(enabled.and(found.not())));
+        const last = tail.read();
+        next.write(last, select(accept.and(last.gt(0)), token, next.read(last)));
+        previous.write(token, select(accept, last, previous.read(token)));
+        next.write(token, select(accept, i32(0), next.read(token)));
+        head.write(select(accept.and(last.eq(0)), token, head.read()));
+        tail.write(select(accept, token, tail.read()));
+        occupied.write(token, select(accept, i32(1), occupied.read(token)));
+        heldNote.write(token, select(accept, key, heldNote.read(token)));
+        heldChannel.write(token, select(accept, ch, heldChannel.read(token)));
+        heldVelocity.write(token, select(accept, vel, heldVelocity.read(token)));
+        if (config.mode === 'mono')
+            monoPriority(accept);
+        else {
+            scratch.write(2, 2 * size + 1);
+            scratch.write(3, 0);
+            for (let n = 0; n < size; n++) {
+                const a = age.read(n);
+                const r = releaseAge.read(n);
+                const score = select(a.eq(0), i32(0), select(r.gt(0), r, a.add(size)));
+                const best = scratch.read(2);
+                const chosen = scratch.read(3);
+                const better = score.lt(best); // ascending slots break ties deterministically
+                scratch.write(3, select(better, i32(n), chosen));
+                scratch.write(2, select(better, score, best));
+            }
+            activate(scratch.read(3), token, accept, bool(true));
+        }
+    }
+    function channelOff(ch, immediate, when = bool(true)) {
+        const enabled = when.and(ch.gte(0)).and(ch.lte(15));
+        // Remove matching identities through bounded, constant-time list unlinking.
+        for (let n = 1; n <= heldSize; n++) {
+            removeHeld(i32(n), enabled.and(occupied.read(n).gt(0)).and(heldChannel.read(n).eq(ch)));
+        }
+        if (immediate)
+            for (let n = 0; n < size; n++)
+                freeVoice(n, enabled.and(channel.read(n).eq(ch)));
+        if (config.mode === 'mono')
+            monoPriority(enabled);
+        else if (!immediate)
+            for (let n = 0; n < size; n++)
+                releaseVoice(n, enabled.and(channel.read(n).eq(ch)));
+    }
+    function reset(when = bool(true)) {
+        for (let n = 0; n < size; n++)
+            freeVoice(n, when);
+        for (let n = 0; n <= heldSize; n++) {
+            occupied.write(n, select(when, i32(0), occupied.read(n)));
+            previous.write(n, select(when, i32(0), previous.read(n)));
+            next.write(n, select(when, i32(0), next.read(n)));
+            heldNote.write(n, select(when, i32(0), heldNote.read(n)));
+            heldChannel.write(n, select(when, i32(0), heldChannel.read(n)));
+            heldVelocity.write(n, select(when, i32(0), heldVelocity.read(n)));
+        }
+        head.write(select(when, i32(0), head.read()));
+        tail.write(select(when, i32(0), tail.read()));
+        overflow.write(select(when, false, overflow.read()));
+    }
+    return {
+        capacity: size,
+        heldCapacity: heldSize,
+        noteOn,
+        noteOff,
+        reset,
+        allNotesOff: (ch) => channelOff(ch, false),
+        allSoundOff: (ch) => channelOff(ch, true),
+        overflowed: () => overflow.read(),
+        /** Call once in declaration scope with an existing unworklet MIDI input. */
+        bindMidi(input) {
+            input.onEvent('noteOn', e => noteOn(e.note, e.channel, e.velocity));
+            input.onEvent('noteOff', e => noteOff(e.note, e.channel));
+            input.onEvent('cc', e => {
+                channelOff(e.channel, false, e.controller.eq(123));
+                channelOff(e.channel, true, e.controller.eq(120));
+            });
+        },
+        voices: Array.from({ length: size }, (_, index) => ({
+            read() {
+                const active = age.read(index).gt(0);
+                return {
+                    active,
+                    gate: owner.read(index).gt(0),
+                    note: select(active, note.read(index), i32(-1)),
+                    channel: select(active, channel.read(index), i32(-1)),
+                    velocity: velocity.read(index),
+                };
+            },
+            /** One latched start/retrigger; read once per sample before invoking the envelope. */
+            takeRetrigger() {
+                const value = retrigger.read(index).gt(0);
+                retrigger.write(index, 0);
+                return value;
+            },
+            /** Envelope completion may free only a released voice, never a newly held one. */
+            releaseFinished(done) {
+                freeVoice(index, done.and(owner.read(index).eq(0)));
+            },
+        })),
+    };
+});

package/dist/wavetable-bands.d.ts

@@ -0,0 +1,37 @@
+import type { WavetableConfig, WavetableControls } from './wavetable.js';
+export interface PreparedWavetableBands {
+    /** Band-major, then frame-major complete cycles, without duplicated endpoints. */
+    data: Float32Array;
+    frameLength: number;
+    frameCount: number;
+    /** Descending retained positive harmonics; DC is preserved in every band. */
+    harmonicLimits: readonly number[];
+}
+export interface WavetableBandsOptions {
+    /** Original finite mono cycles. Equal power-of-two lengths 16..4096; 1..16 frames.
+     * All derived bands together must fit 65536 samples. Input is never changed. */
+    frames: readonly Float32Array[];
+}
+/** Layout is the fixed schedule produced by prepareWavetableBands. */
+export interface BandedWavetableConfig extends WavetableConfig {
+    /** Power of two, 16..4096 samples per cycle. */
+    frameLength: number;
+    /** 1..16 morph frames; frameLength * frameCount * derived band count must
+     * fit both the shared resident capacity and the 65536-sample native limit. */
+    frameCount: number;
+}
+/** Prepare harmonic-truncated pitch bands outside the audio callback. No per-band
+ * normalization, resampling, loader, or provenance/license assumption is added.
+ * Reject nonfinite input or reconstruction that overflows float32. DC, phase and
+ * retained harmonic gain are preserved within FFT/float32 roundoff. */
+export declare function prepareWavetableBands({ frames }: WavetableBandsOptions): PreparedWavetableBands;
+/** Four periodic cycle interpolations: frame morph in neighboring pitch bands.
+ * Fetches eight integer resident reads so tiny local fractions survive offsets.
+ * Static harmonic truncation is not a brickwall reconstruction filter and does
+ * not remove interpolation images or bandwidth from modulation/reset/asset edits. */
+export declare const bandedWavetableSource: import("@unworklet/core").SubgraphDecl<[config: BandedWavetableConfig], {
+    tick(c: WavetableControls): {
+        output: import("@unworklet/core").Node<"f32">;
+        missing: import("@unworklet/core").Node<"bool">;
+    };
+}>;