@m4l-jweb/build 0.5.0 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.5.0",
+  "version": "0.6.5",
   "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.5.0"
+    "@m4l-jweb/wrapper": "0.6.5"
   }
 }

package/src/chains.mjs

@@ -192,18 +192,26 @@ export function closeAudio(ctx) {
  * 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) {
+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: ${[...dupes].join(", ")}. ` +
+      `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}]`);
+  }
 }
 
 /**
@@ -355,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));
@@ -462,15 +470,653 @@ function driveChain(ctx) {
   }
 }
 
+/**
+ * "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));
+
+  // 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 }));
+  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));
+
+    // 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 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}`, 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));
+  });
+
+  // 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));
+    // 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);
+  }
+}
+
 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

@@ -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";
@@ -17,7 +17,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { AMXD_TYPES, assertES5, buildAmxd, extraPayloadsJs, payloadJs } from "./amxd.mjs";
 import { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, resetLayout } from "./chains.mjs";
-import { applySurface, loadSurface, surfaceContext } from "./surface.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: [],
@@ -188,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);
 
@@ -199,9 +213,14 @@ export function composePatcher(base, d, surface) {
   }
 
   applySurface(ctx);
+  applyWindows(ctx);
+  applyPersistence(ctx);
   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;
 }
 
@@ -229,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"})`);
@@ -292,20 +320,39 @@ 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);
 
+    // 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

@@ -294,3 +294,237 @@ 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, unmatchedId } = 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));
+    // 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,
+        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: 1,
+        outlettype: [""],
+        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],
+              },
+            },
+            // 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] } },
+          ],
+        },
+      },
+    });
+  });
+}
+
+/**
+ * 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.5.0",
-    "@m4l-jweb/surface": "^0.5.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.5.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/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;