@m4l-jweb/build 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.4.0",
+  "version": "0.6.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.6.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,116 @@ 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, scope = "the patcher") {
+  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 in ${scope}: ${[...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.`,
+    );
+  }
+  // A SUBPATCHER is its own id namespace, so its boxes are checked against each
+  // other and not against ours - a floating window's [jweb] may be called
+  // `obj-jweb` even though the device's is too. It is checked, though: the window
+  // codegen emitted two inlets sharing one id and nothing said a word, because
+  // this only ever looked at the top level.
+  for (const { box: b } of boxes) {
+    if (b.patcher?.boxes) assertUniqueBoxIds(b.patcher.boxes, deviceName, `subpatcher [${b.text ?? b.id}]`);
+  }
+}
+
 /**
  * "midiin" - feed incoming MIDI notes to the app as `notein <pitch> <velocity>`.
  *
@@ -172,25 +290,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 +324,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 +354,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 +392,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 +412,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 +431,263 @@ 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);
+  }
+}
+
+/**
+ * "download" - `[maxurl]`, so the app can fetch a file to DISK.
+ *
+ *   [js] out 1 -> [route maxurl] -> [maxurl] -> [prepend maxurl_done]     -> [js] in 0
+ *                                            -> [prepend maxurl_progress] -> [js] in 0
+ *
+ * The bytes never enter the Max message stream: [js] hands maxurl a request dict
+ * carrying `filename_out` and libcurl writes the file itself. What comes back here
+ * is only the RESULT - a response dict name, and progress. That is the whole point:
+ * [js] is a control plane, not a data plane. See the fetch section of core.ts for
+ * the request dict, which is where this feature was actually broken.
+ *
+ * The request leaves [js] on OUTLET 1 (the aux outlet) rather than outlet 0, which
+ * belongs to [jweb]: a `maxurl` message on outlet 0 would be delivered to the web
+ * view, which has no idea what to do with it. The [route maxurl] then strips the
+ * tag, so what reaches the object is the bare `dictionary <name>` it expects.
+ *
+ * maxurl has TWO outlets (per its reference page): 0 = the response dictionary,
+ * 1 = progress. Not three.
+ */
+function downloadChain(ctx) {
+  const { boxes, lines, unmatchedId } = ctx; // unmatchedId is the wrapper's [js]
+
+  boxes.push(box("obj-maxurl", "maxurl", { numinlets: 2, numoutlets: 2, outlettype: ["", ""] }));
+
+  boxes.push(box("obj-route-maxurl", "route maxurl", { numoutlets: 2, outlettype: ["", ""] }));
+  lines.push(line(unmatchedId, 1, "obj-route-maxurl", 0));
+  lines.push(line("obj-route-maxurl", 0, "obj-maxurl", 0));
+
+  // Tag both replies, so [js] dispatches them to a handler rather than to
+  // anything(), which would swallow them - they arrive as a bare `dictionary
+  // <name>` and a bare list otherwise.
+  boxes.push(box("obj-prepend-maxurl-done", "prepend maxurl_done"));
+  boxes.push(box("obj-prepend-maxurl-progress", "prepend maxurl_progress"));
+
+  lines.push(line("obj-maxurl", 0, "obj-prepend-maxurl-done", 0));
+  lines.push(line("obj-maxurl", 1, "obj-prepend-maxurl-progress", 0));
+
+  lines.push(line("obj-prepend-maxurl-done", 0, unmatchedId, 0));
+  lines.push(line("obj-prepend-maxurl-progress", 0, unmatchedId, 0));
+}
+
+/**
+ * "samples" - the first chain that ORIGINATES a sound: a named [buffer~] per slot,
+ * loaded from a file on disk, played back through [groove~] into the signal path.
+ *
+ *   app -> buffer_load <slot> <path>  -> [js] (resolves the path)
+ *                                     -> buffer_replace -> [buffer~ <name>]
+ *          buffer_play <slot>         -> [groove~] set + play
+ *          buffer_stop                -> [groove~] stop
+ *   app <- buffer_ready <slot> <sr> <ms> <chans>   when the read actually completed
+ *          buffer_error <slot> <msg>                when there was no file to read
+ *
+ * THE BYTES NEVER CROSS THE BRIDGE. [buffer~] reads the file itself; what travels in
+ * Max messages is a path and, coming back, a description of what landed - the same
+ * rule the `download` chain follows, which is how you get the file there in the
+ * first place.
+ *
+ * WAV/AIFF/Next-Sun ONLY. [buffer~]'s `read`/`replace` does not take MP3 - that list
+ * (MP3, OGG, FLAC, M4A) is [sfplay~]'s, which streams from disk rather than filling a
+ * buffer, and is therefore a different chain. A format it cannot read is an error in
+ * the Max console and NO bang, so the app's promise times out rather than lying.
+ *
+ * WHAT LOADED IS NOT WHAT YOU ASKED FOR, so the chain reports what it GOT. `replace`
+ * resizes the buffer and adopts the FILE's channel count and sample rate, so a slot
+ * is not mono because you wanted it to be. [info~] is banged from the buffer's own
+ * "read completed" outlet (outlet 1 - outlet 0 is a mouse position in the editing
+ * window) and reports sample rate, duration and channels; the app derives frames from
+ * those. A frame count on its own is not proof of a read: a failed `replace` leaves
+ * the PREVIOUS contents in place, so "there are samples in there" says nothing. The
+ * bang does - it only fires when a read completed - and until it does the app's
+ * promise is still open (see loadSample() in @m4l-jweb/bridge, which is where the
+ * timeout lives).
+ *
+ * info~'s outlets fire right-to-left, so the LAST one to arrive is outlet 0, the
+ * sample rate - which is therefore the one wired to [pack]'s hot inlet. Wire it the
+ * other way round and the message goes out carrying the PREVIOUS load's numbers.
+ *
+ * ONE VOICE, DELIBERATELY. `groove~` takes `set <buffer-name>` to switch buffers, so
+ * one stereo player covers N slots: this is a PREVIEW - the sample browser's "let me
+ * hear it, through the track" - not a sampler. Polyphony is the `instrument` chain,
+ * and it is still open (doc/TODO.md item 2).
+ *
+ * It SUMS into the signal path rather than claiming it ([+~]), because it makes sound
+ * of its own: on an audio effect the preview plays over the track's audio, and on an
+ * instrument there is nothing at the input to add.
+ *
+ * The buffer NAMES are global to Max, and they are generated from the device name
+ * (`buf-<device>-<slot>`), so two INSTANCES of the same device on two tracks name
+ * their buffers alike - and Max hands the name to whichever loaded last. Not
+ * verified in Live yet; a preview device you drag onto one track is unaffected.
+ *
+ * Slots default to one, named "preview". `slots: ["kick", "snare"]` in the manifest
+ * gives you more.
+ */
+function samplesChain(ctx) {
+  const { boxes, lines, device, jwebId, unmatchedId } = ctx;
+  const slots = device?.slots ?? ["preview"];
+  const bufName = (slot) => `buf-${device?.name}-${slot}`;
+
+  // `buffer_load` is NOT claimed from [jweb]. It goes on to the wrapper, which
+  // resolves the path and hands it back on its AUX OUTLET as `buffer_replace <slot>
+  // <abs path>` - the same shape the `download` chain takes `maxurl` in.
+  //
+  // The detour is the whole fix. The app writes a path relative to the device's
+  // folder (that is where fetchToFile puts the file), and [buffer~] does not resolve
+  // it that way: a bare name is looked up in MAX'S SEARCH PATH, which the device's
+  // folder is not in, so a file that was downloaded correctly reports "can't open".
+  // The resolved path then contains SPACES on a normal Live install ("Ableton
+  // Library"), and a path travelling through the patcher as message text would split
+  // there into atoms. Out of [js] it stays one symbol.
+  boxes.push(box("obj-samples-route", "route buffer_play buffer_stop", { numoutlets: 3, outlettype: ["", "", ""] }));
+  claimAppMessages(ctx, "obj-samples-route", 2);
+
+  boxes.push(box("obj-samples-replaceroute", "route buffer_replace", { numoutlets: 2, outlettype: ["", ""] }));
+  lines.push(line(unmatchedId, 1, "obj-samples-replaceroute", 0));
+
+  // `route` strips the selector, so the slot name is now the first word of both
+  // remaining messages: a second route per stream dispatches on it.
+  const slotList = slots.join(" ");
+  const slotOutlets = { numoutlets: slots.length + 1, outlettype: slots.map(() => "").concat("") };
+  boxes.push(box("obj-samples-loadslot", `route ${slotList}`, slotOutlets));
+  boxes.push(box("obj-samples-playslot", `route ${slotList}`, slotOutlets));
+  lines.push(line("obj-samples-replaceroute", 0, "obj-samples-loadslot", 0));
+  lines.push(line("obj-samples-route", 0, "obj-samples-playslot", 0));
+
+  // The player. `groove~ <buffer> 2` = two signal outlets (plus a loop-sync outlet),
+  // and it MIXES a buffer with more channels down rather than dropping them.
+  // @loop 0 makes it a one-shot: a preview that loops forever is a preview you have
+  // to fight. [sig~ 1.] is the playback rate, in the left inlet, which is a SIGNAL
+  // inlet - a float there means something else entirely (a position, in ms).
+  boxes.push(box("obj-samples-rate", "sig~ 1.", { numinlets: 1, numoutlets: 1, outlettype: ["signal"] }));
+  boxes.push(
+    box("obj-samples-groove", `groove~ ${bufName(slots[0])} 2 @loop 0`, {
+      numinlets: 3,
+      numoutlets: 3,
+      outlettype: ["signal", "signal", "signal"],
+    }),
+  );
+  lines.push(line("obj-samples-rate", 0, "obj-samples-groove", 0));
+
+  // 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 }));
+  lines.push(line("obj-samples-route", 1, "obj-samples-stopmsg", 0));
+  lines.push(line("obj-samples-stopmsg", 0, "obj-samples-groove", 0));
+
+  slots.forEach((slot, i) => {
+    const buf = `obj-samples-buf-${slot}`;
+    const info = `obj-samples-info-${slot}`;
+
+    // buffer~: outlet 0 is a mouse position, outlet 1 is the bang on a completed
+    // read. Only the second one means anything here.
+    boxes.push(box(buf, `buffer~ ${bufName(slot)}`, { numinlets: 1, numoutlets: 2, outlettype: ["float", "bang"] }));
+    boxes.push(box(`obj-samples-replace-${slot}`, "prepend replace"));
+    lines.push(line("obj-samples-loadslot", i, `obj-samples-replace-${slot}`, 0));
+    lines.push(line(`obj-samples-replace-${slot}`, 0, buf, 0));
+
+    // What actually landed. info~'s outlets: 0 = sample rate, 6 = duration in ms,
+    // 8 = number of channels (per its reference page - do not count them from
+    // memory). They fire right-to-left, so 0 arrives last and is the hot one.
+    boxes.push(
+      box(info, `info~ ${bufName(slot)}`, {
+        numinlets: 1,
+        numoutlets: 10,
+        outlettype: ["float", "list", "float", "float", "float", "float", "float", "", "int", ""],
+      }),
+    );
+    boxes.push(box(`obj-samples-pack-${slot}`, "pack 0. 0. 0", { numinlets: 3, numoutlets: 1, outlettype: [""] }));
+    boxes.push(box(`obj-samples-ready-${slot}`, `prepend buffer_ready ${slot}`));
+
+    lines.push(line(buf, 1, info, 0)); // the read completed - ask what it was
+    lines.push(line(info, 8, `obj-samples-pack-${slot}`, 2)); // channels (fires first)
+    lines.push(line(info, 6, `obj-samples-pack-${slot}`, 1)); // duration, ms
+    lines.push(line(info, 0, `obj-samples-pack-${slot}`, 0)); // sample rate - hot, last
+    lines.push(line(`obj-samples-pack-${slot}`, 0, `obj-samples-ready-${slot}`, 0));
+    lines.push(line(`obj-samples-ready-${slot}`, 0, jwebId, 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-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 }));
+
+    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}`, 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));
+  });
+
+  // Sum into the signal path: this chain MAKES sound, it does not process what came
+  // before. Claiming the stage instead would silence the track the preview plays over.
+  for (const [ch, id] of [
+    [0, "obj-samples-mix-l"],
+    [1, "obj-samples-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-samples-groove", ch, id, 1));
+    ctx.setAudioOut(ch, id, 0);
+  }
+}
+
 export const CHAINS = {
   midiin: midiInChain,
+  samples: samplesChain,
   midiout: midiOutChain,
   passthrough: passthroughChain,
   gain: gainChain,
   lowpass: lowpassChain,
+  drive: driveChain,
+  download: downloadChain,
 };
 
 /** Add a chain to the vocabulary. Called before generatePatchers(). */

package/src/index.mjs

@@ -8,7 +8,7 @@
  *   wrapper/device.ts  - extra [js] message handlers, concatenated last
  */
 import archiver from "archiver";
-import { createReadStream, createWriteStream, existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { createReadStream, createWriteStream, existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from "node:fs";
 import { copyFile, rename, stat } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -16,8 +16,8 @@ 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 { applySurface, loadSurface, surfaceContext } from "./surface.mjs";
+import { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, resetLayout } from "./chains.mjs";
+import { applySurface, applyWindows, applyPersistence, loadSurface, surfaceContext } from "./surface.mjs";
 
 const require = createRequire(import.meta.url);
 const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -80,6 +80,14 @@ export function buildWrapper(root) {
         // At [js] global scope `this` IS the jsthis object - that is how
         // `this.patcher.filepath` works.
         noImplicitThis: false,
+        // ...and that is ONLY true in sloppy mode. `strict: true` makes tsc emit
+        // "use strict" at the top of every file, under which `this` inside a plainly
+        // called function is UNDEFINED - so `this.patcher` would throw. Max's [js] is
+        // an ES5-era interpreter that does not enforce strict semantics, so the
+        // device works anyway; it works by accident, on a technicality of a very old
+        // engine, and any [js] that ever grew a real strict mode would take every
+        // device down with it. Emit what we actually target.
+        alwaysStrict: false,
         noImplicitAny: false,
         skipLibCheck: true,
         types: [],
@@ -138,6 +146,75 @@ 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);
+  applyWindows(ctx);
+  applyPersistence(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 +223,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 +232,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";
@@ -265,11 +302,23 @@ export async function packageDevices(root) {
     /**
      * Payloads ride inside wrapper.js as base64 and are written to real files
      * next to the .amxd on first load, because Chromium and any external
-     * process are blind to Max's frozen virtual filesystem. The UI is always
-     * one; a device can declare more (`payloads: ["dist/foo.cjs"]`).
+     * process are blind to Max's frozen virtual filesystem.
+     * We embed ALL .html files found in the UI directory (including the main UI and any windows).
      */
-    let wrapperData = banner + wrapperJs + payloadJs("UI_PAYLOAD", uiName, uiHtml);
+    let wrapperData = banner + wrapperJs;
+    const uiDirContent = readdirSync(path.join(dist, "ui", d.ui ?? d.name)).filter((f) => f.endsWith(".html"));
+
+    // Main UI payload
+    wrapperData += payloadJs("UI_PAYLOAD", uiName, readFileSync(path.join(dist, "ui", d.ui ?? d.name, "index.html")));
+
+    // Additional window payloads
+    const extraWindows = uiDirContent.filter((f) => f !== "index.html");
     const payloads = (d.payloads ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) }));
+
+    for (const winHtml of extraWindows) {
+      payloads.push({ name: `${d.name}_${winHtml}`, data: readFileSync(path.join(dist, "ui", d.ui ?? d.name, winHtml)) });
+    }
+
     if (payloads.length) wrapperData += extraPayloadsJs(payloads);
 
     const amxd = buildAmxd({

package/src/surface.mjs

@@ -294,3 +294,208 @@ export function applySurface(ctx) {
     lines.push(line(`obj-set-${id}`, 0, paramObject(id), 0));
   });
 }
+
+/**
+ * Compile a declared `window` into the patcher: a subpatcher holding its own
+ * [jweb], and a [pcontrol] that opens it when the app asks.
+ *
+ *   [jweb] -> [route window_x_open window_x_close] -> [t b] -> [open( -> [pcontrol] -> [p Title]
+ *
+ * ------------------------------------------------------------------------------
+ * A MAXCLASS IS NOT A NAME YOU INVENT, and that is what was broken here.
+ *
+ * This generated the open/close message boxes as `newobj` with the TEXT "open"
+ * and "wclose", and the [pcontrol] as a box with `maxclass: "pcontrol"`. Neither
+ * is a thing:
+ *
+ *   - `newobj` means "an object box", and its text names the object. There is no
+ *     Max object called `open`, so what got built was a BROKEN box - the dashed
+ *     outline you would see instantly in the Max editor, and see nothing of here.
+ *     A message box is `maxclass: "message"` with the message in `text`
+ *     (chains.mjs's [flush( does this - copy that, do not reinvent it).
+ *   - `pcontrol` is an object, not a box class: `maxclass: "newobj"`,
+ *     `text: "pcontrol"`. A box with an unknown maxclass does not instantiate.
+ *
+ * A patcher full of broken boxes still LOADS, keeps its cords, and does nothing.
+ * That is why the message reached [jweb]'s outlet, the route matched, and the
+ * window never opened - and why the failure was misread as `[route]` refusing to
+ * match jweb's output. The route was fine. It was firing into a box that had
+ * failed to exist.
+ * ------------------------------------------------------------------------------
+ */
+export function applyWindows(ctx) {
+  const { boxes, lines, surface } = ctx;
+  const windowIds = surface?.windows ? Object.keys(surface.windows) : [];
+  if (windowIds.length === 0) return;
+
+  const selectors = windowIds.flatMap((id) => [`window_${id}_open`, `window_${id}_close`]);
+
+  const routeId = "obj-windows-route";
+  boxes.push(
+    box(routeId, `route ${selectors.join(" ")}`, {
+      numoutlets: selectors.length + 1,
+      outlettype: selectors.map(() => "").concat(""),
+    }),
+  );
+  // IN SERIES, like every other claimant of the app's message stream. Hanging this
+  // route off [jweb] in parallel (which it did) leaves two paths to [js], so the
+  // wrapper sees every unrouted message - `ui_ready` included - twice.
+  claimAppMessages(ctx, routeId, selectors.length);
+
+  windowIds.forEach((id, index) => {
+    const spec = surface.windows[id];
+
+    // `route` STRIPS the selector, so `window_x_open 1` emerges as a bare `1`. A
+    // message box would try to interpret that as its own argument, so bang it
+    // instead: [t b] makes the trigger unambiguous whatever the app sent.
+    //
+    // The words are [pcontrol]'s: `open` and `close`. NOT `wclose` - that is
+    // [thispatcher]'s vocabulary, and pcontrol says so out loud
+    // ("pcontrol: doesn't understand \"wclose\""), which is the one thing an
+    // unrecognised NAME usually does not do. See pcontrol.maxref.xml.
+    for (const [outlet, verb, tag] of [
+      [index * 2, "open", "open"],
+      [index * 2 + 1, "close", "close"],
+    ]) {
+      const triggerId = `obj-window-${id}-t-${tag}`;
+      const msgId = `obj-window-${id}-${tag}msg`;
+      boxes.push(box(triggerId, "t b"));
+      // A MESSAGE box: maxclass "message", the message in `text`. Not a newobj.
+      boxes.push(box(msgId, verb, { maxclass: "message", numinlets: 2, numoutlets: 1 }));
+      lines.push(line(routeId, outlet, triggerId, 0));
+      lines.push(line(triggerId, 0, msgId, 0));
+      lines.push(line(msgId, 0, `obj-window-${id}-pcontrol`, 0));
+    }
+
+    // [pcontrol] is the supported way to open a subpatcher's window from outside
+    // it. `open` shows it, `wclose` hides it.
+    const pcontrolId = `obj-window-${id}-pcontrol`;
+    boxes.push(box(pcontrolId, "pcontrol"));
+
+    const subpatcherId = `obj-window-${id}-sub`;
+    lines.push(line(pcontrolId, 0, subpatcherId, 0));
+    boxes.push({
+      box: {
+        id: subpatcherId,
+        maxclass: "newobj",
+        text: `p ${spec.title}`,
+        // The inlet is not decoration: Max will not connect a patch cord to a
+        // 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,
+        patching_rect: [16, 620, 120, 22],
+        patcher: {
+          fileversion: 1,
+          appversion: { major: 8, minor: 0, revision: 0, architecture: "x64", modernui: 1 },
+          rect: [100, 100, spec.width, spec.height],
+          openinpresentation: 1,
+          boxes: [
+            { box: { id: "obj-in", maxclass: "inlet", patching_rect: [16, 16, 30, 30], numinlets: 0, numoutlets: 1, outlettype: [""] } },
+            // The page's URL cannot be WIRED here - this [jweb] is inside a
+            // subpatcher and the wrapper's [js] is outside it. The wrapper reaches
+            // it by NAME instead (messnamed), once the payload is extracted.
+            {
+              box: {
+                id: "obj-recv",
+                maxclass: "newobj",
+                text: `r window-read-${id}`,
+                numinlets: 0,
+                numoutlets: 1,
+                outlettype: [""],
+                patching_rect: [16, 56, 160, 22],
+              },
+            },
+            {
+              box: {
+                id: "obj-jweb",
+                maxclass: "jweb",
+                numinlets: 1,
+                numoutlets: 2,
+                outlettype: ["", ""],
+                patching_rect: [16, 96, spec.width, spec.height],
+                presentation: 1,
+                presentation_rect: [0, 0, spec.width, spec.height],
+              },
+            },
+          ],
+          lines: [{ patchline: { source: ["obj-recv", 0], destination: ["obj-jweb", 0] } }],
+        },
+      },
+    });
+  });
+}
+
+/**
+ * Compile a declared `state` slot: a named [dict] the app reads and writes, and a
+ * [pattr] bound to it, which is what actually SAVES.
+ *
+ * ------------------------------------------------------------------------------
+ * WHAT MAKES LIVE SAVE IT IS `parameter_enable`, and nothing else.
+ *
+ * A pattr on its own persists in a PATCHER. A Max for Live device is not saved as a
+ * patcher - Live saves the SET - so the pattr's value goes with it only when the
+ * pattr is a Live parameter. Max's own pattr help says so in one line:
+ *
+ *   "In Max for Live, if you activate the parameter_enable attribute, the pattr
+ *    value will be saved with the Live set."
+ *
+ * The first version of this emitted `@save 1`, which is not a pattr attribute at
+ * all ("pattr: 'save' is not a valid attribute argument"), and `@autorestore 1`,
+ * which restores from the PATCHER and so does nothing here. The state survived a
+ * reload of the page and would not have survived a reload of the set.
+ *
+ * The recipe below is copied from a device Ableton ships - `pattr Delays` in
+ * "Max DelayTaps.amxd", which persists an array of tap times exactly this way:
+ *
+ *   parameter_type 3       BLOB. Not a float, not an enum - an opaque value Live
+ *                          stores and hands back, which is the whole point: JSON is
+ *                          not a number and must never pretend to be one.
+ *   parameter_invisible 1  ...so it stays out of the automation lane and off Push.
+ *                          A blob cannot be automated, and a slot that offered to be
+ *                          would be a lie in every Live UI that listed it.
+ *   parameter_enable 1     in saved_object_attributes - the switch itself.
+ *
+ * `dict` is an OBJECT (`maxclass: "newobj"`, text `dict <name>`), not a box class.
+ * It was emitted as `maxclass: "dict"` - a box class Max does not have, so the box
+ * never instantiated and the pattr bound to nothing. Same mistake as the windows,
+ * same silence.
+ * ------------------------------------------------------------------------------
+ */
+export function applyPersistence(ctx) {
+  const { boxes, surface } = ctx;
+  const stateIds = surface?.state ? Object.keys(surface.state) : [];
+
+  for (const id of stateIds) {
+    const dictId = `obj-state-${id}`;
+    // `varname` is the SCRIPTING name, which is what [pattr]'s @bindto resolves -
+    // it binds to a NAMED object in the patcher, not to a box id (which is ours, and
+    // which Max is free to renumber). The dict's own name argument is what [js]
+    // addresses with `new Dict("obj-state-<id>")`, so all three agree.
+    boxes.push(box(dictId, `dict ${dictId}`, { varname: dictId, numinlets: 2, numoutlets: 4, outlettype: ["dictionary", "", "", ""] }));
+
+    const pattrId = `obj-pattr-${id}`;
+    boxes.push(
+      box(pattrId, `pattr ${pattrId} @bindto ${dictId}`, {
+        numinlets: 2,
+        numoutlets: 3,
+        outlettype: ["", "", ""],
+        varname: pattrId,
+        saved_attribute_attributes: {
+          valueof: {
+            parameter_longname: pattrId,
+            // Live truncates a short name at 8 characters (see the parameter
+            // compiler above), and it is never displayed for an invisible blob -
+            // but it must still be there and still be unique.
+            parameter_shortname: `st_${id}`.slice(0, 8),
+            parameter_type: 3, // blob
+            parameter_invisible: 1,
+          },
+        },
+        saved_object_attributes: {
+          parameter_enable: 1, // THE switch: no parameter, no save.
+        },
+      }),
+    );
+  }
+}

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.6.0",
+    "@m4l-jweb/surface": "^0.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^0.4.0",
+    "@m4l-jweb/build": "^0.6.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, ...).
  *

package/templates/starter/scripts/build-ui.mjs

@@ -1,19 +1,50 @@
 /**
- * build-ui.mjs - bundle one self-contained UI per device.
+ * build-ui.mjs - bundle one self-contained UI per device, plus one per WINDOW.
  *
- * Emits dist/ui/<device>/index.html, which `m4l-jweb build` then embeds into the
- * matching .amxd as a base64 payload.
+ * Emits dist/ui/<device>/index.html (the device view) and, for every window the
+ * device declares in its surface.ts, dist/ui/<device>/<winId>.html. `m4l-jweb
+ * build` embeds all of them into the matching .amxd as base64 payloads.
  *
  * Sequential, not parallel: vite reads DEVICE from the environment, and two
  * concurrent builds would race on it. The builds are ~500 ms each.
+ *
+ * THE RENAME DANCE around the window builds is load-bearing. Vite always writes
+ * its entry as `index.html`, so a window build lands on top of the device view we
+ * just produced - and `emptyOutDir` cannot be left on for it either, or the window
+ * build wipes the folder instead. So the device view is moved aside, the windows
+ * are built and renamed one by one, and it is moved back.
  */
 import { build } from "vite";
 import { uiDirs } from "./devices.mjs";
+// The PACKAGE export, not a path into packages/ - this file is copied verbatim
+// into the `m4l-jweb init` scaffold (tests/starter.test.mjs pins that), and a
+// scaffolded repo has no packages/ directory to reach into.
+import { loadSurface } from "@m4l-jweb/build/surface";
+import { renameSync } from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
 
 for (const dir of uiDirs) {
   process.env.DEVICE = dir;
+  delete process.env.WINDOW; // ...so this build empties the out dir and is the device view
   console.log(`\nm4l-jweb: bundling UI for ${dir}`);
   await build();
+
+  const outDir = path.join(root, "dist", "ui", dir);
+  const surface = await loadSurface(root, dir);
+  const windows = surface?.windows ? Object.keys(surface.windows) : [];
+  if (!windows.length) continue;
+
+  renameSync(path.join(outDir, "index.html"), path.join(outDir, "_device.html"));
+  for (const winId of windows) {
+    process.env.WINDOW = winId;
+    process.env.WINDOW_ENTRY = surface.windows[winId].entry;
+    console.log(`\nm4l-jweb: bundling window ${winId} for ${dir}`);
+    await build();
+    renameSync(path.join(outDir, "index.html"), path.join(outDir, `${winId}.html`));
+  }
+  renameSync(path.join(outDir, "_device.html"), path.join(outDir, "index.html"));
 }
 
 console.log(`\nm4l-jweb: ${uiDirs.length} UI bundle(s) -> dist/ui/`);

package/templates/starter/vite.config.ts

@@ -33,11 +33,14 @@ export default defineConfig(() => {
   // The device UI is bundled into ONE self-contained index.html (every script,
   // style and asset inlined) so it can be embedded in the .amxd as a base64
   // payload and extracted to a real file:// path that jweb (Chromium) reads.
+  const WINDOW_ENTRY = process.env.WINDOW_ENTRY;
+
   const config: UserConfig = {
     base: "./",
   plugins: [react(), viteSingleFile()],
   resolve: {
     alias: [
+      { find: "@device/App", replacement: fileURLToPath(new URL(`./src/app/${DEVICE}/${WINDOW_ENTRY ? WINDOW_ENTRY : "App"}`, import.meta.url)) },
       { find: "@device", replacement: fileURLToPath(new URL(`./src/app/${DEVICE}`, import.meta.url)) },
       { find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) },
     ],
@@ -60,7 +63,7 @@ export default defineConfig(() => {
     build: {
       // dist/ui/<device>/index.html - one per device, picked up by `m4l-jweb build`.
       outDir: `dist/ui/${DEVICE}`,
-      emptyOutDir: true,
+      emptyOutDir: !process.env.WINDOW,
     },
   };
   return config;