@m4l-jweb/build 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.6.0",
+  "version": "0.7.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.6.0"
+    "@m4l-jweb/wrapper": "0.7.0"
   }
 }

package/src/chains.mjs

@@ -363,7 +363,7 @@ function gainChain(ctx) {
  * 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) {
+export function fanParamInto(ctx, paramId, dstId, dstInlet) {
   const [objId, objOut] = ctx.paramObject(paramId);
   const [routeId, routeOut] = ctx.paramValue(paramId);
   ctx.lines.push(line(objId, objOut, dstId, dstInlet));
@@ -611,6 +611,22 @@ function samplesChain(ctx) {
   );
   lines.push(line("obj-samples-rate", 0, "obj-samples-groove", 0));
 
+  // MONO FOLD. `groove~ <buf> 2` hard-wires two signal outlets to L and R, and a
+  // MONO buffer drives outlet 0 ONLY - so a mono file (most of tidal-drum-machines
+  // is mono) plays in one ear. The channel count is not a build-time fact: [info~]
+  // MEASURES it when the buffer loads. So gate the R channel at RUNTIME - a
+  // [selector~ 2] whose control says which groove~ outlet is the real right channel:
+  //   input 1 = groove~ outlet 1 (a stereo file's true R)
+  //   input 2 = groove~ outlet 0 (fold the mono signal to R as well)
+  // The control is the currently-loaded slot's channel count run through
+  // [expr ($i1==1)+1]: mono(1) -> 2 (fold), stereo(2) -> 1 (real R). The L channel
+  // always takes groove~ outlet 0, so it needs no gate.
+  boxes.push(box("obj-samples-rsel", "selector~ 2", { numinlets: 3, numoutlets: 1, outlettype: ["signal"] }));
+  boxes.push(box("obj-samples-rgate", "expr ($i1==1)+1", { numinlets: 1, numoutlets: 1, outlettype: ["int"] }));
+  lines.push(line("obj-samples-groove", 1, "obj-samples-rsel", 1)); // stereo R -> input 1
+  lines.push(line("obj-samples-groove", 0, "obj-samples-rsel", 2)); // mono fold -> input 2
+  lines.push(line("obj-samples-rgate", 0, "obj-samples-rsel", 0)); // which one, per loaded slot
+
   // Stop: a bare `buffer_stop` arrives from [route] as a BANG - the word is gone -
   // so re-materialize it in a message box, or groove~ hears nothing it knows.
   boxes.push(box("obj-samples-stopmsg", "stop", { maxclass: "message", numinlets: 2, numoutlets: 1 }));
@@ -648,18 +664,29 @@ function samplesChain(ctx) {
     lines.push(line(`obj-samples-pack-${slot}`, 0, `obj-samples-ready-${slot}`, 0));
     lines.push(line(`obj-samples-ready-${slot}`, 0, jwebId, 0));
 
+    // Retain THIS slot's measured channel count, so play can re-assert the mono
+    // fold for whichever buffer is loaded into the one shared groove~. [info~]
+    // outlet 8 stores it in [f]'s cold inlet (no output); the play trigger bangs it
+    // out to the shared gate below. Every slot's [f] feeds that one gate.
+    boxes.push(box(`obj-samples-chans-${slot}`, "f", { numinlets: 2, numoutlets: 1, outlettype: [""] }));
+    lines.push(line(info, 8, `obj-samples-chans-${slot}`, 1)); // measured channels, cold-stored
+    lines.push(line(`obj-samples-chans-${slot}`, 0, "obj-samples-rgate", 0));
+
     // Play: pick the buffer, THEN start it. Two cords out of one outlet fire in an
     // order Max chooses, so the sequence goes through a [t b b] - right outlet
     // first - and never through a fan-out. Starting the OLD buffer and then
     // switching is exactly the bug that looks like "the wrong sample previewed".
-    boxes.push(box(`obj-samples-trig-${slot}`, "t b b", { numinlets: 1, numoutlets: 2, outlettype: ["bang", "bang"] }));
+    boxes.push(box(`obj-samples-trig-${slot}`, "t b b b", { numinlets: 1, numoutlets: 3, outlettype: ["bang", "bang", "bang"] }));
     boxes.push(box(`obj-samples-set-${slot}`, `set ${bufName(slot)}`, { maxclass: "message", numinlets: 2, numoutlets: 1 }));
     // A float in groove~'s left inlet is a playback POSITION in ms, and 0 is "from
     // the beginning" - which is also what starts it after a `stop`.
     boxes.push(box(`obj-samples-start-${slot}`, "0", { maxclass: "message", numinlets: 2, numoutlets: 1 }));
 
+    // [t] fires right-to-left, so: set the fold gate, THEN the buffer, THEN start -
+    // the gate and the buffer are both in place before groove~ makes a sound.
     lines.push(line("obj-samples-playslot", i, `obj-samples-trig-${slot}`, 0));
-    lines.push(line(`obj-samples-trig-${slot}`, 1, `obj-samples-set-${slot}`, 0)); // right first: set the buffer
+    lines.push(line(`obj-samples-trig-${slot}`, 2, `obj-samples-chans-${slot}`, 0)); // first: assert the fold
+    lines.push(line(`obj-samples-trig-${slot}`, 1, `obj-samples-set-${slot}`, 0)); // then: set the buffer
     lines.push(line(`obj-samples-trig-${slot}`, 0, `obj-samples-start-${slot}`, 0)); // ...then play it
     lines.push(line(`obj-samples-set-${slot}`, 0, "obj-samples-groove", 0));
     lines.push(line(`obj-samples-start-${slot}`, 0, "obj-samples-groove", 0));
@@ -674,7 +701,372 @@ function samplesChain(ctx) {
     const [srcId, srcOut] = ctx.audioIn(ch);
     boxes.push(box(id, "+~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
     lines.push(line(srcId, srcOut, id, 0));
-    lines.push(line("obj-samples-groove", ch, id, 1));
+    // L takes groove~ outlet 0 directly; R takes the mono-fold [selector~] instead
+    // of groove~ outlet 1, so a mono buffer reaches both ears.
+    if (ch === 0) lines.push(line("obj-samples-groove", 0, id, 1));
+    else lines.push(line("obj-samples-rsel", 0, id, 1));
+    ctx.setAudioOut(ch, id, 0);
+  }
+}
+
+/**
+ * "delay" - a feedback delay, sent from a dry/wet knob: `.delay()`, `.delaytime()`
+ * and `.delayfeedback()` mapped straight onto Max's delay line.
+ *
+ *   dry -->[+~ fbsum]-->[tapin~ 2000]-->[tapout~ 250]--+--> wet
+ *           ^                                          |
+ *           +----------[*~ feedback]<-----------------+
+ *   out = dry + delay * wet
+ *
+ * SEND-STYLE, WHICH IS WHAT MAKES IT NEUTRAL. The dry input reaches the output
+ * summing [+~] at UNITY, untouched; the delayed signal is scaled by the `delay`
+ * mix and added on top. At `delay` = 0 the wet [*~] contributes exactly 0.0, so the
+ * output is bit-for-bit the input - a straight wire, which is the neutrality
+ * contract this chain declares in CHAIN_NEUTRAL below. That is the whole reason a
+ * wet path is SUMMED rather than crossfaded: `dry + 0` is identity, `dry*1 + wet*0`
+ * is too but invites a `1 - mix` no one can null-test by eye.
+ *
+ * tapin~/tapout~, per Max's reference (read on disk, not remembered): tapin~ writes
+ * a signal into a delay line; tapout~ reads it back, and the connection between them
+ * is NOT a signal cord - it is the delay-line link. tapout~'s inlet 0 takes BOTH
+ * that link and the delay time (a float in ms), the same way groove~'s left inlet
+ * takes a signal and messages at once. `tapin~ 2000` sizes the line to the top of
+ * `delaytime`'s range; a delay time past the max is silently clamped, so the max is
+ * a real limit, not decoration.
+ *
+ * Feedback closes the loop THROUGH a [+~] before tapin~, so the delayed signal is
+ * re-injected with the dry input rather than replacing it. At `delayfeedback` = 0
+ * the loop gain is 0 and you get a single echo.
+ *
+ * Requires `delay`, `delaytime`, `delayfeedback` in the device's surface (or point
+ * the chain at other names with `delayParam` / `delaytimeParam` /
+ * `delayfeedbackParam`). All in REAL units: the mix and feedback are 0-1, the time
+ * is in ms - the chain does no arithmetic on any of them.
+ */
+function delayChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const mixParam = requireParam(ctx, "delay", device?.delayParam ?? "delay", "delayParam");
+  const timeParam = requireParam(ctx, "delay", device?.delaytimeParam ?? "delaytime", "delaytimeParam");
+  const fbParam = requireParam(ctx, "delay", device?.delayfeedbackParam ?? "delayfeedback", "delayfeedbackParam");
+
+  for (const [ch, s] of [
+    [0, "l"],
+    [1, "r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    const fbsum = `obj-delay-fbsum-${s}`;
+    const tin = `obj-delay-tapin-${s}`;
+    const tout = `obj-delay-tapout-${s}`;
+    const fb = `obj-delay-fb-${s}`;
+    const wet = `obj-delay-wet-${s}`;
+    const mix = `obj-delay-mix-${s}`;
+
+    boxes.push(box(fbsum, "+~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(tin, "tapin~ 2000", { numinlets: 1, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(tout, "tapout~ 250", { numinlets: 1, numoutlets: 1, outlettype: ["signal"] }));
+    // A float, not int - the feedback and wet gains start at 0.0 so the stage is a
+    // wire until its parameters load, and the right inlets stay in float mode.
+    boxes.push(box(fb, "*~ 0.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(wet, "*~ 0.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(mix, "+~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+
+    // dry (+ feedback) into the delay line
+    lines.push(line(srcId, srcOut, fbsum, 0));
+    lines.push(line(fb, 0, fbsum, 1));
+    lines.push(line(fbsum, 0, tin, 0));
+    lines.push(line(tin, 0, tout, 0)); // the delay-line link, not a signal cord
+    fanParamInto(ctx, timeParam, tout, 0); // delay time, ms, into tapout~'s inlet
+
+    // feedback loop: the tap, scaled, back to the sum
+    lines.push(line(tout, 0, fb, 0));
+    fanParamInto(ctx, fbParam, fb, 1);
+
+    // the send: dry at unity + the tap scaled by `delay`
+    lines.push(line(tout, 0, wet, 0));
+    fanParamInto(ctx, mixParam, wet, 1);
+    lines.push(line(srcId, srcOut, mix, 0));
+    lines.push(line(wet, 0, mix, 1));
+    ctx.setAudioOut(ch, mix, 0);
+  }
+}
+
+/**
+ * "reverb" - `cverb~` sent from a dry/wet knob (`.room()`).
+ *
+ *   dry --+--------------------> [+~ mix] --> out
+ *         |                        ^
+ *         +-->[cverb~]-->[*~ room]-+
+ *
+ * cverb~ SHIPS INSIDE LIVE (`resources/externals/m4l/cverb~.mxe64`, checked on disk)
+ * and is MONAURAL and WET-ONLY: its output is pure reverberation, no dry component.
+ * A wet-only object dropped straight in the path is a colouration you cannot switch
+ * off - the exact trap the neutrality contract exists to forbid. So the dry/wet is a
+ * property of THIS chain, not something a device is trusted to remember: the dry
+ * signal reaches the output [+~] at unity, and the reverb is scaled by `room` and
+ * summed on top. At `room` = 0 the wet [*~] is 0.0 and the output is the input,
+ * bit-for-bit (CHAIN_NEUTRAL below).
+ *
+ * Mono, so one cverb~ per channel. The reverb TIME is fixed at the object's argument
+ * - the `fx` surface exposes only the send (`room`), not a time - so there is no
+ * parameter for it; add one and fan it into inlet 1 (signal/float, reverb time in
+ * ms, per the reference) if a device wants it.
+ *
+ * Requires `room` in the device's surface (or `roomParam`), 0-1.
+ */
+function reverbChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const mixParam = requireParam(ctx, "reverb", device?.roomParam ?? "room", "roomParam");
+
+  for (const [ch, s] of [
+    [0, "l"],
+    [1, "r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    const rv = `obj-reverb-cverb-${s}`;
+    const wet = `obj-reverb-wet-${s}`;
+    const mix = `obj-reverb-mix-${s}`;
+
+    boxes.push(box(rv, "cverb~ 2000.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(wet, "*~ 0.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(mix, "+~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+
+    lines.push(line(srcId, srcOut, rv, 0));
+    lines.push(line(rv, 0, wet, 0));
+    fanParamInto(ctx, mixParam, wet, 1);
+    lines.push(line(srcId, srcOut, mix, 0)); // dry at unity
+    lines.push(line(wet, 0, mix, 1)); // + reverb scaled by `room`
+    ctx.setAudioOut(ch, mix, 0);
+  }
+}
+
+/**
+ * The [poly~] voice patch: ONE played note, start to finish, as its own patcher.
+ *
+ * [poly~] loads N copies of this and hands each `note` message to the first voice
+ * whose [thispoly~] is not busy - so polyphony and voice-stealing are Max's job, not
+ * the app's, which is the whole reason to spend a [poly~] rather than run N groove~s
+ * and a scheduler by hand. Max cannot embed this inline (no factory device does; they
+ * all ship it as a named .maxpat), so the build freezes it into the .amxd as a
+ * dependency and [poly~] resolves it by name from the device's own bundle - the same
+ * way `Analogue Drums.amxd` carries `analog.Kick~.maxpat` (checked on disk).
+ *
+ * MULTI-SAMPLE. A voice can play ANY of the device's slots - one named [buffer~] per
+ * slot - so the instrument is a keymap, not one repitched sample. The voice request at
+ * [in 1] is the list `slot rate velocity durMs channels`:
+ *   - slot       -> which buffer: [sel 0 1 ...] picks the matching `set <bufName>`
+ *                   message, so groove~ switches to that slot's buffer before it starts.
+ *   - rate       -> playback RATE straight into [sig~] -> groove~'s left (signal) inlet.
+ *                   EXPLICIT, not derived: the app decides whether a note plays a
+ *                   dedicated sample at rate 1 or a repitched one at rate 2, which is
+ *                   what makes this a multi-sample keymap rather than one stretched
+ *                   buffer. No pitch->rate arithmetic here.
+ *   - velocity   -> amplitude, /127, on both channels' [*~].
+ *   - durMs      -> when to FREE the voice: [delay durMs] -> 0 to [thispoly~] and
+ *                   `stop` to groove~. The app times the note; Max holds the voice
+ *                   exactly that long. A one-shot past the sample's end is silent
+ *                   anyway (@loop 0), so this only bounds the allocation.
+ *   - channels   -> the mono fold, the SAME runtime gate the samples chain uses: a
+ *                   mono buffer drives groove~ outlet 0 only, so a [selector~ 2] keyed
+ *                   on the measured channel count folds it into R (see samplesChain).
+ *
+ * The order is sequenced with [t]: the whole list reaches [unpack] (buffer selected,
+ * rate, gate and duration all set) BEFORE the voice marks itself busy and starts
+ * groove~ from 0. Buffer-select is separate from start - `set <buf>` switches the
+ * buffer WITHOUT playing, and only the seq's `0` starts it - so a note never begins on
+ * the previous note's buffer or rate.
+ */
+function instrumentVoicePatch(bufNames) {
+  let vy = 40;
+  const vbox = (id, text, extra = {}) => ({
+    box: { id, maxclass: "newobj", text, numinlets: 1, numoutlets: 1, outlettype: [""], patching_rect: [24, (vy += 30), 150, 22], ...extra },
+  });
+  const vmsg = (id, text) => ({
+    box: { id, maxclass: "message", text, numinlets: 2, numoutlets: 1, outlettype: [""], patching_rect: [200, (vy += 30), 90, 22] },
+  });
+
+  const L = (s, so, d, di) => ({ patchline: { source: [s, so], destination: [d, di] } });
+
+  const boxes = [
+    vbox("v-in", "in 1", { numinlets: 0, numoutlets: 1 }),
+    vbox("v-trig", "t b l", { numoutlets: 2, outlettype: ["bang", ""] }),
+    vbox("v-unpack", "unpack 0 0. 0 0 0", { numoutlets: 5, outlettype: ["int", "float", "int", "int", "int"] }),
+    vbox("v-seq", "t b b", { numoutlets: 2, outlettype: ["bang", "bang"] }),
+    vmsg("v-busy", "1"),
+    vmsg("v-start", "0"),
+    vbox("v-thispoly", "thispoly~", { numoutlets: 2, outlettype: ["int", "int"] }),
+    // slot -> which buffer. [sel] fires the matching outlet; the last (rightmost) is
+    // the no-match passthrough, left unwired.
+    vbox("v-sel", `sel ${bufNames.map((_, i) => i).join(" ")}`, { numoutlets: bufNames.length + 1, outlettype: bufNames.map(() => "bang").concat("") }),
+    vbox("v-sig", "sig~", { numoutlets: 1, outlettype: ["signal"] }),
+    vbox("v-vel", "/ 127.", { outlettype: ["float"] }),
+    // groove~ starts on the FIRST slot's buffer; `set` switches it per note.
+    vbox("v-groove", `groove~ ${bufNames[0]} 2 @loop 0`, { numinlets: 3, numoutlets: 3, outlettype: ["signal", "signal", "signal"] }),
+    vbox("v-gate", "expr ($i1==1)+1", { outlettype: ["int"] }),
+    vbox("v-rsel", "selector~ 2", { numinlets: 3, numoutlets: 1, outlettype: ["signal"] }),
+    vbox("v-ampL", "*~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }),
+    vbox("v-ampR", "*~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }),
+    vbox("v-del", "delay", { numinlets: 2, numoutlets: 1, outlettype: ["bang"] }),
+    vbox("v-free", "t b b", { numoutlets: 2, outlettype: ["bang", "bang"] }),
+    vmsg("v-freebusy", "0"),
+    vmsg("v-stop", "stop"),
+    vbox("v-out1", "out~ 1", { numinlets: 1, numoutlets: 0 }),
+    vbox("v-out2", "out~ 2", { numinlets: 1, numoutlets: 0 }),
+  ];
+
+  const lines = [
+    L("v-in", 0, "v-trig", 0),
+    // list first (right outlet), then the start sequence (left) - values before play.
+    L("v-trig", 1, "v-unpack", 0),
+    L("v-trig", 0, "v-seq", 0),
+    L("v-unpack", 0, "v-sel", 0), // slot -> pick a buffer
+    L("v-unpack", 1, "v-sig", 0), // rate (explicit) -> signal rate
+    L("v-sig", 0, "v-groove", 0),
+    L("v-unpack", 2, "v-vel", 0), // velocity -> amp
+    L("v-vel", 0, "v-ampL", 1),
+    L("v-vel", 0, "v-ampR", 1),
+    L("v-unpack", 3, "v-del", 1), // duration -> delay time (cold)
+    L("v-unpack", 4, "v-gate", 0), // channels -> mono fold gate
+    L("v-gate", 0, "v-rsel", 0),
+    // the start sequence: mark busy, then start groove~ from 0 AND arm the free timer.
+    L("v-seq", 1, "v-busy", 0),
+    L("v-busy", 0, "v-thispoly", 0),
+    L("v-seq", 0, "v-start", 0),
+    L("v-start", 0, "v-groove", 0),
+    L("v-seq", 0, "v-del", 0), // bang the delay: it fires after durMs
+    // groove~ out: L direct, R via the mono-fold selector (stereo R vs. folded mono).
+    L("v-groove", 0, "v-ampL", 0),
+    L("v-groove", 1, "v-rsel", 1), // stereo R
+    L("v-groove", 0, "v-rsel", 2), // mono fold
+    L("v-rsel", 0, "v-ampR", 0),
+    L("v-ampL", 0, "v-out1", 0),
+    L("v-ampR", 0, "v-out2", 0),
+    // free the voice when the note's duration elapses.
+    L("v-del", 0, "v-free", 0),
+    L("v-free", 1, "v-freebusy", 0),
+    L("v-freebusy", 0, "v-thispoly", 0),
+    L("v-free", 0, "v-stop", 0),
+    L("v-stop", 0, "v-groove", 0),
+  ];
+
+  // One `set <buffer>, ` message per slot: [sel] outlet i switches groove~ to that
+  // slot's buffer WITHOUT starting it (the seq's `0` does that). A trailing comma
+  // would start it; there is none, deliberately.
+  bufNames.forEach((buf, i) => {
+    const setId = `v-set-${i}`;
+    boxes.push(vmsg(setId, `set ${buf}`));
+    lines.push(L("v-sel", i, setId, 0));
+    lines.push(L(setId, 0, "v-groove", 0));
+  });
+
+  return {
+    patcher: {
+      fileversion: 1,
+      appversion: { major: 8, minor: 0, revision: 0, architecture: "x64", modernui: 1 },
+      rect: [100, 100, 320, 600],
+      boxes,
+      lines,
+    },
+  };
+}
+
+/**
+ * "instrument" - the marquee: a [poly~] of sample voices over a KEYMAP of named
+ * buffers, PLAYED by the note contract the bridge exports. `samples` made the first
+ * sound as ONE preview voice; this is the other half - N voices, N buffers, Max doing
+ * the allocation and stealing.
+ *
+ *   app -> voice_play <slot> <rate> <vel> <durMs> <chans>  -> [route] -> [prepend note] -> [poly~]
+ *          buffer_load <slot> <path>                       -> [js] resolves -> [buffer~ <slot>]
+ *   app <- buffer_ready <slot> <sr> <ms> <chans>            when that slot's read completed
+ *
+ * The load path is the samples chain's, deliberately: the bytes never cross the bridge
+ * ([buffer~] reads the file, the wrapper resolves the path on its aux outlet), and the
+ * reply reports what [info~] MEASURED, not what was asked for. Every slot is its own
+ * named [buffer~]; the voice picks one per note by index and plays it at the rate the
+ * app chose - so a dedicated sample plays at rate 1 and a repitched one at rate 2,
+ * which is the app's decision, not the chain's.
+ *
+ * `slots: ["c", "e", "g"]` in the manifest is three buffers; the default is one
+ * ("voice"). The buffer NAMES are `buf-<device>-<slot>`, global to Max - so two copies
+ * of the device on two tracks name their buffers alike (harmless for a demo, the drum-
+ * rack instance problem noted in doc/TODO.md).
+ *
+ * It SUMS into the signal path ([+~]): an instrument makes sound where there was none
+ * at its input, so there is nothing to claim a stage over.
+ */
+function instrumentChain(ctx) {
+  const { boxes, lines, device, jwebId, unmatchedId } = ctx;
+  const slots = device?.slots ?? ["voice"];
+  const bufName = (slot) => `buf-${device?.name}-${slot}`;
+  const voices = device?.voices ?? 8;
+  const voiceFile = `${device?.name}-voice.maxpat`;
+
+  // The frozen voice patch (a keymap of every slot's buffer), and the [poly~] that
+  // loads N copies of it.
+  ctx.extras.push({ name: voiceFile, data: instrumentVoicePatch(slots.map(bufName)) });
+  // [poly~]'s name is the file WITHOUT its extension, per Max's abstraction lookup.
+  boxes.push(
+    box(`obj-instr-poly`, `poly~ ${voiceFile.replace(/\.maxpat$/, "")} ${voices}`, {
+      numinlets: 1,
+      numoutlets: 2,
+      outlettype: ["signal", "signal"],
+    }),
+  );
+
+  // voice_play -> `note <slot> <rate> <vel> <durMs> <chans>` -> poly~. `route` strips
+  // the selector, leaving the bare args; `prepend note` is the word poly~ dispatches on
+  // to pick a free voice. Claimed in series so ui_ready still reaches the wrapper.
+  boxes.push(box("obj-instr-playroute", "route voice_play", { numoutlets: 2, outlettype: ["", ""] }));
+  claimAppMessages(ctx, "obj-instr-playroute", 1);
+  boxes.push(box("obj-instr-note", "prepend note"));
+  lines.push(line("obj-instr-playroute", 0, "obj-instr-note", 0));
+  lines.push(line("obj-instr-note", 0, "obj-instr-poly", 0));
+
+  // The load path, from the wrapper's aux outlet - identical in shape to samples: a
+  // bare buffer name resolves against MAX'S SEARCH PATH, not the device folder, so the
+  // wrapper resolves it and hands back `buffer_replace <slot> <abs path>`. One buffer
+  // per slot, dispatched by slot name (route matches a whole word).
+  boxes.push(box("obj-instr-replaceroute", "route buffer_replace", { numoutlets: 2, outlettype: ["", ""] }));
+  lines.push(line(unmatchedId, 1, "obj-instr-replaceroute", 0));
+  boxes.push(box("obj-instr-loadslot", `route ${slots.join(" ")}`, { numoutlets: slots.length + 1, outlettype: slots.map(() => "").concat("") }));
+  lines.push(line("obj-instr-replaceroute", 0, "obj-instr-loadslot", 0));
+
+  slots.forEach((slot, i) => {
+    const buf = `obj-instr-buf-${slot}`;
+    const info = `obj-instr-info-${slot}`;
+    boxes.push(box(buf, `buffer~ ${bufName(slot)}`, { numinlets: 1, numoutlets: 2, outlettype: ["float", "bang"] }));
+    boxes.push(box(`obj-instr-replace-${slot}`, "prepend replace"));
+    lines.push(line("obj-instr-loadslot", i, `obj-instr-replace-${slot}`, 0));
+    lines.push(line(`obj-instr-replace-${slot}`, 0, buf, 0));
+
+    // Report what LOADED, from the read-completed outlet (1). info~ fires right-to-left,
+    // so the sample rate (outlet 0) arrives last and drives [pack]'s hot inlet.
+    boxes.push(
+      box(info, `info~ ${bufName(slot)}`, {
+        numinlets: 1,
+        numoutlets: 10,
+        outlettype: ["float", "list", "float", "float", "float", "float", "float", "", "int", ""],
+      }),
+    );
+    boxes.push(box(`obj-instr-pack-${slot}`, "pack 0. 0. 0", { numinlets: 3, numoutlets: 1, outlettype: [""] }));
+    boxes.push(box(`obj-instr-ready-${slot}`, `prepend buffer_ready ${slot}`));
+    lines.push(line(buf, 1, info, 0));
+    lines.push(line(info, 8, `obj-instr-pack-${slot}`, 2)); // channels
+    lines.push(line(info, 6, `obj-instr-pack-${slot}`, 1)); // duration ms
+    lines.push(line(info, 0, `obj-instr-pack-${slot}`, 0)); // sample rate, hot
+    lines.push(line(`obj-instr-pack-${slot}`, 0, `obj-instr-ready-${slot}`, 0));
+    lines.push(line(`obj-instr-ready-${slot}`, 0, jwebId, 0));
+  });
+
+  // Sum the voices into the signal path - an instrument originates sound.
+  for (const [ch, id] of [
+    [0, "obj-instr-mix-l"],
+    [1, "obj-instr-mix-r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    boxes.push(box(id, "+~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    lines.push(line(srcId, srcOut, id, 0));
+    lines.push(line("obj-instr-poly", ch, id, 1));
     ctx.setAudioOut(ch, id, 0);
   }
 }
@@ -682,14 +1074,49 @@ function samplesChain(ctx) {
 export const CHAINS = {
   midiin: midiInChain,
   samples: samplesChain,
+  instrument: instrumentChain,
   midiout: midiOutChain,
   passthrough: passthroughChain,
   gain: gainChain,
   lowpass: lowpassChain,
   drive: driveChain,
+  delay: delayChain,
+  reverb: reverbChain,
   download: downloadChain,
 };
 
+/**
+ * The NEUTRALITY CONTRACT: the parameter value at which each stage is a straight
+ * wire - identical input and output samples.
+ *
+ * The DSP graph is written at BUILD time and every stage is ALWAYS in the signal
+ * path, including the ones a device's line never mentions. That is only safe if each
+ * stage has a setting where it does nothing, and if the library can say what it is.
+ * Two kinds of stage reach neutral two ways:
+ *
+ *   naturally transparent - `gain` (1.0), `lowpass` (18 kHz, nothing left to remove),
+ *     `drive` (1x): the DSP object itself is a wire at that value.
+ *   send-style wet/dry - `delay` (0), `reverb` (0): the wet branch is scaled to 0.0
+ *     and summed onto an untouched dry path, so the output is `dry + 0`. A WET-ONLY
+ *     object (cverb~) has NO neutral of its own - it must carry this dry/wet, which
+ *     is why it is a property of the chain and pinned here, not left to a device.
+ *
+ * `tests/neutrality.test.mjs` null-tests the send-style stages structurally (the dry
+ * wire survives at unity and the only other path is gain-0), which is what can be
+ * proven with no Max in the loop; the bit-exact acoustic check is a listening test,
+ * the same standing as hello-audio.
+ */
+export const CHAIN_NEUTRAL = {
+  gain: { gain: 1 },
+  lowpass: { cutoff: 18000 },
+  drive: { drive: 1 },
+  delay: { delay: 0 },
+  reverb: { room: 0 },
+};
+
+/** The send-style chains: wet-only or naturally additive, neutral by a 0 mix they own. */
+export const WET_DRY_CHAINS = ["delay", "reverb"];
+
 /** Add a chain to the vocabulary. Called before generatePatchers(). */
 export function registerChain(name, fn) {
   CHAINS[name] = fn;

package/src/index.mjs

@@ -196,7 +196,13 @@ export function composePatcher(base, d, surface) {
    *                    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) };
+  // Extra frozen dependencies a chain contributes to the .amxd - a [poly~] voice
+  // patch, say, which Max cannot embed inline and must resolve as a named .maxpat
+  // from the device's own bundle (the same way a frozen M4L instrument ships its
+  // voice abstraction). A chain pushes { name, data } here; generatePatchers writes
+  // each next to the device patcher and packageDevices freezes it into the container.
+  const extras = [];
+  const ctx = { boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d, extras, ...surfaceContext(surface) };
 
   openAudio(ctx);
 
@@ -212,6 +218,9 @@ export function composePatcher(base, d, surface) {
   closeAudio(ctx);
   assertUniqueBoxIds(boxes, d.name);
 
+  // Ride the chain-contributed extras out on the returned object. Destructuring
+  // `{ patcher }` (the tests, the writer) ignores it; the packager reads it.
+  p.extras = extras;
   return p;
 }
 
@@ -239,6 +248,15 @@ export async function generatePatchers(root) {
     const surface = await loadSurface(root, d.ui ?? d.name);
     const p = composePatcher(base, d, surface);
 
+    // A chain's frozen dependencies (e.g. a [poly~] voice patch) are written beside
+    // the device patcher and their names recorded in a sidecar, so packageDevices -
+    // a separate pass that only sees dist/ - knows which files to freeze into which
+    // device. Strip them from the patcher json itself; they are not part of it.
+    const extras = p.extras ?? [];
+    delete p.extras;
+    for (const ex of extras) writeFileSync(path.join(outDir, ex.name), typeof ex.data === "string" ? ex.data : JSON.stringify(ex.data));
+    writeFileSync(path.join(outDir, `${d.name}.extras.json`), JSON.stringify(extras.map((e) => e.name)));
+
     writeFileSync(path.join(outDir, `${d.name}.json`), JSON.stringify(p, null, "\t"));
     const params = surface ? surface.ids.join(", ") : "none";
     console.log(`m4l-jweb: ${d.name}.json (${d.type}, chains: ${(d.chains ?? []).join(", ") || "none"}, params: ${params || "none"})`);
@@ -321,13 +339,20 @@ export async function packageDevices(root) {
 
     if (payloads.length) wrapperData += extraPayloadsJs(payloads);
 
+    // Frozen dependencies: readable by Max-native objects only (a poly~ voice
+    // patcher, say), which is exactly why they can stay frozen rather than being
+    // extracted to disk like the UI. Two sources: manifest `extraFiles` (files in
+    // the repo) and chain-generated files recorded in the sidecar by generatePatchers.
+    const chainExtrasList = path.join(dist, "patchers", `${d.name}.extras.json`);
+    const chainExtras = existsSync(chainExtrasList)
+      ? JSON.parse(readFileSync(chainExtrasList, "utf8")).map((name) => ({ name, data: readFileSync(path.join(dist, "patchers", name)) }))
+      : [];
+
     const amxd = buildAmxd({
       patcherJson: readFileSync(path.join(dist, "patchers", `${d.name}.json`), "utf8"),
       wrapperJs: wrapperData,
       deviceName,
-      // Frozen dependencies: readable by Max-native objects only (a poly~
-      // voice patcher, say), which is exactly why they can stay frozen.
-      extras: (d.extraFiles ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) })),
+      extras: [...(d.extraFiles ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) })), ...chainExtras],
     });
     writeFileSync(path.join(outDir, deviceName), amxd);
     console.log(`m4l-jweb: ${deviceName} (${d.type}, ${amxd.length} bytes)`);

package/src/surface.mjs

@@ -124,7 +124,61 @@ export async function loadSurface(root, uiDir) {
  * Generating the objects
  * ------------------------------------------------------------------ */
 
-const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu" };
+const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu", button: "live.text" };
+
+/* ------------------------------------------------------------------ *
+ * Native declarative layout (surface `layout.native`)
+ *
+ * A parameter listed in `layout.native` renders as a native `live.*` object IN
+ * THE DEVICE VIEW, next to a `[jweb]` shifted right to make room. This is a pure
+ * PRESENTATION overlay: the dial the compiler already emits gains three keys
+ * (`presentation`, `presentation_rect`, `varname`) and nothing about its wiring,
+ * its fan-out or the app's `set_<id>` route changes. A dial that carries no rect
+ * is exactly today's invisible object.
+ * ------------------------------------------------------------------ */
+
+// The device view Live gives an M4L device. Height is fixed at ~169 px; the width
+// is whatever the presentation content needs, which is the whole mechanism this
+// relies on (Live recomputes device width from the presentation rects).
+const DEVICE_H = 169;
+const MARGIN = 8;
+// Per-kind native sizes, from Max's own live.* defaults. A live.dial includes its
+// own label under the knob, which is why it is taller than a bare toggle.
+const NATIVE_SIZE = { dial: [44, 48], toggle: [44, 15], menu: [100, 15], button: [48, 15] };
+// Vertical pitch: a dial is 48 px tall and wants 8 px of air beneath its label.
+const PITCH_Y = 56;
+
+/**
+ * `id -> presentation_rect` for every native parameter, plus the zone's total
+ * width (how far `[jweb]` shifts right). A pure function of the declaration, so
+ * `tests/` can drive it directly.
+ *
+ * Column-major: fills `rows` down the first column, then starts a new column to
+ * the right. Adding a parameter at the end therefore never reshuffles the ones
+ * before it - the reading order stays stable.
+ */
+export function computeNativeSlots(surface) {
+  const native = surface?.layout?.native;
+  if (!native || native.params.length === 0) return { slots: new Map(), width: 0 };
+  const rows = native.rows ?? 3;
+  const slots = new Map();
+  let row = 0;
+  let colW = 0;
+  let x = MARGIN;
+  for (const id of native.params) {
+    const [w, h] = NATIVE_SIZE[surface.params[id].kind];
+    if (row >= rows) {
+      // Column full: step right by the widest box in the column just finished.
+      row = 0;
+      x += colW + MARGIN;
+      colW = 0;
+    }
+    slots.set(id, [x, MARGIN + row * PITCH_Y, w, h]);
+    colW = Math.max(colW, w);
+    row += 1;
+  }
+  return { slots, width: x + colW + MARGIN };
+}
 
 /**
  * Max's `parameter_type`: 0 = float, 1 = int, 2 = enum.
@@ -134,7 +188,7 @@ const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu" }
  * where a float one would read "2.4 of [off 1/4 1/8 ...]".
  */
 function parameterType(spec) {
-  if (spec.kind === "menu" || spec.kind === "toggle") return 2;
+  if (spec.kind === "menu" || spec.kind === "toggle" || spec.kind === "button") return 2;
   return spec.step === 1 ? 1 : 0;
 }
 
@@ -183,7 +237,7 @@ function unitAttrs(spec) {
 
 /** The parameter's value as MAX stores it: numbers, always. */
 function initialValue(spec) {
-  if (spec.kind === "toggle") return spec.default ? 1 : 0;
+  if (spec.kind === "toggle" || spec.kind === "button") return spec.default ? 1 : 0;
   if (spec.kind === "menu") return spec.options.indexOf(spec.default);
   return spec.default;
 }
@@ -226,7 +280,7 @@ function parameterAttrs(id, spec) {
     if (spec.steps !== undefined) attrs.parameter_steps = spec.steps;
   }
 
-  if (spec.kind === "toggle") {
+  if (spec.kind === "toggle" || spec.kind === "button") {
     attrs.parameter_mmax = 1;
     attrs.parameter_enum = ["off", "on"];
   }
@@ -239,6 +293,16 @@ function parameterAttrs(id, spec) {
   return attrs;
 }
 
+/**
+ * Box-level (not parameter) attributes a kind needs. A `button` is a `live.text`,
+ * which unlike a `live.toggle` carries VISIBLE TEXT: `text`/`texton` is the label it
+ * shows off/on, and `mode: 1` makes it a toggle rather than a momentary button.
+ */
+function kindBoxAttrs(spec) {
+  if (spec.kind === "button") return { text: spec.label, texton: spec.label, mode: 1 };
+  return {};
+}
+
 /**
  * Compile the Surface into the patcher.
  *
@@ -250,9 +314,29 @@ export function applySurface(ctx) {
   const { boxes, lines, surface, jwebId } = ctx;
   if (!surface || surface.ids.length === 0) return;
 
+  // Where the native dials go, if any were declared. `slots` is empty for a
+  // surface with no `layout`, and then this whole feature is inert - a param
+  // carries no presentation rect and stays the invisible object it is today.
+  const native = surface.layout?.native;
+  const { slots, width: nativeW } = computeNativeSlots(surface);
+
+  // The view switch (panel layouts) is NOT a grid dial: it is pinned to the
+  // top-right, over where the web UI paints its own switch button, so the control
+  // stays in one place when the app flips between the two views. It is excluded from
+  // `computeNativeSlots` (it is not in `native.params`), so give it a rect here.
+  const switchId = native?.switch;
+  const jwebBox = boxes.find((b) => b.box.id === jwebId)?.box;
+  const [, , jpw] = jwebBox?.presentation_rect ?? [0, 0, 420, DEVICE_H];
+  let switchRect = null;
+  if (switchId) {
+    const [sw, sh] = NATIVE_SIZE[surface.params[switchId].kind];
+    switchRect = [jpw - sw - MARGIN, MARGIN, sw, sh];
+  }
+
   let x = 480;
   for (const id of surface.ids) {
     const spec = surface.params[id];
+    const rect = id === switchId ? switchRect : slots.get(id);
     boxes.push({
       box: {
         id: paramObject(id),
@@ -262,6 +346,13 @@ export function applySurface(ctx) {
         outlettype: [""],
         parameter_enable: 1,
         patching_rect: [x, 300, 44, 48],
+        ...kindBoxAttrs(spec),
+        // A native param is shown in the device view: it gets a presentation rect
+        // and a scripting name (prefixed `param-` so it cannot collide with a state
+        // dict's `obj-state-<id>` varname). Everything else about the box - the
+        // wiring below, the fan-out, useParam() - is UNCHANGED. Presentation is
+        // purely a display overlay on the same graph.
+        ...(rect ? { presentation: 1, presentation_rect: rect, varname: `param-${id}` } : {}),
         saved_attribute_attributes: { valueof: parameterAttrs(id, spec) },
       },
     });
@@ -273,6 +364,26 @@ export function applySurface(ctx) {
     x += 56;
   }
 
+  // Position [jweb] for the native layout. WIDTH is preserved (React layouts were
+  // built for 420 px). A surface with no native content leaves [jweb] where the
+  // template put it.
+  if ((nativeW > 0 || switchId) && jwebBox) {
+    const [, py, pw, ph] = jwebBox.presentation_rect ?? [0, 0, 420, DEVICE_H];
+    if (native.panel) {
+      // LAYERED two-screen: [jweb] covers the whole device and the dials overlap its
+      // left. The app shows one layer at a time (useNativePanel), so the overlap is
+      // never seen - web mode fills the full width, no reserved strip.
+      jwebBox.presentation_rect = [0, py, Math.max(pw, nativeW), ph];
+    } else {
+      // Side-by-side: the dials to the left, [jweb] shifted right, both visible.
+      jwebBox.presentation_rect = [nativeW, py, pw, ph];
+    }
+    // Give [jweb] a scripting name so the wrapper can hide/show it at runtime
+    // (useNativePanel). Must equal JWEB_VARNAME in @m4l-jweb/surface - the one string
+    // the app and this codegen must agree on.
+    jwebBox.varname = "obj-jweb";
+  }
+
   // Write direction: one route for every `set_<id>` the app can send. It goes at
   // the END of the chain of routes (see claimAppMessages), so a chain that already
   // took [jweb]'s outlet keeps it and hands us what it did not match.
@@ -295,6 +406,36 @@ export function applySurface(ctx) {
   });
 }
 
+/**
+ * Runtime show/hide of native dials - the `layout.native` visibility override.
+ *
+ * `layout.native` makes a parameter a native `live.*` object, and its presentation
+ * is STATIC: `presentation: 1` is stamped into the .amxd at build time, so every
+ * listed dial is always visible. A device like the fx line wants the opposite - a
+ * stage the current line does not name should not clutter the view, the way its old
+ * HTML slider was simply not rendered. React can hide a slider; a native object
+ * cannot hide itself, so the app drives it from outside via `native_show`/
+ * `native_hide <varname>` (useNativeVisibility).
+ *
+ * ------------------------------------------------------------------------------
+ * THIS IS A SPIKE, and its FIRST mechanism already FAILED IN LIVE.
+ *
+ * Attempt 1 (this codegen, now retired): a `[thispatcher]` running `script hide
+ * <varname>`. Verified in Live - the dials did NOT disappear. `script hide` acts on
+ * the PATCHING canvas; the M4L device view is the PRESENTATION, and `script` has no
+ * documented reach into it.
+ *
+ * Attempt 2 (current): the wrapper's [js] handles `native_show`/`native_hide` and
+ * manipulates the object through the Maxobj API (`this.patcher.getnamed(varname)`),
+ * with console diagnostics. So this codegen no longer claims the messages - it lets
+ * them fall through to the wrapper. See `native_show`/`native_hide` in core.ts.
+ *
+ * If attempt 2 also fails to reach the presentation, the honest conclusion is that a
+ * frozen M4L device cannot hide a native object at runtime, and the fallback is a
+ * build-time choice (fewer native params, or a device keeps HTML controls).
+ * ------------------------------------------------------------------------------
+ */
+
 /**
  * Compile a declared `window` into the patcher: a subpatcher holding its own
  * [jweb], and a [pcontrol] that opens it when the app asks.
@@ -324,7 +465,7 @@ export function applySurface(ctx) {
  * ------------------------------------------------------------------------------
  */
 export function applyWindows(ctx) {
-  const { boxes, lines, surface } = ctx;
+  const { boxes, lines, surface, unmatchedId } = ctx;
   const windowIds = surface?.windows ? Object.keys(surface.windows) : [];
   if (windowIds.length === 0) return;
 
@@ -374,6 +515,12 @@ export function applyWindows(ctx) {
 
     const subpatcherId = `obj-window-${id}-sub`;
     lines.push(line(pcontrolId, 0, subpatcherId, 0));
+    // The window's [jweb] can now TALK BACK. Its output leaves the subpatcher on an
+    // [outlet] and this cord carries it to the wrapper's [js] - the same [js] the
+    // device view feeds. It is tagged `window <id>` inside (below), so the wrapper
+    // tells the two apart and can answer the right one. Without this the window's
+    // page could display but never send a message: the [jweb] outlet went nowhere.
+    lines.push(line(subpatcherId, 0, unmatchedId, 0));
     boxes.push({
       box: {
         id: subpatcherId,
@@ -383,7 +530,8 @@ export function applyWindows(ctx) {
         // subpatcher that has no inlets, so [pcontrol] would end up wired to
         // NOTHING - silently, in the saved file. That was attempt 1.
         numinlets: 1,
-        numoutlets: 0,
+        numoutlets: 1,
+        outlettype: [""],
         patching_rect: [16, 620, 120, 22],
         patcher: {
           fileversion: 1,
@@ -418,8 +566,30 @@ export function applyWindows(ctx) {
                 presentation_rect: [0, 0, spec.width, spec.height],
               },
             },
+            // TAG the window's messages with which window they are, so the wrapper's
+            // `window()` can answer THIS window (its [jweb] has no cord from [js], so
+            // a reply goes back by name). The page emits bare selectors; the tag is
+            // added here, in the patcher, not in the app - so a window page is an
+            // ordinary bridge client that happens to be in its own runtime.
+            {
+              box: {
+                id: "obj-tag",
+                maxclass: "newobj",
+                text: `prepend window ${id}`,
+                numinlets: 1,
+                numoutlets: 1,
+                outlettype: [""],
+                patching_rect: [16, 96 + spec.height + 16, 160, 22],
+              },
+            },
+            { box: { id: "obj-out", maxclass: "outlet", patching_rect: [16, 96 + spec.height + 48, 30, 30], numinlets: 1, numoutlets: 0 } },
+          ],
+          lines: [
+            { patchline: { source: ["obj-recv", 0], destination: ["obj-jweb", 0] } },
+            // [jweb] outlet 0 is the page's messages; tag them and send them out.
+            { patchline: { source: ["obj-jweb", 0], destination: ["obj-tag", 0] } },
+            { patchline: { source: ["obj-tag", 0], destination: ["obj-out", 0] } },
           ],
-          lines: [{ patchline: { source: ["obj-recv", 0], destination: ["obj-jweb", 0] } }],
         },
       },
     });

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.6.0",
-    "@m4l-jweb/surface": "^0.6.0",
+    "@m4l-jweb/bridge": "^0.7.0",
+    "@m4l-jweb/surface": "^0.7.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^0.6.0",
+    "@m4l-jweb/build": "^0.7.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",