@m4l-jweb/build 0.5.0 → 0.6.0

package/package.json

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

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}]`);
+  }
 }
 
 /**
@@ -462,13 +470,224 @@ 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));
+
+  // 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";
@@ -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: [],
@@ -199,6 +207,8 @@ export function composePatcher(base, d, surface) {
   }
 
   applySurface(ctx);
+  applyWindows(ctx);
+  applyPersistence(ctx);
   closeAudio(ctx);
   assertUniqueBoxIds(boxes, d.name);
 
@@ -292,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.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;