From c9381a11f9ba182ac4ae8e5aab3584883003125c Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Fri, 3 Oct 2025 17:21:05 -0500
Subject: [PATCH 01/48] Working version

---
 packages/core/controls.mjs      | 144 +++++++++++++++++++++++++++++---
 packages/superdough/helpers.mjs | 124 +++++++++++++++++----------
 2 files changed, 213 insertions(+), 55 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 7e3c2a8e..a2136367 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -72,6 +72,27 @@ export function registerControl(names, ...aliases) {
   return bag;
 }
 
+export function registerMultiControl(names, maxControls, ...aliases) {
+  names = Array.isArray(names) ? names : [names];
+  let bag = {};
+  for (let i = 1; i <= maxControls; i++) {
+    let theseAliases = [...aliases];
+    let theseNames = [...names];
+    if (i === 1) {
+      // adds e.g. fm1 as an alias for fm
+      const aliases1 = theseAliases.map((a) => `${a}1`);
+      const names1 = theseNames.map((n) => `${n}1`);
+      theseAliases = theseAliases.concat(aliases1).concat(names1);
+    } else {
+      theseAliases = theseAliases.map((a) => `${a}${i}`);
+      theseNames = theseNames.map((n) => `${n}${i}`);
+    }
+    const subBag = registerControl(theseNames, ...theseAliases);
+    bag = { ...bag, ...subBag };
+  }
+  return bag;
+}
+
 /**
  * Select a sound / sample by name. When using mininotation, you can also optionally supply 'n' and 'gain' parameters
  * separated by ':'.
@@ -444,21 +465,22 @@ export const { attack, att } = registerControl('attack', 'att');
  * ._scope()
  *
  */
-export const { fmh } = registerControl(['fmh', 'fmi'], 'fmh');
+export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerMultiControl(['fmh', 'fmi'], 8, 'fmh');
 /**
  * Sets the Frequency Modulation of the synth.
  * Controls the modulation index, which defines the brightness of the sound.
  *
- * @name fm
+ * @name fmi
  * @param {number | Pattern} brightness modulation index
- * @synonyms fmi
+ * @synonyms fm
  * @example
  * note("c e g b g e")
  * .fm("<0 1 2 8 32>")
  * ._scope()
  *
  */
-export const { fmi, fm } = registerControl(['fmi', 'fmh'], 'fm');
+export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2, fm3, fm4, fm5, fm6, fm7, fm8 } =
+  registerMultiControl(['fmi', 'fmh'], 8, 'fm');
 // fm envelope
 /**
  * Ramp type of fm envelope. Exp might be a bit broken..
@@ -474,11 +496,15 @@ export const { fmi, fm } = registerControl(['fmi', 'fmh'], 'fm');
  * ._scope()
  *
  */
-export const { fmenv } = registerControl('fmenv');
+export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fmenv8 } = registerMultiControl(
+  'fmenv',
+  8,
+);
 /**
  * Attack time for the FM envelope: time it takes to reach maximum modulation
  *
  * @name fmattack
+ * @synonyms fmatt
  * @param {number | Pattern} time attack time
  * @example
  * note("c e g b g e")
@@ -487,7 +513,26 @@ export const { fmenv } = registerControl('fmenv');
  * ._scope()
  *
  */
-export const { fmattack } = registerControl('fmattack');
+export const {
+  fmattack,
+  fmattack1,
+  fmattack2,
+  fmattack3,
+  fmattack4,
+  fmattack5,
+  fmattack6,
+  fmattack7,
+  fmattack8,
+  fmatt,
+  fmatt1,
+  fmatt2,
+  fmatt3,
+  fmatt4,
+  fmatt5,
+  fmatt6,
+  fmatt7,
+  fmatt8,
+} = registerMultiControl('fmattack', 8, 'fmatt');
 
 /**
  * Waveform of the fm modulator
@@ -500,12 +545,16 @@ export const { fmattack } = registerControl('fmattack');
  * n("0 1 2 3".fast(4)).chord("<Dm Am F G>").voicing().s("sawtooth").fmwave("brown").fm(.6)
  *
  */
-export const { fmwave } = registerControl('fmwave');
+export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmwave7, fmwave8 } = registerMultiControl(
+  'fmwave',
+  8,
+);
 
 /**
  * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
  *
  * @name fmdecay
+ * @synonyms fmdec
  * @param {number | Pattern} time decay time
  * @example
  * note("c e g b g e")
@@ -515,11 +564,31 @@ export const { fmwave } = registerControl('fmwave');
  * ._scope()
  *
  */
-export const { fmdecay } = registerControl('fmdecay');
+export const {
+  fmdecay,
+  fmdecay1,
+  fmdecay2,
+  fmdecay3,
+  fmdecay4,
+  fmdecay5,
+  fmdecay6,
+  fmdecay7,
+  fmdecay8,
+  fmdec,
+  fmdec1,
+  fmdec2,
+  fmdec3,
+  fmdec4,
+  fmdec5,
+  fmdec6,
+  fmdec7,
+  fmdec8,
+} = registerMultiControl('fmdecay', 8, 'fmdec');
 /**
  * Sustain level for the FM envelope: how much modulation is applied after the decay phase
  *
  * @name fmsustain
+ * @synonyms fmsus
  * @param {number | Pattern} level sustain level
  * @example
  * note("c e g b g e")
@@ -529,10 +598,61 @@ export const { fmdecay } = registerControl('fmdecay');
  * ._scope()
  *
  */
-export const { fmsustain } = registerControl('fmsustain');
-// these are not really useful... skipping for now
-export const { fmrelease } = registerControl('fmrelease');
-export const { fmvelocity } = registerControl('fmvelocity');
+export const {
+  fmsustain,
+  fmsustain1,
+  fmsustain2,
+  fmsustain3,
+  fmsustain4,
+  fmsustain5,
+  fmsustain6,
+  fmsustain7,
+  fmsustain8,
+  fmsus,
+  fmsus1,
+  fmsus2,
+  fmsus3,
+  fmsus4,
+  fmsus5,
+  fmsus6,
+  fmsus7,
+  fmsus8,
+} = registerMultiControl('fmsustain', 8, 'fmsus');
+/**
+ * Release time for the FM envelope: how much modulation is applied after the note is released
+ *
+ * @name fmrelease
+ * @synonyms fmrel
+ * @param {number | Pattern} time release time
+ *
+ */
+export const {
+  fmrelease,
+  fmrelease1,
+  fmrelease2,
+  fmrelease3,
+  fmrelease4,
+  fmrelease5,
+  fmrelease6,
+  fmrelease7,
+  fmrelease8,
+  fmrel,
+  fmrel1,
+  fmrel2,
+  fmrel3,
+  fmrel4,
+  fmrel5,
+  fmrel6,
+  fmrel7,
+  fmrel8,
+} = registerMultiControl('fmrelease', 8, 'fmrel');
+
+// FM Matrix
+for (let i = 0; i <= 8; i++) {
+  for (let j = 0; j <= 8; j++) {
+    registerControl(`fm${i}${j}`);
+  }
+}
 
 /**
  * Select the sound bank to use. To be used together with `s`. The bank name (+ "_") will be prepended to the value of `s`.
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 47bca330..361733f1 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -325,7 +325,7 @@ const mod = (freq, range = 1, type = 'sine') => {
   osc.start();
   const g = new GainNode(ctx, { gain: range });
   osc.connect(g); // -range, range
-  return { node: g, stop: (t) => osc.stop(t) };
+  return { fm: osc, scaled: g, stop: (t) => osc.stop(t) };
 };
 const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
@@ -334,48 +334,86 @@ const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') =>
   return mod(modfreq, modgain, wave);
 };
 export function applyFM(param, value, begin) {
-  const {
-    fmh: fmHarmonicity = 1,
-    fmi: fmModulationIndex,
-    fmenv: fmEnvelopeType = 'exp',
-    fmattack: fmAttack,
-    fmdecay: fmDecay,
-    fmsustain: fmSustain,
-    fmrelease: fmRelease,
-    fmvelocity: fmVelocity,
-    fmwave: fmWaveform = 'sine',
-    duration,
-  } = value;
-  let modulator;
-  let stop = () => {};
-
-  if (fmModulationIndex) {
-    const ac = getAudioContext();
-    const envGain = ac.createGain();
-    const fmmod = fm(param, fmHarmonicity, fmModulationIndex, fmWaveform);
-
-    modulator = fmmod.node;
-    stop = fmmod.stop;
-    if (![fmAttack, fmDecay, fmSustain, fmRelease, fmVelocity].some((v) => v !== undefined)) {
-      // no envelope by default
-      modulator.connect(param);
-    } else {
-      const [attack, decay, sustain, release] = getADSRValues([fmAttack, fmDecay, fmSustain, fmRelease]);
-      const holdEnd = begin + duration;
-      getParamADSR(
-        envGain.gain,
-        attack,
-        decay,
-        sustain,
-        release,
-        0,
-        1,
-        begin,
-        holdEnd,
-        fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
-      );
-      modulator.connect(envGain);
-      envGain.connect(param);
+  const ac = getAudioContext();
+  let target = param;
+  let stop = (t) => {};
+  const targets = [param];
+  const modulators = [];
+  for (let i = 0; i < 8; i++) {
+    const iS = `${i === 0 ? '' : i}`;
+    let modulator;
+    const fmModulationIndex = value[`fmi${iS}`];
+    if (fmModulationIndex) {
+      const fmmod = fm(target, value[`fmh${iS}`] ?? 1, fmModulationIndex, value[`fmwave${iS}`] ?? 'sine');
+      modulator = fmmod.scaled;
+      const currStop = stop;
+      stop = (t) => {
+        currStop(t);
+        fmmod.stop(t);
+      };
+      const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${iS}`]);
+      if (!adsr.some((v) => v !== undefined)) {
+        // no envelope by default
+        modulator.connect(target);
+        modulators.push(modulator);
+      } else {
+        const envGain = ac.createGain();
+        const [attack, decay, sustain, release] = getADSRValues(adsr);
+        const holdEnd = begin + value.duration;
+        const fmEnvelopeType = value[`fmenv${iS}`] ?? 'exp';
+        getParamADSR(
+          envGain.gain,
+          attack,
+          decay,
+          sustain,
+          release,
+          0,
+          1,
+          begin,
+          holdEnd,
+          fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
+        );
+        modulator.connect(envGain);
+        envGain.connect(target);
+        modulators.push(envGain);
+      }
+      targets.push(fmmod.fm?.frequency);
+      if (targets[i]) {
+        // Cannot connect to noises, for example
+        target = targets[i];
+      }
+    }
+  }
+  // Matrix
+  for (let i = 1; i <= 8; i++) {
+    for (let j = 0; j <= 8; j++) {
+      let control;
+      if (i === j + 1) {
+        // Standard fm3 -> fm2 -> fm1 -> param usage
+        control = `fm${i}`;
+      } else {
+        control = `fm${i}${j}`;
+      }
+      const amt = value[control];
+      if (!amt) continue;
+      const source = modulators[i - 1];
+      const target = targets[j];
+      if (!source) {
+        const iS = `${i === 1 ? '' : i}`;
+        logger(
+          `[superdough] failed to connect FM from source ${i} (due to control ${control}): source ${i} does not exist. Please use control fm${iS} to set it up`,
+          'warning',
+        );
+        continue;
+      }
+      if (!target) {
+        logger(
+          `[superdough] failed to connect FM to target ${j} (due to control ${control}): target ${j} does not exist. Please use control fm${j} to set it up`,
+          'warning',
+        );
+        continue;
+      }
+      source.connect(target);
     }
   }
   return { stop };

From 7cf9db4872fe8d2bde619da87f197a4b1df64a70 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Fri, 3 Oct 2025 18:20:41 -0500
Subject: [PATCH 02/48] Big matrix refactor

---
 packages/core/controls.mjs      |   2 +-
 packages/superdough/helpers.mjs | 124 ++++++++++++++------------------
 2 files changed, 55 insertions(+), 71 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index a2136367..3f8847d9 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -650,7 +650,7 @@ export const {
 // FM Matrix
 for (let i = 0; i <= 8; i++) {
   for (let j = 0; j <= 8; j++) {
-    registerControl(`fm${i}${j}`);
+    registerControl(`fmi${i}${j}`, `fm${i}${j}`);
   }
 }
 
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 361733f1..89ae7da6 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -309,7 +309,7 @@ export function webAudioTimeout(audioContext, onComplete, startTime, stopTime) {
   constantNode.stop(stopTime);
   return constantNode;
 }
-const mod = (freq, range = 1, type = 'sine') => {
+const mod = (freq, type = 'sine') => {
   const ctx = getAudioContext();
   let osc;
   if (noises.includes(type)) {
@@ -321,99 +321,83 @@ const mod = (freq, range = 1, type = 'sine') => {
     osc.type = type;
     osc.frequency.value = freq;
   }
-
   osc.start();
-  const g = new GainNode(ctx, { gain: range });
-  osc.connect(g); // -range, range
-  return { fm: osc, scaled: g, stop: (t) => osc.stop(t) };
+  return { osc, stop: (t) => osc.stop(t), freq };
 };
+
 const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
   const modfreq = carrfreq * harmonicityRatio;
-  const modgain = modfreq * modulationIndex;
-  return mod(modfreq, modgain, wave);
+  return mod(modfreq, wave)
 };
+
 export function applyFM(param, value, begin) {
   const ac = getAudioContext();
-  let target = param;
   let stop = (t) => {};
-  const targets = [param];
-  const modulators = [];
-  for (let i = 0; i < 8; i++) {
-    const iS = `${i === 0 ? '' : i}`;
-    let modulator;
-    const fmModulationIndex = value[`fmi${iS}`];
-    if (fmModulationIndex) {
-      const fmmod = fm(target, value[`fmh${iS}`] ?? 1, fmModulationIndex, value[`fmwave${iS}`] ?? 'sine');
-      modulator = fmmod.scaled;
-      const currStop = stop;
-      stop = (t) => {
-        currStop(t);
-        fmmod.stop(t);
-      };
-      const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${iS}`]);
-      if (!adsr.some((v) => v !== undefined)) {
-        // no envelope by default
-        modulator.connect(target);
-        modulators.push(modulator);
-      } else {
-        const envGain = ac.createGain();
-        const [attack, decay, sustain, release] = getADSRValues(adsr);
-        const holdEnd = begin + value.duration;
-        const fmEnvelopeType = value[`fmenv${iS}`] ?? 'exp';
-        getParamADSR(
-          envGain.gain,
-          attack,
-          decay,
-          sustain,
-          release,
-          0,
-          1,
-          begin,
-          holdEnd,
-          fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
-        );
-        modulator.connect(envGain);
-        envGain.connect(target);
-        modulators.push(envGain);
-      }
-      targets.push(fmmod.fm?.frequency);
-      if (targets[i]) {
-        // Cannot connect to noises, for example
-        target = targets[i];
-      }
-    }
-  }
+  const fms = {};
   // Matrix
   for (let i = 1; i <= 8; i++) {
     for (let j = 0; j <= 8; j++) {
       let control;
       if (i === j + 1) {
         // Standard fm3 -> fm2 -> fm1 -> param usage
-        control = `fm${i}`;
+        const iS = i === 1 ? '' : i;
+        control = `fmi${iS}`;
       } else {
-        control = `fm${i}${j}`;
+        control = `fmi${i}${j}`;
       }
       const amt = value[control];
       if (!amt) continue;
-      const source = modulators[i - 1];
-      const target = targets[j];
-      if (!source) {
-        const iS = `${i === 1 ? '' : i}`;
+      let io = [];
+      for (let [isMod, idx] of [[true, i], [false, j]]) {
+        debugger;
+        if (idx === 0) {
+          io.push(param);
+          continue;
+        }
+        if (!fms[idx]) {
+          const idxS = idx === 1 ? '' : idx;
+          const { osc, freq } = fm(param, value[`fmh${idxS}`] ?? 1, value[`fmwave${idxS}`] ?? 'sine');
+          const currStop = stop;
+          stop = (t) => {
+            currStop(t);
+            osc.stop(t);
+          };
+          const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${idxS}`]);
+          if (!adsr.some((v) => v !== undefined)) {
+            fms[idx] = { input: osc.frequency, output: osc, freq};
+          } else {
+            const envGain = ac.createGain();
+            const [attack, decay, sustain, release] = getADSRValues(adsr);
+            const holdEnd = begin + value.duration;
+            const fmEnvelopeType = value[`fmenv${idxS}`] ?? 'exp';
+            getParamADSR(
+              envGain.gain,
+              attack,
+              decay,
+              sustain,
+              release,
+              0,
+              1,
+              begin,
+              holdEnd,
+              fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
+            );
+            fms[idx] = { input: osc.frequency, output: osc.connect(envGain), freq};
+          }
+        }
+        const { input, output, freq } = fms[idx];
+        const g = gainNode(amt * freq);
+        io.push(isMod ? output.connect(g) : input);
+      }
+      if (!io[1]) {
         logger(
-          `[superdough] failed to connect FM from source ${i} (due to control ${control}): source ${i} does not exist. Please use control fm${iS} to set it up`,
+          `[superdough] control ${control} failed to connect FM ${i} to target ${j} due to missing frequency parameter (likely because fm${j} is noise)`,
           'warning',
         );
         continue;
       }
-      if (!target) {
-        logger(
-          `[superdough] failed to connect FM to target ${j} (due to control ${control}): target ${j} does not exist. Please use control fm${j} to set it up`,
-          'warning',
-        );
-        continue;
-      }
-      source.connect(target);
+      io[0].connect(io[1]);
     }
   }
   return { stop };

From bd73d96847889f78b4a3cc9e98d4df0eeeb5244f Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Fri, 3 Oct 2025 18:49:49 -0500
Subject: [PATCH 03/48] Cleanup

---
 packages/superdough/helpers.mjs           | 15 +++---
 test/__snapshots__/examples.test.mjs.snap | 58 +++++++++++------------
 2 files changed, 38 insertions(+), 35 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 89ae7da6..de8daaf5 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -1,6 +1,7 @@
+import { logger } from './logger.mjs';
+import { getNoiseBuffer } from './noise.mjs';
 import { getAudioContext } from './superdough.mjs';
 import { clamp, nanFallback, midiToFreq, noteToMidi } from './util.mjs';
-import { getNoiseBuffer } from './noise.mjs';
 
 export const noises = ['pink', 'white', 'brown', 'crackle'];
 
@@ -328,7 +329,7 @@ const mod = (freq, type = 'sine') => {
 const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
   const modfreq = carrfreq * harmonicityRatio;
-  return mod(modfreq, wave)
+  return mod(modfreq, wave);
 };
 
 export function applyFM(param, value, begin) {
@@ -349,8 +350,10 @@ export function applyFM(param, value, begin) {
       const amt = value[control];
       if (!amt) continue;
       let io = [];
-      for (let [isMod, idx] of [[true, i], [false, j]]) {
-        debugger;
+      for (let [isMod, idx] of [
+        [true, i],
+        [false, j],
+      ]) {
         if (idx === 0) {
           io.push(param);
           continue;
@@ -365,7 +368,7 @@ export function applyFM(param, value, begin) {
           };
           const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${idxS}`]);
           if (!adsr.some((v) => v !== undefined)) {
-            fms[idx] = { input: osc.frequency, output: osc, freq};
+            fms[idx] = { input: osc.frequency, output: osc, freq };
           } else {
             const envGain = ac.createGain();
             const [attack, decay, sustain, release] = getADSRValues(adsr);
@@ -383,7 +386,7 @@ export function applyFM(param, value, begin) {
               holdEnd,
               fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
             );
-            fms[idx] = { input: osc.frequency, output: osc.connect(envGain), freq};
+            fms[idx] = { input: osc.frequency, output: osc.connect(envGain), freq };
           }
         }
         const { input, output, freq } = fms[idx];
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 73278947..be8b371a 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -3880,35 +3880,6 @@ exports[`runs examples > example "floor" example index 0 1`] = `
 ]
 `;
 
-exports[`runs examples > example "fm" example index 0 1`] = `
-[
-  "[ 0/1 → 1/6 | note:c fmi:0 ]",
-  "[ 1/6 → 1/3 | note:e fmi:0 ]",
-  "[ 1/3 → 1/2 | note:g fmi:0 ]",
-  "[ 1/2 → 2/3 | note:b fmi:0 ]",
-  "[ 2/3 → 5/6 | note:g fmi:0 ]",
-  "[ 5/6 → 1/1 | note:e fmi:0 ]",
-  "[ 1/1 → 7/6 | note:c fmi:1 ]",
-  "[ 7/6 → 4/3 | note:e fmi:1 ]",
-  "[ 4/3 → 3/2 | note:g fmi:1 ]",
-  "[ 3/2 → 5/3 | note:b fmi:1 ]",
-  "[ 5/3 → 11/6 | note:g fmi:1 ]",
-  "[ 11/6 → 2/1 | note:e fmi:1 ]",
-  "[ 2/1 → 13/6 | note:c fmi:2 ]",
-  "[ 13/6 → 7/3 | note:e fmi:2 ]",
-  "[ 7/3 → 5/2 | note:g fmi:2 ]",
-  "[ 5/2 → 8/3 | note:b fmi:2 ]",
-  "[ 8/3 → 17/6 | note:g fmi:2 ]",
-  "[ 17/6 → 3/1 | note:e fmi:2 ]",
-  "[ 3/1 → 19/6 | note:c fmi:8 ]",
-  "[ 19/6 → 10/3 | note:e fmi:8 ]",
-  "[ 10/3 → 7/2 | note:g fmi:8 ]",
-  "[ 7/2 → 11/3 | note:b fmi:8 ]",
-  "[ 11/3 → 23/6 | note:g fmi:8 ]",
-  "[ 23/6 → 4/1 | note:e fmi:8 ]",
-]
-`;
-
 exports[`runs examples > example "fmattack" example index 0 1`] = `
 [
   "[ 0/1 → 1/6 | note:c fmi:4 fmattack:0 ]",
@@ -4025,6 +3996,35 @@ exports[`runs examples > example "fmh" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "fmi" example index 0 1`] = `
+[
+  "[ 0/1 → 1/6 | note:c fmi:0 ]",
+  "[ 1/6 → 1/3 | note:e fmi:0 ]",
+  "[ 1/3 → 1/2 | note:g fmi:0 ]",
+  "[ 1/2 → 2/3 | note:b fmi:0 ]",
+  "[ 2/3 → 5/6 | note:g fmi:0 ]",
+  "[ 5/6 → 1/1 | note:e fmi:0 ]",
+  "[ 1/1 → 7/6 | note:c fmi:1 ]",
+  "[ 7/6 → 4/3 | note:e fmi:1 ]",
+  "[ 4/3 → 3/2 | note:g fmi:1 ]",
+  "[ 3/2 → 5/3 | note:b fmi:1 ]",
+  "[ 5/3 → 11/6 | note:g fmi:1 ]",
+  "[ 11/6 → 2/1 | note:e fmi:1 ]",
+  "[ 2/1 → 13/6 | note:c fmi:2 ]",
+  "[ 13/6 → 7/3 | note:e fmi:2 ]",
+  "[ 7/3 → 5/2 | note:g fmi:2 ]",
+  "[ 5/2 → 8/3 | note:b fmi:2 ]",
+  "[ 8/3 → 17/6 | note:g fmi:2 ]",
+  "[ 17/6 → 3/1 | note:e fmi:2 ]",
+  "[ 3/1 → 19/6 | note:c fmi:8 ]",
+  "[ 19/6 → 10/3 | note:e fmi:8 ]",
+  "[ 10/3 → 7/2 | note:g fmi:8 ]",
+  "[ 7/2 → 11/3 | note:b fmi:8 ]",
+  "[ 11/3 → 23/6 | note:g fmi:8 ]",
+  "[ 23/6 → 4/1 | note:e fmi:8 ]",
+]
+`;
+
 exports[`runs examples > example "fmsustain" example index 0 1`] = `
 [
   "[ 0/1 → 1/6 | note:c fmi:4 fmdecay:0.1 fmsustain:1 ]",

From 1be9f40574aa213d3ef501024e5a0e18cb04fef9 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Sat, 18 Oct 2025 10:42:35 +0100
Subject: [PATCH 04/48] timeline feature

---
 packages/core/impure.mjs | 60 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 packages/core/impure.mjs

diff --git a/packages/core/impure.mjs b/packages/core/impure.mjs
new file mode 100644
index 00000000..66fc1dd5
--- /dev/null
+++ b/packages/core/impure.mjs
@@ -0,0 +1,60 @@
+/*
+stateful.mjs - File of shame for stateful, impure and otherwise illegal pattern methods
+Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { register, reify } from './pattern.mjs';
+
+let timelines = {};
+
+export const reset_timelines = function () {
+  timelines = {};
+};
+
+export const timeline = register(
+  'timeline',
+  function (tpat, pat) {
+    tpat = reify(tpat);
+    const f = function (state) {
+      let scheduler = !!state.controls._cps;
+
+      const timehaps = tpat.query(state);
+      const result = [];
+      for (const timehap of timehaps) {
+        const tlid = timehap.value;
+        const ignore = false;
+        let offset;
+        if (tlid in timelines) {
+          offset = timelines[tlid];
+        } else {
+          const timearc = timehap.wholeOrPart();
+          if (!scheduler || state.span.begin.lt(timearc.midpoint())) {
+            offset = timearc.begin;
+          } else {
+            // Sync to end of timearc if we first see it over halfway into its
+            // timespan. Allows 'cuing up' next timeline when live coding.
+            offset = timearc.end;
+          }
+        }
+        if (scheduler) {
+          // update state
+          timelines[tlid] = offset;
+          const negative = 0 - tlid;
+          if (negative in timelines) {
+            delete timelines[negative];
+          }
+        }
+
+        const pathaps = pat
+          .late(offset)
+          .query(state.setSpan(timehap.part))
+          .map((h) => h.setContext(h.combineContext(timehap)));
+        result.push(...pathaps);
+      }
+      return result;
+    };
+    return new Pattern(f, pat._steps);
+  },
+  false,
+);

From b2ce4591d9bd4260511bb08a06f791f515452456 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Sat, 18 Oct 2025 10:42:55 +0100
Subject: [PATCH 05/48] sort exports and add impure.mjs

---
 packages/core/index.mjs | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/packages/core/index.mjs b/packages/core/index.mjs
index e4daf445..9260e367 100644
--- a/packages/core/index.mjs
+++ b/packages/core/index.mjs
@@ -1,6 +1,6 @@
 /*
 index.mjs - <short description TODO>
-Copyright (C) 2022 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
+Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
@@ -11,20 +11,21 @@ import createClock from './zyklus.mjs';
 import { logger } from './logger.mjs';
 export { Fraction, controls, createClock };
 export * from './controls.mjs';
-export * from './hap.mjs';
-export * from './pattern.mjs';
-export * from './signal.mjs';
-export * from './pick.mjs';
-export * from './state.mjs';
-export * from './timespan.mjs';
-export * from './util.mjs';
-export * from './speak.mjs';
-export * from './evaluate.mjs';
-export * from './repl.mjs';
 export * from './cyclist.mjs';
+export * from './evaluate.mjs';
+export * from './hap.mjs';
+export * from './impure.mjs';
 export * from './logger.mjs';
+export * from './pattern.mjs';
+export * from './pick.mjs';
+export * from './repl.mjs';
+export * from './signal.mjs';
+export * from './speak.mjs';
+export * from './state.mjs';
 export * from './time.mjs';
+export * from './timespan.mjs';
 export * from './ui.mjs';
+export * from './util.mjs';
 export { default as drawLine } from './drawLine.mjs';
 // below won't work with runtime.mjs (json import fails)
 /* import * as p from './package.json';

From 92a82ce4bdf951ae80a34c0e609aa3515951fa6f Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Sat, 18 Oct 2025 10:49:15 +0100
Subject: [PATCH 06/48] delint

---
 packages/core/impure.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/impure.mjs b/packages/core/impure.mjs
index 66fc1dd5..e16cfbe4 100644
--- a/packages/core/impure.mjs
+++ b/packages/core/impure.mjs
@@ -4,7 +4,7 @@ Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { register, reify } from './pattern.mjs';
+import { register, reify, Pattern } from './pattern.mjs';
 
 let timelines = {};
 

From 4c49cd9297326cf4991f1dca879bef3ed657be51 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sat, 18 Oct 2025 11:24:56 -0500
Subject: [PATCH 07/48] More examples

---
 packages/core/controls.mjs                | 30 ++++++++++++++++++
 test/__snapshots__/examples.test.mjs.snap | 37 +++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 55a07cc2..281bf76b 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -456,6 +456,9 @@ export const { attack, att } = registerControl('attack', 'att');
  * Whole numbers and simple ratios sound more natural,
  * while decimal numbers and complex ratios sound metallic.
  *
+ * A number may be added afterwards to control the harmonicity of
+ * any of the 8 individual FMs (e.g. `fmh2`)
+ *
  * @name fmh
  * @param {number | Pattern} harmonicity
  * @example
@@ -470,6 +473,11 @@ export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerM
  * Sets the Frequency Modulation of the synth.
  * Controls the modulation index, which defines the brightness of the sound.
  *
+ * A number may be added afterwards to control the modulation index of
+ * any of the 8 individual FMs (e.g. `fm3`). Also, FMs may be routed into
+ * each other with matrix commands like `fm13`, which would send `fm1` back into
+ * `fm3`
+ *
  * @name fmi
  * @param {number | Pattern} brightness modulation index
  * @synonyms fm
@@ -477,6 +485,10 @@ export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerM
  * note("c e g b g e")
  * .fm("<0 1 2 8 32>")
  * ._scope()
+ * @example
+ * s("sine").note("F1").seg(8)
+ *  .fm(4).fm2(rand.mul(4)).fm3(saw.mul(8).slow(8))
+ *  .fmh(1.06).fmh2(10).fmh3(0.1)
  *
  */
 export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2, fm3, fm4, fm5, fm6, fm7, fm8 } =
