@m4l-jweb/build 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,6 @@
     "archiver": "^7.0.1",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "0.4.0"
+    "@m4l-jweb/wrapper": "0.5.0"
   }
 }

package/src/chains.mjs

@@ -5,9 +5,17 @@
  * `lines` (cords: [sourceBox, outlet] -> [destBox, inlet]). So we never draw
  * one - we generate it. Patch cords become code review.
  *
- * A chain is a small function that claims [jweb]'s outlet, routes the selectors
- * it owns, and passes everything else on to `unmatchedTo`. Add your own with
- * `registerChain()`; keep them small and named after what they do.
+ * A chain is a small function that claims a STAGE and hands the rest on. There
+ * are two streams to claim a stage in, and both work the same way:
+ *
+ *   the app's messages  `claimAppMessages(ctx, myRoute, unmatchedOutlet)`
+ *   the signal path     `ctx.audioIn(ch)` / `ctx.setAudioOut(ch, id, outlet)`
+ *
+ * A chain never OWNS either stream. It takes what the stage before it left, and
+ * says what it leaves for the stage after it - which is what makes
+ * `chains: ["lowpass", "gain"]` a series rather than two devices fighting over one
+ * patcher. Add your own with `registerChain()`; keep them small and named after
+ * what they do.
  */
 
 let y = 300; // stack generated objects below the hand-made ones
@@ -96,6 +104,108 @@ export function claimAppMessages(ctx, routeId, unmatchedOutlet) {
   ctx.appOut = [routeId, unmatchedOutlet];
 }
 
