@denaudio/den 0.0.0-stage → 0.2.0

package/dist/loop-crossfade.js

@@ -0,0 +1,72 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+const PHASE_SCALE = 2 ** 128;
+function integer(value, low, high, name) {
+    if (!Number.isInteger(value) || value < low || value > high)
+        throw new RangeError(`${name} must be an integer in [${low},${high}]`);
+}
+// Preserve the local fraction before adding an integer slice/head offset. An
+// absolute position addition would erase tiny phase * full-finite-PCM products.
+// Resident reads retain the existing ingress, bounds and per-tap sanitization.
+function localRead(sample, local, start, end, loop) {
+    const whole = i32(local.floor()), fraction = local.sub(f64(whole));
+    const first = start.add(whole).min(end.sub(1).max(start));
+    const next = select(first.add(1).gte(end), select(loop, start, first), first.add(1));
+    const a = sample.read(f64(first), start, end, false), b = sample.read(f64(next), start, end, false);
+    return f32(f64(a).mul(f64(1).sub(fraction)).add(f64(b).mul(fraction)));
+}
+/** 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 const crossfadedLoopPlayer = defineSubgraph((config) => {
+    if (!Number.isFinite(config.sampleRate) || config.sampleRate < 8000 || config.sampleRate > 192000)
+        throw new RangeError('sampleRate must be in [8000,192000] Hz');
+    const { sample, startFrame = 0, endFrame = sample.capacity, crossfadeFrames, releaseFrames = 0 } = config;
+    integer(startFrame, 0, sample.capacity - 1, 'startFrame');
+    integer(endFrame, startFrame + 1, sample.capacity, 'endFrame');
+    integer(crossfadeFrames, 0, Math.floor((endFrame - startFrame) / 2), 'crossfadeFrames');
+    integer(releaseFrames, 0, Math.ceil(config.sampleRate * 10), 'releaseFrames');
+    const phase = state.f64(0).named('scaledPhase'), active = state.bool(false).named('active');
+    const previousGate = state.bool(false).named('previousGate'), revision = state.i32(-1).named('revision');
+    const remaining = state.i32(0).named('releaseRemaining');
+    // Transient materialization keeps repeated resident read graphs bounded. Only
+    // persistent phase/gate/release/revision state is required across snapshots.
+    const current = state.f64(0).expose({ name: 'scaledCurrentPhase', snapshot: 'transient' });
+    const speedState = state.f64(0).expose({ name: 'scaledSpeed', snapshot: 'transient' });
+    const endState = state.i32(0).expose({ name: 'end', snapshot: 'transient' });
+    const overlapState = state.i32(0).expose({ name: 'overlap', snapshot: 'transient' });
+    const periodState = state.i32(0).expose({ name: 'period', snapshot: 'transient' });
+    return { tick(c) {
+            endState.write(sample.length().min(endFrame));
+            const end = endState.read(), start = i32(startFrame), length = end.sub(start).max(0), available = length.gt(0);
+            overlapState.write(length.div(2).min(crossfadeFrames));
+            periodState.write(length.sub(overlapState.read()));
+            const overlap = overlapState.read(), period = periodState.read();
+            speedState.write(select(c.rate.eq(c.rate), f64(c.rate), f64(0)).clamp(-16, 16).mul(sample.sourceSampleRate / config.sampleRate).mul(PHASE_SCALE));
+            const speed = speedState.read().div(PHASE_SCALE), changed = sample.revision().eq(revision.read()).not();
+            // A load is NOT a gate rise: evaluate against the actual prior gate first.
+            const trigger = c.trigger.or(c.gate.and(previousGate.read().not())).and(c.gate).and(c.reset.not()).and(available);
+            const alive = select(trigger, bool(true), active.read().and(changed.not())).and(c.reset.not()).and(available);
+            const initial = select(speed.lt(0), f64(period.sub(1).max(0)), f64(0));
+            current.write(select(trigger, initial, select(c.reset.or(changed).or(available.not()), f64(0), phase.read().div(PHASE_SCALE))).mul(PHASE_SCALE));
+            const q = current.read().div(PHASE_SCALE);
+            const releaseLeft = select(trigger, i32(releaseFrames), select(c.gate, remaining.read(), remaining.read().sub(1).max(0)));
+            const gain = releaseFrames > 0 ? f64(releaseLeft).div(releaseFrames) : select(c.gate, f64(1), f64(0));
+            active.write(alive.and(gain.gt(0)));
+            const playing = active.read(), primaryStart = start.add(overlap);
+            const tail = localRead(sample, q, primaryStart, end, overlap.eq(0));
+            const headPhase = q.sub(f64(period.sub(overlap))).max(0);
+            const head = localRead(sample, headPhase, start, end, bool(false));
+            const weight = select(overlap.gt(0), headPhase.div(f64(overlap.max(1))), f64(0));
+            const mixed = f32(f64(tail).mul(f64(1).sub(weight)).add(f64(head).mul(weight)));
+            const output = select(playing, f32(f64(mixed).mul(gain)), f32(0));
+            const advanced = q.add(speed), divisor = f64(period.max(1));
+            const wrapped = advanced.sub(advanced.div(divisor).floor().mul(divisor));
+            // Negative tiny increments can round a remainder to the upper endpoint.
+            const next = select(wrapped.gte(divisor), f64(0), wrapped.max(0));
+            phase.write(select(playing, next, q).mul(PHASE_SCALE));
+            remaining.write(select(playing, releaseLeft, i32(0)));
+            previousGate.write(c.gate.and(c.reset.not()));
+            revision.write(sample.revision());
+            return { output, active: playing, position: f32(f64(primaryStart).add(q)), phase: f32(q), periodFrames: period, crossfadeFrames: overlap, missing: available.not() };
+        } };
+});

package/dist/modulation-fx.d.ts

@@ -0,0 +1,47 @@
+import { type Node } from '@unworklet/core';
+export interface FlangerConfig {
+    sampleRate: number;
+    /** Fixed capacity in seconds, [one sample, 0.02]. Default 0.02. */
+    maxDelaySeconds?: number;
+    /** Right LFO phase relative to left, in cycles. Default 0.5. */
+    stereoPhaseCycles?: number;
+}
+export interface FlangerControls {
+    delaySeconds: Node<'f32'>;
+    depthSeconds: Node<'f32'>;
+    rateHz: Node<'f32'>;
+    /** Positive feedback, clamped to [0, 0.95]. */
+    feedback: Node<'f32'>;
+    mix: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** Stereo moving-head comb/flanger. Call once per sample; finite inputs required. */
+export declare const flanger: import("@unworklet/core").SubgraphDecl<[config: FlangerConfig], {
+    tick(left: Node<"f32">, right: Node<"f32">, c: FlangerControls): {
+        left: Node<"f32">;
+        right: Node<"f32">;
+        timingRejected: Node<"bool">;
+        modulationClipped: Node<"bool">;
+    };
+}>;
+export interface PhaserConfig {
+    sampleRate: number;
+    /** Fixed number of normalized first-order allpasses. Default 4. */
+    stages?: 2 | 4 | 6 | 8;
+}
+export interface PhaserControls {
+    /** Per-stage -90 degree frequency. Clamped to [20, 0.45 * sampleRate]. */
+    frequencyHz: Node<'f32'>;
+    /** One-sample-delayed wet feedback, clamped to [-0.95, 0.95]. */
+    feedback: Node<'f32'>;
+    mix: Node<'f32'>;
+    bypass: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+/** Mono allpass phaser, not a delay preset. Compose two instances for stereo.
+ * Normalized lattice scattering preserves per-sample energy under cutoff motion.
+ */
+export declare const phaser: import("@unworklet/core").SubgraphDecl<[config: PhaserConfig], {
+    tick(input: Node<"f32">, c: PhaserControls): Node<"f32">;
+}>;

package/dist/modulation-fx.js

@@ -0,0 +1,58 @@
+import { defineSubgraph, f32, f64, instantiate, select, sqrt, state } from '@unworklet/core';
+import { delayFx } from './delay-fx.js';
+/** Stereo moving-head comb/flanger. Call once per sample; finite inputs required. */
+export const flanger = defineSubgraph((config) => {
+    const maxDelaySeconds = config.maxDelaySeconds ?? 0.02;
+    if (!Number.isFinite(maxDelaySeconds) || maxDelaySeconds < 1 / config.sampleRate || maxDelaySeconds > 0.02) {
+        throw new RangeError('flanger capacity must be between one sample and 0.02 seconds');
+    }
+    const engine = instantiate(delayFx, { ...config, maxDelaySeconds, tone: 'flat' }, { name: 'delay' });
+    return {
+        tick(left, right, c) {
+            return engine.tick(left, right, {
+                timeLeftSeconds: c.delaySeconds, timeRightSeconds: c.delaySeconds,
+                sync: f32(0).gt(1), bpm: f32(120), beatsLeft: f32(1), beatsRight: f32(1),
+                feedback: c.feedback, cutoffHz: f32(1000), mix: c.mix,
+                rateHz: c.rateHz, depthSeconds: c.depthSeconds,
+                bypass: c.bypass, reset: c.reset,
+            });
+        },
+    };
+});
+/** Mono allpass phaser, not a delay preset. Compose two instances for stereo.
+ * Normalized lattice scattering preserves per-sample energy under cutoff motion.
+ */
+export const phaser = defineSubgraph((config) => {
+    const { sampleRate, stages = 4 } = config;
+    if (!Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000 || ![2, 4, 6, 8].includes(stages)) {
+        throw new RangeError('phaser requires an integer sample rate in [8000,192000] and 2/4/6/8 stages');
+    }
+    const history = Array.from({ length: stages }, (_, i) => state.f64(0).named(`stage${i}`));
+    const signal = state.f64(0).expose({ name: 'signal', snapshot: 'transient' });
+    const coefficient = state.f64(0).expose({ name: 'coefficient', snapshot: 'transient' });
+    const coupling = state.f64(0).expose({ name: 'coupling', snapshot: 'transient' });
+    const feedback = state.f64(0).named('feedback');
+    return {
+        tick(input, c) {
+            const angle = f64(c.frequencyHz).clamp(20, 0.45 * sampleRate).mul(Math.PI / sampleRate);
+            const z = angle.mul(angle);
+            // Degree 13/14 sine/cosine on [0, .45*pi], as in the existing SVF.
+            const sine = angle.mul(f64(-1 / 6227020800).mul(z).add(1 / 39916800).mul(z).sub(1 / 362880).mul(z).add(1 / 5040).mul(z).sub(1 / 120).mul(z).add(1 / 6).mul(z).neg().add(1));
+            const cosine = f64(-1 / 87178291200).mul(z).add(1 / 479001600).mul(z).sub(1 / 3628800).mul(z).add(1 / 40320).mul(z).sub(1 / 720).mul(z).add(1 / 24).mul(z).sub(1 / 2).mul(z).add(1);
+            coefficient.write(sine.sub(cosine).div(sine.add(cosine)).clamp(-0.999999, 0.999999));
+            const a = coefficient.read();
+            coupling.write(sqrt(f64(1).sub(a.mul(a)).clamp(0, 1)));
+            const b = coupling.read();
+            signal.write(f64(select(c.bypass, f32(0), input)).add(select(c.reset, f64(0), feedback.read()).mul(f64(c.feedback).clamp(-0.95, 0.95))));
+            for (const slot of history) {
+                const x = signal.read(), previous = select(c.reset, f64(0), slot.read());
+                signal.write(a.mul(x).add(b.mul(previous)));
+                slot.write(b.mul(x).sub(a.mul(previous)));
+            }
+            const wet = signal.read();
+            feedback.write(wet);
+            const mix = f64(c.mix).clamp(0, 1);
+            return select(c.bypass, input, f32(f64(input).mul(f64(1).sub(mix)).add(wet.mul(mix))));
+        },
+    };
+});

package/dist/modulation.d.ts

@@ -0,0 +1,132 @@
+import { type MidiOutputHandle, type Node } from '@unworklet/core';
+export type ClockMode = 'free' | 'tempo';
+export interface MusicalClockConfig {
+    sampleRate: number;
+    mode: ClockMode;
+    /** Fixed cycle length, 1..64 steps. */
+    steps: number;
+    /** Tempo mode only: power of two in [1/64,64], default 1. */
+    stepsPerBeat?: number;
+}
+export interface MusicalClockControls {
+    /** Free mode: steps/second. Tempo mode: BPM. Clamped to [0,1000]. */
+    rate: Node<'f32'>;
+    /** Hold at step/phase zero with no tick. First reset-low sample ticks. */
+    reset: Node<'bool'>;
+    /** Rising edge seeks; held high does not pin or retrigger. Reset consumes it. */
+    seek: Node<'bool'>;
+    /** Steps, clamped to +/-1048576 then wrapped into the fixed cycle. */
+    position: Node<'f32'>;
+}
+export interface MusicalClockOutput {
+    step: Node<'f32'>;
+    /** Fraction of the current step, in [0,1). */
+    phase: Node<'f32'>;
+    /** Initial sample, reset release, seek edge, or a step boundary. */
+    tick: Node<'bool'>;
+}
+export interface SequenceStep {
+    value: number;
+    gate: number;
+}
+export interface StepSequenceConfig extends Omit<MusicalClockConfig, 'steps'> {
+    /** Fixed 1..64 steps; values [-1,1], gate fractions [0,1]. */
+    steps: readonly SequenceStep[];
+}
+export interface StepSequenceOutput extends MusicalClockOutput {
+    value: Node<'f32'>;
+    gate: Node<'bool'>;
+}
+export type MsegCurve = 'linear' | 'easeIn' | 'easeOut' | 'smoothstep';
+export interface MsegSegment {
+    seconds: number;
+    target: number;
+    curve: MsegCurve;
+}
+export interface MsegConfig {
+    sampleRate: number;
+    initial: number;
+    /** Fixed 1..16 segments; durations [0,30] s, targets [-1,1]. */
+    segments: readonly MsegSegment[];
+    /** Whole envelope repeats; the final target need not match initial. */
+    loop?: boolean;
+}
+export interface MsegControls {
+    trigger: Node<'bool'>;
+    reset: Node<'bool'>;
+}
+export interface MsegOutput {
+    value: Node<'f32'>;
+    done: Node<'bool'>;
+    segment: Node<'f32'>;
+}
+export interface SampleAndHoldConfig {
+    initial: number;
+}
+export interface RandomModulatorConfig extends SampleAndHoldConfig {
+    seed: number;
+}
+export interface RandomModulatorControls {
+    /** Level-sensitive sample request: advances once on every high sample. */
+    trigger: Node<'bool'>;
+    reset: Node<'bool'>;
+    /** rho in rho*previous+(1-rho)*uniform; clamped [0,1]. */
+    correlation: Node<'f32'>;
+}
+/** Sample clock, no transport or event scheduler. Call exactly once per sample. */
+export declare const musicalClock: import("@unworklet/core").SubgraphDecl<[config: MusicalClockConfig], {
+    tick(c: MusicalClockControls): MusicalClockOutput;
+}>;
+/** Fixed step values and gate fractions; no MIDI generation or smoothing. */
+export declare const stepSequence: import("@unworklet/core").SubgraphDecl<[config: StepSequenceConfig], {
+    tick(c: MusicalClockControls): StepSequenceOutput;
+}>;
+/**
+ * Fixed piecewise envelope. Rising trigger emits the first duration step;
+ * held trigger does not retrigger. Reset consumes trigger and emits initial.
+ * Zero-length segments collapse at their boundary in list order. Loop jumps
+ * from last target to the first segment's first step on the next sample.
+ */
+export declare const mseg: import("@unworklet/core").SubgraphDecl<[config: MsegConfig], {
+    tick(c: MsegControls): MsegOutput;
+}>;
+/** Level-sensitive sampling; full finite f32 range. Native state maps -0 to +0. */
+export declare const sampleAndHold: import("@unworklet/core").SubgraphDecl<[config: SampleAndHoldConfig], {
+    tick(input: Node<"f32">, trigger: Node<"bool">, reset: Node<"bool">): Node<"f32">;
+}>;
+/**
+ * Park-Miller seeded S&H / bounded correlated random. Each high trigger advances
+ * the PRNG, including correlation=1. Reset wins, restores seed/initial, and
+ * never advances. This is a convex random recurrence, not normalized Gaussian
+ * noise or a specified spectral color. All dynamic inputs must be finite.
+ */
+export declare const randomModulator: import("@unworklet/core").SubgraphDecl<[config: RandomModulatorConfig], {
+    tick(c: RandomModulatorControls): Node<"f32">;
+}>;
+export interface ArpeggiatorNote {
+    note: number;
+    velocity: number;
+    gate: number;
+}
+export interface FixedArpeggiatorConfig extends Omit<MusicalClockConfig, 'steps'> {
+    channel: number;
+    /** Fixed order, 1..64 notes. gate=0 is a rest; no incoming chord capture. */
+    notes: readonly ArpeggiatorNote[];
+}
+export interface FixedArpeggiatorControls extends MusicalClockControls {
+    /** Native unsigned 32-bit absolute timestamp bits, carried by an i32 node. */
+    atSample: Node<'i32'>;
+}
+export interface FixedArpeggiatorOutput extends MusicalClockOutput {
+    note: Node<'f32'>;
+    gate: Node<'bool'>;
+}
+/**
+ * Bounded fixed-note arp using a caller-owned native MIDI output. At most one
+ * off then one on per sample. Output capacity >=256 plus per-quantum draining
+ * is required for the conservative burst bound, not guaranteed host delivery.
+ * Rate zero holds a sounding note; reset before stopping/disconnecting.
+ */
+export declare const fixedArpeggiator: import("@unworklet/core").SubgraphDecl<[config: FixedArpeggiatorConfig], {
+    tick(output: MidiOutputHandle, c: FixedArpeggiatorControls): FixedArpeggiatorOutput;
+}>;

package/dist/modulation.js

@@ -0,0 +1,228 @@
+import { bool, defineSubgraph, f32, f64, i32, instantiate, select, state } from '@unworklet/core';
+function checkRate(rate) {
+    if (!Number.isInteger(rate) || rate < 8000 || rate > 192000)
+        throw new RangeError('modulation sampleRate must be an integer in [8000,192000]');
+}
+function boundedNumber(value, lo, hi, name) {
+    if (!Number.isFinite(value) || value < lo || value > hi)
+        throw new RangeError(`${name} must be finite in [${lo},${hi}]`);
+}
+function checkClock(config) {
+    checkRate(config.sampleRate);
+    if (config.mode !== 'free' && config.mode !== 'tempo')
+        throw new RangeError('clock mode must be free or tempo');
+    if (!Number.isInteger(config.steps) || config.steps < 1 || config.steps > 64)
+        throw new RangeError('clock steps must be an integer in [1,64]');
+    const division = config.stepsPerBeat ?? 1;
+    if (!Number.isFinite(division) || division < 1 / 64 || division > 64 || !Number.isInteger(Math.log2(division))) {
+        throw new RangeError('stepsPerBeat must be a power of two in [1/64,64]');
+    }
+    if (config.mode === 'free' && division !== 1)
+        throw new RangeError('stepsPerBeat applies only to tempo mode');
+}
+// Core 0.4.1 flushes tiny scalar-state writes. Exact power-of-two scaling
+// preserves every finite f32 control, including subnormals, without a new
+// amplitude threshold. Even the largest finite f32 input remains finite here.
+const SCALE = 2 ** 128;
+const PHASE_MAX = 1 - 2 ** -24;
+const clockCore = defineSubgraph((config) => {
+    checkClock(config);
+    const threshold = config.sampleRate * (config.mode === 'tempo' ? 60 : 1);
+    const division = config.mode === 'tempo' ? config.stepsPerBeat ?? 1 : 1;
+    const lastPosition = config.steps - 2 ** (Math.ceil(Math.log2(config.steps)) - 53);
+    const position = state.f64(0).named('positionScaled');
+    const error = state.f64(0).named('errorScaled');
+    const step = state.i32(0).named('step');
+    const pending = state.bool(true).named('pending');
+    const previousSeek = state.bool(false).named('previousSeek');
+    // Explicit materialization keeps capture/compile work bounded for composed
+    // consumers, rather than expanding shared arithmetic recursively.
+    const current = state.f64(0).named('currentScaled');
+    const increment = state.f64(0).named('incrementScaled');
+    const sum = state.f64(0).named('sumScaled');
+    const nextError = state.f64(0).named('nextErrorScaled');
+    return {
+        tick(c) {
+            const seek = c.seek.and(previousSeek.read().not()).and(c.reset.not());
+            const request = f64(c.position.clamp(-1048576, 1048576));
+            const wrapped = request.sub(request.div(config.steps).floor().mul(config.steps)).min(lastPosition);
+            const targetStep = wrapped.floor();
+            const oldStep = select(c.reset, i32(0), select(seek, i32(targetStep), step.read()));
+            current.write(select(c.reset, f64(0), select(seek, wrapped.sub(targetStep).mul(threshold * SCALE), position.read())));
+            const compensation = select(c.reset.or(seek), f64(0), error.read());
+            // A positive compensation at an exactly rounded threshold means the
+            // true position is still below the boundary. Preserve that distinction
+            // for gate=1 and crossing decisions (no epsilon or early sample tick).
+            const phase = current.read().sub(compensation).div(threshold * SCALE).clamp(0, 1 - 2 ** -53);
+            const pulse = c.reset.not().and(seek.or(pending.read()));
+            // Accumulate frequency units, not rounded samples-per-step or repeated
+            // fractional periods. Compensated summation preserves fractional tempos.
+            increment.write(f64(c.rate.clamp(0, 1000)).mul(division * SCALE).sub(compensation));
+            sum.write(current.read().add(increment.read()));
+            nextError.write(sum.read().sub(current.read()).sub(increment.read()));
+            const crossed = sum.read().gt(threshold * SCALE).or(sum.read().eq(threshold * SCALE).and(nextError.read().lte(0)));
+            const next = sum.read().sub(select(crossed, f64(threshold * SCALE), f64(0)));
+            const nextStep = oldStep.add(select(crossed, i32(1), i32(0)));
+            error.write(select(c.reset, f64(0), nextError.read()));
+            position.write(select(c.reset, f64(0), next));
+            step.write(select(c.reset, i32(0), select(nextStep.gte(config.steps), i32(0), nextStep)));
+            pending.write(c.reset.or(crossed));
+            previousSeek.write(c.seek);
+            return { step: f32(oldStep), phase: f32(phase).clamp(0, PHASE_MAX), phase64: phase, tick: pulse };
+        },
+    };
+});
+/** Sample clock, no transport or event scheduler. Call exactly once per sample. */
+export const musicalClock = defineSubgraph((config) => {
+    const clock = instantiate(clockCore, config, { name: 'clock' });
+    return { tick(c) {
+            const value = clock.tick(c);
+            return { step: value.step, phase: value.phase, tick: value.tick };
+        } };
+});
+/** Fixed step values and gate fractions; no MIDI generation or smoothing. */
+export const stepSequence = defineSubgraph((config) => {
+    if (!Array.isArray(config.steps) || config.steps.length < 1 || config.steps.length > 64)
+        throw new RangeError('sequence requires 1..64 steps');
+    const steps = config.steps.map(step => {
+        boundedNumber(step.value, -1, 1, 'step value');
+        boundedNumber(step.gate, 0, 1, 'step gate');
+        return { value: step.value, gate: step.gate };
+    });
+    const clock = instantiate(clockCore, { ...config, steps: steps.length }, { name: 'clock' });
+    return { tick(c) {
+            const t = clock.tick(c);
+            let value = f32(steps[0].value), gate = f64(steps[0].gate);
+            for (let n = 1; n < steps.length; n++) {
+                value = select(t.step.eq(n), f32(steps[n].value), value);
+                gate = select(t.step.eq(n), f64(steps[n].gate), gate);
+            }
+            return { value, step: t.step, phase: t.phase, tick: t.tick,
+                gate: c.reset.not().and(t.phase64.lt(gate)) };
+        } };
+});
+/**
+ * Fixed piecewise envelope. Rising trigger emits the first duration step;
+ * held trigger does not retrigger. Reset consumes trigger and emits initial.
+ * Zero-length segments collapse at their boundary in list order. Loop jumps
+ * from last target to the first segment's first step on the next sample.
+ */
+export const mseg = defineSubgraph((config) => {
+    checkRate(config.sampleRate);
+    boundedNumber(config.initial, -1, 1, 'MSEG initial');
+    if (!Array.isArray(config.segments) || config.segments.length < 1 || config.segments.length > 16)
+        throw new RangeError('MSEG requires 1..16 segments');
+    if (config.loop !== undefined && typeof config.loop !== 'boolean')
+        throw new RangeError('MSEG loop must be boolean');
+    let total = 0, startValue = config.initial;
+    const segments = config.segments.map(segment => {
+        boundedNumber(segment.seconds, 0, 30, 'MSEG seconds');
+        boundedNumber(segment.target, -1, 1, 'MSEG target');
+        if (!['linear', 'easeIn', 'easeOut', 'smoothstep'].includes(segment.curve))
+            throw new RangeError('unknown MSEG curve');
+        const frames = Math.round(segment.seconds * config.sampleRate);
+        const result = { ...segment, start: total, frames, startValue };
+        total += frames;
+        startValue = segment.target;
+        return result;
+    });
+    if (config.loop && total === 0)
+        throw new RangeError('looped MSEG needs at least one duration sample');
+    const frame = state.i32(0).named('frame');
+    const started = state.bool(false).named('started');
+    const previousTrigger = state.bool(false).named('previousTrigger');
+    return { tick(c) {
+            const trigger = c.trigger.and(previousTrigger.read().not()).and(c.reset.not());
+            const active = c.reset.not().and(started.read().or(trigger));
+            const advance = config.loop ? select(frame.read().gte(total), i32(1), frame.read().add(1)) : frame.read().add(1).min(total);
+            frame.write(select(active, select(trigger, i32(Math.min(1, total)), advance), i32(0)));
+            const elapsed = frame.read();
+            let value = f64(config.initial), index = i32(0);
+            for (let n = 0; n < segments.length; n++) {
+                const s = segments[n];
+                const t = f64(elapsed.sub(s.start)).div(Math.max(1, s.frames)).clamp(0, 1);
+                const curve = s.curve === 'easeIn' ? t.mul(t) : s.curve === 'easeOut' ? t.mul(f64(2).sub(t)) : s.curve === 'smoothstep' ? t.mul(t).mul(f64(3).sub(t.mul(2))) : t;
+                const applicable = active.and(s.frames === 0 ? elapsed.gte(s.start) : elapsed.gt(s.start));
+                const next = s.frames === 0 ? f64(s.target) : f64(s.startValue).add(curve.mul(s.target - s.startValue));
+                value = select(applicable, next, value);
+                index = select(applicable, i32(n), index);
+            }
+            started.write(active);
+            previousTrigger.write(c.trigger);
+            return { value: f32(value).clamp(-1, 1), segment: f32(index), done: active.not().or(bool(!config.loop).and(elapsed.gte(total))) };
+        } };
+});
+/** Level-sensitive sampling; full finite f32 range. Native state maps -0 to +0. */
+export const sampleAndHold = defineSubgraph((config) => {
+    boundedNumber(config.initial, -1, 1, 'sampleAndHold initial');
+    const held = state.f64(config.initial * SCALE).named('heldScaled');
+    return { tick(input, trigger, reset) {
+            held.write(select(reset, f64(config.initial * SCALE), select(trigger, f64(input).mul(SCALE), held.read())));
+            return f32(held.read().div(SCALE));
+        } };
+});
+/**
+ * Park-Miller seeded S&H / bounded correlated random. Each high trigger advances
+ * the PRNG, including correlation=1. Reset wins, restores seed/initial, and
+ * never advances. This is a convex random recurrence, not normalized Gaussian
+ * noise or a specified spectral color. All dynamic inputs must be finite.
+ */
+export const randomModulator = defineSubgraph((config) => {
+    boundedNumber(config.initial, -1, 1, 'random initial');
+    if (!Number.isInteger(config.seed) || config.seed < 1 || config.seed > 2147483646)
+        throw new RangeError('random seed must be an integer in [1,2147483646]');
+    const seed = state.f64(config.seed).named('seed');
+    const value = state.f64(config.initial * SCALE).named('valueScaled');
+    return { tick(c) {
+            // Product <= 3.61e13 < 2^53; all integer arithmetic is exactly represented.
+            const product = seed.read().mul(16807);
+            const nextSeed = product.sub(product.div(2147483647).floor().mul(2147483647));
+            seed.write(select(c.reset, f64(config.seed), select(c.trigger, nextSeed, seed.read())));
+            const uniform = seed.read().sub(1).div(2147483645).mul(2).sub(1);
+            const rho = f64(c.correlation.clamp(0, 1));
+            const next = value.read().mul(rho).add(uniform.mul(f64(1).sub(rho)).mul(SCALE));
+            value.write(select(c.reset, f64(config.initial * SCALE), select(c.trigger, next, value.read())));
+            return f32(value.read().div(SCALE)).clamp(-1, 1);
+        } };
+});
+/**
+ * Bounded fixed-note arp using a caller-owned native MIDI output. At most one
+ * off then one on per sample. Output capacity >=256 plus per-quantum draining
+ * is required for the conservative burst bound, not guaranteed host delivery.
+ * Rate zero holds a sounding note; reset before stopping/disconnecting.
+ */
+export const fixedArpeggiator = defineSubgraph((config) => {
+    if (!Number.isInteger(config.channel) || config.channel < 0 || config.channel > 15)
+        throw new RangeError('arp channel must be an integer in [0,15]');
+    if (!Array.isArray(config.notes) || config.notes.length < 1 || config.notes.length > 64)
+        throw new RangeError('arp requires 1..64 notes');
+    const notes = config.notes.map(note => {
+        if (!Number.isInteger(note.note) || note.note < 0 || note.note > 127)
+            throw new RangeError('arp note must be an integer in [0,127]');
+        if (!Number.isInteger(note.velocity) || note.velocity < 1 || note.velocity > 127)
+            throw new RangeError('arp velocity must be an integer in [1,127]');
+        boundedNumber(note.gate, 0, 1, 'arp gate');
+        return { ...note };
+    });
+    const clock = instantiate(clockCore, { ...config, steps: notes.length }, { name: 'clock' });
+    const active = state.bool(false).named('active');
+    const activeNote = state.i32(notes[0].note).named('activeNote');
+    return { tick(output, c) {
+            const t = clock.tick(c);
+            let note = i32(notes[0].note), velocity = i32(notes[0].velocity), fraction = f64(notes[0].gate);
+            for (let n = 1; n < notes.length; n++) {
+                note = select(t.step.eq(n), i32(notes[n].note), note);
+                velocity = select(t.step.eq(n), i32(notes[n].velocity), velocity);
+                fraction = select(t.step.eq(n), f64(notes[n].gate), fraction);
+            }
+            const gate = c.reset.not().and(t.phase64.lt(fraction));
+            const previous = active.read();
+            const off = previous.and(gate.not().or(t.tick));
+            const on = gate.and(previous.not().or(t.tick));
+            output.emitIf(off, { type: 'noteOff', channel: config.channel, note: activeNote.read(), velocity: 0, atSample: c.atSample });
+            output.emitIf(on, { type: 'noteOn', channel: config.channel, note, velocity, atSample: c.atSample });
+            activeNote.write(select(on, note, activeNote.read()));
+            active.write(gate);
+            return { note: f32(note), gate, step: t.step, phase: t.phase, tick: t.tick };
+        } };
+});

package/dist/mpe-expression.d.ts

@@ -0,0 +1,36 @@
+import { type MidiInputHandle, type Node } from '@unworklet/core';
+export interface MpeExpressionConfig {
+    /** Fixed lower zone: native channel 0 is master, 1..memberChannels are members. Default 15. */
+    memberChannels?: number;
+    /** Symmetric semitone range, finite [0,96]. Default 48. No RPN negotiation. */
+    memberBendRange?: number;
+    /** Symmetric semitone range, finite [0,96]. Default 2. */
+    masterBendRange?: number;
+}
+/** Pass the existing allocator voice's active/channel fields without remapping. */
+export interface MpeExpressionVoice {
+    active: Node<'bool'>;
+    channel: Node<'i32'>;
+}
+/** Lower-zone expression routing only: no note allocator or pedal propagation.
+ * Bind once to the same native MIDI input as the existing allocation policy.
+ * See docs/mpe-expression.md for channel reuse, reset and unsupported features.
+ */
+export declare const mpeExpression: import("@unworklet/core").SubgraphDecl<[config: MpeExpressionConfig], {
+    memberChannels: number;
+    memberBendRange: number;
+    masterBendRange: number;
+    reset: (when?: Node<"bool">) => void;
+    bindMidi(input: MidiInputHandle): void;
+    read(voice: MpeExpressionVoice): {
+        inZone: Node<"bool">;
+        memberBend: Node<"f32">;
+        masterBend: Node<"f32">;
+        /** Already includes both bend ranges. Do not add performancePolicy.bend again. */
+        bendSemitones: Node<"f32">;
+        memberPressure: Node<"f32">;
+        masterPressure: Node<"f32">;
+        memberTimbre: Node<"f32">;
+        masterTimbre: Node<"f32">;
+    };
+}>;

package/dist/mpe-expression.js

@@ -0,0 +1,73 @@
+import { bool, defineSubgraph, f32, f64, i32, select, state } from '@unworklet/core';
+/** Lower-zone expression routing only: no note allocator or pedal propagation.
+ * Bind once to the same native MIDI input as the existing allocation policy.
+ * See docs/mpe-expression.md for channel reuse, reset and unsupported features.
+ */
+export const mpeExpression = defineSubgraph((config) => {
+    const members = config.memberChannels ?? 15;
+    const memberRange = config.memberBendRange ?? 48;
+    const masterRange = config.masterBendRange ?? 2;
+    if (!Number.isInteger(members) || members < 1 || members > 15) {
+        throw new RangeError('mpeExpression memberChannels must be an integer in [1,15]');
+    }
+    for (const [name, value] of [['memberBendRange', memberRange], ['masterBendRange', masterRange]]) {
+        if (!Number.isFinite(value) || value < 0 || value > 96)
+            throw new RangeError(`mpeExpression ${name} must be finite in [0,96]`);
+    }
+    const ints = (name) => state.buffer.i32({ size: members + 1 }).expose({ name, snapshot: 'transient' });
+    // Store centered integer MIDI values, so fresh-instance transient defaults
+    // represent bend 8192, pressure 0 and CC74 64. In-place restore leaves
+    // transient state unchanged; reset() is the explicit clearing operation.
+    const bend = ints('bend'), pressure = ints('pressure'), timbre = ints('timbre');
+    const validChannel = (channel) => channel.gte(0).and(channel.lte(members));
+    const valid7 = (value) => value.gte(0).and(value.lte(127));
+    const normalizedBend = (channel) => {
+        const value = bend.read(channel);
+        return f64(value).div(select(value.lt(0), f64(8192), f64(8191)));
+    };
+    function reset(when = bool(true)) {
+        for (let channel = 0; channel <= members; channel++) {
+            bend.write(channel, select(when, i32(0), bend.read(channel)));
+            pressure.write(channel, select(when, i32(0), pressure.read(channel)));
+            timbre.write(channel, select(when, i32(0), timbre.read(channel)));
+        }
+    }
+    return {
+        memberChannels: members, memberBendRange: memberRange, masterBendRange: masterRange,
+        reset,
+        bindMidi(input) {
+            input.onEvent('pitchBend', e => {
+                const channel = e.channel.clamp(0, members);
+                const valid = validChannel(e.channel).and(e.value.gte(0)).and(e.value.lte(16383));
+                bend.write(channel, select(valid, e.value.sub(8192), bend.read(channel)));
+            });
+            input.onEvent('channelPressure', e => {
+                const channel = e.channel.clamp(0, members);
+                pressure.write(channel, select(validChannel(e.channel).and(valid7(e.pressure)), e.pressure, pressure.read(channel)));
+            });
+            input.onEvent('cc', e => {
+                const channel = e.channel.clamp(0, members), valid = validChannel(e.channel).and(valid7(e.value));
+                const clear = valid.and(e.controller.eq(121));
+                bend.write(channel, select(clear, i32(0), bend.read(channel)));
+                pressure.write(channel, select(clear, i32(0), pressure.read(channel)));
+                timbre.write(channel, select(clear, i32(0), select(valid.and(e.controller.eq(74)), e.value.sub(64), timbre.read(channel))));
+            });
+        },
+        read(voice) {
+            const inZone = voice.active.and(voice.channel.gte(1)).and(voice.channel.lte(members));
+            const channel = voice.channel.clamp(1, members);
+            const member = normalizedBend(channel), master = normalizedBend(i32(0));
+            const lane = (value) => select(inZone, value, f32(0));
+            return {
+                inZone,
+                memberBend: lane(f32(member)), masterBend: lane(f32(master)),
+                /** Already includes both bend ranges. Do not add performancePolicy.bend again. */
+                bendSemitones: lane(f32(member.mul(memberRange).add(master.mul(masterRange)))),
+                memberPressure: lane(f32(pressure.read(channel)).div(127)),
+                masterPressure: lane(f32(pressure.read(0)).div(127)),
+                memberTimbre: lane(f32(timbre.read(channel).add(64)).div(127)),
+                masterTimbre: lane(f32(timbre.read(0).add(64)).div(127)),
+            };
+        },
+    };
+});