@@ -485,6 +497,9 @@ export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2
 /**
  * Ramp type of fm envelope. Exp might be a bit broken..
  *
+ * A number may be added afterwards to control the envelope of
+ * any of the 8 individual FMs (e.g. `fmenv4`)
+ *
  * @name fmenv
  * @param {number | Pattern} type lin | exp
  * @example
@@ -503,6 +518,9 @@ export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fm
 /**
  * Attack time for the FM envelope: time it takes to reach maximum modulation
  *
+ * A number may be added afterwards to control the attack of the envelope of
+ * any of the 8 individual FMs (e.g. `fmatt5`)
+ *
  * @name fmattack
  * @synonyms fmatt
  * @param {number | Pattern} time attack time
@@ -537,6 +555,9 @@ export const {
 /**
  * Waveform of the fm modulator
  *
+ * A number may be added afterwards to control the waveform
+ * any of the 8 individual FMs (e.g. `fmwave6`)
+ *
  * @name fmwave
  * @param {number | Pattern} wave waveform
  * @example
@@ -553,6 +574,9 @@ export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmw
 /**
  * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
  *
+ * A number may be added afterwards to control the decay of the envelope of
+ * any of the 8 individual FMs (e.g. `fmdec6`)
+ *
  * @name fmdecay
  * @synonyms fmdec
  * @param {number | Pattern} time decay time
@@ -587,6 +611,9 @@ export const {
 /**
  * Sustain level for the FM envelope: how much modulation is applied after the decay phase
  *
+ * A number may be added afterwards to control the sustain of the envelope of
+ * any of the 8 individual FMs (e.g. `fmsus7`)
+ *
  * @name fmsustain
  * @synonyms fmsus
  * @param {number | Pattern} level sustain level
@@ -621,6 +648,9 @@ export const {
 /**
  * Release time for the FM envelope: how much modulation is applied after the note is released
  *
+ * A number may be added afterwards to control the release of the envelope of
+ * any of the 8 individual FMs (e.g. `fmrel8`)
+ *
  * @name fmrelease
  * @synonyms fmrel
  * @param {number | Pattern} time release time
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 590c47e4..04360a4d 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -4101,6 +4101,43 @@ exports[`runs examples > example "fmi" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "fmi" example index 1 1`] = `
+[
+  "[ 0/1 → 1/8 | s:sine note:F1 fmi:4 fmi2:0 fmi3:0 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 1/8 → 1/4 | s:sine note:F1 fmi:4 fmi2:2.7408622801303864 fmi3:0.125 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 1/4 → 3/8 | s:sine note:F1 fmi:4 fmi2:1.479038767516613 fmi3:0.25 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 3/8 → 1/2 | s:sine note:F1 fmi:4 fmi2:1.605570062994957 fmi3:0.375 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 1/2 → 5/8 | s:sine note:F1 fmi:4 fmi2:1.041922464966774 fmi3:0.5 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 5/8 → 3/4 | s:sine note:F1 fmi:4 fmi2:0.5425434708595276 fmi3:0.625 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 3/4 → 7/8 | s:sine note:F1 fmi:4 fmi2:0.7833059206604958 fmi3:0.75 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 7/8 → 1/1 | s:sine note:F1 fmi:4 fmi2:1.590524323284626 fmi3:0.875 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 1/1 → 9/8 | s:sine note:F1 fmi:4 fmi2:2.078168660402298 fmi3:1 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 9/8 → 5/4 | s:sine note:F1 fmi:4 fmi2:2.689958058297634 fmi3:1.125 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 5/4 → 11/8 | s:sine note:F1 fmi:4 fmi2:2.914912812411785 fmi3:1.25 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 11/8 → 3/2 | s:sine note:F1 fmi:4 fmi2:0.7312150076031685 fmi3:1.375 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 3/2 → 13/8 | s:sine note:F1 fmi:4 fmi2:2.4336322993040085 fmi3:1.5 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 13/8 → 7/4 | s:sine note:F1 fmi:4 fmi2:1.987018845975399 fmi3:1.625 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 7/4 → 15/8 | s:sine note:F1 fmi:4 fmi2:0.8189515843987465 fmi3:1.75 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 15/8 → 2/1 | s:sine note:F1 fmi:4 fmi2:2.3782287165522575 fmi3:1.875 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 2/1 → 17/8 | s:sine note:F1 fmi:4 fmi2:3.838108479976654 fmi3:2 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 17/8 → 9/4 | s:sine note:F1 fmi:4 fmi2:3.613561175763607 fmi3:2.125 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 9/4 → 19/8 | s:sine note:F1 fmi:4 fmi2:1.3819300457835197 fmi3:2.25 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 19/8 → 5/2 | s:sine note:F1 fmi:4 fmi2:3.346026562154293 fmi3:2.375 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 5/2 → 21/8 | s:sine note:F1 fmi:4 fmi2:1.8344642966985703 fmi3:2.5 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 21/8 → 11/4 | s:sine note:F1 fmi:4 fmi2:0.6407739371061325 fmi3:2.625 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 11/4 → 23/8 | s:sine note:F1 fmi:4 fmi2:2.5329310819506645 fmi3:2.75 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 23/8 → 3/1 | s:sine note:F1 fmi:4 fmi2:0.06501668691635132 fmi3:2.875 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 3/1 → 25/8 | s:sine note:F1 fmi:4 fmi2:0.8691564425826073 fmi3:3 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 25/8 → 13/4 | s:sine note:F1 fmi:4 fmi2:1.3729755133390427 fmi3:3.125 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 13/4 → 27/8 | s:sine note:F1 fmi:4 fmi2:3.9694602862000465 fmi3:3.25 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 27/8 → 7/2 | s:sine note:F1 fmi:4 fmi2:1.6347672045230865 fmi3:3.375 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 7/2 → 29/8 | s:sine note:F1 fmi:4 fmi2:1.639795258641243 fmi3:3.5 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 29/8 → 15/4 | s:sine note:F1 fmi:4 fmi2:3.7565943151712418 fmi3:3.625 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 15/4 → 31/8 | s:sine note:F1 fmi:4 fmi2:3.2486692890524864 fmi3:3.75 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+  "[ 31/8 → 4/1 | s:sine note:F1 fmi:4 fmi2:2.9446661546826363 fmi3:3.875 fmh:1.06 fmh2:10 fmh3:0.1 ]",
+]
+`;
+
 exports[`runs examples > example "fmsustain" example index 0 1`] = `
 [
   "[ 0/1 → 1/6 | note:c fmi:4 fmdecay:0.1 fmsustain:1 ]",

From 654c1a86f08550586049fcef4a6b4c9ac5007755 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Tue, 18 Nov 2025 16:02:33 -0600
Subject: [PATCH 08/48] Simplify declarations via globalThis; fix cleanup/stop

---
 packages/core/controls.mjs      | 106 +++++---------------------------
 packages/superdough/helpers.mjs |  46 +++++++++-----
 2 files changed, 44 insertions(+), 108 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 02178de9..854f48ff 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -468,7 +468,8 @@ export const { attack, att } = registerControl('attack', 'att');
  * ._scope()
  *
  */
-export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerMultiControl(['fmh', 'fmi'], 8, 'fmh');
+Object.assign(globalThis, registerMultiControl(['fmh', 'fmi'], 8, 'fmh'));
+
 /**
  * Sets the Frequency Modulation of the synth.
  * Controls the modulation index, which defines the brightness of the sound.
@@ -491,8 +492,8 @@ export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerM
  *  .fmh(1.06).fmh2(10).fmh3(0.1)
  *
  */
-export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2, fm3, fm4, fm5, fm6, fm7, fm8 } =
-  registerMultiControl(['fmi', 'fmh'], 8, 'fm');
+Object.assign(globalThis, registerMultiControl(['fmi', 'fmh'], 8, 'fm'));
+
 // fm envelope
 /**
  * Ramp type of fm envelope. Exp might be a bit broken..
@@ -511,10 +512,8 @@ export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2
  * ._scope()
  *
  */
-export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fmenv8 } = registerMultiControl(
-  'fmenv',
-  8,
-);
+Object.assign(globalThis, registerMultiControl('fmenv', 8));
+
 /**
  * Attack time for the FM envelope: time it takes to reach maximum modulation
  *
@@ -531,26 +530,7 @@ export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fm
  * ._scope()
  *
  */
-export const {
-  fmattack,
-  fmattack1,
-  fmattack2,
-  fmattack3,
-  fmattack4,
-  fmattack5,
-  fmattack6,
-  fmattack7,
-  fmattack8,
-  fmatt,
-  fmatt1,
-  fmatt2,
-  fmatt3,
-  fmatt4,
-  fmatt5,
-  fmatt6,
-  fmatt7,
-  fmatt8,
-} = registerMultiControl('fmattack', 8, 'fmatt');
+Object.assign(globalThis, registerMultiControl('fmattack', 8, 'fmatt'));
 
 /**
  * Waveform of the fm modulator
@@ -566,10 +546,7 @@ export const {
  * n("0 1 2 3".fast(4)).chord("<Dm Am F G>").voicing().s("sawtooth").fmwave("brown").fm(.6)
  *
  */
-export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmwave7, fmwave8 } = registerMultiControl(
-  'fmwave',
-  8,
-);
+Object.assign(globalThis, registerMultiControl('fmwave', 8));
 
 /**
  * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
@@ -588,26 +565,8 @@ export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmw
  * ._scope()
  *
  */
-export const {
-  fmdecay,
-  fmdecay1,
-  fmdecay2,
-  fmdecay3,
-  fmdecay4,
-  fmdecay5,
-  fmdecay6,
-  fmdecay7,
-  fmdecay8,
-  fmdec,
-  fmdec1,
-  fmdec2,
-  fmdec3,
-  fmdec4,
-  fmdec5,
-  fmdec6,
-  fmdec7,
-  fmdec8,
-} = registerMultiControl('fmdecay', 8, 'fmdec');
+Object.assign(globalThis, registerMultiControl('fmdecay', 8, 'fmdec'));
+
 /**
  * Sustain level for the FM envelope: how much modulation is applied after the decay phase
  *
@@ -625,26 +584,8 @@ export const {
  * ._scope()
  *
  */
-export const {
-  fmsustain,
-  fmsustain1,
-  fmsustain2,
-  fmsustain3,
-  fmsustain4,
-  fmsustain5,
-  fmsustain6,
-  fmsustain7,
-  fmsustain8,
-  fmsus,
-  fmsus1,
-  fmsus2,
-  fmsus3,
-  fmsus4,
-  fmsus5,
-  fmsus6,
-  fmsus7,
-  fmsus8,
-} = registerMultiControl('fmsustain', 8, 'fmsus');
+Object.assign(globalThis, registerMultiControl('fmsustain', 8, 'fmsus'));
+
 /**
  * Release time for the FM envelope: how much modulation is applied after the note is released
  *
@@ -656,31 +597,12 @@ export const {
  * @param {number | Pattern} time release time
  *
  */