+/* ------------------------------------------------------------------ *
+ * The signal path
+ * ------------------------------------------------------------------ */
+
+/** The device's audio endpoints. Created by the BUILD, never by a chain. */
+export const AUDIO_IN = "obj-plugin";
+export const AUDIO_OUT = "obj-plugout";
+
+/** plugin~ hands us a stereo pair, so every stage is a pair of signal objects. */
+export const AUDIO_CHANNELS = 2;
+
+/**
+ * Create the device's audio endpoints, once, before any chain runs.
+ *
+ * THIS IS THE FIX FOR A SILENT BUG. Every audio chain used to create `plugin~` and
+ * `plugout~` for itself and wire itself between them - so each one was a whole
+ * device, not a stage in one. `chains: ["lowpass", "gain"]` emitted two boxes
+ * sharing the id `obj-plugin`, two sharing `obj-plugout`, and FOUR sources summing
+ * into the output: the filtered pair and the unfiltered gain pair, in parallel. The
+ * effects did not stack, they mixed - with no error at build time and none in Live.
+ * It just sounded wrong in a way you would blame on your DSP.
+ *
+ * So the endpoints belong to the device, and a chain occupies a STAGE between them:
+ *
+ *   [plugin~] -> [onepole~] -> [*~] -> [plugout~]
+ *                 "lowpass"   "gain"
+ *
+ * `ctx.audioIn(ch)` is whatever the last stage left on that channel - `plugin~` if
+ * you are the first. `ctx.setAudioOut(ch, id, outlet)` says you are the tail now.
+ * `closeAudio()` wires the final tail into `plugout~` once every chain has run.
+ *
+ * It is the same shape as `claimAppMessages()` one layer down: several things want
+ * one stream, so they are chained in SERIES with an explicit hand-off rather than
+ * hung off the source in parallel.
+ */
+export function openAudio(ctx) {
+  const { boxes, lines, device } = ctx;
+  const type = device?.type;
+
+  if (type !== "audio" && type !== "instrument") {
+    // A MIDI effect has no signal path at all. Say so when a chain asks for one,
+    // rather than emitting a cord from a box that does not exist - which Max opens
+    // as a patcher with a missing object and no explanation.
+    const refuse = () => {
+      throw new Error(
+        `a chain on device "${device?.name}" asked for the signal path, but the device is type "${type}". ` +
+          `plugin~/plugout~ exist only in an audio-effect or instrument device: set \`type: "audio"\` in patcher/devices.mjs.`,
+      );
+    };
+    ctx.audioIn = refuse;
+    ctx.setAudioOut = refuse;
+    return;
+  }
+
+  // An audio effect has no MIDI ports. An instrument keeps them: MIDI in is how it
+  // is played.
+  if (type === "audio") {
+    removeBox(boxes, lines, "obj-midiin");
+    removeBox(boxes, lines, "obj-midiout");
+  }
+
+  boxes.push(box(AUDIO_IN, "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
+  boxes.push(box(AUDIO_OUT, "plugout~", { numinlets: 2, numoutlets: 0 }));
+
+  // The tail of the signal path, per channel. Nothing has claimed a stage yet, so
+  // it is the input: a device with no audio chain at all is a straight wire.
+  ctx.audioTail = Array.from({ length: AUDIO_CHANNELS }, (_, ch) => [AUDIO_IN, ch]);
+  ctx.audioIn = (ch) => ctx.audioTail[ch];
+  ctx.setAudioOut = (ch, id, outlet = 0) => {
+    ctx.audioTail[ch] = [id, outlet];
+  };
+}
+
+/** Wire whatever the last stage left into `plugout~`. The build calls this last. */
+export function closeAudio(ctx) {
+  if (!ctx.audioTail) return; // not an audio device
+  ctx.audioTail.forEach(([srcId, srcOut], ch) => ctx.lines.push(line(srcId, srcOut, AUDIO_OUT, ch)));
+}
+
+/**
+ * Two boxes with one id is a MALFORMED patcher, and Max resolves it however it
+ * likes - so the device loads, and the cords go somewhere nobody chose. That was
+ * the visible half of the audio-chain bug, and nothing rejected it. This does.
+ *
+ * The build calls it after every chain and the Surface have run, on the patcher
+ * that is about to be written, so it covers the canned chains, a device repo's own
+ * `patcher/chains.mjs`, and the template underneath both.
+ */
+export function assertUniqueBoxIds(boxes, deviceName) {
+  const seen = new Set();
+  const dupes = new Set();
+  for (const { box: b } of boxes) (seen.has(b.id) ? dupes : seen).add(b.id);
+  if (dupes.size) {
+    throw new Error(
+      `device "${deviceName}" generated duplicate box ids: ${[...dupes].join(", ")}. ` +
+        `Two boxes with one id is a patcher Max will interpret however it likes. ` +
+        `A chain that creates a box another chain also creates is not a stage - it is claiming to be the whole device. ` +
+        `Take the stage before you (ctx.audioIn / ctx.appOut) and hand yours on, or name your boxes after your chain.`,
+    );
+  }
+}
+
 /**
  * "midiin" - feed incoming MIDI notes to the app as `notein <pitch> <velocity>`.
  *
@@ -172,25 +282,23 @@ function midiOutChain(ctx) {
 /**
  * "passthrough" - an audio effect that passes its input through UNTOUCHED.
  *
- * It is a straight wire: `plugin~ -> plugout~`. Removing it from a track sounds
+ * It claims no stage, so the signal path stays what the build left it:
+ * `plugin~ -> plugout~`, a straight wire. Removing the device from a track sounds
  * identical, because it does nothing to the audio - it exists to prove that an
  * audio-effect container builds and that the UI runs inside one.
  *
- * It is a scaffold, not a feature. If you want an audio effect that is audible,
- * you want `gain` below, or your own chain shaped like it.
+ * It is a scaffold, not a feature, and since the build now creates the endpoints it
+ * is also a NO-OP: `type: "audio"` with no chains at all does exactly this. It
+ * survives because `chains: ["passthrough"]` says out loud what an empty list only
+ * implies. If you want an audio effect that is audible, you want `gain` below, or
+ * your own chain shaped like it.
  */
-function passthroughChain({ boxes, lines }) {
-  // An audio effect has no MIDI ports.
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
-  lines.push(line("obj-plugin", 0, "obj-plugout", 0));
-  lines.push(line("obj-plugin", 1, "obj-plugout", 1));
+function passthroughChain(ctx) {
+  ctx.audioIn(0); // ...and hand it straight on. Also asserts the device HAS audio.
 }
 
 /**
- * "gain" - an audio effect that actually DOES something: `plugin~ -> *~ -> plugout~`,
+ * "gain" - an audio effect that actually DOES something: `*~` in the signal path,
  * with a Live parameter riding the multiplier. Turn the dial, hear the level move.
  *
  * The smallest honest example of the shape every audio effect has - your DSP goes
@@ -208,23 +316,18 @@ function passthroughChain({ boxes, lines }) {
  */
 function gainChain(ctx) {
   const { boxes, lines, device } = ctx;
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-
   const paramId = requireParam(ctx, "gain", device?.gainParam ?? "gain", "gainParam");
 
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
-
   // One *~ per channel: a signal object handles ONE signal, and plugin~ hands us
   // a stereo pair. `1.` (a float, not an int) keeps the right inlet in float mode.
-  for (const [i, id] of [
+  for (const [ch, id] of [
     [0, "obj-gain-l"],
     [1, "obj-gain-r"],
   ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch); // whatever the last stage left
     boxes.push(box(id, "*~ 1.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
-    lines.push(line("obj-plugin", i, id, 0));
-    lines.push(line(id, 0, "obj-plugout", i));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0); // we are the tail now
     fanParamInto(ctx, paramId, id, 1);
   }
 }
@@ -243,6 +346,14 @@ function gainChain(ctx) {
  *
  * The boxes named here are created LATER, by applySurface(). A patchline may name a
  * box further down the array: a patcher is a graph, not a script.
+ *
+ * THE VALUE ARRIVES IN REAL UNITS, AND A CHAIN DOES NO ARITHMETIC ON IT. The range,
+ * the unit and the curve live on the PARAMETER (`range: [40, 18000]`, `unit: "Hz"`,
+ * `exponent`) - which is where Live wants them: the automation lane reads Hz, Push
+ * reads "7.3 kHz", and the number drops straight into the DSP object. `lowpass`
+ * used to take a 0-1 parameter and map it with `[expr 40. * pow(450., $f1)]`; a
+ * chain that reintroduces a mapping like that DOUBLE-MAPS a parameter that already
+ * carries its own curve, and lies to every readout while it does it.
  */
 function fanParamInto(ctx, paramId, dstId, dstInlet) {
   const [objId, objOut] = ctx.paramObject(paramId);
@@ -273,7 +384,7 @@ function requireParam(ctx, chainName, paramId, overrideField) {
  * parameter via `set_cutoff` - so moving it moves the dial, the automation lane
  * and the filter together. It is one control, with two faces.
  *
- * `plugin~ -> onepole~ -> plugout~`, one filter per channel.
+ * `onepole~` in the signal path, one filter per channel.
  *
  * WHY onepole~ and not lores~/svf~/biquad~: a one-pole is a 6 dB/octave slope -
  * the gentlest filter there is. It cannot self-oscillate, cannot blow up, and
@@ -293,23 +404,18 @@ function requireParam(ctx, chainName, paramId, overrideField) {
  */
 function lowpassChain(ctx) {
   const { boxes, lines, device } = ctx;
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-
   const paramId = requireParam(ctx, "lowpass", device?.cutoffParam ?? "cutoff", "cutoffParam");
 
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
-
   // One filter per channel: a signal object handles ONE signal, and plugin~ hands
   // us a stereo pair. Both take the same cutoff, so the image does not shift.
-  for (const [i, id] of [
+  for (const [ch, id] of [
     [0, "obj-lpf-l"],
     [1, "obj-lpf-r"],
   ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
     boxes.push(box(id, "onepole~ 18000.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
-    lines.push(line("obj-plugin", i, id, 0));
-    lines.push(line(id, 0, "obj-plugout", i));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0);
     // The cutoff, in Hz, into the RIGHT inlet - from both of its sources: the dial
     // (a knob turn, an automation lane, a Push encoder) and the route (the app's
     // write, which the dial will not re-emit because it arrives as `set`).
@@ -317,12 +423,52 @@ function lowpassChain(ctx) {
   }
 }
 
+/**
+ * "drive" - soft-clipping distortion: an `overdrive~` in the signal path, with a
+ * Live parameter on the drive factor.
+ *
+ * THE CHAIN WHOSE PLACE IN THE LIST YOU CAN HEAR, and it is in the vocabulary for
+ * that reason as much as for the sound. `lowpass` and `gain` are both LINEAR, so
+ * they commute: `["lowpass", "gain"]` and `["gain", "lowpass"]` generate different
+ * patchers and produce identical audio. A composition built only from those two
+ * cannot be verified by ear - you would reorder them, hear nothing change, and
+ * reasonably conclude the build was broken.
+ *
+ * Distortion does not commute with a level change. `["gain", "drive"]` turns the
+ * signal down and THEN distorts it, so a quiet input barely clips; `["drive",
+ * "gain"]` distorts at full level and turns the result down, so it stays dirty and
+ * gets quieter. Same two chains, same parameters, unmistakably different sound -
+ * which is what makes the series real rather than a claim in a test.
+ *
+ * `overdrive~` limits to +/- 1 and takes its drive factor (1 = clean, 10 = filthy)
+ * in the RIGHT inlet, per Max's own reference. Below 1 it distorts violently; the
+ * parameter's range starts at 1, which is where a user would expect "off" to be.
+ *
+ * Requires a parameter named `drive` (or pass `device.driveParam`).
+ */
+function driveChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const paramId = requireParam(ctx, "drive", device?.driveParam ?? "drive", "driveParam");
+
+  for (const [ch, id] of [
+    [0, "obj-drive-l"],
+    [1, "obj-drive-r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    boxes.push(box(id, "overdrive~ 1.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0);
+    fanParamInto(ctx, paramId, id, 1);
+  }
+}
+
 export const CHAINS = {
   midiin: midiInChain,
   midiout: midiOutChain,
   passthrough: passthroughChain,
   gain: gainChain,
   lowpass: lowpassChain,
+  drive: driveChain,
 };
 
 /** Add a chain to the vocabulary. Called before generatePatchers(). */

package/src/index.mjs

@@ -16,7 +16,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { AMXD_TYPES, assertES5, buildAmxd, extraPayloadsJs, payloadJs } from "./amxd.mjs";
-import { CHAINS, resetLayout } from "./chains.mjs";
+import { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, resetLayout } from "./chains.mjs";
 import { applySurface, loadSurface, surfaceContext } from "./surface.mjs";
 
 const require = createRequire(import.meta.url);
@@ -138,6 +138,73 @@ async function loadDeviceChains(root) {
   console.log("m4l-jweb: loaded device chains from patcher/chains.mjs");
 }
 
+/**
+ * One device, one patcher: the template, its chains, its Surface. Pure - it takes
+ * the base patcher and the device's declaration and returns the JSON to write.
+ *
+ * It is exported because the tests generate patchers too, and a test that
+ * assembled the pipeline itself could pass while the build wired something else.
+ * The ORDER below is the pipeline, and every step of it is load-bearing:
+ *
+ *   openAudio      the device's plugin~/plugout~, created ONCE, before any chain -
+ *                  so a chain is a stage in the signal path, not the owner of it.
+ *   the chains     in declaration order, each taking what the last one left.
+ *   applySurface   LAST of the message-stream claimants: it routes every `set_<id>`
+ *                  off the app's stream and passes on what nobody claimed
+ *                  (ui_ready, ...) to the wrapper. Doing it last means no chain has
+ *                  to know the Surface exists.
+ *   closeAudio     the final stage's output into plugout~.
+ *   assertUnique   two boxes with one id is a malformed patcher, and Max resolves
+ *                  it however it likes. Nothing else would report it.
+ */
+export function composePatcher(base, d, surface) {
+  const amxdtype = AMXD_TYPES[d.type];
+  if (!amxdtype) throw new Error(`unknown type "${d.type}" for device "${d.name}" (midi | audio | instrument)`);
+
+  const p = structuredClone(base);
+  const { boxes, lines } = p.patcher;
+  p.patcher.project.amxdtype = amxdtype;
+  resetLayout();
+
+  // The wrapper is mode-switched by its object-box argument. `mode` defaults
+  // to the device type, but they are not always the same thing: a sample
+  // player can be an audio-effect device ("type") that the wrapper must treat
+  // as a sampler ("mode").
+  //
+  // jsarguments[0] is the SCRIPT NAME, so the mode lands at jsarguments[1].
+  const mode = d.mode ?? d.type;
+  boxes.find((b) => b.box.id === "obj-js").box.text = `js wrapper.js ${mode}`;
+
+  const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
+
+  /**
+   * The device's parameters, declared once in src/app/<ui>/surface.ts. A chain
+   * that drives DSP from a parameter needs two things from it, and needs BOTH:
+   *
+   *   paramObject(id)  the live.* object's outlet - a knob turn, an automation
+   *                    lane, a Push encoder.
+   *   paramValue(id)   the route outlet carrying what the APP wrote. Not
+   *                    redundant: the app's write reaches the object as `set`,
+   *                    which updates it WITHOUT output, so the object would
+   *                    never pass that value on. See surface.mjs.
+   */
+  const ctx = { boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d, ...surfaceContext(surface) };
+
+  openAudio(ctx);
+
+  for (const name of d.chains ?? []) {
+    const chain = CHAINS[name];
+    if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
+    chain(ctx);
+  }
+
+  applySurface(ctx);
+  closeAudio(ctx);
+  assertUniqueBoxIds(boxes, d.name);
+
+  return p;
+}
+
 export async function generatePatchers(root) {
   const devices = await readManifest(root);
   const base = readBase(root);
@@ -146,36 +213,6 @@ export async function generatePatchers(root) {
   mkdirSync(outDir, { recursive: true });
 
   for (const d of devices) {
-    const amxdtype = AMXD_TYPES[d.type];
-    if (!amxdtype) throw new Error(`unknown type "${d.type}" for device "${d.name}" (midi | audio | instrument)`);
-
-    const p = structuredClone(base);
-    const { boxes, lines } = p.patcher;
-    p.patcher.project.amxdtype = amxdtype;
-    resetLayout();
-
-    // The wrapper is mode-switched by its object-box argument. `mode` defaults
-    // to the device type, but they are not always the same thing: a sample
-    // player can be an audio-effect device ("type") that the wrapper must treat
-    // as a sampler ("mode").
-    //
-    // jsarguments[0] is the SCRIPT NAME, so the mode lands at jsarguments[1].
-    const mode = d.mode ?? d.type;
-    boxes.find((b) => b.box.id === "obj-js").box.text = `js wrapper.js ${mode}`;
-
-    const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
-
-    /**
-     * The device's parameters, declared once in src/app/<ui>/surface.ts. A chain
-     * that drives DSP from a parameter needs two things from it, and needs BOTH:
-     *
-     *   paramObject(id)  the live.* object's outlet - a knob turn, an automation
-     *                    lane, a Push encoder.
-     *   paramValue(id)   the route outlet carrying what the APP wrote. Not
-     *                    redundant: the app's write reaches the object as `set`,
-     *                    which updates it WITHOUT output, so the object would
-     *                    never pass that value on. See surface.mjs.
-     */
     // The manifest carried `parameters` until 0.4.0. It is now declared in
     // src/app/<ui>/surface.ts and generated from there - so a leftover field is not
     // a harmless extra key, it is a device whose parameters have SILENTLY
@@ -185,22 +222,12 @@ export async function generatePatchers(root) {
         `device "${d.name}" still declares \`parameters\` in patcher/devices.mjs. ` +
           `That field is gone: declare them in src/app/${d.ui ?? d.name}/surface.ts with defineSurface(), ` +
           `which generates the live.* objects, both wiring directions and the protocol selectors. ` +
-          `See doc/SURFACE.md.`,
+          `See doc/ARCHITECTURE.md - "Parameters: the Surface Push reads".`,
       );
     }
 
     const surface = await loadSurface(root, d.ui ?? d.name);
-    const ctx = { boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d, ...surfaceContext(surface) };
-
-    for (const name of d.chains ?? []) {
-      const chain = CHAINS[name];
-      if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
-      chain(ctx);
-    }
-
-    // AFTER the chains: the Surface routes every `set_<id>` off the app's message
-    // stream, and passes on what nobody claimed (ui_ready, ...) to the wrapper.
-    applySurface(ctx);
+    const p = composePatcher(base, d, surface);
 
     writeFileSync(path.join(outDir, `${d.name}.json`), JSON.stringify(p, null, "\t"));
     const params = surface ? surface.ids.join(", ") : "none";

package/templates/starter/package.json

@@ -17,13 +17,13 @@
     "format": "prettier --write \"src/**/*.{ts,tsx,css}\" \"scripts/*.mjs\" \"patcher/*.mjs\""
   },
   "dependencies": {
-    "@m4l-jweb/bridge": "^0.4.0",
-    "@m4l-jweb/surface": "^0.4.0",
+    "@m4l-jweb/bridge": "^0.5.0",
+    "@m4l-jweb/surface": "^0.5.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^0.4.0",
+    "@m4l-jweb/build": "^0.5.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/starter/patcher/devices.mjs

@@ -15,10 +15,20 @@
  *                               <chan> <delayMs>` (see sendNote()); pipe +
  *                               makenote + midiformat place it on Max's
  *                               scheduler. The app computes WHEN.
- *                 "lowpass"     plugin~ -> onepole~ -> plugout~, with a `cutoff`
+ *                 "lowpass"     onepole~ in the signal path, with a `cutoff`
  *                               parameter. An audio effect you can hear.
- *                 "gain"        plugin~ -> *~ -> plugout~, with a `gain` parameter.
- *                 "passthrough" plugin~ -> plugout~. Does nothing to the audio.
+ *                 "drive"       overdrive~ in the signal path, with a `drive`
+ *                               parameter. Soft-clipping distortion.
+ *                 "gain"        *~ in the signal path, with a `gain` parameter.
+ *                 "passthrough" nothing at all. Does not touch the audio.
+ *
+ *               THE ORDER IS THE SIGNAL PATH. An audio device's plugin~/plugout~
+ *               are created by the build; each audio chain claims one STAGE
+ *               between them, so `["lowpass", "drive", "gain"]` is
+ *               plugin~ -> onepole~ -> overdrive~ -> *~ -> plugout~. Reorder the
+ *               list and the device is rewired - and with a nonlinear stage like
+ *               `drive` in it, you can hear the difference. (Two LINEAR stages
+ *               commute: swapping "lowpass" and "gain" sounds identical.)
  *   unmatchedTo where messages the chains did not consume go. "js" sends them to
  *               the wrapper (ui_ready, ...).
  *