-export const {
-  fmrelease,
-  fmrelease1,
-  fmrelease2,
-  fmrelease3,
-  fmrelease4,
-  fmrelease5,
-  fmrelease6,
-  fmrelease7,
-  fmrelease8,
-  fmrel,
-  fmrel1,
-  fmrel2,
-  fmrel3,
-  fmrel4,
-  fmrel5,
-  fmrel6,
-  fmrel7,
-  fmrel8,
-} = registerMultiControl('fmrelease', 8, 'fmrel');
+Object.assign(globalThis, registerMultiControl('fmrelease', 8, 'fmrel'));
 
 // FM Matrix
 for (let i = 0; i <= 8; i++) {
   for (let j = 0; j <= 8; j++) {
-    registerControl(`fmi${i}${j}`, `fm${i}${j}`);
+    Object.assign(globalThis, registerControl(`fmi${i}${j}`, `fm${i}${j}`));
   }
 }
 
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index b856a0d8..0ab43791 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -336,6 +336,7 @@ export function webAudioTimeout(audioContext, onComplete, startTime, stopTime) {
   constantNode.stop(stopTime);
   return constantNode;
 }
+
 const mod = (freq, type = 'sine') => {
   const ctx = getAudioContext();
   let osc;
@@ -349,10 +350,10 @@ const mod = (freq, type = 'sine') => {
     osc.frequency.value = freq;
   }
   osc.start();
-  return { osc, stop: (t) => osc.stop(t), freq };
+  return { osc, freq };
 };
 
-const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') => {
+const fm = (frequencyparam, harmonicityRatio, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
   const modfreq = carrfreq * harmonicityRatio;
   return mod(modfreq, wave);
@@ -360,7 +361,7 @@ const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') =>
 
 export function applyFM(param, value, begin) {
   const ac = getAudioContext();
-  let stop = (t) => {};
+  const toStop = []; // fm oscillators we will expose `stop` for
   const fms = {};
   // Matrix
   for (let i = 1; i <= 8; i++) {
@@ -377,8 +378,8 @@ export function applyFM(param, value, begin) {
       if (!amt) continue;
       let io = [];
       for (let [isMod, idx] of [
-        [true, i],
-        [false, j],
+        [true, i], // source
+        [false, j], // target
       ]) {
         if (idx === 0) {
           io.push(param);
@@ -387,15 +388,11 @@ export function applyFM(param, value, begin) {
         if (!fms[idx]) {
           const idxS = idx === 1 ? '' : idx;
           const { osc, freq } = fm(param, value[`fmh${idxS}`] ?? 1, value[`fmwave${idxS}`] ?? 'sine');
-          const currStop = stop;
-          stop = (t) => {
-            currStop(t);
-            osc.stop(t);
-          };
+          toStop.push(osc);
+          const toCleanup = [osc]; // nodes we want to cleanup after oscillator `stop`
           const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${idxS}`]);
-          if (!adsr.some((v) => v !== undefined)) {
-            fms[idx] = { input: osc.frequency, output: osc, freq };
-          } else {
+          let output = osc;
+          if (adsr.some((v) => v !== undefined)) {
             const envGain = ac.createGain();
             const [attack, decay, sustain, release] = getADSRValues(adsr);
             const holdEnd = begin + value.duration;
@@ -412,12 +409,16 @@ export function applyFM(param, value, begin) {
               holdEnd,
               fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
             );
-            fms[idx] = { input: osc.frequency, output: osc.connect(envGain), freq };
+            toCleanup.push(envGain);
+            output = osc.connect(envGain);
           }
+          fms[idx] = { input: osc.frequency, output, freq, toCleanup };
+          osc.onended = () => cleanupNodes(fms[idx].toCleanup);
         }
-        const { input, output, freq } = fms[idx];
+        const { input, output, freq, toCleanup } = fms[idx];
         const g = gainNode(amt * freq);
         io.push(isMod ? output.connect(g) : input);
+        toCleanup.push(g);
       }
       if (!io[1]) {
         logger(
@@ -429,7 +430,9 @@ export function applyFM(param, value, begin) {
       io[0].connect(io[1]);
     }
   }
-  return { stop };
+  return {
+    stop: (t) => toStop.forEach((m) => m?.stop(t)),
+  };
 }
 
 // Saturation curves
@@ -549,3 +552,14 @@ export const destroyAudioWorkletNode = (node) => {
   node.disconnect();
   node.parameters.get('end')?.setValueAtTime(0, 0);
 };
+
+export const cleanupNode = (node, time) => {
+  if (node == null) return;
+  node.disconnect?.();
+  node.parameters?.get('end')?.setValueAtTime(0, 0);
+  node.stop?.(time);
+};
+
+export const cleanupNodes = (nodes, time) => {
+  nodes.forEach((n) => cleanupNode(n, time));
+};

From 7bc6fcbf2a56a8b0f12aed9d9c386fbe43dbfa6c Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 18:24:48 -0600
Subject: [PATCH 09/48] Add channel support to midi in

---
 packages/midi/midi.mjs                    | 34 +++++++++++++++++------
 test/__snapshots__/examples.test.mjs.snap | 21 ++++++++++++++
 2 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/packages/midi/midi.mjs b/packages/midi/midi.mjs
index 32f03012..0fee380c 100644
--- a/packages/midi/midi.mjs
+++ b/packages/midi/midi.mjs
@@ -479,14 +479,23 @@ Pattern.prototype.midi = function (midiport, options = {}) {
 
 let listeners = {};
 const refs = {};
+const refsByChan = {};
 
 /**
  * MIDI input: Opens a MIDI input port to receive MIDI control change messages.
+ *
+ * The output is a function that accepts a midi cc value to query as well as (optionally) a midi channel
  * @param {string | number} input MIDI device name or index defaulting to 0
- * @returns {Function}
+ * @returns {function(number, number=): function(): number} A function from (cc, channel?) to
+ *   the most recently received midi cc value through the input (normalized to 0 to 1)
  * @example
- * let cc = await midin('IAC Driver Bus 1')
+ * const cc = await midin('IAC Driver Bus 1')
  * note("c a f e").lpf(cc(0).range(0, 1000)).lpq(cc(1).range(0, 10)).sound("sawtooth")
+ * @example
+ * const allCC = await midin('IAC Driver Bus 1')
+ * const cc = (ccNum) => allCC(ccNum, 2) // just channel 2
+ * note("c a f e").s("saw")
+ *   .when(cc(0).gt(0), x => x.postgain(0))
  */
 export async function midin(input) {
   if (isPattern(input)) {
@@ -511,17 +520,24 @@ export async function midin(input) {
       }`,
     );
   }
-  // ensure refs for this input are initialized
-  if (!refs[input]) {
-    refs[input] = {};
-  }
-  const cc = (cc) => ref(() => refs[input][cc] || 0);
+  refs[input] ??= {};
+  refsByChan[input] ??= {};
+  const cc = (cc, chan) => {
+    if (chan !== undefined) {
+      return ref(() => refsByChan[input][cc]?.[chan] || 0);
+    }
+    return ref(() => refs[input][cc] || 0);
+  };
 
   listeners[input] && device.removeListener('midimessage', listeners[input]);
   listeners[input] = (e) => {
-    const cc = e.dataBytes[0];
+    const ccNum = e.dataBytes[0];
     const v = e.dataBytes[1];
-    refs[input] && (refs[input][cc] = v / 127);
+    const chan = e.message.channel;
+    const scaled = v / 127;
+    refsByChan[input][ccNum] ??= {};
+    refsByChan[input][ccNum][chan] = scaled;
+    refs[input][ccNum] = scaled;
   };
   device.addListener('midimessage', listeners[input]);
   return cc;
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 31e4bddd..783fee99 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -6533,6 +6533,27 @@ exports[`runs examples > example "midin" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "midin" example index 1 1`] = `
+[
+  "[ 0/1 → 1/4 | note:c s:saw ]",
+  "[ 1/4 → 1/2 | note:a s:saw ]",
+  "[ 1/2 → 3/4 | note:f s:saw ]",
+  "[ 3/4 → 1/1 | note:e s:saw ]",
+  "[ 1/1 → 5/4 | note:c s:saw ]",
+  "[ 5/4 → 3/2 | note:a s:saw ]",
+  "[ 3/2 → 7/4 | note:f s:saw ]",
+  "[ 7/4 → 2/1 | note:e s:saw ]",
+  "[ 2/1 → 9/4 | note:c s:saw ]",
+  "[ 9/4 → 5/2 | note:a s:saw ]",
+  "[ 5/2 → 11/4 | note:f s:saw ]",
+  "[ 11/4 → 3/1 | note:e s:saw ]",
+  "[ 3/1 → 13/4 | note:c s:saw ]",
+  "[ 13/4 → 7/2 | note:a s:saw ]",
+  "[ 7/2 → 15/4 | note:f s:saw ]",
+  "[ 15/4 → 4/1 | note:e s:saw ]",
+]
+`;
+
 exports[`runs examples > example "midiport" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:c midiport:0 ]",

From 020a6bc75fb1467a518c32c2d132298747693d8a Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 20:31:31 -0600
Subject: [PATCH 10/48] First pass at transient processor

---
 packages/core/controls.mjs       |  2 +
 packages/superdough/worklets.mjs | 70 ++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 809a45ab..80a244ef 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -2584,3 +2584,5 @@ export const scrub = register(
   },
   false,
 );
+
+export const { transient } = registerControl(['transient', 'transsustain', 'transattack']);
diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index bf633a63..334e2d82 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -11,6 +11,9 @@ const PI = Math.PI;
 const TWO_PI = 2 * PI;
 const INVSR = 1 / sampleRate;
 
+const timeToCoeff = (t) => Math.exp(-INVSR / t);
+const dbToLin = (db) => Math.pow(10, db / 20);
+
 const clamp = (num, min, max) => Math.min(Math.max(num, min), max);
 const mod = (n, m) => ((n % m) + m) % m;
 const lerp = (a, b, n) => n * (b - a) + a;
@@ -1383,3 +1386,70 @@ class WavetableOscillatorProcessor extends AudioWorkletProcessor {
 }
 
 registerProcessor('wavetable-oscillator-processor', WavetableOscillatorProcessor);
+
+class TransientProcessor extends AudioWorkletProcessor {
+  static get parameterDescriptors() {
+    return [];
+  }
+
+  constructor(options) {
+    super();
+    this.gainCoeff = timeToCoeff(0.2);
+    this.avgGain = 1;
+    let {
+      attackTime = 0.003,
+      sustainTime = 0.08,
+      attack = 0,
+      sustain = 0,
+      sensitivity = 0.1,
+      mix = 1,
+    } = options.processorOptions;
+    attackTime = clamp(attackTime, 0.0005, 0.05);
+    sustainTime = clamp(sustainTime, 0.01, 0.5);
+    this.attackCoeff = timeToCoeff(attackTime);
+    this.sustainCoeff = timeToCoeff(sustainTime);
+    this.attackAmt = clamp(attack, -1, 1);
+    this.sustainAmt = clamp(sustain, -1, 1);
+    this.scaling = 0.5 + 5 * clamp(sensitivity, 0, 1);
+    this.mix = clamp(mix, 0, 1);
+  }
+
+  process(inputs, outputs, _params) {
+    const input = inputs[0];
+    const output = outputs[0];
+    if (!input || !output) {
+      return true;
+    }
+    const channels = output.length;
+    this.attackEnv ??= new Float32Array(channels);
+    this.sustainEnv ??= new Float32Array(channels);
+    let avgGain = this.avgGain;
+    for (let ch = 0; ch < channels; ch++) {
+      const inCh = input[ch];
+      const outCh = output[ch];
+      let attEnv = this.attackEnv[ch];
+      let susEnv = this.sustainEnv[ch];
+      for (let i = 0; i < blockSize; i++) {
+        const x = Math.abs(inCh[i]);
+        attEnv = lerp(attEnv, x, this.attackCoeff);
+        susEnv = lerp(susEnv, x, this.sustainCoeff);
+        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
+        const attScale = Math.max(0, peakiness);
+        const susScale = Math.max(0, -peakiness);
+        const attackGain = dbToLin(this.attackAmt * attScale * 18); // max 18db
+        const sustainGain = dbToLin(this.sustainAmt * susScale * 36); // max 36db
+        const gain = clamp(attackGain * sustainGain, 0, 8);
+        avgGain = lerp(avgGain, gain, this.gainCoeff);
+        const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
+        const wet = x * gain * makeup;
+        outCh[i] = lerp(x, wet, this.mix);
+      }
+      this.attackEnv[ch] = attEnv;
+      this.sustainEnv[ch] = susEnv;
+    }
+    this.avgGain = avgGain;
+    return true;
+  }
+}
+
+registerProcessor('transient-processor', TransientProcessor);

From 68840de188622e302276aa7dd31f8c895e6c6887 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 20:58:28 -0600
Subject: [PATCH 11/48] Working version

---
 packages/superdough/superdough.mjs | 19 +++++++++++++++++++
 packages/superdough/worklets.mjs   | 13 ++++++-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 650f9c2c..acf6edef 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -451,6 +451,9 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     compressorKnee,
     compressorAttack,
     compressorRelease,
+    transient,
+    transsustain,
+    transattack,
   } = value;
 
   delaytime = delaytime ?? cycleToSeconds(delaysync, cps);
@@ -532,6 +535,22 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   chain.push(sourceNode);
   stretch !== undefined && chain.push(getWorklet(ac, 'phase-vocoder-processor', { pitchFactor: stretch }));
 
+  transient !== undefined &&
+    chain.push(
+      getWorklet(
+        ac,
+        'transient-processor',
+        {},
+        {
+          processorOptions: {
+            attack: transient,
+            sustain: transsustain,
+            attackTime: transattack,
+          },
+        },
+      ),
+    );
+
   // gain stage
   chain.push(gainNode(gain));
 
diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index 334e2d82..6af7dffc 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -11,7 +11,7 @@ const PI = Math.PI;
 const TWO_PI = 2 * PI;
 const INVSR = 1 / sampleRate;
 
-const timeToCoeff = (t) => Math.exp(-INVSR / t);
+const timeToCoeff = (t) => 1 - Math.exp(-INVSR / t);
 const dbToLin = (db) => Math.pow(10, db / 20);
 
 const clamp = (num, min, max) => Math.min(Math.max(num, min), max);
@@ -1420,17 +1420,16 @@ class TransientProcessor extends AudioWorkletProcessor {
     if (!input || !output) {
       return true;
     }
-    const channels = output.length;
+    const channels = input.length;
     this.attackEnv ??= new Float32Array(channels);
     this.sustainEnv ??= new Float32Array(channels);
     let avgGain = this.avgGain;
     for (let ch = 0; ch < channels; ch++) {
-      const inCh = input[ch];
-      const outCh = output[ch];
       let attEnv = this.attackEnv[ch];
       let susEnv = this.sustainEnv[ch];
-      for (let i = 0; i < blockSize; i++) {
-        const x = Math.abs(inCh[i]);
+      for (let n = 0; n < blockSize; n++) {
+        const sample = input[ch][n];
+        const x = Math.abs(sample);
         attEnv = lerp(attEnv, x, this.attackCoeff);
         susEnv = lerp(susEnv, x, this.sustainCoeff);
         const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
@@ -1442,7 +1441,7 @@ class TransientProcessor extends AudioWorkletProcessor {
         avgGain = lerp(avgGain, gain, this.gainCoeff);
         const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
         const wet = x * gain * makeup;
-        outCh[i] = lerp(x, wet, this.mix);
+        output[ch][n] = lerp(sample, wet, this.mix);
       }
       this.attackEnv[ch] = attEnv;
       this.sustainEnv[ch] = susEnv;

From df047fd48dbb4df27ca596f2ca085eeb2fb86c4d Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 22:28:10 -0600
Subject: [PATCH 12/48] Optimizations

---
 packages/core/controls.mjs         | 14 +++++++++++++-
 packages/superdough/superdough.mjs |  2 --
 packages/superdough/worklets.mjs   | 16 +++++++++++-----
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 80a244ef..bca7036a 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -2585,4 +2585,16 @@ export const scrub = register(
   false,
 );
 
-export const { transient } = registerControl(['transient', 'transsustain', 'transattack']);
+/**
+ * Transient shaper. Gives independent control over the emphasis on transients
+ * and sustains
+ *
+ * @name transient
+ * @param {number | Pattern} attack Emphasis on transients; between -1 (deaccentuate) and 1 (accentuate)
+ * @param {number | Pattern} sustain Emphasis on the sustains; between -1 (deaccentuate) and 1 (accentuate)
+ * @example
+ * s("bd").transient("<-1 -0.5 0 0.5 1>")
+ * @example
+ * s("hh*16").bank("tr909").transient("<-1:1 1:-1>")
+ */
+export const { transient } = registerControl(['transient', 'transsustain']);
diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index acf6edef..ac6ca732 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -453,7 +453,6 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     compressorRelease,
     transient,
     transsustain,
-    transattack,
   } = value;
 
   delaytime = delaytime ?? cycleToSeconds(delaysync, cps);
@@ -545,7 +544,6 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
           processorOptions: {
             attack: transient,
             sustain: transsustain,
-            attackTime: transattack,
           },
         },
       ),
diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index 6af7dffc..6b370166 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -1412,6 +1412,10 @@ class TransientProcessor extends AudioWorkletProcessor {
     this.sustainAmt = clamp(sustain, -1, 1);
     this.scaling = 0.5 + 5 * clamp(sensitivity, 0, 1);
     this.mix = clamp(mix, 0, 1);
+    const maxAttackDb = this.attackAmt * 6;
+    const maxSustainDb = this.sustainAmt * 36;
+    this.attackMaxGain = dbToLin(maxAttackDb) - 1; // increasing from 1
+    this.sustainMaxGain = dbToLin(maxSustainDb) - 1;
   }
 
   process(inputs, outputs, _params) {
@@ -1433,15 +1437,17 @@ class TransientProcessor extends AudioWorkletProcessor {
         attEnv = lerp(attEnv, x, this.attackCoeff);
         susEnv = lerp(susEnv, x, this.sustainCoeff);
         const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
-        const attScale = Math.max(0, peakiness);
-        const susScale = Math.max(0, -peakiness);
-        const attackGain = dbToLin(this.attackAmt * attScale * 18); // max 18db
-        const sustainGain = dbToLin(this.sustainAmt * susScale * 36); // max 36db
+        const attScale = peakiness > 0 ? peakiness : 0;
+        const susScale = peakiness < 0 ? -peakiness : 0;
+        const attackGain = 1 + attScale * this.attackMaxGain;
+        const sustainGain = 1 + susScale * this.sustainMaxGain;
         const gain = clamp(attackGain * sustainGain, 0, 8);
         avgGain = lerp(avgGain, gain, this.gainCoeff);
         const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
         const wet = x * gain * makeup;
-        output[ch][n] = lerp(sample, wet, this.mix);
+        let y = lerp(sample, wet, this.mix);
+        y /= (1 + Math.abs(y)); // soft clip
+        output[ch][n] = y;
       }
       this.attackEnv[ch] = attEnv;
       this.sustainEnv[ch] = susEnv;

From be36898803a59f201d3d3db4e79bf35a2cc53edb Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 22:29:33 -0600
Subject: [PATCH 13/48] Formatting and examples

---
 packages/superdough/worklets.mjs          |  2 +-
 test/__snapshots__/examples.test.mjs.snap | 78 +++++++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index 6b370166..e5dd0a0d 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -1446,7 +1446,7 @@ class TransientProcessor extends AudioWorkletProcessor {
         const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
         const wet = x * gain * makeup;
         let y = lerp(sample, wet, this.mix);
-        y /= (1 + Math.abs(y)); // soft clip
+        y /= 1 + Math.abs(y); // soft clip
         output[ch][n] = y;
       }
       this.attackEnv[ch] = attEnv;
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 31e4bddd..66777d5e 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -11410,6 +11410,84 @@ exports[`runs examples > example "tour" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "transient" example index 0 1`] = `
+[
+  "[ 0/1 → 1/1 | s:bd transient:-1 ]",
+  "[ 1/1 → 2/1 | s:bd transient:-0.5 ]",
+  "[ 2/1 → 3/1 | s:bd transient:0 ]",
+  "[ 3/1 → 4/1 | s:bd transient:0.5 ]",
+]
+`;
+
+exports[`runs examples > example "transient" example index 1 1`] = `
+[
+  "[ 0/1 → 1/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 1/16 → 1/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 1/8 → 3/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 3/16 → 1/4 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 1/4 → 5/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 5/16 → 3/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 3/8 → 7/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 7/16 → 1/2 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 1/2 → 9/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 9/16 → 5/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 5/8 → 11/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 11/16 → 3/4 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 3/4 → 13/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 13/16 → 7/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 7/8 → 15/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 15/16 → 1/1 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 1/1 → 17/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 17/16 → 9/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 9/8 → 19/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 19/16 → 5/4 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 5/4 → 21/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 21/16 → 11/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 11/8 → 23/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 23/16 → 3/2 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 3/2 → 25/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 25/16 → 13/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 13/8 → 27/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 27/16 → 7/4 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 7/4 → 29/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 29/16 → 15/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 15/8 → 31/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 31/16 → 2/1 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 2/1 → 33/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 33/16 → 17/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 17/8 → 35/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 35/16 → 9/4 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 9/4 → 37/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 37/16 → 19/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 19/8 → 39/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 39/16 → 5/2 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 5/2 → 41/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 41/16 → 21/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 21/8 → 43/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 43/16 → 11/4 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 11/4 → 45/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 45/16 → 23/8 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 23/8 → 47/16 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 47/16 → 3/1 | s:hh bank:tr909 transient:-1 transsustain:1 ]",
+  "[ 3/1 → 49/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 49/16 → 25/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 25/8 → 51/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 51/16 → 13/4 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 13/4 → 53/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 53/16 → 27/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 27/8 → 55/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 55/16 → 7/2 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 7/2 → 57/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 57/16 → 29/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 29/8 → 59/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 59/16 → 15/4 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 15/4 → 61/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 61/16 → 31/8 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 31/8 → 63/16 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+  "[ 63/16 → 4/1 | s:hh bank:tr909 transient:1 transsustain:-1 ]",
+]
+`;
+
 exports[`runs examples > example "transpose" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:C2 ]",

From 6c01c16a0cbd4dda8f4fe6081746824d79972701 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 22:39:21 -0600
Subject: [PATCH 14/48] Fix typo

---
 packages/superdough/worklets.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index e5dd0a0d..67d5e164 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -1436,7 +1436,7 @@ class TransientProcessor extends AudioWorkletProcessor {
         const x = Math.abs(sample);
         attEnv = lerp(attEnv, x, this.attackCoeff);
         susEnv = lerp(susEnv, x, this.sustainCoeff);
-        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
+        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1, 1);
         const attScale = peakiness > 0 ? peakiness : 0;
         const susScale = peakiness < 0 ? -peakiness : 0;
         const attackGain = 1 + attScale * this.attackMaxGain;
@@ -1444,7 +1444,7 @@ class TransientProcessor extends AudioWorkletProcessor {
         const gain = clamp(attackGain * sustainGain, 0, 8);
         avgGain = lerp(avgGain, gain, this.gainCoeff);
         const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
-        const wet = x * gain * makeup;
+        const wet = sample * gain * makeup;
         let y = lerp(sample, wet, this.mix);
         y /= 1 + Math.abs(y); // soft clip
         output[ch][n] = y;

From 36587ae74732fa69f58704b2a0f3a0ebfbf8e96a Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 23 Nov 2025 22:55:36 -0600
Subject: [PATCH 15/48] Switch back to original version

---
 packages/superdough/worklets.mjs | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index 67d5e164..d88e9dea 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -1412,10 +1412,6 @@ class TransientProcessor extends AudioWorkletProcessor {
     this.sustainAmt = clamp(sustain, -1, 1);
     this.scaling = 0.5 + 5 * clamp(sensitivity, 0, 1);
     this.mix = clamp(mix, 0, 1);
-    const maxAttackDb = this.attackAmt * 6;
-    const maxSustainDb = this.sustainAmt * 36;
-    this.attackMaxGain = dbToLin(maxAttackDb) - 1; // increasing from 1
-    this.sustainMaxGain = dbToLin(maxSustainDb) - 1;
   }
 
   process(inputs, outputs, _params) {
@@ -1436,11 +1432,11 @@ class TransientProcessor extends AudioWorkletProcessor {
         const x = Math.abs(sample);
         attEnv = lerp(attEnv, x, this.attackCoeff);
         susEnv = lerp(susEnv, x, this.sustainCoeff);
-        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1, 1);
+        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
         const attScale = peakiness > 0 ? peakiness : 0;
         const susScale = peakiness < 0 ? -peakiness : 0;
-        const attackGain = 1 + attScale * this.attackMaxGain;
-        const sustainGain = 1 + susScale * this.sustainMaxGain;
+        const attackGain = dbToLin(this.attackAmt * attScale * 18);
+        const sustainGain = dbToLin(this.sustainAmt * susScale * 36);
         const gain = clamp(attackGain * sustainGain, 0, 8);
         avgGain = lerp(avgGain, gain, this.gainCoeff);
         const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;

From a278f21f1b0a8923d3d454c0e0f0b70de828845b Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Mon, 24 Nov 2025 17:52:00 -0600
Subject: [PATCH 16/48] Allow register in autocomplete, add vel as synonym for
 velocity, fix some controls

---
 packages/core/controls.mjs | 20 +++++++++-----------
 packages/core/pattern.mjs  |  1 -
 2 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index a9d7cc26..a59b30d1 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -380,12 +380,13 @@ export const { accelerate } = registerControl('accelerate');
  * Sets the velocity from 0 to 1. Is multiplied together with gain.
  *
  * @name velocity
+ * @synonyms vel
  * @example
  * s("hh*8")
  * .gain(".4!2 1 .4!2 1 .4 1")
  * .velocity(".4 1")
  */
-export const { velocity } = registerControl('velocity');
+export const { velocity, vel } = registerControl('velocity', 'vel');
 /**
  * Controls the gain by an exponential amount.
  *
@@ -1323,14 +1324,13 @@ export const { lpdepth } = registerControl('lpdepth');
  * Depth of the LFO for the lowpass filter, in HZ
  *
  * @name lpdepthfrequency
- * @synonyms
- * lpdethfreq
+ * @synonyms lpdepthfreq
  * @param {number | Pattern} depth depth of modulation
  * @example
  * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).lpdepthfrequency("<200 500 100 0>")
  */
 
-export const { lpdepthfrequency } = registerControl('lpdepthfrequency', 'lpdepthfreq');
+export const { lpdepthfrequency, lpdepthfreq } = registerControl('lpdepthfrequency', 'lpdepthfreq');
 
 /**
  * Shape of the LFO for the lowpass filter
@@ -1384,14 +1384,13 @@ export const { bpdepth } = registerControl('bpdepth');
  * Depth of the LFO for the bandpass filter, in HZ
  *
  * @name bpdepthfrequency
- * @synonyms
- * bpdethfreq
+ * @synonyms bpdepthfreq
  * @param {number | Pattern} depth depth of modulation
  * @example
  * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).bpdepthfrequency("<200 500 100 0>")
  */
 
-export const { bpdepthfrequency } = registerControl('bpdepthfrequency', 'bpdepthfreq');
+export const { bpdepthfrequency, bpdepthfreq } = registerControl('bpdepthfrequency', 'bpdepthfreq');
 
 /**
  * Shape of the LFO for the bandpass filter
@@ -1439,20 +1438,19 @@ export const { hpsync } = registerControl('hpsync');
  * @name hpdepth
  * @param {number | Pattern} depth depth of modulation
  */
-export const { hpdepth, hpdepthfreq } = registerControl('hpdepth');
+export const { hpdepth } = registerControl('hpdepth');
 
 /**
  * Depth of the LFO for the hipass filter, in hz
  *
  * @name hpdepthfrequency
- * @synonyms
- * hpdethfreq
+ * @synonyms hpdepthfreq
  * @param {number | Pattern} depth depth of modulation
  * @example
  * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).hpdepthfrequency("<200 500 100 0>")
  */
 
-export const { hpdepthfrequency } = registerControl('hpdepthfrequency', 'hpdepthfreq');
+export const { hpdepthfrequency, hpdepthfreq } = registerControl('hpdepthfrequency', 'hpdepthfreq');
 
 /**
  * Shape of the LFO for the highpass filter
diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 4737f0db..01a7efbd 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -1587,7 +1587,6 @@ export const func = curry((a, b) => reify(b).func(a));
  *
  * @param {string | string[]} name name of the function, or an array of names to be used as synonyms
  * @param {function} func function with 1 or more params, where last is the current pattern
- * @noAutocomplete
  *
  */
 export function register(name, func, patternify = true, preserveSteps = false, join = (x) => x.innerJoin()) {

From d7afb8a6c097de11a34fdde58a9f976e38a3ba18 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Mon, 24 Nov 2025 18:01:20 -0600
Subject: [PATCH 17/48] Add register example

---
 packages/core/pattern.mjs                 |  7 +++++
 test/__snapshots__/examples.test.mjs.snap | 37 +++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 01a7efbd..4753ebfd 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -1587,6 +1587,13 @@ export const func = curry((a, b) => reify(b).func(a));
  *
  * @param {string | string[]} name name of the function, or an array of names to be used as synonyms
  * @param {function} func function with 1 or more params, where last is the current pattern
+ * @param {bool} patternify defaults to true; if set to false, you will have more control over the arguments to `func` as they will be
+ *   in their raw form and it will be up to you to patternify them and/or query them for values
+ * @example
+ * const vlpf = register('vlpf', (freq, pat) => {
+ *   return pat.fmap((v) => ({...v, cutoff: freq * (v.velocity ?? 1) }));
+ * })
+ * s("saw").seg(8).velocity(rand).vlpf(800)
  *
  */
 export function register(name, func, patternify = true, preserveSteps = false, join = (x) => x.innerJoin()) {
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 8cbee39d..db1b6228 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -9064,6 +9064,43 @@ exports[`runs examples > example "ratio" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "register" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | s:saw velocity:0 cutoff:0 ]",
+  "[ 1/8 → 1/4 | s:saw velocity:0.6852155700325966 cutoff:548.1724560260773 ]",
+  "[ 1/4 → 3/8 | s:saw velocity:0.36975969187915325 cutoff:295.8077535033226 ]",
+  "[ 3/8 → 1/2 | s:saw velocity:0.40139251574873924 cutoff:321.1140125989914 ]",
+  "[ 1/2 → 5/8 | s:saw velocity:0.2604806162416935 cutoff:208.3844929933548 ]",
+  "[ 5/8 → 3/4 | s:saw velocity:0.1356358677148819 cutoff:108.50869417190552 ]",
+  "[ 3/4 → 7/8 | s:saw velocity:0.19582648016512394 cutoff:156.66118413209915 ]",
+  "[ 7/8 → 1/1 | s:saw velocity:0.3976310808211565 cutoff:318.1048646569252 ]",
+  "[ 1/1 → 9/8 | s:saw velocity:0.5195421651005745 cutoff:415.6337320804596 ]",
+  "[ 9/8 → 5/4 | s:saw velocity:0.6724895145744085 cutoff:537.9916116595268 ]",
+  "[ 5/4 → 11/8 | s:saw velocity:0.7287282031029463 cutoff:582.982562482357 ]",
+  "[ 11/8 → 3/2 | s:saw velocity:0.18280375190079212 cutoff:146.2430015206337 ]",
+  "[ 3/2 → 13/8 | s:saw velocity:0.6084080748260021 cutoff:486.7264598608017 ]",
+  "[ 13/8 → 7/4 | s:saw velocity:0.49675471149384975 cutoff:397.4037691950798 ]",
+  "[ 7/4 → 15/8 | s:saw velocity:0.20473789609968662 cutoff:163.7903168797493 ]",
+  "[ 15/8 → 2/1 | s:saw velocity:0.5945571791380644 cutoff:475.6457433104515 ]",
+  "[ 2/1 → 17/8 | s:saw velocity:0.9595271199941635 cutoff:767.6216959953308 ]",
+  "[ 17/8 → 9/4 | s:saw velocity:0.9033902939409018 cutoff:722.7122351527214 ]",
+  "[ 9/4 → 19/8 | s:saw velocity:0.34548251144587994 cutoff:276.38600915670395 ]",
+  "[ 19/8 → 5/2 | s:saw velocity:0.8365066405385733 cutoff:669.2053124308586 ]",
+  "[ 5/2 → 21/8 | s:saw velocity:0.45861607417464256 cutoff:366.89285933971405 ]",
+  "[ 21/8 → 11/4 | s:saw velocity:0.16019348427653313 cutoff:128.1547874212265 ]",
+  "[ 11/4 → 23/8 | s:saw velocity:0.6332327704876661 cutoff:506.5862163901329 ]",
+  "[ 23/8 → 3/1 | s:saw velocity:0.01625417172908783 cutoff:13.003337383270264 ]",
+  "[ 3/1 → 25/8 | s:saw velocity:0.21728911064565182 cutoff:173.83128851652145 ]",
+  "[ 25/8 → 13/4 | s:saw velocity:0.34324387833476067 cutoff:274.59510266780853 ]",
+  "[ 13/4 → 27/8 | s:saw velocity:0.9923650715500116 cutoff:793.8920572400093 ]",
+  "[ 27/8 → 7/2 | s:saw velocity:0.40869180113077164 cutoff:326.9534409046173 ]",
+  "[ 7/2 → 29/8 | s:saw velocity:0.40994881466031075 cutoff:327.9590517282486 ]",
+  "[ 29/8 → 15/4 | s:saw velocity:0.9391485787928104 cutoff:751.3188630342484 ]",
+  "[ 15/4 → 31/8 | s:saw velocity:0.8121673222631216 cutoff:649.7338578104973 ]",
+  "[ 31/8 → 4/1 | s:saw velocity:0.7361665386706591 cutoff:588.9332309365273 ]",
+]
+`;
+
 exports[`runs examples > example "release" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:c3 release:0 ]",

From 7e5a907ce57210783375268e76b482b31835c1bb Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Mon, 24 Nov 2025 18:41:25 -0600
Subject: [PATCH 18/48] Add a few more functions to autocomplete

---
 packages/core/pattern.mjs                 |  27 ++++-
 test/__snapshots__/examples.test.mjs.snap | 133 ++++++++++++++++++++++
 2 files changed, 155 insertions(+), 5 deletions(-)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 4753ebfd..14b2b11e 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -574,7 +574,8 @@ export class Pattern {
    * Returns a new Pattern, which only returns haps that meet the given test.
    * @param {Function} hap_test - a function which returns false for haps to be removed from the pattern
    * @returns Pattern
-   * @noAutocomplete
+   * @example
+   * s("bd*8").velocity(rand).filterHaps((h) => (h.whole.begin % 1) < h.value.velocity)
    */
   filterHaps(hap_test) {
     return new Pattern((state) => this.query(state).filter(hap_test));
@@ -585,12 +586,22 @@ export class Pattern {
    * inside haps.
    * @param {Function} value_test
    * @returns Pattern
-   * @noAutocomplete
+   * @synonyms filtval
+   * @example
+   * const drums = s("bd sd bd sd")
+   * kick: drums.filterValues((v) => v.s === 'bd').duck(2)
+   * snare: drums.filterValues((v) => v.s === 'sd')
+   * bass: s("saw!4").note("G#1").lpf(80).lpenv(4).orbit(2)
    */
   filterValues(value_test) {
     return new Pattern((state) => this.query(state).filter((hap) => value_test(hap.value))).setSteps(this._steps);
   }
 
+  // synonym
+  filtval(value_test) {
+    this.filterValues(value_test);
+  }
+
   /**
    * Returns a new pattern, with haps containing undefined values removed from
    * query results.
@@ -2665,8 +2676,13 @@ export const hsl = register('hsl', (h, s, l, pat) => {
 /**
  * Tags each Hap with an identifier. Good for filtering. The function populates Hap.context.tags (Array).
  * @name tag
- * @noAutocomplete
  * @param {string} tag anything unique
+ * @example
+ * s("saw!16").note("F1")
+ *   .lpf(tri.range(40, 80).slow(4)).lpenv(5).lpq(4).lpd(0.15)
+ *   .when(rand.late(0.1).gte(0.5), x => x.transpose("12").tag('altered'))
+ *   .when(rand.late(0.2).gte(0.5), x => x.s("square").tag('altered'))
+ *   .when("<0 1>", x => x.filter((hap) => hap.hasTag('altered')))
  */
 Pattern.prototype.tag = function (tag) {
   return this.withContext((ctx) => ({ ...ctx, tags: (ctx.tags || []).concat([tag]) }));
@@ -2677,15 +2693,16 @@ Pattern.prototype.tag = function (tag) {
  * @name filter
  * @param {Function} test function to test Hap
  * @example
- * s("hh!7 oh").filter(hap => hap.value.s==='hh')
+ * s("hh!7 oh").filter(hap => hap.value.s === 'hh')
  */
 export const filter = register('filter', (test, pat) => pat.withHaps((haps) => haps.filter(test)));
 
 /**
  * Filters haps by their begin time
  * @name filterWhen
- * @noAutocomplete
  * @param {Function} test function to test Hap.whole.begin
+ * @example
+ * oneCycle: s("bd*4").filterWhen((t) => t < 1)
  */
 export const filterWhen = register('filterWhen', (test, pat) => pat.filter((h) => test(h.whole.begin)));
 
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index db1b6228..68eae824 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -4043,6 +4043,70 @@ exports[`runs examples > example "filter" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "filterHaps" example index 0 1`] = `
+[
+  "[ 1/8 → 1/4 | s:bd velocity:0.6852155700325966 ]",
+  "[ 1/4 → 3/8 | s:bd velocity:0.36975969187915325 ]",
+  "[ 3/8 → 1/2 | s:bd velocity:0.40139251574873924 ]",
+  "[ 1/1 → 9/8 | s:bd velocity:0.5195421651005745 ]",
+  "[ 9/8 → 5/4 | s:bd velocity:0.6724895145744085 ]",
+  "[ 5/4 → 11/8 | s:bd velocity:0.7287282031029463 ]",
+  "[ 3/2 → 13/8 | s:bd velocity:0.6084080748260021 ]",
+  "[ 2/1 → 17/8 | s:bd velocity:0.9595271199941635 ]",
+  "[ 17/8 → 9/4 | s:bd velocity:0.9033902939409018 ]",
+  "[ 9/4 → 19/8 | s:bd velocity:0.34548251144587994 ]",
+  "[ 19/8 → 5/2 | s:bd velocity:0.8365066405385733 ]",
+  "[ 3/1 → 25/8 | s:bd velocity:0.21728911064565182 ]",
+  "[ 25/8 → 13/4 | s:bd velocity:0.34324387833476067 ]",
+  "[ 13/4 → 27/8 | s:bd velocity:0.9923650715500116 ]",
+  "[ 27/8 → 7/2 | s:bd velocity:0.40869180113077164 ]",
+  "[ 29/8 → 15/4 | s:bd velocity:0.9391485787928104 ]",
+  "[ 15/4 → 31/8 | s:bd velocity:0.8121673222631216 ]",
+]
+`;
+
+exports[`runs examples > example "filterValues" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 1/4 → 1/2 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 1/2 → 3/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 3/4 → 1/1 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 1/1 → 5/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 5/4 → 3/2 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 3/2 → 7/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 7/4 → 2/1 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 2/1 → 9/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 9/4 → 5/2 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 5/2 → 11/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 11/4 → 3/1 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 3/1 → 13/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 13/4 → 7/2 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 7/2 → 15/4 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+  "[ 15/4 → 4/1 | s:saw note:G#1 cutoff:80 lpenv:4 orbit:2 ]",
+]
+`;
+
+exports[`runs examples > example "filterWhen" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:bd ]",
+  "[ 1/4 → 1/2 | s:bd ]",
+  "[ 1/2 → 3/4 | s:bd ]",
+  "[ 3/4 → 1/1 | s:bd ]",
+  "[ 1/1 → 5/4 | s:bd ]",
+  "[ 5/4 → 3/2 | s:bd ]",
+  "[ 3/2 → 7/4 | s:bd ]",
+  "[ 7/4 → 2/1 | s:bd ]",
+  "[ 2/1 → 9/4 | s:bd ]",
+  "[ 9/4 → 5/2 | s:bd ]",
+  "[ 5/2 → 11/4 | s:bd ]",
+  "[ 11/4 → 3/1 | s:bd ]",
+  "[ 3/1 → 13/4 | s:bd ]",
+  "[ 13/4 → 7/2 | s:bd ]",
+  "[ 7/2 → 15/4 | s:bd ]",
+  "[ 15/4 → 4/1 | s:bd ]",
+]
+`;
+
 exports[`runs examples > example "firstOf" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:g3 ]",
@@ -11749,6 +11813,75 @@ exports[`runs examples > example "sysexid" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "tag" example index 0 1`] = `
+[
+  "[ 0/1 → 1/16 | s:square note:F1 cutoff:40 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 1/16 → 1/8 | s:square note:F1 cutoff:41.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 1/8 → 3/16 | s:square note:F1 cutoff:42.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 3/16 → 1/4 | s:square note:F1 cutoff:43.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 1/4 → 5/16 | s:square note:F1 cutoff:45 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 5/16 → 3/8 | s:square note:F1 cutoff:46.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 3/8 → 7/16 | s:square note:F1 cutoff:47.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 7/16 → 1/2 | s:square note:F1 cutoff:48.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 1/2 → 9/16 | s:square note:F1 cutoff:50 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 9/16 → 5/8 | s:square note:F1 cutoff:51.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 5/8 → 11/16 | s:square note:F1 cutoff:52.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 11/16 → 3/4 | s:square note:F1 cutoff:53.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 3/4 → 13/16 | s:square note:F1 cutoff:55 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 13/16 → 7/8 | s:square note:F1 cutoff:56.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 7/8 → 15/16 | s:square note:F1 cutoff:57.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 15/16 → 1/1 | s:square note:F1 cutoff:58.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 1/1 → 17/16 | s:saw note:F2 cutoff:60 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 17/16 → 9/8 | s:saw note:F2 cutoff:61.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 9/8 → 19/16 | s:saw note:F2 cutoff:62.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 19/16 → 5/4 | s:saw note:F2 cutoff:63.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 5/4 → 21/16 | s:saw note:F2 cutoff:65 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 21/16 → 11/8 | s:saw note:F2 cutoff:66.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 11/8 → 23/16 | s:saw note:F2 cutoff:67.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 23/16 → 3/2 | s:saw note:F2 cutoff:68.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 3/2 → 25/16 | s:saw note:F2 cutoff:70 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 25/16 → 13/8 | s:saw note:F2 cutoff:71.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 13/8 → 27/16 | s:saw note:F2 cutoff:72.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 27/16 → 7/4 | s:saw note:F2 cutoff:73.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 7/4 → 29/16 | s:saw note:F2 cutoff:75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 29/16 → 15/8 | s:saw note:F2 cutoff:76.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 15/8 → 31/16 | s:saw note:F2 cutoff:77.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 31/16 → 2/1 | s:saw note:F2 cutoff:78.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 2/1 → 33/16 | s:saw note:F1 cutoff:80 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 33/16 → 17/8 | s:saw note:F1 cutoff:78.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 17/8 → 35/16 | s:saw note:F1 cutoff:77.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 35/16 → 9/4 | s:saw note:F1 cutoff:76.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 9/4 → 37/16 | s:saw note:F1 cutoff:75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 37/16 → 19/8 | s:saw note:F1 cutoff:73.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 19/8 → 39/16 | s:saw note:F1 cutoff:72.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 39/16 → 5/2 | s:saw note:F1 cutoff:71.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 5/2 → 41/16 | s:saw note:F1 cutoff:70 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 41/16 → 21/8 | s:saw note:F1 cutoff:68.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 21/8 → 43/16 | s:saw note:F1 cutoff:67.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 43/16 → 11/4 | s:saw note:F1 cutoff:66.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 11/4 → 45/16 | s:saw note:F1 cutoff:65 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 45/16 → 23/8 | s:saw note:F1 cutoff:63.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 23/8 → 47/16 | s:saw note:F1 cutoff:62.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 47/16 → 3/1 | s:saw note:F1 cutoff:61.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 3/1 → 49/16 | s:square note:F1 cutoff:60 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 49/16 → 25/8 | s:square note:F1 cutoff:58.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 25/8 → 51/16 | s:square note:F1 cutoff:57.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 51/16 → 13/4 | s:square note:F1 cutoff:56.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 13/4 → 53/16 | s:square note:F1 cutoff:55 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 53/16 → 27/8 | s:square note:F1 cutoff:53.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 27/8 → 55/16 | s:square note:F1 cutoff:52.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 55/16 → 7/2 | s:square note:F1 cutoff:51.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 7/2 → 57/16 | s:square note:F1 cutoff:50 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 57/16 → 29/8 | s:square note:F1 cutoff:48.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 29/8 → 59/16 | s:square note:F1 cutoff:47.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 59/16 → 15/4 | s:square note:F1 cutoff:46.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 15/4 → 61/16 | s:square note:F1 cutoff:45 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 61/16 → 31/8 | s:square note:F1 cutoff:43.75 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 31/8 → 63/16 | s:square note:F1 cutoff:42.5 lpenv:5 resonance:4 lpdecay:0.15 ]",
+  "[ 63/16 → 4/1 | s:square note:F1 cutoff:41.25 lpenv:5 resonance:4 lpdecay:0.15 ]",
+]
+`;
+
 exports[`runs examples > example "take" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd ]",

From 39e7f700791bc92b3949a1ca721e64d002f94842 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Mon, 24 Nov 2025 18:43:47 -0600
Subject: [PATCH 19/48] Remove synonym

---
 packages/core/pattern.mjs | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 14b2b11e..9f5929a6 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -586,7 +586,6 @@ export class Pattern {
    * inside haps.
    * @param {Function} value_test
    * @returns Pattern
-   * @synonyms filtval
    * @example
    * const drums = s("bd sd bd sd")
    * kick: drums.filterValues((v) => v.s === 'bd').duck(2)
@@ -597,11 +596,6 @@ export class Pattern {
     return new Pattern((state) => this.query(state).filter((hap) => value_test(hap.value))).setSteps(this._steps);
   }
 
-  // synonym
-  filtval(value_test) {
-    this.filterValues(value_test);
-  }
-
   /**
    * Returns a new pattern, with haps containing undefined values removed from
    * query results.

From d65b908bda4784975ae8cc57f23562a68798dc2a Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Tue, 25 Nov 2025 17:27:37 -0600
Subject: [PATCH 20/48] Disconnect lfos for phaser and filters

---
 packages/superdough/helpers.mjs    |  5 +++--
 packages/superdough/superdough.mjs | 35 ++++++++++++++++++++----------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index baa4db25..ed2c0c44 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -240,6 +240,7 @@ export function createFilter(context, start, end, params, cps, cycle) {
     rate = cps * sync;
   }
   const hasLFO = [depth, depthfrequency, skew, shape, rate].some((v) => v !== undefined);
+  let lfo;
   if (hasLFO) {
     depth = depth ?? 1;
     const time = cycle / cps;
@@ -255,10 +256,10 @@ export function createFilter(context, start, end, params, cps, cycle) {
       time,
       curve: 1,
     };
-    getParamLfo(context, frequencyParam, start, end, lfoValues);
+    lfo = getParamLfo(context, frequencyParam, start, end, lfoValues);
   }
 
-  return filter;
+  return { filter, lfo };
 }
 
 // stays 1 until .5, then fades out
diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 0db41c08..110f2b31 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -287,7 +287,7 @@ export function connectToDestination(input, channels) {
 
 function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000, sweep = 2000) {
   const ac = getAudioContext();
-  const lfoGain = getLfo(ac, time, end, { frequency, depth: sweep * 2 });
+  const lfo = getLfo(ac, time, end, { frequency, depth: sweep * 2 });
 
   //filters
   const numStages = 2; //num of filters in series
@@ -300,14 +300,14 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
     filter.frequency.value = centerFrequency + fOffset;
     filter.Q.value = 2 - Math.min(Math.max(depth * 2, 0), 1.9);
 
-    lfoGain.connect(filter.detune);
+    lfo.connect(filter.detune);
     fOffset += 282;
     if (i > 0) {
       filterChain[i - 1].connect(filter);
     }
     filterChain.push(filter);
   }
-  return filterChain[filterChain.length - 1];
+  return { filter: filterChain[filterChain.length - 1], lfo };
 }
 
 function getFilterType(ftype) {
@@ -561,9 +561,13 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     const lpParams = pickAndRename(value, lpMap);
     lpParams.type = 'lowpass';
     let lp = () => createFilter(ac, t, end, lpParams, cps, cycle);
-    chain.push(lp());
+    const { filter: lpf1, lfo: lfo1 } = lp();
+    chain.push(lpf1);
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
-      chain.push(lp());
+      const { filter: lpf2, lfo: lfo2 } = lp();
+      chain.push(lpf2);
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 
@@ -590,9 +594,13 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     const hpParams = pickAndRename(value, hpMap);
     hpParams.type = 'highpass';
     let hp = () => createFilter(ac, t, end, hpParams, cps, cycle);
-    chain.push(hp());
+    const { filter: hpf1, lfo: lfo1 } = hp();
+    chain.push(hpf1);
+    lfo1 && audioNodes.push(lfo1)
     if (ftype === '24db') {
-      chain.push(hp());
+      const { filter: hpf2, lfo: lfo2 } = hp();
+      chain.push(hpf2);
+      lfo2 && audioNodes.push(lfo2)
     }
   }
 
@@ -619,9 +627,13 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     const bpParams = pickAndRename(value, bpMap);
     bpParams.type = 'bandpass';
     let bp = () => createFilter(ac, t, end, bpParams, cps, cycle);
-    chain.push(bp());
+    const { filter: bpf1, lfo: lfo1 } = bp();
+    chain.push(bpf1);
+    lfo1 && audioNodes.push(lfo1)
     if (ftype === '24db') {
-      chain.push(bp());
+      const { filter: bpf2, lfo: lfo2 } = hp();
+      chain.push(bpf2);
+      lfo2 && audioNodes.push(lfo2)
     }
   }
 
@@ -685,8 +697,9 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   }
   // phaser
   if (phaser !== undefined && phaserdepth > 0) {
-    const phaserFX = getPhaser(t, endWithRelease, phaser, phaserdepth, phasercenter, phasersweep);
-    chain.push(phaserFX);
+    const { phaser, lfo } = getPhaser(t, endWithRelease, phaser, phaserdepth, phasercenter, phasersweep);
+    audioNodes.push(lfo);
+    chain.push(phaser);
   }
 
   // last gain

From 692359309f211cda7b5dd26a6cd20c208a6090b7 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Tue, 25 Nov 2025 17:31:11 -0600
Subject: [PATCH 21/48] Typo and formatting

---
 packages/superdough/superdough.mjs | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 110f2b31..5a8b7280 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -596,11 +596,11 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     let hp = () => createFilter(ac, t, end, hpParams, cps, cycle);
     const { filter: hpf1, lfo: lfo1 } = hp();
     chain.push(hpf1);
-    lfo1 && audioNodes.push(lfo1)
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
       const { filter: hpf2, lfo: lfo2 } = hp();
       chain.push(hpf2);
-      lfo2 && audioNodes.push(lfo2)
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 
@@ -629,11 +629,11 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     let bp = () => createFilter(ac, t, end, bpParams, cps, cycle);
     const { filter: bpf1, lfo: lfo1 } = bp();
     chain.push(bpf1);
-    lfo1 && audioNodes.push(lfo1)
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
-      const { filter: bpf2, lfo: lfo2 } = hp();
+      const { filter: bpf2, lfo: lfo2 } = bp();
       chain.push(bpf2);
-      lfo2 && audioNodes.push(lfo2)
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 

From f4b1baac878d99af91916fe27174f8b268320b33 Mon Sep 17 00:00:00 2001
From: Alex McLean <alex@slab.org>
Date: Thu, 27 Nov 2025 15:34:18 +0000
Subject: [PATCH 22/48] add revv() for reversing whole patterns

---
 packages/core/pattern.mjs                 | 19 ++++++++++++++++++-
 packages/core/test/pattern.test.mjs       | 12 ++++++++++++
 test/__snapshots__/examples.test.mjs.snap | 13 +++++++++++++
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 4737f0db..9a9ffe98 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -2234,7 +2234,7 @@ export const brak = register('brak', function (pat) {
 });
 
 /**
- * Reverse all haps in a pattern
+ * Reverse all cycles in a pattern. See also `revv` for reversing a whole pattern.
  *
  * @name rev
  * @memberof Pattern
@@ -2266,6 +2266,23 @@ export const rev = register(
   true,
 );
 
+/**
+ * Reverse a whole pattern. See also `revv` for reversing each cycle.
+ *
+ * @name rev
+ * @memberof Pattern
+ * @returns Pattern
+ * @example
+ * // This is the same as `<[g e] [d c]>`. If `rev()` is used, you get
+ * // the same as `<[d c] [g e]>`, where each cycle reverses, but the order of
+ * // cycles stays the same.
+ * note("<[c d] [e g]>").revv()
+ */
+export const revv = register('revv', function (pat) {
+  const negateSpan = (span) => new TimeSpan(Fraction(0).sub(span.end), Fraction(0).sub(span.begin));
+  return pat.withQuerySpan(negateSpan).withHapSpan(negateSpan);
+});
+
 /** Like press, but allows you to specify the amount by which each
  * event is shifted. pressBy(0.5) is the same as press, while
  * pressBy(1/3) shifts each event by a third of its timespan.
diff --git a/packages/core/test/pattern.test.mjs b/packages/core/test/pattern.test.mjs
index 1df5c877..408ff274 100644
--- a/packages/core/test/pattern.test.mjs
+++ b/packages/core/test/pattern.test.mjs
@@ -586,6 +586,18 @@ describe('Pattern', () => {
           .map((a) => a.value),
       ).toStrictEqual(['c', 'b', 'a']);
     });
+    it('Does not reverse the order of cycles', () => {
+      expect(fastcat('a', 'b', 'c', 'd').slow(2).rev().fast(2).sortHapsByPart().firstCycle()).toStrictEqual(
+        fastcat('b', 'a', 'd', 'c').firstCycle(),
+      );
+    });
+  });
+  describe('revv()', () => {
+    it('Does reverse the order of cycles', () => {
+      expect(fastcat('a', 'b', 'c', 'd').slow(2).revv().fast(2).sortHapsByPart().firstCycle()).toStrictEqual(
+        fastcat('d', 'c', 'b', 'a').firstCycle(),
+      );
+    });
   });
   describe('sequence()', () => {
     it('Can work like fastcat', () => {
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 4fc037b1..064f4c2d 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -9256,6 +9256,19 @@ exports[`runs examples > example "rev" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "rev" example index 0 2`] = `
+[
+  "[ 0/1 → 1/2 | note:g ]",
+  "[ 1/2 → 1/1 | note:e ]",
+  "[ 1/1 → 3/2 | note:d ]",
+  "[ 3/2 → 2/1 | note:c ]",
+  "[ 2/1 → 5/2 | note:g ]",
+  "[ 5/2 → 3/1 | note:e ]",
+  "[ 3/1 → 7/2 | note:d ]",
+  "[ 7/2 → 4/1 | note:c ]",
+]
+`;
+
 exports[`runs examples > example "ribbon" example index 0 1`] = `
 [
   "[ 0/1 → 1/1 | note:d ]",

From a6008e270097f28e012baaa97b2c8e21bb82f944 Mon Sep 17 00:00:00 2001
From: ndr0n <esquilofreniko@gmail.com>
Date: Fri, 28 Nov 2025 04:03:48 +0000
Subject: [PATCH 23/48] added export to getSuperdoughAudioController() so that
 its possible to route superdough audio on external application integrations.

---
 packages/superdough/superdough.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 0db41c08..5e9bb59d 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -274,7 +274,7 @@ export async function initAudioOnFirstClick(options) {
 }
 
 let controller;
-function getSuperdoughAudioController() {
+export function getSuperdoughAudioController() {
   if (controller == null) {
     controller = new SuperdoughAudioController(getAudioContext());
   }

From 18dc4944bffff559fe686395eb487731088ed2e5 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Fri, 28 Nov 2025 12:36:23 -0600
Subject: [PATCH 24/48] Typos and cleanup

---
 packages/superdough/superdough.mjs | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 5a8b7280..f54689ac 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -307,7 +307,7 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
     }
     filterChain.push(filter);
   }
-  return { filter: filterChain[filterChain.length - 1], lfo };
+  return { phaser: filterChain[filterChain.length - 1], lfo };
 }
 
 function getFilterType(ftype) {
@@ -413,7 +413,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     release = 0,
 
     //phaser
-    phaserrate: phaser,
+    phaserrate,
     phaserdepth = getDefaultValue('phaserdepth'),
     phasersweep,
     phasercenter,
@@ -560,7 +560,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     };
     const lpParams = pickAndRename(value, lpMap);
     lpParams.type = 'lowpass';
-    let lp = () => createFilter(ac, t, end, lpParams, cps, cycle);
+    const lp = () => createFilter(ac, t, end, lpParams, cps, cycle);
     const { filter: lpf1, lfo: lfo1 } = lp();
     chain.push(lpf1);
     lfo1 && audioNodes.push(lfo1);
@@ -593,7 +593,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     };
     const hpParams = pickAndRename(value, hpMap);
     hpParams.type = 'highpass';
-    let hp = () => createFilter(ac, t, end, hpParams, cps, cycle);
+    const hp = () => createFilter(ac, t, end, hpParams, cps, cycle);
     const { filter: hpf1, lfo: lfo1 } = hp();
     chain.push(hpf1);
     lfo1 && audioNodes.push(lfo1);
@@ -626,7 +626,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     };
     const bpParams = pickAndRename(value, bpMap);
     bpParams.type = 'bandpass';
-    let bp = () => createFilter(ac, t, end, bpParams, cps, cycle);
+    const bp = () => createFilter(ac, t, end, bpParams, cps, cycle);
     const { filter: bpf1, lfo: lfo1 } = bp();
     chain.push(bpf1);
     lfo1 && audioNodes.push(lfo1);
@@ -696,8 +696,8 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     chain.push(panner);
   }
   // phaser
-  if (phaser !== undefined && phaserdepth > 0) {
-    const { phaser, lfo } = getPhaser(t, endWithRelease, phaser, phaserdepth, phasercenter, phasersweep);
+  if (phaserrate !== undefined && phaserdepth > 0) {
+    const { phaser, lfo } = getPhaser(t, endWithRelease, phaserrate, phaserdepth, phasercenter, phasersweep);
     audioNodes.push(lfo);
     chain.push(phaser);
   }

From cb591815edb75dcd0d52f0ef8f63f211b1c22dad Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Fri, 28 Nov 2025 21:35:35 +0000
Subject: [PATCH 25/48] fix copy paste errors

---
 packages/core/pattern.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 9a9ffe98..88a0993c 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -2267,9 +2267,9 @@ export const rev = register(
 );
 
 /**
- * Reverse a whole pattern. See also `revv` for reversing each cycle.
+ * Reverse a whole pattern. See also `rev` for reversing each cycle.
  *
- * @name rev
+ * @name revv
  * @memberof Pattern
  * @returns Pattern
  * @example

From 956598da18fbfd66256fbcb18e1225c31e32af30 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Fri, 28 Nov 2025 22:03:21 +0000
Subject: [PATCH 26/48] snapshot

---
 test/__snapshots__/examples.test.mjs.snap | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 064f4c2d..e4b46b97 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -9256,7 +9256,7 @@ exports[`runs examples > example "rev" example index 0 1`] = `
 ]
 `;
 
-exports[`runs examples > example "rev" example index 0 2`] = `
+exports[`runs examples > example "revv" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | note:g ]",
   "[ 1/2 → 1/1 | note:e ]",

From b65cc2128feabf0a5909e652fe59058303aadbf1 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Sat, 29 Nov 2025 14:47:03 +0000
Subject: [PATCH 27/48] [perf] fix phaser leak of unused biquads

---
 packages/superdough/superdough.mjs | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 6f610d51..514c492c 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -290,7 +290,7 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
   const lfo = getLfo(ac, time, end, { frequency, depth: sweep * 2 });
 
   //filters
-  const numStages = 2; //num of filters in series
+  const numStages = 1; //num of filters in series
   let fOffset = 0;
   const filterChain = [];
   for (let i = 0; i < numStages; i++) {
@@ -302,12 +302,9 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
 
     lfo.connect(filter.detune);
     fOffset += 282;
-    if (i > 0) {
-      filterChain[i - 1].connect(filter);
-    }
     filterChain.push(filter);
   }
-  return { phaser: filterChain[filterChain.length - 1], lfo };
+  return { phaser: filterChain, lfo };
 }
 
 function getFilterType(ftype) {
@@ -699,7 +696,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   if (phaserrate !== undefined && phaserdepth > 0) {
     const { phaser, lfo } = getPhaser(t, endWithRelease, phaserrate, phaserdepth, phasercenter, phasersweep);
     audioNodes.push(lfo);
-    chain.push(phaser);
+    Array.prototype.push.apply(chain, phaser);
   }
 
   // last gain

From 68b1cb87ca32ebcc9080a25abe5cf2019ffad24d Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Mon, 1 Dec 2025 15:29:19 +0000
Subject: [PATCH 28/48] [perf] release unused AudioBufferSourceNode +
 releaseAudioNode

---
 packages/superdough/helpers.mjs   | 31 +++++++++++++++++++++++++++----
 packages/superdough/sampler.mjs   | 16 +++++++++-------
 packages/superdough/synth.mjs     | 13 +++++--------
 packages/superdough/wavetable.mjs |  5 ++---
 packages/superdough/worklets.mjs  |  9 +++++----
 5 files changed, 48 insertions(+), 26 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index ed2c0c44..3e9b8113 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -554,10 +554,33 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
   return Number(freq);
 };
 
-export const destroyAudioWorkletNode = (node) => {
-  if (node == null) {
-    return;
+export const releaseAudioNode = (node) => {
+  // check we received an AudioNode
+  if (!(node instanceof AudioNode)) {
+    throw new Error('releaseAudioNode can only release an AudioNode');
   }
+
+  // https://developer.mozilla.org/en-US/docs/Web/API/AudioNode/disconnect
   node.disconnect();
-  node.parameters.get('end')?.setValueAtTime(0, 0);
+
+  // make sure all AudioScheduledSourceNode is in a stopped state
+  // https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode
+  if (node instanceof AudioScheduledSourceNode) {
+    try {
+      node.stop();
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'InvalidStateError') {
+        node.start(node.context.currentTime + 5); // will never happen
+        node.stop();
+      }
+    }
+  }
+
+  // https://www.w3.org/TR/webaudio-1.1/#AudioNode-actively-processing
+  // An AudioWorkletNode is actively processing when its AudioWorkletProcessor's [[callable process]]
+  // returns true and either its active source flag is true or
+  // any AudioNode connected to one of its inputs is actively processing.
+  if (node instanceof AudioWorkletNode) {
+    node.parameters.get('end')?.setValueAtTime(0, 0);
+  }
 };
diff --git a/packages/superdough/sampler.mjs b/packages/superdough/sampler.mjs
index aaa1a8e4..e066a260 100644
--- a/packages/superdough/sampler.mjs
+++ b/packages/superdough/sampler.mjs
@@ -1,7 +1,7 @@
 import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import { registerSound, registerWaveTable } from './index.mjs';
 import { getAudioContext } from './audioContext.mjs';
-import { getADSRValues, getParamADSR, getPitchEnvelope, getVibratoOscillator } from './helpers.mjs';
+import { getADSRValues, getParamADSR, getPitchEnvelope, getVibratoOscillator, releaseAudioNode } from './helpers.mjs';
 import { logger } from './logger.mjs';
 
 const bufferCache = {}; // string: Promise<ArrayBuffer>
@@ -286,17 +286,19 @@ export async function onTriggerSample(t, value, onended, bank, resolveUrl) {
 
   const { bufferSource, sliceDuration, offset } = await getSampleBufferSource(value, bank, resolveUrl);
 
-  // asny stuff above took too long?
-  if (ac.currentTime > t) {
-    logger(`[sampler] still loading sound "${s}:${n}"`, 'highlight');
-    // console.warn('sample still loading:', s, n);
-    return;
-  }
   if (!bufferSource) {
     logger(`[sampler] could not load "${s}:${n}"`, 'error');
     return;
   }
 
+  // async stuff above took too long?
+  if (ac.currentTime > t) {
+    logger(`[sampler] loading sound "${s}:${n}" took too long`, 'highlight');
+    // AudioBufferSourceNode will never be used. discard it
+    releaseAudioNode(bufferSource);
+    return;
+  }
+
   // vibrato
   let vibratoOscillator = getVibratoOscillator(bufferSource.detune, value, t);
 
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index 3b27bf6c..d50aebae 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -3,7 +3,6 @@ import { registerSound, soundMap } from './superdough.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import {
   applyFM,
-  destroyAudioWorkletNode,
   gainNode,
   getADSRValues,
   getFrequencyFromValue,
@@ -13,6 +12,7 @@ import {
   getVibratoOscillator,
   getWorklet,
   noises,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';
@@ -192,8 +192,7 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          envGain.disconnect();
+          releaseAudioNode(o);
           onended();
           fm?.stop();
           vibratoOscillator?.stop();
@@ -270,8 +269,7 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          envGain.disconnect();
+          releaseAudioNode(o);
           onended();
         },
         begin,
@@ -344,9 +342,8 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          destroyAudioWorkletNode(lfo);
-          envGain.disconnect();
+          releaseAudioNode(o);
+          lfo && releaseAudioNode(lfo);
           onended();
           fm?.stop();
           vibratoOscillator?.stop();
diff --git a/packages/superdough/wavetable.mjs b/packages/superdough/wavetable.mjs
index 3659edcd..e9d81041 100644
--- a/packages/superdough/wavetable.mjs
+++ b/packages/superdough/wavetable.mjs
@@ -3,13 +3,13 @@ import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import {
   applyFM,
   applyParameterModulators,
-  destroyAudioWorkletNode,
   getADSRValues,
   getFrequencyFromValue,
   getParamADSR,
   getPitchEnvelope,
   getVibratoOscillator,
   getWorklet,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';
@@ -319,10 +319,9 @@ export async function onTriggerSynth(t, value, onended, tables, cps, frameLen) {
   const timeoutNode = webAudioTimeout(
     ac,
     () => {
-      destroyAudioWorkletNode(source);
+      releaseAudioNode(source);
       vibratoOscillator?.stop();
       fm?.stop();
-      node.disconnect();
       wtPosModulators?.disconnect();
       wtWarpModulators?.disconnect();
       onended();
diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index bf633a63..2f75453b 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -508,13 +508,14 @@ class SuperSawOscillatorProcessor extends AudioWorkletProcessor {
     ];
   }
   process(_input, outputs, params) {
-    if (currentTime <= params.begin[0]) {
-      return true;
-    }
     if (currentTime >= params.end[0]) {
-      // this.port.postMessage({ type: 'onended' });
+      // should terminate
       return false;
     }
+    if (currentTime <= params.begin[0]) {
+      // keep alive
+      return true;
+    }
     const output = outputs[0];
     const voices = params.voices[0]; // k-rate
     for (let i = 0; i < output[0].length; i++) {

From af7855402ff42f156758cedff87a041519a0417d Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Mon, 1 Dec 2025 20:43:55 +0000
Subject: [PATCH 29/48] Accept non-instanciated nodes for better developer
 experience

---
 packages/superdough/helpers.mjs | 2 ++
 packages/superdough/synth.mjs   | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 3e9b8113..3f57d0a5 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -555,6 +555,8 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
 };
 
 export const releaseAudioNode = (node) => {
+  if (node == null) return;
+
   // check we received an AudioNode
   if (!(node instanceof AudioNode)) {
     throw new Error('releaseAudioNode can only release an AudioNode');
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index d50aebae..b0235446 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -343,7 +343,7 @@ export function registerSynthSounds() {
         ac,
         () => {
           releaseAudioNode(o);
-          lfo && releaseAudioNode(lfo);
+          releaseAudioNode(lfo);
           onended();
           fm?.stop();
           vibratoOscillator?.stop();

From 0ec9826de548ac7ac0b9d22b58ae6a4f17da7b90 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Tue, 2 Dec 2025 09:29:50 +0000
Subject: [PATCH 30/48] onceEnded mechanism to clean audioNode.onended
 callbacks

---
 packages/soundfonts/fontloader.mjs |  5 ++--
 packages/superdough/helpers.mjs    | 46 ++++++++++++++++++------------
 packages/superdough/sampler.mjs    | 13 +++++++--
 packages/superdough/zzfx.mjs       |  7 +++--
 4 files changed, 45 insertions(+), 26 deletions(-)

diff --git a/packages/soundfonts/fontloader.mjs b/packages/soundfonts/fontloader.mjs
index 427f57e3..ca9e45d5 100644
--- a/packages/soundfonts/fontloader.mjs
+++ b/packages/soundfonts/fontloader.mjs
@@ -6,6 +6,7 @@ import {
   getADSRValues,
   getPitchEnvelope,
   getVibratoOscillator,
+  onceEnded,
 } from '@strudel/webaudio';
 import gm from './gm.mjs';
 
@@ -170,12 +171,12 @@ export function registerSoundfonts() {
 
         bufferSource.stop(envEnd);
         const stop = (releaseTime) => {};
-        bufferSource.onended = () => {
+        onceEnded(bufferSource, () => {
           bufferSource.disconnect();
           vibratoOscillator?.stop();
           node.disconnect();
           onended();
-        };
+        });
         return { node, stop };
       },
       { type: 'soundfont', prebake: true, fonts },
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 3f57d0a5..219c66d6 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -349,20 +349,11 @@ export function webAudioTimeout(audioContext, onComplete, startTime, stopTime) {
   constantNode.connect(zeroGain);
 
   // Schedule the `onComplete` callback to occur at `stopTime`
-  constantNode.onended = () => {
-    // Ensure garbage collection
-    try {
-      zeroGain.disconnect();
-    } catch {
-      // pass
-    }
-    try {
-      constantNode.disconnect();
-    } catch {
-      // pass
-    }
+  onceEnded(constantNode, () => {
+    releaseAudioNode(zeroGain);
+    releaseAudioNode(constantNode);
     onComplete();
-  };
+  });
   constantNode.start(startTime);
   constantNode.stop(stopTime);
   return constantNode;
@@ -554,6 +545,17 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
   return Number(freq);
 };
 
+// This helper should be used instead of the `node.onended = callback` pattern
+// It adds a mechanism to help minimize gc retention
+export const onceEnded = (node, callback) => {
+  let onended = callback;
+  node.onended = function cleanup() {
+    onended && onended();
+    onended = null;
+    this.onended = null;
+  };
+};
+
 export const releaseAudioNode = (node) => {
   if (node == null) return;
 
@@ -565,16 +567,24 @@ export const releaseAudioNode = (node) => {
   // https://developer.mozilla.org/en-US/docs/Web/API/AudioNode/disconnect
   node.disconnect();
 
-  // make sure all AudioScheduledSourceNode is in a stopped state
+  // make sure all AudioScheduledSourceNodes are in a stopped state
   // https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode
   if (node instanceof AudioScheduledSourceNode) {
+    if (node.onended && node.onended.name !== 'cleanup') {
+      logger(
+        `[superdough] Deprecation warning: it seems your code path is setting 'node.onended = callback' instead of using the onceEnded helper`,
+      );
+    }
     try {
       node.stop();
     } catch (e) {
-      if (e instanceof DOMException && e.name === 'InvalidStateError') {
-        node.start(node.context.currentTime + 5); // will never happen
-        node.stop();
-      }
+      // At the stage, `start` was not called on the node
+      // but an `onended` callback releasing resources may exist
+      // and we want it to fire :
+      // - we force a start/stop cycle so that `onended` gets called
+      // - we `lock` the node so that no-one can start it
+      node.start(node.context.currentTime + 5); // will never happen
+      node.stop();
     }
   }
 
diff --git a/packages/superdough/sampler.mjs b/packages/superdough/sampler.mjs
index e066a260..1e8c786b 100644
--- a/packages/superdough/sampler.mjs
+++ b/packages/superdough/sampler.mjs
@@ -1,7 +1,14 @@
 import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import { registerSound, registerWaveTable } from './index.mjs';
 import { getAudioContext } from './audioContext.mjs';
-import { getADSRValues, getParamADSR, getPitchEnvelope, getVibratoOscillator, releaseAudioNode } from './helpers.mjs';
+import {
+  getADSRValues,
+  getParamADSR,
+  getPitchEnvelope,
+  getVibratoOscillator,
+  onceEnded,
+  releaseAudioNode,
+} from './helpers.mjs';
 import { logger } from './logger.mjs';
 
 const bufferCache = {}; // string: Promise<ArrayBuffer>
@@ -321,13 +328,13 @@ export async function onTriggerSample(t, value, onended, bank, resolveUrl) {
 
   const out = ac.createGain(); // we need a separate gain for the cutgroups because firefox...
   node.connect(out);
-  bufferSource.onended = function () {
+  onceEnded(bufferSource, function () {
     bufferSource.disconnect();
     vibratoOscillator?.stop();
     node.disconnect();
     out.disconnect();
     onended();
-  };
+  });
   let envEnd = holdEnd + release + 0.01;
   bufferSource.stop(envEnd);
   const stop = (endTime) => {
diff --git a/packages/superdough/zzfx.mjs b/packages/superdough/zzfx.mjs
index 32db0395..4a4c58c9 100644
--- a/packages/superdough/zzfx.mjs
+++ b/packages/superdough/zzfx.mjs
@@ -3,6 +3,7 @@ import { midiToFreq, noteToMidi } from './util.mjs';
 import { registerSound } from './superdough.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import { buildSamples } from './zzfx_fork.mjs';
+import { onceEnded, releaseAudioNode } from './helpers.mjs';
 
 export const getZZFX = (value, t) => {
   let {
@@ -83,10 +84,10 @@ export function registerZZFXSounds() {
       wave,
       (t, value, onended) => {
         const { node: o } = getZZFX({ s: wave, ...value }, t);
-        o.onended = () => {
-          o.disconnect();
+        onceEnded(o, () => {
+          releaseAudioNode(o);
           onended();
-        };
+        });
         return {
           node: o,
           stop: () => {},

From 1d4f2b81d8bac8f37ed79f26ed936810f2c62627 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Wed, 3 Dec 2025 11:12:30 -0600
Subject: [PATCH 31/48] Switch back to explicit exports and use new release
 mechanism

---
 packages/core/controls.mjs      | 105 +++++++++++++++++++++++++++++---
 packages/superdough/helpers.mjs |  34 ++++-------
 2 files changed, 108 insertions(+), 31 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 8a848fec..426fd747 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -468,7 +468,7 @@ export const { attack, att } = registerControl('attack', 'att');
  * ._scope()
  *
  */
-Object.assign(globalThis, registerMultiControl(['fmh', 'fmi'], 8, 'fmh'));
+export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerMultiControl(['fmh', 'fmi'], 8, 'fmh');
 
 /**
  * Sets the Frequency Modulation of the synth.
@@ -492,7 +492,8 @@ Object.assign(globalThis, registerMultiControl(['fmh', 'fmi'], 8, 'fmh'));
  *  .fmh(1.06).fmh2(10).fmh3(0.1)
  *
  */
-Object.assign(globalThis, registerMultiControl(['fmi', 'fmh'], 8, 'fm'));
+export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2, fm3, fm4, fm5, fm6, fm7, fm8 } =
+  registerMultiControl(['fmi', 'fmh'], 8, 'fm');
 
 // fm envelope
 /**
@@ -512,7 +513,10 @@ Object.assign(globalThis, registerMultiControl(['fmi', 'fmh'], 8, 'fm'));
  * ._scope()
  *
  */
-Object.assign(globalThis, registerMultiControl('fmenv', 8));
+export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fmenv8 } = registerMultiControl(
+  'fmenv',
+  8,
+);
 
 /**
  * Attack time for the FM envelope: time it takes to reach maximum modulation
@@ -530,7 +534,26 @@ Object.assign(globalThis, registerMultiControl('fmenv', 8));
  * ._scope()
  *
  */
-Object.assign(globalThis, registerMultiControl('fmattack', 8, 'fmatt'));
+export const {
+  fmattack,
+  fmattack1,
+  fmattack2,
+  fmattack3,
+  fmattack4,
+  fmattack5,
+  fmattack6,
+  fmattack7,
+  fmattack8,
+  fmatt,
+  fmatt1,
+  fmatt2,
+  fmatt3,
+  fmatt4,
+  fmatt5,
+  fmatt6,
+  fmatt7,
+  fmatt8,
+} = registerMultiControl('fmattack', 8, 'fmatt');
 
 /**
  * Waveform of the fm modulator
@@ -546,7 +569,10 @@ Object.assign(globalThis, registerMultiControl('fmattack', 8, 'fmatt'));
  * n("0 1 2 3".fast(4)).chord("<Dm Am F G>").voicing().s("sawtooth").fmwave("brown").fm(.6)
  *
  */
-Object.assign(globalThis, registerMultiControl('fmwave', 8));
+export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmwave7, fmwave8 } = registerMultiControl(
+  'fmwave',
+  8,
+);
 
 /**
  * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
@@ -565,7 +591,26 @@ Object.assign(globalThis, registerMultiControl('fmwave', 8));
  * ._scope()
  *
  */
-Object.assign(globalThis, registerMultiControl('fmdecay', 8, 'fmdec'));
+export const {
+  fmdecay,
+  fmdecay1,
+  fmdecay2,
+  fmdecay3,
+  fmdecay4,
+  fmdecay5,
+  fmdecay6,
+  fmdecay7,
+  fmdecay8,
+  fmdec,
+  fmdec1,
+  fmdec2,
+  fmdec3,
+  fmdec4,
+  fmdec5,
+  fmdec6,
+  fmdec7,
+  fmdec8,
+} = registerMultiControl('fmdecay', 8, 'fmdec');
 
 /**
  * Sustain level for the FM envelope: how much modulation is applied after the decay phase
@@ -584,7 +629,26 @@ Object.assign(globalThis, registerMultiControl('fmdecay', 8, 'fmdec'));
  * ._scope()
  *
  */
-Object.assign(globalThis, registerMultiControl('fmsustain', 8, 'fmsus'));
+export const {
+  fmsustain,
+  fmsustain1,
+  fmsustain2,
+  fmsustain3,
+  fmsustain4,
+  fmsustain5,
+  fmsustain6,
+  fmsustain7,
+  fmsustain8,
+  fmsus,
+  fmsus1,
+  fmsus2,
+  fmsus3,
+  fmsus4,
+  fmsus5,
+  fmsus6,
+  fmsus7,
+  fmsus8,
+} = registerMultiControl('fmsustain', 8, 'fmsus');
 
 /**
  * Release time for the FM envelope: how much modulation is applied after the note is released
@@ -597,12 +661,35 @@ Object.assign(globalThis, registerMultiControl('fmsustain', 8, 'fmsus'));
  * @param {number | Pattern} time release time
  *
  */
-Object.assign(globalThis, registerMultiControl('fmrelease', 8, 'fmrel'));
+export const {
+  fmrelease,
+  fmrelease1,
+  fmrelease2,
+  fmrelease3,
+  fmrelease4,
+  fmrelease5,
+  fmrelease6,
+  fmrelease7,
+  fmrelease8,
+  fmrel,
+  fmrel1,
+  fmrel2,
+  fmrel3,
+  fmrel4,
+  fmrel5,
+  fmrel6,
+  fmrel7,
+  fmrel8,
+} = registerMultiControl('fmrelease', 8, 'fmrel');
 
 // FM Matrix
+// Note: we do not declare top-level exports here since it would add
+// ~162 more explicit exports. This is likely fine as the most common use-case would be to at least
+// declare one other FM prior to utilizing the matrix functionality, but if we ever decide we need it,
+// TODO to add it explicitly / go with the globalThis approach
 for (let i = 0; i <= 8; i++) {
   for (let j = 0; j <= 8; j++) {
-    Object.assign(globalThis, registerControl(`fmi${i}${j}`, `fm${i}${j}`));
+    registerControl(`fmi${i}${j}`, `fm${i}${j}`);
   }
 }
 
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 073ed00b..2080d32e 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -372,13 +372,13 @@ const mod = (freq, type = 'sine') => {
     osc.frequency.value = freq;
   }
   osc.start();
-  return { osc, freq };
+  return osc;
 };
 
 const fm = (frequencyparam, harmonicityRatio, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
   const modfreq = carrfreq * harmonicityRatio;
-  return mod(modfreq, wave);
+  return { osc: mod(modfreq, wave), freq: modfreq };
 };
 
 export function applyFM(param, value, begin) {
@@ -434,13 +434,12 @@ export function applyFM(param, value, begin) {
             toCleanup.push(envGain);
             output = osc.connect(envGain);
           }
-          fms[idx] = { input: osc.frequency, output, freq, toCleanup };
-          osc.onended = () => cleanupNodes(fms[idx].toCleanup);
+          fms[idx] = { input: osc.frequency, output, freq, osc, toCleanup };
         }
-        const { input, output, freq, toCleanup } = fms[idx];
+        const { input, output, freq, osc, toCleanup } = fms[idx];
         const g = gainNode(amt * freq);
         io.push(isMod ? output.connect(g) : input);
-        toCleanup.push(g);
+        cleanupOnEnd(osc, [...toCleanup, g]);
       }
       if (!io[1]) {
         logger(
@@ -451,11 +450,6 @@ export function applyFM(param, value, begin) {
       }
       io[0].connect(io[1]);
     }
-    fmmod.osc.onended = () => {
-      envGain.disconnect();
-      modulator.disconnect();
-      fmmod.osc.disconnect();
-    };
   }
   return {
     stop: (t) => toStop.forEach((m) => m?.stop(t)),
@@ -575,10 +569,9 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
 // This helper should be used instead of the `node.onended = callback` pattern
 // It adds a mechanism to help minimize gc retention
 export const onceEnded = (node, callback) => {
-  let onended = callback;
+  const onended = callback;
   node.onended = function cleanup() {
     onended && onended();
-    onended = null;
     this.onended = null;
   };
 };
@@ -624,13 +617,10 @@ export const releaseAudioNode = (node) => {
   }
 };
 
-export const cleanupNode = (node, time) => {
-  if (node == null) return;
-  node.disconnect?.();
-  node.parameters?.get('end')?.setValueAtTime(0, 0);
-  node.stop?.(time);
-};
-
-export const cleanupNodes = (nodes, time) => {
-  nodes.forEach((n) => cleanupNode(n, time));
+// Once the `anchor` node has ended, release all nodes in `toCleanup`
+export const cleanupOnEnd = (anchor, toCleanup) => {
+  onceEnded(
+    anchor,
+    () => toCleanup.forEach((n) => releaseAudioNode(n)),
+  );
 };

From 196f70ab6bfa14613490dd1117d1e01ab48249c3 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Wed, 3 Dec 2025 11:13:21 -0600
Subject: [PATCH 32/48] Formatting

---
 packages/superdough/helpers.mjs | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 2080d32e..0b696df9 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -619,8 +619,5 @@ export const releaseAudioNode = (node) => {
 
 // Once the `anchor` node has ended, release all nodes in `toCleanup`
 export const cleanupOnEnd = (anchor, toCleanup) => {
-  onceEnded(
-    anchor,
-    () => toCleanup.forEach((n) => releaseAudioNode(n)),
-  );
+  onceEnded(anchor, () => toCleanup.forEach((n) => releaseAudioNode(n)));
 };

From 0b711e879c767ab1c4bfba7af0c655d28da70f8c Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Thu, 4 Dec 2025 08:23:36 +0000
Subject: [PATCH 33/48] Improve naming & backward compat

---
 packages/superdough/superdough.mjs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 514c492c..19166549 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -291,7 +291,7 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
 
   //filters
   const numStages = 1; //num of filters in series
-  let fOffset = 0;
+  let fOffset = 282; //for backward compat in #1800
   const filterChain = [];
   for (let i = 0; i < numStages; i++) {
     const filter = ac.createBiquadFilter();
@@ -304,7 +304,7 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
     fOffset += 282;
     filterChain.push(filter);
   }
-  return { phaser: filterChain, lfo };
+  return { filterChain, lfo };
 }
 
 function getFilterType(ftype) {
@@ -694,9 +694,9 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   }
   // phaser
   if (phaserrate !== undefined && phaserdepth > 0) {
-    const { phaser, lfo } = getPhaser(t, endWithRelease, phaserrate, phaserdepth, phasercenter, phasersweep);
+    const { filterChain, lfo } = getPhaser(t, endWithRelease, phaserrate, phaserdepth, phasercenter, phasersweep);
     audioNodes.push(lfo);
-    Array.prototype.push.apply(chain, phaser);
+    chain.push(...filterChain);
   }
 
   // last gain

From 46291bf85ca0cf583568266f02f7370c6eb67e82 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Thu, 4 Dec 2025 13:17:20 +0000
Subject: [PATCH 34/48] Difuse the `onceEnded` mechanism

---
 packages/superdough/helpers.mjs |  4 ++--
 packages/superdough/noise.mjs   |  4 ++--
 packages/superdough/synth.mjs   | 13 +++++++------
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 0b696df9..6fe1e5b7 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -324,10 +324,10 @@ export function getVibratoOscillator(param, value, t) {
     gain.gain.value = vibmod * 100;
     vibratoOscillator.connect(gain);
     gain.connect(param);
-    vibratoOscillator.onended = () => {
+    onceEnded(vibratoOscillator, () => {
       gain.disconnect(param);
       vibratoOscillator.disconnect(gain);
-    };
+    });
     vibratoOscillator.start(t);
     return vibratoOscillator;
   }
diff --git a/packages/superdough/noise.mjs b/packages/superdough/noise.mjs
index 3e41515d..da60e87a 100644
--- a/packages/superdough/noise.mjs
+++ b/packages/superdough/noise.mjs
@@ -1,4 +1,4 @@
-import { drywet } from './helpers.mjs';
+import { drywet, onceEnded } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
 
 let noiseCache = {};
@@ -65,7 +65,7 @@ export function getNoiseOscillator(type = 'white', t, density = 0.02) {
 export function getNoiseMix(inputNode, wet, t) {
   const noiseOscillator = getNoiseOscillator('pink', t);
   const noiseMix = drywet(inputNode, noiseOscillator.node, wet);
-  noiseOscillator.node.onended = () => noiseMix.onended();
+  onceEnded(noiseOscillator.node, () => noiseMix.onended());
   return {
     node: noiseMix.node,
     stop: (time) => noiseOscillator?.stop(time),
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index b0235446..a2d3aeca 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -1,5 +1,6 @@
 import { clamp } from './util.mjs';
 import { registerSound, soundMap } from './superdough.mjs';
+import { onceEnded } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import {
   applyFM,
@@ -110,7 +111,7 @@ export function registerSynthSounds() {
 
       const mix = gainNode(mixGain);
 
-      o.onended = () => {
+      onceEnded(o, () => {
         o.disconnect();
         g.disconnect();
         sat.disconnect();
@@ -118,7 +119,7 @@ export function registerSynthSounds() {
         noiseGain.disconnect();
         mix.disconnect();
         onended();
-      };
+      });
 
       const node = o.connect(sat).connect(g).connect(mix);
       noise.node.connect(noiseGain).connect(mix);
@@ -384,11 +385,11 @@ export function registerSynthSounds() {
 
         const { duration } = value;
 
-        o.onended = () => {
+        onceEnded(o, () => {
           o.disconnect();
           g.disconnect();
           onended();
-        };
+        });
 
         const envGain = gainNode(1);
         let node = o.connect(g).connect(envGain);
@@ -489,11 +490,11 @@ export function getOscillator(s, t, value, onended) {
     noiseMix = getNoiseMix(o, noise, t);
   }
 
-  o.onended = () => {
+  onceEnded(o, () => {
     noiseMix || o.disconnect();
     noiseMix?.node.disconnect();
     onended();
-  };
+  });
   o.start(t);
 
   return {

From c7586e96ff8ff1bbeb7b8d6b965d4a8a6b8fce3b Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Thu, 4 Dec 2025 13:20:17 +0000
Subject: [PATCH 35/48] Add comment on `end` worklet param

---
 packages/superdough/helpers.mjs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 6fe1e5b7..f000db63 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -613,6 +613,8 @@ export const releaseAudioNode = (node) => {
   // returns true and either its active source flag is true or
   // any AudioNode connected to one of its inputs is actively processing.
   if (node instanceof AudioWorkletNode) {
+    // while `end` is not native to the web audio API, it is common practice in superdough
+    // to use that param in the worklets to trigger returning false from the processor
     node.parameters.get('end')?.setValueAtTime(0, 0);
   }
 };

From f6f507dd291ccdaca4ca5b2d32dc456fd48edbe2 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Thu, 4 Dec 2025 15:26:59 +0000
Subject: [PATCH 36/48] propagate `releaseAudioNode` in packages

---
 packages/soundfonts/fontloader.mjs |  6 +++---
 packages/superdough/helpers.mjs    |  6 +++---
 packages/superdough/sampler.mjs    |  8 ++++----
 packages/superdough/superdough.mjs |  4 ++--
 packages/superdough/synth.mjs      | 24 ++++++++++++------------
 packages/superdough/wavetable.mjs  |  6 +++---
 6 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/packages/soundfonts/fontloader.mjs b/packages/soundfonts/fontloader.mjs
index ca9e45d5..95e21089 100644
--- a/packages/soundfonts/fontloader.mjs
+++ b/packages/soundfonts/fontloader.mjs
@@ -7,6 +7,7 @@ import {
   getPitchEnvelope,
   getVibratoOscillator,
   onceEnded,
+  releaseAudioNode,
 } from '@strudel/webaudio';
 import gm from './gm.mjs';
 
@@ -172,9 +173,8 @@ export function registerSoundfonts() {
         bufferSource.stop(envEnd);
         const stop = (releaseTime) => {};
         onceEnded(bufferSource, () => {
-          bufferSource.disconnect();
-          vibratoOscillator?.stop();
-          node.disconnect();
+          releaseAudioNode(bufferSource);
+          releaseAudioNode(vibratoOscillator);
           onended();
         });
         return { node, stop };
diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index f000db63..5202dbdf 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -189,7 +189,7 @@ export function applyParameterModulators(audioContext, param, start, end, envelo
     getParamADSR(param, attack, decay, sustain, release, min, max, start, holdEnd, curve);
   }
   const lfo = getParamLfo(audioContext, param, start, end, lfoValues);
-  return { lfo, disconnect: () => lfo?.disconnect() };
+  return lfo
 }
 export function createFilter(context, start, end, params, cps, cycle) {
   let {
@@ -325,8 +325,8 @@ export function getVibratoOscillator(param, value, t) {
     vibratoOscillator.connect(gain);
     gain.connect(param);
     onceEnded(vibratoOscillator, () => {
-      gain.disconnect(param);
-      vibratoOscillator.disconnect(gain);
+      releaseAudioNode(gain);
+      releaseAudioNode(vibratoOscillator);
     });
     vibratoOscillator.start(t);
     return vibratoOscillator;
diff --git a/packages/superdough/sampler.mjs b/packages/superdough/sampler.mjs
index 1e8c786b..0e1e291f 100644
--- a/packages/superdough/sampler.mjs
+++ b/packages/superdough/sampler.mjs
@@ -329,10 +329,10 @@ export async function onTriggerSample(t, value, onended, bank, resolveUrl) {
   const out = ac.createGain(); // we need a separate gain for the cutgroups because firefox...
   node.connect(out);
   onceEnded(bufferSource, function () {
-    bufferSource.disconnect();
-    vibratoOscillator?.stop();
-    node.disconnect();
-    out.disconnect();
+    releaseAudioNode(bufferSource);
+    releaseAudioNode(vibratoOscillator);
+    releaseAudioNode(node);
+    releaseAudioNode(out);
     onended();
   });
   let envEnd = holdEnd + release + 0.01;
diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 6f610d51..bfcf3ab5 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -9,7 +9,7 @@ import './reverb.mjs';
 import './vowel.mjs';
 import { nanFallback, _mod, cycleToSeconds, pickAndRename } from './util.mjs';
 import workletsUrl from './worklets.mjs?audioworklet';
-import { createFilter, gainNode, getCompressor, getDistortion, getLfo, getWorklet, effectSend } from './helpers.mjs';
+import { createFilter, gainNode, getCompressor, getDistortion, getLfo, getWorklet, effectSend, releaseAudioNode } from './helpers.mjs';
 import { map } from 'nanostores';
 import { logger } from './logger.mjs';
 import { loadBuffer } from './sampler.mjs';
@@ -506,7 +506,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   } else if (getSound(s)) {
     const { onTrigger } = getSound(s);
     const onEnded = () => {
-      audioNodes.forEach((n) => n?.disconnect());
+      audioNodes.forEach((n) => releaseAudioNode(n));
       activeSoundSources.delete(chainID);
     };
     const soundHandle = await onTrigger(t, value, onEnded, cps);
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index a2d3aeca..e82c889a 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -1,6 +1,5 @@
 import { clamp } from './util.mjs';
 import { registerSound, soundMap } from './superdough.mjs';
-import { onceEnded } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import {
   applyFM,
@@ -13,6 +12,7 @@ import {
   getVibratoOscillator,
   getWorklet,
   noises,
+  onceEnded,
   releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
@@ -53,7 +53,7 @@ export function registerSynthSounds() {
         const g = gainNode(0.3);
 
         let sound = getOscillator(s, t, value, () => {
-          g.disconnect();
+          releaseAudioNode(g);
           onended();
         });
 
@@ -112,12 +112,12 @@ export function registerSynthSounds() {
       const mix = gainNode(mixGain);
 
       onceEnded(o, () => {
-        o.disconnect();
-        g.disconnect();
-        sat.disconnect();
-        noise.node.disconnect();
-        noiseGain.disconnect();
-        mix.disconnect();
+        releaseAudioNode(o);
+        releaseAudioNode(g);
+        releaseAudioNode(sat);
+        releaseAudioNode(noise.node);
+        releaseAudioNode(noiseGain);
+        releaseAudioNode(mix);
         onended();
       });
 
@@ -386,8 +386,8 @@ export function registerSynthSounds() {
         const { duration } = value;
 
         onceEnded(o, () => {
-          o.disconnect();
-          g.disconnect();
+          releaseAudioNode(o);
+          releaseAudioNode(g);
           onended();
         });
 
@@ -491,8 +491,8 @@ export function getOscillator(s, t, value, onended) {
   }
 
   onceEnded(o, () => {
-    noiseMix || o.disconnect();
-    noiseMix?.node.disconnect();
+    noiseMix || releaseAudioNode(o);
+    releaseAudioNode(noiseMix?.node);
     onended();
   });
   o.start(t);
diff --git a/packages/superdough/wavetable.mjs b/packages/superdough/wavetable.mjs
index e9d81041..4311c5ca 100644
--- a/packages/superdough/wavetable.mjs
+++ b/packages/superdough/wavetable.mjs
@@ -320,10 +320,10 @@ export async function onTriggerSynth(t, value, onended, tables, cps, frameLen) {
     ac,
     () => {
       releaseAudioNode(source);
-      vibratoOscillator?.stop();
+      releaseAudioNode(vibratoOscillator);
       fm?.stop();
-      wtPosModulators?.disconnect();
-      wtWarpModulators?.disconnect();
+      releaseAudioNode(wtPosModulators);
+      releaseAudioNode(wtWarpModulators);
       onended();
     },
     t,

From 1225d0443748b04c1a84b077c71f88b5f66c7428 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Thu, 4 Dec 2025 15:29:21 +0000
Subject: [PATCH 37/48] codeformat

---
 packages/superdough/helpers.mjs    |  2 +-
 packages/superdough/superdough.mjs | 11 ++++++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index 5202dbdf..a5f199fb 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -189,7 +189,7 @@ export function applyParameterModulators(audioContext, param, start, end, envelo
     getParamADSR(param, attack, decay, sustain, release, min, max, start, holdEnd, curve);
   }
   const lfo = getParamLfo(audioContext, param, start, end, lfoValues);
-  return lfo
+  return lfo;
 }
 export function createFilter(context, start, end, params, cps, cycle) {
   let {
diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index bfcf3ab5..98a87513 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -9,7 +9,16 @@ import './reverb.mjs';
 import './vowel.mjs';
 import { nanFallback, _mod, cycleToSeconds, pickAndRename } from './util.mjs';
 import workletsUrl from './worklets.mjs?audioworklet';
-import { createFilter, gainNode, getCompressor, getDistortion, getLfo, getWorklet, effectSend, releaseAudioNode } from './helpers.mjs';
+import {
+  createFilter,
+  gainNode,
+  getCompressor,
+  getDistortion,
+  getLfo,
+  getWorklet,
+  effectSend,
+  releaseAudioNode,
+} from './helpers.mjs';
 import { map } from 'nanostores';
 import { logger } from './logger.mjs';
 import { loadBuffer } from './sampler.mjs';

From 16b5faf3331ce18a9a791059a7a71995815ecb54 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 7 Dec 2025 11:23:55 -0600
Subject: [PATCH 38/48] Removing failing tests due to shabda removal

---
 packages/superdough/sampler.mjs           |  6 ----
 test/__snapshots__/examples.test.mjs.snap | 36 -----------------------
 2 files changed, 42 deletions(-)

diff --git a/packages/superdough/sampler.mjs b/packages/superdough/sampler.mjs
index 1e8c786b..bdf524d1 100644
--- a/packages/superdough/sampler.mjs
+++ b/packages/superdough/sampler.mjs
@@ -243,12 +243,6 @@ export async function fetchSampleMap(url) {
  *  sd: '808sd/SD0010.WAV'
  *  }, 'https://raw.githubusercontent.com/tidalcycles/Dirt-Samples/master/');
  * s("[bd ~]*2, [~ hh]*2, ~ sd")
- * @example
- * samples('shabda:noise,chimp:2')
- * s("noise <chimp:0*2 chimp:1>")
- * @example
- * samples('shabda/speech/fr-FR/f:chocolat')
- * s("chocolat*4")
  */
 
 export const samples = async (sampleMap, baseUrl = sampleMap._base || '', options = {}) => {
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 5c76f4a8..7ecaf97b 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -9722,42 +9722,6 @@ exports[`runs examples > example "samples" example index 1 1`] = `
 ]
 `;
 
-exports[`runs examples > example "samples" example index 2 1`] = `
-[
-  "[ 0/1 → 1/2 | s:noise ]",
-  "[ 1/2 → 3/4 | s:chimp n:0 ]",
-  "[ 3/4 → 1/1 | s:chimp n:0 ]",
-  "[ 1/1 → 3/2 | s:noise ]",
-  "[ 3/2 → 2/1 | s:chimp n:1 ]",
-  "[ 2/1 → 5/2 | s:noise ]",
-  "[ 5/2 → 11/4 | s:chimp n:0 ]",
-  "[ 11/4 → 3/1 | s:chimp n:0 ]",
-  "[ 3/1 → 7/2 | s:noise ]",
-  "[ 7/2 → 4/1 | s:chimp n:1 ]",
-]
-`;
-
-exports[`runs examples > example "samples" example index 3 1`] = `
-[
-  "[ 0/1 → 1/4 | s:chocolat ]",
-  "[ 1/4 → 1/2 | s:chocolat ]",
-  "[ 1/2 → 3/4 | s:chocolat ]",
-  "[ 3/4 → 1/1 | s:chocolat ]",
-  "[ 1/1 → 5/4 | s:chocolat ]",
-  "[ 5/4 → 3/2 | s:chocolat ]",
-  "[ 3/2 → 7/4 | s:chocolat ]",
-  "[ 7/4 → 2/1 | s:chocolat ]",
-  "[ 2/1 → 9/4 | s:chocolat ]",
-  "[ 9/4 → 5/2 | s:chocolat ]",
-  "[ 5/2 → 11/4 | s:chocolat ]",
-  "[ 11/4 → 3/1 | s:chocolat ]",
-  "[ 3/1 → 13/4 | s:chocolat ]",
-  "[ 13/4 → 7/2 | s:chocolat ]",
-  "[ 7/2 → 15/4 | s:chocolat ]",
-  "[ 15/4 → 4/1 | s:chocolat ]",
-]
-`;
-
 exports[`runs examples > example "saw" example index 0 1`] = `
 [
   "[ 0/1 → 1/8 | note:c3 clip:0 ]",

From fe7e8f7add4b45216416d1f65038a6bb65f4ec04 Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 7 Dec 2025 13:21:06 -0600
Subject: [PATCH 39/48] Clearer docstring

---
 packages/midi/midi.mjs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/midi/midi.mjs b/packages/midi/midi.mjs
index 0fee380c..cd38d358 100644
--- a/packages/midi/midi.mjs
+++ b/packages/midi/midi.mjs
@@ -486,8 +486,9 @@ const refsByChan = {};
  *
  * The output is a function that accepts a midi cc value to query as well as (optionally) a midi channel
  * @param {string | number} input MIDI device name or index defaulting to 0
- * @returns {function(number, number=): function(): number} A function from (cc, channel?) to
- *   the most recently received midi cc value through the input (normalized to 0 to 1)
+ * @returns {function(number, number=): Pattern} A function from (cc, channel?) to a pattern.
+ *   When queried, the pattern will produces the most recently received midi value (normalized to 0 to 1)
+ *   that came through that cc number (and channel, if provided)
  * @example
  * const cc = await midin('IAC Driver Bus 1')
  * note("c a f e").lpf(cc(0).range(0, 1000)).lpq(cc(1).range(0, 10)).sound("sawtooth")

From 358b1e3f563ffe6bafd33689b1fec8e7c02c4ecc Mon Sep 17 00:00:00 2001
From: Aria <weglossing@gmail.com>
Date: Sun, 7 Dec 2025 13:28:57 -0600
Subject: [PATCH 40/48] Make sure processor turns off; fix array sizes for JIT

---
 packages/superdough/superdough.mjs |  2 ++
 packages/superdough/worklets.mjs   | 17 ++++++++++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs
index 52bf332e..b4df1f73 100644
--- a/packages/superdough/superdough.mjs
+++ b/packages/superdough/superdough.mjs
@@ -544,6 +544,8 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
           processorOptions: {
             attack: transient,
             sustain: transsustain,
+            begin: t,
+            end: endWithRelease,
           },
         },
       ),
diff --git a/packages/superdough/worklets.mjs b/packages/superdough/worklets.mjs
index d190cf41..a59aeb75 100644
--- a/packages/superdough/worklets.mjs
+++ b/packages/superdough/worklets.mjs
@@ -1404,6 +1404,8 @@ class TransientProcessor extends AudioWorkletProcessor {
       sustain = 0,
       sensitivity = 0.1,
       mix = 1,
+      begin = 0,
+      end = 0,
     } = options.processorOptions;
     attackTime = clamp(attackTime, 0.0005, 0.05);
     sustainTime = clamp(sustainTime, 0.01, 0.5);
@@ -1413,17 +1415,26 @@ class TransientProcessor extends AudioWorkletProcessor {
     this.sustainAmt = clamp(sustain, -1, 1);
     this.scaling = 0.5 + 5 * clamp(sensitivity, 0, 1);
     this.mix = clamp(mix, 0, 1);
+    this.begin = begin;
+    this.end = end;
+    this.attackEnv = new Float32Array(2); // assume stereo
+    this.sustainEnv = new Float32Array(2);
   }
 
   process(inputs, outputs, _params) {
     const input = inputs[0];
     const output = outputs[0];
-    if (!input || !output) {
+    if (currentTime >= this.end) {
+      return false;
+    }
+    if (currentTime <= this.begin) {
       return true;
     }
     const channels = input.length;
-    this.attackEnv ??= new Float32Array(channels);
-    this.sustainEnv ??= new Float32Array(channels);
+    if (channels > this.attackEnv.length) {
+      this.attackEnv = new Float32Array(channels);
+      this.sustainEnv = new Float32Array(channels);
+    }
     let avgGain = this.avgGain;
     for (let ch = 0; ch < channels; ch++) {
       let attEnv = this.attackEnv[ch];

From 71d36b79edfdf85cb035764b418662210226d245 Mon Sep 17 00:00:00 2001
From: jeromew <jerome.wagner@m4x.org>
Date: Mon, 8 Dec 2025 17:31:34 +0000
Subject: [PATCH 41/48] Improve getOscillator/noiseMix release

---
 packages/superdough/helpers.mjs | 9 ++++++---
 packages/superdough/noise.mjs   | 7 +++++--
 packages/superdough/synth.mjs   | 3 ++-
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/packages/superdough/helpers.mjs b/packages/superdough/helpers.mjs
index a5f199fb..5abc2bad 100644
--- a/packages/superdough/helpers.mjs
+++ b/packages/superdough/helpers.mjs
@@ -283,9 +283,12 @@ export function drywet(dry, wet, wetAmount = 0) {
   wet_gain.connect(mix);
   return {
     node: mix,
-    onended: () => {
-      dry_gain.disconnect(mix);
-      wet_gain.disconnect(mix);
+    teardown: () => {
+      releaseAudioNode(dry_gain);
+      releaseAudioNode(wet_gain);
+      // it is not the responsability of drywet
+      // to call `releaseAudioNode` on
+      // the 2 external args dry and wet
       dry.disconnect(dry_gain);
       wet.disconnect(wet_gain);
     },
diff --git a/packages/superdough/noise.mjs b/packages/superdough/noise.mjs
index da60e87a..52d9306a 100644
--- a/packages/superdough/noise.mjs
+++ b/packages/superdough/noise.mjs
@@ -1,4 +1,4 @@
-import { drywet, onceEnded } from './helpers.mjs';
+import { drywet, onceEnded, releaseAudioNode } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
 
 let noiseCache = {};
@@ -65,9 +65,12 @@ export function getNoiseOscillator(type = 'white', t, density = 0.02) {
 export function getNoiseMix(inputNode, wet, t) {
   const noiseOscillator = getNoiseOscillator('pink', t);
   const noiseMix = drywet(inputNode, noiseOscillator.node, wet);
-  onceEnded(noiseOscillator.node, () => noiseMix.onended());
+  onceEnded(noiseOscillator.node, () => {
+    releaseAudioNode(noiseOscillator.node);
+  });
   return {
     node: noiseMix.node,
     stop: (time) => noiseOscillator?.stop(time),
+    teardown: noiseMix.teardown,
   };
 }
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index e82c889a..d9ee0d93 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -491,7 +491,8 @@ export function getOscillator(s, t, value, onended) {
   }
 
   onceEnded(o, () => {
-    noiseMix || releaseAudioNode(o);
+    noiseMix?.teardown();
+    releaseAudioNode(o);
     releaseAudioNode(noiseMix?.node);
     onended();
   });

From e89414e400362ebe064858e4c0b1cc3441b56dca Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Wed, 10 Dec 2025 09:19:12 +0000
Subject: [PATCH 42/48] fix .as so it doesn't set undefined values

---
 packages/core/controls.mjs | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index c7edef74..f28d13f6 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -2753,8 +2753,13 @@ export const as = register('as', (mapping, pat) => {
   mapping = Array.isArray(mapping) ? mapping : [mapping];
   return pat.fmap((v) => {
     v = Array.isArray(v) ? v : [v];
-    v = Object.fromEntries(mapping.map((prop, i) => [getControlName(prop), v[i]]));
-    return v;
+    const entries = [];
+    for (let i = 0; i < mapping.length; ++i) {
+      if (v[i] !== undefined) {
+        entries.push([getControlName(mapping[i]), v[i]]);
+      }
+    }
+    return Object.fromEntries(entries);
   });
 });
 

From 12884cba3a0db216fa14a1c1c3d2521ab38fcccf Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 12:09:26 +0000
Subject: [PATCH 43/48] Updates relating to LLM, github, etc

---
 CONTRIBUTING.md | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a7f65b5b..a4cf5d9e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,20 +4,13 @@ Thanks for wanting to contribute!!! There are many ways you can add value to thi
 
 ## Move to codeberg
 
-We are currently in the process of moving from github to codeberg -- not everything is working, please bear with us.
-
-To update your local clone, you can run this command:
-
-```
-git remote set-url origin git@codeberg.org:uzu/strudel.git
-```
-
+Along with many other live coding projects, we have moved from Microsoft's Github platform to Codeberg for ethical reasons. Please don't fork the project back to github.
 
 ## Communication Channels
 
-To get in touch with the contributors, either
+To get in touch with the community, either
 
-- [join the Tidal Discord Channel](https://discord.com/invite/HGEdXmRkzT) and go to the #strudel channel
+- [join the Tidal Discord Channel](https://discord.com/invite/HGEdXmRkzT) and go to the #strudel channels
 - Find related discussions on the [tidal club forum](https://club.tidalcycles.org/)
 
 ## Ask a Question
@@ -36,22 +29,33 @@ Use one of the Communication Channels listed above and drop us a line or two!
 ## Share Music
 
 If you made some music with strudel, you can give back some love and share what you've done!
-Your creation could also be part of the random selection in the REPL if you want.
 Use one of the Communication Channels listed above.
+(There used to be a random selection of contributed patterns in the REPL, but that is unfortunately disabled for now due to abuse)
 
 ## Improve the Docs
 
-If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/),
-you can edit each file directly on codeburg. (we are currently fixing the "Edit this page" links in the right sidebar)
+If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeburg. There are "Edit this page" links in the right sidebar that take you to the right place.
 
 ## Propose a Feature
 
-If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above.
-Maybe you even want to help with the implementation of that feature!
+If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above. Please bear in mind that this is a free/open source project, oriented around collaborative discussion. Maybe you even want to help with the implementation of that feature!
+
+## Contribute a feature
+
+It's generally best to start with discussion rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
+
+## AI/LLM policy
+
+Strudel is a project handmade by humans, with a lot of thought and nuance. We are still developing our response to the onslaught of LLM technology.
+
+If you have used LLMs (so called 'AI'), please make that clear in the pull request. If code is LLM-generated/isn't your own work, then the PR will not be merged, for practical and legal reasons.
+
+There are #llm-chat and #llm-share channels on our discord. Please do not discuss or share LLM-related things outside of those channels.
 
 ## Report a Bug
 
 If you've found a bug, or some behaviour that does not seem right, you are welcome to file an [issue](https://codeberg.org/uzu/strudel/issues).
+
 Please check that it has not been reported before.
 
 ## Fix a Bug
@@ -118,8 +122,7 @@ There are also eslint extensions / plugins for most editors.
 
 ## Running all CI Checks
 
-When opening a PR, the CI runner will automatically check the code style and eslint, as well as run all tests.
-You can run the same check with `pnpm check`
+When opening a PR, the CI runner will (once approved by a human) check the code style and eslint, as well as run all tests. You can run the same check with `pnpm check`.
 
 ## Package Workflow
 

From 960f1de9d2d125c95737b73abaf382fcfe4b5ab7 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 12:16:54 +0000
Subject: [PATCH 44/48] tweaks

---
 CONTRIBUTING.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4cf5d9e..10146bec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,7 +10,7 @@ Along with many other live coding projects, we have moved from Microsoft's Githu
 
 To get in touch with the community, either
 
-- [join the Tidal Discord Channel](https://discord.com/invite/HGEdXmRkzT) and go to the #strudel channels
+- [join the Uzulang Discord Server](https://discord.com/invite/HGEdXmRkzT) and go to the strudel channels (Uzulangs are a family of live coding languages inspired by each other, including TidalCycles as well as Strudel)
 - Find related discussions on the [tidal club forum](https://club.tidalcycles.org/)
 
 ## Ask a Question
@@ -42,9 +42,9 @@ If you want a specific feature that is not part of strudel yet, feel free to use
 
 ## Contribute a feature
 
-It's generally best to start with discussion rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
+Pull requests welcome! Consider starting with discussion or proof-of-concept first, rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
 
-## AI/LLM policy
+### AI/LLM policy
 
 Strudel is a project handmade by humans, with a lot of thought and nuance. We are still developing our response to the onslaught of LLM technology.
 

From 96835be056e626020b6917ab8fad2cbcbcae1232 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 15:07:57 +0000
Subject: [PATCH 45/48] tweaks

---
 CONTRIBUTING.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 10146bec..b8a941fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,7 +34,7 @@ Use one of the Communication Channels listed above.
 
 ## Improve the Docs
 
-If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeburg. There are "Edit this page" links in the right sidebar that take you to the right place.
+If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeberg. There are "Edit this page" links in the right sidebar that take you to the right place.
 
 ## Propose a Feature
 
@@ -44,11 +44,13 @@ If you want a specific feature that is not part of strudel yet, feel free to use
 
 Pull requests welcome! Consider starting with discussion or proof-of-concept first, rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
 
+At the time of writing we have a PR backlog, and generally prioritise bugfixes and contributions that have arisen through community discussion.
+
 ### AI/LLM policy
 
-Strudel is a project handmade by humans, with a lot of thought and nuance. We are still developing our response to the onslaught of LLM technology.
+Strudel is a project handmade by humans, with thought and nuance. 
 
-If you have used LLMs (so called 'AI'), please make that clear in the pull request. If code is LLM-generated/isn't your own work, then the PR will not be merged, for practical and legal reasons.
+If you have used LLMs (so called 'AI'), please detail that in the pull request. We are still developing our response to the onslaught of LLM technology, but for practical and legal reasons are currently not accepting wholly LLM-generated code. We are also not accepting PRs that add LLM features to strudel itself.
 
 There are #llm-chat and #llm-share channels on our discord. Please do not discuss or share LLM-related things outside of those channels.
 

From 8cbe4b945cfbd050ddbd85755c459a65135a90f0 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 16:39:08 +0000
Subject: [PATCH 46/48] Respond to glossing's review

---
 packages/core/impure.mjs | 35 +++++++++++++++++++++++++++++------
 packages/core/repl.mjs   |  4 ++++
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/packages/core/impure.mjs b/packages/core/impure.mjs
index e16cfbe4..84886aa4 100644
--- a/packages/core/impure.mjs
+++ b/packages/core/impure.mjs
@@ -8,24 +8,48 @@ import { register, reify, Pattern } from './pattern.mjs';
 
 let timelines = {};
 
+export const reset_state = function () {
+  reset_timelines();
+};
+
 export const reset_timelines = function () {
   timelines = {};
 };
 
+/***
+ * Allows you to switch a pattern between different 'timelines'. This is particularly useful when
+ * live coding, for example when you want to cue a pattern up to play from its start.
+ *
+ * Timelines are specified by number, so that if you had a pattern like
+ * `n("<0 1 2 3>").s("num").timeline(1)` playing, then changed the '1'
+ * to '2', it would always align '0' to the nearest cycle. You will likely want to trigger
+ * an evaluation a little bit before the cycle starts, to avoid missing events.
+ *
+ * If you change and evaluate a pattern without changing the timeline, it will stay on that timeline
+ * without resetting.
+ *
+ * Rather than incrementing a timeline to reset it, it's easier to negate it, e.g. by switching between `-2`
+ * and `2`. This is because when you negate a timeline it will always reset.
+ *
+ * You can also pattern the timeline if you want, to create strange resetting patterns.
+ */
+
 export const timeline = register(
   'timeline',
   function (tpat, pat) {
     tpat = reify(tpat);
     const f = function (state) {
-      let scheduler = !!state.controls._cps;
+      // Is this called from the scheduler? (rather than from e.g. the visualiser)
+      const scheduler = !!state.controls._cyclist;
 
       const timehaps = tpat.query(state);
       const result = [];
       for (const timehap of timehaps) {
         const tlid = timehap.value;
-        const ignore = false;
         let offset;
-        if (tlid in timelines) {
+        if (tlid === 0) {
+          offset = 0;
+        } else if (tlid in timelines) {
           offset = timelines[tlid];
         } else {
           const timearc = timehap.wholeOrPart();
@@ -40,9 +64,8 @@ export const timeline = register(
         if (scheduler) {
           // update state
           timelines[tlid] = offset;
-          const negative = 0 - tlid;
-          if (negative in timelines) {
-            delete timelines[negative];
+          if (tlid !== 0) {
+            delete timelines[-tlid];
           }
         }
 
diff --git a/packages/core/repl.mjs b/packages/core/repl.mjs
index 171697eb..cd78cca4 100644
--- a/packages/core/repl.mjs
+++ b/packages/core/repl.mjs
@@ -5,6 +5,7 @@ import { errorLogger, logger } from './logger.mjs';
 import { setTime } from './time.mjs';
 import { evalScope } from './evaluate.mjs';
 import { register, Pattern, isPattern, silence, stack } from './pattern.mjs';
+import { reset_state } from './impure.mjs';
 
 export function repl({
   defaultOutput,
@@ -52,6 +53,9 @@ export function repl({
     onToggle: (started) => {
       updateState({ started });
       onToggle?.(started);
+      if (!started) {
+        reset_state();
+      }
     },
     setInterval,
     clearInterval,

From 37990b459f3571d4b254ca99030e21d4cf836104 Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 16:51:25 +0000
Subject: [PATCH 47/48] bugfix and tweak doc

---
 packages/core/impure.mjs | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/packages/core/impure.mjs b/packages/core/impure.mjs
index 84886aa4..304f801f 100644
--- a/packages/core/impure.mjs
+++ b/packages/core/impure.mjs
@@ -25,13 +25,21 @@ export const reset_timelines = function () {
  * to '2', it would always align '0' to the nearest cycle. You will likely want to trigger
  * an evaluation a little bit before the cycle starts, to avoid missing events.
  *
- * If you change and evaluate a pattern without changing the timeline, it will stay on that timeline
- * without resetting.
+ * After the first use, a timeline will continue with the same 'offset'. That is, if you change
+ * a pattern without changing its timeline number, it will stay on that timeline without resetting.
  *
  * Rather than incrementing a timeline to reset it, it's easier to negate it, e.g. by switching between `-2`
  * and `2`. This is because when you negate a timeline it will always reset.
  *
  * You can also pattern the timeline if you want, to create strange resetting patterns.
+ * @param {number | Pattern} timeline The timeline that the pattern should play on.
+ * @example
+ * n("<0 1 2 3>(3,8)")
+ *   .sound("num")
+ *   // resets the timeline every two cycles, by negating the timeline.
+ *   // in a lot of cases this will be edited by a human live coder
+ *   // rather than patterned!
+ *   .timeline("<2 -2>".slow(2))
  */
 
 export const timeline = register(
@@ -40,8 +48,7 @@ export const timeline = register(
     tpat = reify(tpat);
     const f = function (state) {
       // Is this called from the scheduler? (rather than from e.g. the visualiser)
-      const scheduler = !!state.controls._cyclist;
-
+      const scheduler = !!state.controls.cyclist;
       const timehaps = tpat.query(state);
       const result = [];
       for (const timehap of timehaps) {

From c6e0f0533e927a878339a9828c32d21ac9115a7c Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Thu, 11 Dec 2025 23:32:10 +0000
Subject: [PATCH 48/48] add delta

---
 packages/core/signal.mjs                  |  9 ++++
 test/__snapshots__/examples.test.mjs.snap | 53 +++++++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/packages/core/signal.mjs b/packages/core/signal.mjs
index 62fc26ad..9ac76895 100644
--- a/packages/core/signal.mjs
+++ b/packages/core/signal.mjs
@@ -882,3 +882,12 @@ export const whenKey = register('whenKey', function (input, func, pat) {
 export const keyDown = register('keyDown', function (pat) {
   return pat.fmap(_keyDown);
 });
+
+/**
+ * A pattern that gives the duration of events that are combined with it.
+ * @example
+ * sound("bd sd [bd bd] sd*4 [- sd] [bd [bd bd]]").note(delta.withValue(x => 1/x + 20))
+ */
+export const delta = new Pattern(function (state) {
+  return [new Hap(undefined, state.span, state.span.duration)];
+});
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 09d285b5..17dcb08b 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -2784,6 +2784,59 @@ exports[`runs examples > example "delaysync" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "delta" example index 0 1`] = `
+[
+  "[ 0/1 → 1/6 | s:bd note:26 ]",
+  "[ 1/6 → 1/3 | s:sd note:26 ]",
+  "[ 1/3 → 5/12 | s:bd note:32 ]",
+  "[ 5/12 → 1/2 | s:bd note:32 ]",
+  "[ 1/2 → 13/24 | s:sd note:44 ]",
+  "[ 13/24 → 7/12 | s:sd note:44 ]",
+  "[ 7/12 → 5/8 | s:sd note:44 ]",
+  "[ 5/8 → 2/3 | s:sd note:44 ]",
+  "[ 3/4 → 5/6 | s:sd note:32 ]",
+  "[ 5/6 → 11/12 | s:bd note:32 ]",
+  "[ 11/12 → 23/24 | s:bd note:44 ]",
+  "[ 23/24 → 1/1 | s:bd note:44 ]",
+  "[ 1/1 → 7/6 | s:bd note:26 ]",
+  "[ 7/6 → 4/3 | s:sd note:26 ]",
+  "[ 4/3 → 17/12 | s:bd note:32 ]",
+  "[ 17/12 → 3/2 | s:bd note:32 ]",
+  "[ 3/2 → 37/24 | s:sd note:44 ]",
+  "[ 37/24 → 19/12 | s:sd note:44 ]",
+  "[ 19/12 → 13/8 | s:sd note:44 ]",
+  "[ 13/8 → 5/3 | s:sd note:44 ]",
+  "[ 7/4 → 11/6 | s:sd note:32 ]",
+  "[ 11/6 → 23/12 | s:bd note:32 ]",
+  "[ 23/12 → 47/24 | s:bd note:44 ]",
+  "[ 47/24 → 2/1 | s:bd note:44 ]",
+  "[ 2/1 → 13/6 | s:bd note:26 ]",
+  "[ 13/6 → 7/3 | s:sd note:26 ]",
+  "[ 7/3 → 29/12 | s:bd note:32 ]",
+  "[ 29/12 → 5/2 | s:bd note:32 ]",
+  "[ 5/2 → 61/24 | s:sd note:44 ]",
+  "[ 61/24 → 31/12 | s:sd note:44 ]",
+  "[ 31/12 → 21/8 | s:sd note:44 ]",
+  "[ 21/8 → 8/3 | s:sd note:44 ]",
+  "[ 11/4 → 17/6 | s:sd note:32 ]",
+  "[ 17/6 → 35/12 | s:bd note:32 ]",
+  "[ 35/12 → 71/24 | s:bd note:44 ]",
+  "[ 71/24 → 3/1 | s:bd note:44 ]",
+  "[ 3/1 → 19/6 | s:bd note:26 ]",
+  "[ 19/6 → 10/3 | s:sd note:26 ]",
+  "[ 10/3 → 41/12 | s:bd note:32 ]",
+  "[ 41/12 → 7/2 | s:bd note:32 ]",
+  "[ 7/2 → 85/24 | s:sd note:44 ]",
+  "[ 85/24 → 43/12 | s:sd note:44 ]",
+  "[ 43/12 → 29/8 | s:sd note:44 ]",
+  "[ 29/8 → 11/3 | s:sd note:44 ]",
+  "[ 15/4 → 23/6 | s:sd note:32 ]",
+  "[ 23/6 → 47/12 | s:bd note:32 ]",
+  "[ 47/12 → 95/24 | s:bd note:44 ]",
+  "[ 95/24 → 4/1 | s:bd note:44 ]",
+]
+`;
+
 exports[`runs examples > example "density" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | s:crackle density:0.01 ]",