@m4l-jweb/build 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,7 @@
   "exports": {
     ".": "./src/index.mjs",
     "./chains": "./src/chains.mjs",
+    "./surface": "./src/surface.mjs",
     "./amxd": "./src/amxd.mjs",
     "./init": "./src/init.mjs"
   },
@@ -30,7 +31,8 @@
   "dependencies": {
     "acorn": "^8.17.0",
     "archiver": "^7.0.1",
+    "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "0.3.0"
+    "@m4l-jweb/wrapper": "0.5.0"
   }
 }

package/src/chains.mjs

@@ -5,9 +5,17 @@
  * `lines` (cords: [sourceBox, outlet] -> [destBox, inlet]). So we never draw
  * one - we generate it. Patch cords become code review.
  *
- * A chain is a small function that claims [jweb]'s outlet, routes the selectors
- * it owns, and passes everything else on to `unmatchedTo`. Add your own with
- * `registerChain()`; keep them small and named after what they do.
+ * A chain is a small function that claims a STAGE and hands the rest on. There
+ * are two streams to claim a stage in, and both work the same way:
+ *
+ *   the app's messages  `claimAppMessages(ctx, myRoute, unmatchedOutlet)`
+ *   the signal path     `ctx.audioIn(ch)` / `ctx.setAudioOut(ch, id, outlet)`
+ *
+ * A chain never OWNS either stream. It takes what the stage before it left, and
+ * says what it leaves for the stage after it - which is what makes
+ * `chains: ["lowpass", "gain"]` a series rather than two devices fighting over one
+ * patcher. Add your own with `registerChain()`; keep them small and named after
+ * what they do.
  */
 
 let y = 300; // stack generated objects below the hand-made ones
@@ -52,6 +60,152 @@ export function removeLine(lines, srcId, dstId) {
   }
 }
 
+/**
+ * Splice a `route` into the app's message stream and hand the rest on.
+ *
+ * More than one thing routes [jweb]'s output - `midiout` claims `midinote` and
+ * `flush`, the Surface claims every `set_<id>`, and whatever neither wanted must
+ * still reach the wrapper. They cannot hang off [jweb]'s outlet in parallel: each
+ * would pass the unmatched messages on to [js], and the wrapper would see
+ * `ui_ready` once per route. So they are chained in SERIES, each feeding the next
+ * from its unmatched outlet:
+ *
+ *   [jweb] -> [route midinote flush] -> [route set_density] -> [js]
+ *                        unmatched               unmatched
+ *
+ * `ctx.appOut` names the tail of that chain - the outlet currently carrying
+ * everything nobody has claimed. Claim from THAT, never from `jwebId` directly,
+ * or you steal the messages the chain before you was passing on.
+ *
+ * Do not go looking for the cord to cut by searching for whatever feeds [js]
+ * either: `live.thisdevice` feeds it too, and cutting that one is invisible here
+ * and fatal in Live - it is the bang every LiveAPI observer is created from.
+ */
+export function claimAppMessages(ctx, routeId, unmatchedOutlet) {
+  const [srcId, srcOutlet] = ctx.appOut ?? [ctx.jwebId, 0];
+
+  // Nobody has claimed the stream yet, and yet [jweb] no longer reaches the
+  // wrapper: a chain cut that cord by hand (the old `removeLine(jwebId,
+  // unmatchedId)` idiom) without saying where it put the messages. We cannot know
+  // - and guessing produces a patcher that WORKS while delivering every unrouted
+  // message twice, which is not a failure anyone would look for. Say so instead.
+  if (!ctx.appOut && !ctx.lines.some((l) => l.patchline.source[0] === ctx.jwebId && l.patchline.destination[0] === ctx.unmatchedId)) {
+    throw new Error(
+      `a chain on device "${ctx.device?.name}" took [jweb]'s outlet without claimAppMessages(). ` +
+        `Routes are chained in series, so each one must hand the next what it did not match. ` +
+        `Replace "removeLine(lines, jwebId, unmatchedId); lines.push(line(jwebId, 0, myRoute, 0)); ` +
+        `lines.push(line(myRoute, <last>, unmatchedId, 0));" with "claimAppMessages(ctx, myRoute, <last>)".`,
+    );
+  }
+
+  removeLine(ctx.lines, srcId, ctx.unmatchedId);
+  ctx.lines.push(line(srcId, srcOutlet, routeId, 0));
+  ctx.lines.push(line(routeId, unmatchedOutlet, ctx.unmatchedId, 0));
+  ctx.appOut = [routeId, unmatchedOutlet];
+}
+
+/* ------------------------------------------------------------------ *
+ * The signal path
+ * ------------------------------------------------------------------ */
+
+/** The device's audio endpoints. Created by the BUILD, never by a chain. */
+export const AUDIO_IN = "obj-plugin";
+export const AUDIO_OUT = "obj-plugout";
+
+/** plugin~ hands us a stereo pair, so every stage is a pair of signal objects. */
+export const AUDIO_CHANNELS = 2;
+
+/**
+ * Create the device's audio endpoints, once, before any chain runs.
+ *
+ * THIS IS THE FIX FOR A SILENT BUG. Every audio chain used to create `plugin~` and
+ * `plugout~` for itself and wire itself between them - so each one was a whole
+ * device, not a stage in one. `chains: ["lowpass", "gain"]` emitted two boxes
+ * sharing the id `obj-plugin`, two sharing `obj-plugout`, and FOUR sources summing
+ * into the output: the filtered pair and the unfiltered gain pair, in parallel. The
+ * effects did not stack, they mixed - with no error at build time and none in Live.
+ * It just sounded wrong in a way you would blame on your DSP.
+ *
+ * So the endpoints belong to the device, and a chain occupies a STAGE between them:
+ *
+ *   [plugin~] -> [onepole~] -> [*~] -> [plugout~]
+ *                 "lowpass"   "gain"
+ *
+ * `ctx.audioIn(ch)` is whatever the last stage left on that channel - `plugin~` if
+ * you are the first. `ctx.setAudioOut(ch, id, outlet)` says you are the tail now.
+ * `closeAudio()` wires the final tail into `plugout~` once every chain has run.
+ *
+ * It is the same shape as `claimAppMessages()` one layer down: several things want
+ * one stream, so they are chained in SERIES with an explicit hand-off rather than
+ * hung off the source in parallel.
+ */
+export function openAudio(ctx) {
+  const { boxes, lines, device } = ctx;
+  const type = device?.type;
+
+  if (type !== "audio" && type !== "instrument") {
+    // A MIDI effect has no signal path at all. Say so when a chain asks for one,
+    // rather than emitting a cord from a box that does not exist - which Max opens
+    // as a patcher with a missing object and no explanation.
+    const refuse = () => {
+      throw new Error(
+        `a chain on device "${device?.name}" asked for the signal path, but the device is type "${type}". ` +
+          `plugin~/plugout~ exist only in an audio-effect or instrument device: set \`type: "audio"\` in patcher/devices.mjs.`,
+      );
+    };
+    ctx.audioIn = refuse;
+    ctx.setAudioOut = refuse;
+    return;
+  }
+
+  // An audio effect has no MIDI ports. An instrument keeps them: MIDI in is how it
+  // is played.
+  if (type === "audio") {
+    removeBox(boxes, lines, "obj-midiin");
+    removeBox(boxes, lines, "obj-midiout");
+  }
+
+  boxes.push(box(AUDIO_IN, "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
+  boxes.push(box(AUDIO_OUT, "plugout~", { numinlets: 2, numoutlets: 0 }));
+
+  // The tail of the signal path, per channel. Nothing has claimed a stage yet, so
+  // it is the input: a device with no audio chain at all is a straight wire.
+  ctx.audioTail = Array.from({ length: AUDIO_CHANNELS }, (_, ch) => [AUDIO_IN, ch]);
+  ctx.audioIn = (ch) => ctx.audioTail[ch];
+  ctx.setAudioOut = (ch, id, outlet = 0) => {
+    ctx.audioTail[ch] = [id, outlet];
+  };
+}
+
+/** Wire whatever the last stage left into `plugout~`. The build calls this last. */
+export function closeAudio(ctx) {
+  if (!ctx.audioTail) return; // not an audio device
+  ctx.audioTail.forEach(([srcId, srcOut], ch) => ctx.lines.push(line(srcId, srcOut, AUDIO_OUT, ch)));
+}
+
+/**
+ * Two boxes with one id is a MALFORMED patcher, and Max resolves it however it
+ * likes - so the device loads, and the cords go somewhere nobody chose. That was
+ * the visible half of the audio-chain bug, and nothing rejected it. This does.
+ *
+ * The build calls it after every chain and the Surface have run, on the patcher
+ * that is about to be written, so it covers the canned chains, a device repo's own
+ * `patcher/chains.mjs`, and the template underneath both.
+ */
+export function assertUniqueBoxIds(boxes, deviceName) {
+  const seen = new Set();
+  const dupes = new Set();
+  for (const { box: b } of boxes) (seen.has(b.id) ? dupes : seen).add(b.id);
+  if (dupes.size) {
+    throw new Error(
+      `device "${deviceName}" generated duplicate box ids: ${[...dupes].join(", ")}. ` +
+        `Two boxes with one id is a patcher Max will interpret however it likes. ` +
+        `A chain that creates a box another chain also creates is not a stage - it is claiming to be the whole device. ` +
+        `Take the stage before you (ctx.audioIn / ctx.appOut) and hand yours on, or name your boxes after your chain.`,
+    );
+  }
+}
+
 /**
  * "midiin" - feed incoming MIDI notes to the app as `notein <pitch> <velocity>`.
  *
@@ -77,10 +231,8 @@ function midiInChain({ boxes, lines, jwebId }) {
  * "midiout" - the app emits `midinote <pitch> <vel> <durMs> <chan> <delayMs>`
  * and `flush`. Compute WHEN in your app; let Max place the note precisely.
  */
-function midiOutChain({ boxes, lines, jwebId, unmatchedId }) {
-  // This chain consumes jweb's output, so the template's direct jweb -> js cord
-  // is replaced by the route's unmatched outlet.
-  removeLine(lines, jwebId, unmatchedId);
+function midiOutChain(ctx) {
+  const { boxes, lines } = ctx;
 
   boxes.push(box("obj-route", "route midinote flush", { numoutlets: 3, outlettype: ["", "", ""] }));
   // Explicit unpack instead of letting pipe spread the list: unpack fires
@@ -108,7 +260,11 @@ function midiOutChain({ boxes, lines, jwebId, unmatchedId }) {
   // makenote actually releases hanging notes.
   boxes.push(box("obj-flushmsg", "flush", { maxclass: "message", numinlets: 2, numoutlets: 1 }));
 
-  lines.push(line(jwebId, 0, "obj-route", 0));
+  // Take the app's messages, and pass on what is not a note (ui_ready, set_<id>,
+  // ...) from outlet 2 - to the Surface's route if the device has parameters, and
+  // to the wrapper in the end.
+  claimAppMessages(ctx, "obj-route", 2);
+
   lines.push(line("obj-route", 0, "obj-unpack", 0));
   lines.push(line("obj-route", 1, "obj-flushmsg", 0));
   lines.push(line("obj-flushmsg", 0, "obj-makenote", 0));
@@ -121,32 +277,28 @@ function midiOutChain({ boxes, lines, jwebId, unmatchedId }) {
   lines.push(line("obj-makenote", 1, "obj-packnote", 1));
   lines.push(line("obj-packnote", 0, "obj-fmt", 0));
   lines.push(line("obj-fmt", 0, "obj-midiout", 0));
-  // Unmatched selectors (ui_ready, write_clip, read_notes...) carry on.
-  lines.push(line("obj-route", 2, unmatchedId, 0));
 }
 
 /**
  * "passthrough" - an audio effect that passes its input through UNTOUCHED.
  *
- * It is a straight wire: `plugin~ -> plugout~`. Removing it from a track sounds
+ * It claims no stage, so the signal path stays what the build left it:
+ * `plugin~ -> plugout~`, a straight wire. Removing the device from a track sounds
  * identical, because it does nothing to the audio - it exists to prove that an
  * audio-effect container builds and that the UI runs inside one.
  *
- * It is a scaffold, not a feature. If you want an audio effect that is audible,
- * you want `gain` below, or your own chain shaped like it.
+ * It is a scaffold, not a feature, and since the build now creates the endpoints it
+ * is also a NO-OP: `type: "audio"` with no chains at all does exactly this. It
+ * survives because `chains: ["passthrough"]` says out loud what an empty list only
+ * implies. If you want an audio effect that is audible, you want `gain` below, or
+ * your own chain shaped like it.
  */
-function passthroughChain({ boxes, lines }) {
-  // An audio effect has no MIDI ports.
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
-  lines.push(line("obj-plugin", 0, "obj-plugout", 0));
-  lines.push(line("obj-plugin", 1, "obj-plugout", 1));
+function passthroughChain(ctx) {
+  ctx.audioIn(0); // ...and hand it straight on. Also asserts the device HAS audio.
 }
 
 /**
- * "gain" - an audio effect that actually DOES something: `plugin~ -> *~ -> plugout~`,
+ * "gain" - an audio effect that actually DOES something: `*~` in the signal path,
  * with a Live parameter riding the multiplier. Turn the dial, hear the level move.
  *
  * The smallest honest example of the shape every audio effect has - your DSP goes
@@ -154,112 +306,73 @@ function passthroughChain({ boxes, lines }) {
  * SIGNAL domain, not just the app.
  *
  * Note what does NOT happen here: the value does not travel through [jweb] and
- * back. The dial is wired straight into the `*~` right inlet, in the patcher, so
- * the audio path does not depend on the browser being alive or keeping up. The
- * app gets its own copy of the value (via addParameters) purely to DISPLAY it.
- * Audio is Max's job; the UI is a view of it.
+ * back. The parameter is wired straight into the `*~` right inlet, in the patcher,
+ * so the audio path does not depend on the browser being alive or keeping up. The
+ * app gets its own copy of the value purely to DISPLAY it. Audio is Max's job; the
+ * UI is a view of it.
  *
- * Requires a parameter named `gain` (or pass `device.gainParam`).
+ * Requires a parameter named `gain` in the device's surface.ts (or pass
+ * `device.gainParam`).
  */
-function gainChain({ boxes, lines, device }) {
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-
-  const paramId = device?.gainParam ?? "gain";
-  const declared = (device?.parameters ?? []).some((p) => p.id === paramId);
-  if (!declared) {
-    throw new Error(`chain "gain" on device "${device?.name}" needs a parameter with id "${paramId}" (or set gainParam)`);
-  }
-
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
+function gainChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const paramId = requireParam(ctx, "gain", device?.gainParam ?? "gain", "gainParam");
 
   // One *~ per channel: a signal object handles ONE signal, and plugin~ hands us
   // a stereo pair. `1.` (a float, not an int) keeps the right inlet in float mode.
-  for (const [i, id] of [
+  for (const [ch, id] of [
     [0, "obj-gain-l"],
     [1, "obj-gain-r"],
   ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch); // whatever the last stage left
     boxes.push(box(id, "*~ 1.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
-    lines.push(line("obj-plugin", i, id, 0));
-    lines.push(line(id, 0, "obj-plugout", i));
-    // The live.dial box is created LATER, by addParameters(). A patchline may name
-    // a box that appears further down the boxes array - the patcher is a graph, not
-    // a script - so this cord is valid as long as the parameter is declared, which
-    // is what the check above guarantees.
-    lines.push(line(`obj-param-${paramId}`, 0, id, 1));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0); // we are the tail now
+    fanParamInto(ctx, paramId, id, 1);
   }
 }
 
 /**
- * Let the APP write to a Live parameter: `set_<id> <value>` from [jweb] lands on
- * the live.* object's inlet, and from there in the signal path and in Live's
- * automation, exactly as if the user had turned the dial.
- *
- * This is the missing half of the parameter story. Reading one has always worked
- * (addParameters wires the object out to the app). Writing one did not exist, so
- * a control in the web UI could only ever be a readout of a knob you had to turn
- * somewhere else - useless.
- *
- * TWO TRAPS, and the whole design of this helper is about them:
- *
- * 1. FEEDBACK. Sending a bare value into a live.dial's inlet SETS IT AND MAKES
- *    IT OUTPUT, which sends it straight back to the app - which could set it
- *    again. `set <value>` is the documented message that updates the value
- *    WITHOUT producing outlet output, so the loop never starts. (Spike 1.1 in
- *    doc/SPIKES.md confirms the behaviour properly; the field evidence is
- *    below.)
- *
- * 2. `set` SUPPRESSING THE OUTPUT IS NOT FREE. It silences the dial for
- *    EVERYONE, not just for the app - including whatever the dial drives inside
- *    the patcher. The first version of the lowpass chain fed its filter from the
- *    dial's OUTLET, so writing the parameter with `set` moved the dial and told
- *    the filter nothing: the slider appeared dead and the cutoff never budged.
- *
- *    So the value is FANNED OUT, not chained. The route outlet is the source of
- *    truth for the app's write, and the caller taps it directly (see
- *    `valueOutlet` below) to drive whatever the parameter controls. The dial is
- *    updated in parallel, so Live's automation, MIDI mapping and Push all stay
- *    correct - but nothing downstream *depends* on the dial re-emitting.
- *
- *    The dial's own outlet still feeds the same destination, because that is the
- *    path a real knob-turn, an automation lane or a Push encoder travels.
- *
- * Returns `{ valueOutlet(id) }`: the [route] outlet carrying the raw value the
- * app wrote, for the chain to wire wherever the parameter actually acts.
- *
- * This is a hand-rolled sliver of what the Surface will generate for every
- * parameter at once (Stage 2 of doc/TODO.md). It is here because "a slider in
- * the device window that actually does something" should not have to wait.
+ * Wire a parameter into the thing it controls, from BOTH of its sources:
+ *
+ *   the OBJECT's outlet - a knob turn, an automation lane, a Push encoder.
+ *   the ROUTE's outlet  - the value the app wrote.
+ *
+ * The second is not redundant, and leaving it out is the bug this helper exists to
+ * make unrepeatable. The app's write reaches the object as `set <value>`, which
+ * updates it WITHOUT producing output - so the object never passes the app's value
+ * on, and whatever it drives sits where it was while the UI's slider appears dead.
+ * It did exactly that. See packages/build/src/surface.mjs.
+ *
+ * The boxes named here are created LATER, by applySurface(). A patchline may name a
+ * box further down the array: a patcher is a graph, not a script.
+ *
+ * THE VALUE ARRIVES IN REAL UNITS, AND A CHAIN DOES NO ARITHMETIC ON IT. The range,
+ * the unit and the curve live on the PARAMETER (`range: [40, 18000]`, `unit: "Hz"`,
+ * `exponent`) - which is where Live wants them: the automation lane reads Hz, Push
+ * reads "7.3 kHz", and the number drops straight into the DSP object. `lowpass`
+ * used to take a 0-1 parameter and map it with `[expr 40. * pow(450., $f1)]`; a
+ * chain that reintroduces a mapping like that DOUBLE-MAPS a parameter that already
+ * carries its own curve, and lies to every readout while it does it.
  */
-function writableParams({ boxes, lines, jwebId, unmatchedId }, ids) {
-  removeLine(lines, jwebId, unmatchedId);
+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));
+  ctx.lines.push(line(routeId, routeOut, dstId, dstInlet));
+}
 
-  const selectors = ids.map((id) => `set_${id}`);
-  boxes.push(
-    box("obj-setparam-route", `route ${selectors.join(" ")}`, {
-      numoutlets: ids.length + 1,
-      outlettype: ids.map(() => "").concat(""),
-    }),
-  );
-  lines.push(line(jwebId, 0, "obj-setparam-route", 0));
-
-  ids.forEach((id, i) => {
-    // `route` STRIPS the selector, so what emerges is the bare value. Re-wrap it
-    // as `set <value>` - the set-without-output message - and feed the object, so
-    // the dial, the automation lane and Push all follow the app's slider.
-    boxes.push(box(`obj-set-${id}`, "prepend set"));
-    lines.push(line("obj-setparam-route", i, `obj-set-${id}`, 0));
-    lines.push(line(`obj-set-${id}`, 0, `obj-param-${id}`, 0));
-  });
-
-  // Unmatched (ui_ready, and anything the wrapper handles) carries on.
-  lines.push(line("obj-setparam-route", ids.length, unmatchedId, 0));
-
-  return {
-    /** The outlet carrying the value the APP wrote. Wire it where the parameter acts. */
-    valueOutlet: (id) => ["obj-setparam-route", ids.indexOf(id)],
-  };
+/** A chain that drives DSP from a parameter is broken without it - say so loudly. */
+function requireParam(ctx, chainName, paramId, overrideField) {
+  if (!ctx.surface?.params?.[paramId]) {
+    const declared = ctx.surface ? ctx.surface.ids.join(", ") || "none" : "no surface.ts at all";
+    throw new Error(
+      `chain "${chainName}" on device "${ctx.device?.name}" needs a parameter "${paramId}" in ` +
+        `src/app/${ctx.device?.ui ?? ctx.device?.name}/surface.ts (declared: ${declared}). ` +
+        `Rename it, or point the chain at another one with \`${overrideField}\`.`,
+    );
+  }
+  return paramId;
 }
 
 /**
@@ -271,7 +384,7 @@ function writableParams({ boxes, lines, jwebId, unmatchedId }, ids) {
  * parameter via `set_cutoff` - so moving it moves the dial, the automation lane
  * and the filter together. It is one control, with two faces.
  *
- * `plugin~ -> onepole~ -> plugout~`, one filter per channel.
+ * `onepole~` in the signal path, one filter per channel.
  *
  * WHY onepole~ and not lores~/svf~/biquad~: a one-pole is a 6 dB/octave slope -
  * the gentlest filter there is. It cannot self-oscillate, cannot blow up, and
@@ -279,66 +392,73 @@ function writableParams({ boxes, lines, jwebId, unmatchedId }, ids) {
  * effect is unmistakable when you sweep it, and there is no way to configure it
  * into silence or into a scream. Swap in `svf~` when you want a real filter.
  *
- * THE CUTOFF MAPPING is the interesting part. The dial is 0-1 (a Live parameter
- * wants a bounded, automatable range), but pitch is logarithmic: a linear sweep
- * from 20 Hz to 18 kHz spends almost all its travel in the top octave, where you
- * can hear nothing happening, and races through the bottom, where everything
- * happens. So the value goes through [expr] first:
- *
- *     40 * 450^x     x = 0 -> 40 Hz,  x = 0.5 -> ~850 Hz,  x = 1 -> 18 kHz
- *
- * which spreads the audible action evenly across the knob. This is exactly the
- * curve a filter knob on real hardware has.
+ * THE CUTOFF IS IN HERTZ, and no arithmetic happens here. The chain used to take a
+ * 0-1 parameter and map it through `[expr 40. * pow(450., $f1)]`, because pitch is
+ * logarithmic and a linear knob is useless on a filter. That mapping now lives on
+ * the PARAMETER (`range: [40, 18000]`, `unit: "Hz"`, `exponent`), which is where
+ * Live wants it: the automation lane reads Hz, Push reads "7.3 kHz", the app reads
+ * Hz, and the value drops straight into onepole~. A normalised parameter with the
+ * curve hidden in a chain lies to every one of those readouts.
  *
- * Requires a parameter named `cutoff` (or pass `device.cutoffParam`).
+ * Requires a parameter named `cutoff` (or pass `device.cutoffParam`), in Hz.
  */
 function lowpassChain(ctx) {
   const { boxes, lines, device } = ctx;
-  removeBox(boxes, lines, "obj-midiin");
-  removeBox(boxes, lines, "obj-midiout");
-
-  const paramId = device?.cutoffParam ?? "cutoff";
-  const declared = (device?.parameters ?? []).some((p) => p.id === paramId);
-  if (!declared) {
-    throw new Error(`chain "lowpass" on device "${device?.name}" needs a parameter with id "${paramId}" (or set cutoffParam)`);
-  }
-
-  // The slider in the device window writes the parameter: `set_cutoff <0-1>`.
-  const { valueOutlet } = writableParams(ctx, [paramId]);
-  const [routeId, routeOut] = valueOutlet(paramId);
-
-  boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
-  boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
-
-  // 0-1 -> 40..18000 Hz, logarithmically. Floats, not ints: `40.` and `450.` keep
-  // expr in float mode, and an int cutoff would quantise the sweep into steps.
-  boxes.push(box("obj-cutoff-hz", "expr 40. * pow(450., $f1)", { numinlets: 1, numoutlets: 1, outlettype: [""] }));
-
-  // TWO sources feed the filter, and it needs both:
-  //
-  //   the DIAL's outlet    - a knob turn, an automation lane, a Push encoder.
-  //   the ROUTE's outlet   - the app's slider.
-  //
-  // The second is not redundant. The app writes the dial with `set`, which
-  // updates it WITHOUT producing output - so the dial would never pass the app's
-  // value on, and the filter would sit wherever it was while the slider appeared
-  // to do nothing. (It did exactly that.) Tap the value where it enters.
-  lines.push(line(`obj-param-${paramId}`, 0, "obj-cutoff-hz", 0));
-  lines.push(line(routeId, routeOut, "obj-cutoff-hz", 0));
+  const paramId = requireParam(ctx, "lowpass", device?.cutoffParam ?? "cutoff", "cutoffParam");
 
   // One filter per channel: a signal object handles ONE signal, and plugin~ hands
   // us a stereo pair. Both take the same cutoff, so the image does not shift.
-  for (const [i, id] of [
+  for (const [ch, id] of [
     [0, "obj-lpf-l"],
     [1, "obj-lpf-r"],
   ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
     boxes.push(box(id, "onepole~ 18000.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
-    lines.push(line("obj-plugin", i, id, 0));
-    lines.push(line(id, 0, "obj-plugout", i));
-    // Cutoff into the RIGHT inlet. The dial box itself is created LATER, by
-    // addParameters() - a patchline may name a box further down the array,
-    // because a patcher is a graph, not a script.
-    lines.push(line("obj-cutoff-hz", 0, id, 1));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0);
+    // The cutoff, in Hz, into the RIGHT inlet - from both of its sources: the dial
+    // (a knob turn, an automation lane, a Push encoder) and the route (the app's
+    // write, which the dial will not re-emit because it arrives as `set`).
+    fanParamInto(ctx, paramId, id, 1);
+  }
+}
+
+/**
+ * "drive" - soft-clipping distortion: an `overdrive~` in the signal path, with a
+ * Live parameter on the drive factor.
+ *
+ * THE CHAIN WHOSE PLACE IN THE LIST YOU CAN HEAR, and it is in the vocabulary for
+ * that reason as much as for the sound. `lowpass` and `gain` are both LINEAR, so
+ * they commute: `["lowpass", "gain"]` and `["gain", "lowpass"]` generate different
+ * patchers and produce identical audio. A composition built only from those two
+ * cannot be verified by ear - you would reorder them, hear nothing change, and
+ * reasonably conclude the build was broken.
+ *
+ * Distortion does not commute with a level change. `["gain", "drive"]` turns the
+ * signal down and THEN distorts it, so a quiet input barely clips; `["drive",
+ * "gain"]` distorts at full level and turns the result down, so it stays dirty and
+ * gets quieter. Same two chains, same parameters, unmistakably different sound -
+ * which is what makes the series real rather than a claim in a test.
+ *
+ * `overdrive~` limits to +/- 1 and takes its drive factor (1 = clean, 10 = filthy)
+ * in the RIGHT inlet, per Max's own reference. Below 1 it distorts violently; the
+ * parameter's range starts at 1, which is where a user would expect "off" to be.
+ *
+ * Requires a parameter named `drive` (or pass `device.driveParam`).
+ */
+function driveChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const paramId = requireParam(ctx, "drive", device?.driveParam ?? "drive", "driveParam");
+
+  for (const [ch, id] of [
+    [0, "obj-drive-l"],
+    [1, "obj-drive-r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    boxes.push(box(id, "overdrive~ 1.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0);
+    fanParamInto(ctx, paramId, id, 1);
   }
 }
 
@@ -348,6 +468,7 @@ export const CHAINS = {
   passthrough: passthroughChain,
   gain: gainChain,
   lowpass: lowpassChain,
+  drive: driveChain,
 };
 
 /** Add a chain to the vocabulary. Called before generatePatchers(). */
@@ -356,48 +477,12 @@ export function registerChain(name, fn) {
 }
 
 /**
- * Real Live parameters: automatable, MIDI-mappable, and the ONLY thing Push can
- * display. Each becomes a live.* object wired into the UI as `<id> <value>`, so
- * a parameter change is just another inlet message to your app.
- *
- * `default` is not optional in practice, whatever the type says. A live.* object
- * with no initial value loads at the BOTTOM of its range, and for a great many
- * parameters the bottom of the range is a broken device: a filter cutoff of 0
- * loads as a device that eats the signal, and it looks exactly like a bug in your
- * DSP. Declare `default` and Max stores it as the object's initial value, which
- * Live restores on load and on "reset to default".
+ * Parameters used to be declared in the manifest and generated here, by
+ * `addParameters()`, in ONE direction: object -> app. Writing one back was a
+ * per-chain hand-roll (`writableParams()`).
+ *
+ * Both are gone. A device's parameters are declared in `src/app/<ui>/surface.ts`
+ * and compiled by `applySurface()` in surface.mjs - objects, both directions, and
+ * the fan-out that the `set` behaviour forces. A chain reaches them through
+ * `fanParamInto()` above.
  */
-export function addParameters(boxes, lines, params, dstId) {
-  let x = 480;
-  for (const p of params) {
-    const objId = `obj-param-${p.id}`;
-    const prependId = `obj-prepend-${p.id}`;
-    boxes.push({
-      box: {
-        id: objId,
-        maxclass: p.object, // live.dial | live.toggle | live.menu
-        numinlets: 1,
-        numoutlets: 1,
-        outlettype: [""],
-        parameter_enable: 1,
-        patching_rect: [x, 300, 44, 48],
-        saved_attribute_attributes: {
-          valueof: {
-            parameter_longname: p.id,
-            parameter_shortname: p.id.slice(0, 8), // Push shows short names
-            parameter_type: p.object === "live.toggle" ? 2 : 0, // 2 = enum, 0 = float
-            ...(p.range ? { parameter_range: p.range } : {}),
-            // parameter_initial is a LIST, and it is inert without
-            // parameter_initial_enable - setting one without the other silently
-            // does nothing, which is the worst way for this to fail.
-            ...(p.default !== undefined ? { parameter_initial_enable: 1, parameter_initial: [p.default] } : {}),
-          },
-        },
-      },
-    });
-    boxes.push(box(prependId, `prepend ${p.id}`));
-    lines.push(line(objId, 0, prependId, 0));
-    lines.push(line(prependId, 0, dstId, 0));
-    x += 56;
-  }
-}

package/src/index.mjs

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

package/src/surface.mjs

@@ -0,0 +1,296 @@
+/**
+ * surface.mjs - the Surface compiler.
+ *
+ * One declaration (`src/app/<device>/surface.ts`) becomes the whole Max side of a
+ * parameter: the `live.*` object, its wiring in BOTH directions, and the protocol
+ * selectors the lint then checks for free. It replaces `addParameters()` (which
+ * only ever did the read direction) and `writableParams()` (which did the write
+ * direction, by hand, for one parameter at a time).
+ *
+ * ------------------------------------------------------------------------------
+ * THE TRAP THIS FILE EXISTS TO NOT REPRODUCE
+ *
+ * The app writes a parameter by sending `set_<id> <value>`, and the patcher feeds
+ * the object a `set <value>` message. `set` updates the object WITHOUT making it
+ * output - which is what stops the app feeding itself back in a loop.
+ *
+ * But `set` does not suppress the outlet for the app only. It suppresses it for
+ * EVERYONE, including whatever that object drives inside the patcher. The first
+ * `lowpass` chain fed its filter from the dial's outlet, and the app wrote the
+ * dial with `set`: the dial moved, and the filter never heard a thing. The slider
+ * looked dead.
+ *
+ * So a parameter's value is FANNED OUT, never chained:
+ *
+ *        [jweb] --set_cutoff--> [route] --+--> [prepend set] --> [live.dial] --+
+ *                                         |                                    |
+ *                                         +-------------> the DSP <------------+
+ *                                                    (or whatever it drives)
+ *
+ * The object is updated in parallel, so automation, MIDI mapping and Push all stay
+ * correct - but nothing downstream DEPENDS on it re-emitting. The object's own
+ * outlet still reaches the same destination, because that is the path a knob turn,
+ * an automation lane or a Push encoder travels.
+ *
+ * `paramValue()` below is the route outlet a chain taps for the app's write;
+ * `paramObject()` is the object's own outlet. A chain that drives DSP from a
+ * parameter must wire BOTH. `tests/surface.test.mjs` asserts it.
+ * ------------------------------------------------------------------------------
+ */
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { box, claimAppMessages, line } from "./chains.mjs";
+
+/** The one route that dispatches every `set_<id>` the app sends. */
+export const SURFACE_ROUTE = "obj-surface-route";
+
+/** The `live.*` object for a parameter. Its outlet is a knob turn / automation. */
+export const paramObject = (id) => `obj-param-${id}`;
+
+/**
+ * The route outlet carrying the value the APP wrote - the fan-out tap.
+ *
+ * Deterministic from the declaration, so a chain can wire it before the route box
+ * exists: a patcher is a graph, not a script, and a cord may name a box that
+ * appears later in the array.
+ */
+export const paramValue = (surface, id) => [SURFACE_ROUTE, surface.ids.indexOf(id)];
+
+/**
+ * What a chain is handed to reach the parameters: `surface` (to check a parameter
+ * it needs exists) and the two outlets it must fan a value out of. Spread into the
+ * chain context by the build - and by the codegen test, so the test drives the
+ * chains through the same seam the build does.
+ */
+export function surfaceContext(surface) {
+  return {
+    surface,
+    paramObject: (id) => [paramObject(id), 0],
+    paramValue: (id) => paramValue(surface, id),
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Reading the declaration
+ * ------------------------------------------------------------------ */
+
+/**
+ * Evaluate `src/app/<ui>/surface.ts` in Node.
+ *
+ * It is TypeScript, and it imports @m4l-jweb/surface, whose entry point is also
+ * TypeScript - so it has to be bundled before it can be imported. esbuild does
+ * that in milliseconds. `defineSurface()` returns plain serializable data, so
+ * nothing exotic crosses the boundary.
+ *
+ * `format` is the exception: it is a FUNCTION, and functions do not serialize
+ * into a patcher. It survives the import (this is a real module, not JSON) and is
+ * used app-side only - by the dev harness and the Push preview. Do not try to
+ * ship it into [js].
+ */
+export async function loadSurface(root, uiDir) {
+  const src = path.join(root, "src", "app", uiDir, "surface.ts");
+  if (!existsSync(src)) return null;
+
+  const { build } = await import("esbuild");
+  const tmp = mkdtempSync(path.join(tmpdir(), "m4l-surface-"));
+  const out = path.join(tmp, "surface.mjs");
+  try {
+    await build({
+      entryPoints: [src],
+      outfile: out,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      logLevel: "silent",
+      // React is not imported by a surface declaration, and bundling it here would
+      // be both slow and pointless.
+      external: ["react", "react-dom"],
+    });
+    const mod = await import(pathToFileURL(out).href);
+    const surface = mod.default;
+    if (!surface?.ids) {
+      throw new Error(`${src} must \`export default defineSurface({...})\``);
+    }
+    return surface;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Generating the objects
+ * ------------------------------------------------------------------ */
+
+const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu" };
+
+/**
+ * Max's `parameter_type`: 0 = float, 1 = int, 2 = enum.
+ *
+ * A dial with `step: 1` is an INTEGER parameter - which matters to Live, not just
+ * to us: an int parameter quantises automation and shows whole numbers on Push,
+ * where a float one would read "2.4 of [off 1/4 1/8 ...]".
+ */
+function parameterType(spec) {
+  if (spec.kind === "menu" || spec.kind === "toggle") return 2;
+  return spec.step === 1 ? 1 : 0;
+}
+
+/**
+ * `parameter_unitstyle` - HOW LIVE PRINTS THE VALUE, and the reason a perfectly
+ * good float parameter can read "0" and "1" on a Push.
+ *
+ * The unit style is a display concern with no effect on the value, which is
+ * exactly what makes it easy to get wrong and hard to notice: the dial sweeps
+ * continuously, the DSP hears every intermediate value, and Push rounds the
+ * readout to an integer because THAT is what unit style 0 means. Declare the unit
+ * and the same knob reads "7.3 kHz".
+ *
+ * The order below is the order the unit styles are listed in Max's own reference
+ * (docs/refpages/m4l-ref/parameters.maxref.xml), and 3 = Hertz is confirmed
+ * against the factory devices that ship with Live: every parameter named
+ * "Frequency" / "Master Freq" carries `parameter_unitstyle: 3`.
+ */
+const UNITSTYLE = {
+  int: 0,
+  float: 1,
+  ms: 2,
+  Hz: 3,
+  dB: 4,
+  "%": 5,
+  pan: 6,
+  st: 7,
+  midi: 8,
+  // 9 = Custom (takes parameter_units), 10 = Native.
+};
+const UNITSTYLE_CUSTOM = 9;
+
+/**
+ * A dial's unit. No `unit` means "just a number": integer if the parameter is an
+ * integer, float otherwise - because the default, 0, prints a float as a rounded
+ * integer.
+ */
+function unitAttrs(spec) {
+  if (!spec.unit) return { parameter_unitstyle: spec.step === 1 ? UNITSTYLE.int : UNITSTYLE.float };
+  const known = UNITSTYLE[spec.unit];
+  if (known !== undefined) return { parameter_unitstyle: known };
+  // Anything else is a custom unit: Live prints the number and appends the string
+  // (or honours a sprintf pattern, e.g. "%0.2f Bogons").
+  return { parameter_unitstyle: UNITSTYLE_CUSTOM, parameter_units: spec.unit };
+}
+
+/** The parameter's value as MAX stores it: numbers, always. */
+function initialValue(spec) {
+  if (spec.kind === "toggle") return spec.default ? 1 : 0;
+  if (spec.kind === "menu") return spec.options.indexOf(spec.default);
+  return spec.default;
+}
+
+/**
+ * The `saved_attribute_attributes.valueof` block, in the shape Max itself writes.
+ *
+ * THE RANGE IS `parameter_mmin` / `parameter_mmax`, NOT `parameter_range`. This
+ * cost a device: we emitted `parameter_range: [0, 1]` for a long time, and it is
+ * not a key Max uses for a continuous parameter - so the range was whatever the
+ * object defaulted to, silently. `parameter_range` appears in exactly zero of the
+ * patchers Ableton ships. An enum's options are `parameter_enum`, with
+ * `parameter_mmax` holding the highest index.
+ */
+function parameterAttrs(id, spec) {
+  const attrs = {
+    parameter_longname: id,
+    parameter_shortname: spec.short,
+    parameter_type: parameterType(spec),
+    // `parameter_initial` is a LIST, and it is INERT without
+    // parameter_initial_enable - setting one without the other silently does
+    // nothing, which is the worst way for this to fail. A live.* object with no
+    // initial value loads at the BOTTOM of its range, and for a filter cutoff the
+    // bottom of the range is a device that eats the signal on load.
+    parameter_initial_enable: 1,
+    parameter_initial: [initialValue(spec)],
+  };
+
+  if (spec.kind === "dial") {
+    const [min, max] = spec.range;
+    attrs.parameter_mmin = min;
+    attrs.parameter_mmax = max;
+    Object.assign(attrs, unitAttrs(spec));
+    // `parameter_exponent` bends the knob's travel: > 1 gives the bottom of the
+    // range more of the sweep, which is what a frequency or a time wants, because
+    // hearing is logarithmic and a linear sweep spends its travel where nothing
+    // happens. The VALUE is unaffected - only how the dial's rotation maps onto it.
+    if (spec.exponent !== undefined && spec.exponent !== 1) attrs.parameter_exponent = spec.exponent;
+    // `parameter_steps` quantises a continuous range into N settings.
+    if (spec.steps !== undefined) attrs.parameter_steps = spec.steps;
+  }
+
+  if (spec.kind === "toggle") {
+    attrs.parameter_mmax = 1;
+    attrs.parameter_enum = ["off", "on"];
+  }
+
+  if (spec.kind === "menu") {
+    attrs.parameter_enum = [...spec.options];
+    attrs.parameter_mmax = spec.options.length - 1;
+  }
+
+  return attrs;
+}
+
+/**
+ * Compile the Surface into the patcher.
+ *
+ * Runs AFTER the chains, and claims what they did not want: the app's `set_<id>`
+ * messages are picked off the stream, and everything else carries on to the
+ * wrapper. Doing it last means no chain has to know the Surface exists.
+ */
+export function applySurface(ctx) {
+  const { boxes, lines, surface, jwebId } = ctx;
+  if (!surface || surface.ids.length === 0) return;
+
+  let x = 480;
+  for (const id of surface.ids) {
+    const spec = surface.params[id];
+    boxes.push({
+      box: {
+        id: paramObject(id),
+        maxclass: MAXCLASS[spec.kind],
+        numinlets: 1,
+        numoutlets: 1,
+        outlettype: [""],
+        parameter_enable: 1,
+        patching_rect: [x, 300, 44, 48],
+        saved_attribute_attributes: { valueof: parameterAttrs(id, spec) },
+      },
+    });
+    // Read direction: a knob turn reaches the app as `<id> <value>`. A parameter
+    // is just another inlet message.
+    boxes.push(box(`obj-prepend-${id}`, `prepend ${id}`));
+    lines.push(line(paramObject(id), 0, `obj-prepend-${id}`, 0));
+    lines.push(line(`obj-prepend-${id}`, 0, jwebId, 0));
+    x += 56;
+  }
+
+  // Write direction: one route for every `set_<id>` the app can send. It goes at
+  // the END of the chain of routes (see claimAppMessages), so a chain that already
+  // took [jweb]'s outlet keeps it and hands us what it did not match.
+  const selectors = surface.ids.map((id) => `set_${id}`);
+  boxes.push(
+    box(SURFACE_ROUTE, `route ${selectors.join(" ")}`, {
+      numoutlets: surface.ids.length + 1,
+      outlettype: surface.ids.map(() => "").concat(""),
+    }),
+  );
+  claimAppMessages(ctx, SURFACE_ROUTE, surface.ids.length);
+
+  surface.ids.forEach((id, i) => {
+    // `route` STRIPS the selector, so what emerges is the bare value. Re-wrap it as
+    // `set <value>` - the set-WITHOUT-output message - so the object, the automation
+    // lane and Push all follow the app's control without echoing back at it.
+    boxes.push(box(`obj-set-${id}`, "prepend set"));
+    lines.push(line(SURFACE_ROUTE, i, `obj-set-${id}`, 0));
+    lines.push(line(`obj-set-${id}`, 0, paramObject(id), 0));
+  });
+}

package/templates/starter/README.md

@@ -19,7 +19,7 @@ track.
 | `src/app/{{name}}/App.tsx` | The UI, and the device's logic. A React app. |
 | `src/app/{{name}}/protocol.ts` | Every selector crossing the bridge. Both sides read it. |
 | `src/app/{{name}}/surface.ts` | The Live parameters (automatable, MIDI-mappable, visible to Push). |
-| `patcher/devices.mjs` | The manifest: name, type, chains, parameters. The patcher is generated from it. |
+| `patcher/devices.mjs` | The manifest: name, type, chains. The patcher is generated from it. |
 
 `src/app/shared/` and `scripts/` are infrastructure. You should rarely need to
 touch them.

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

package/templates/starter/patcher/devices.mjs

@@ -15,19 +15,28 @@
  *                               <chan> <delayMs>` (see sendNote()); pipe +
  *                               makenote + midiformat place it on Max's
  *                               scheduler. The app computes WHEN.
- *                 "lowpass"     plugin~ -> onepole~ -> plugout~, with a `cutoff`
+ *                 "lowpass"     onepole~ in the signal path, with a `cutoff`
  *                               parameter. An audio effect you can hear.
- *                 "gain"        plugin~ -> *~ -> plugout~, with a `gain` parameter.
- *                 "passthrough" plugin~ -> plugout~. Does nothing to the audio.
- *   parameters  real Live parameters: automatable, MIDI-mappable, and what Push
- *               reads. Each becomes a live.* object, and reaches the app as
- *               `<id> <value>`.
+ *                 "drive"       overdrive~ in the signal path, with a `drive`
+ *                               parameter. Soft-clipping distortion.
+ *                 "gain"        *~ in the signal path, with a `gain` parameter.
+ *                 "passthrough" nothing at all. Does not touch the audio.
  *
- *               Set `default`. Without it the object loads at the BOTTOM of its
- *               range, which for many parameters is a broken device.
+ *               THE ORDER IS THE SIGNAL PATH. An audio device's plugin~/plugout~
+ *               are created by the build; each audio chain claims one STAGE
+ *               between them, so `["lowpass", "drive", "gain"]` is
+ *               plugin~ -> onepole~ -> overdrive~ -> *~ -> plugout~. Reorder the
+ *               list and the device is rewired - and with a nonlinear stage like
+ *               `drive` in it, you can hear the difference. (Two LINEAR stages
+ *               commute: swapping "lowpass" and "gain" sounds identical.)
  *   unmatchedTo where messages the chains did not consume go. "js" sends them to
  *               the wrapper (ui_ready, ...).
  *
+ * Parameters are NOT here: they are declared in src/app/<ui>/surface.ts, and the
+ * build generates the live.* objects and their wiring from that one declaration.
+ * A chain that names a parameter (`lowpass` wants `cutoff`) fails the build if the
+ * surface does not declare it.
+ *
  * Add a second device by adding an entry here and a folder at src/app/<name>/.
  */
 export default [
@@ -35,7 +44,6 @@ export default [
     name: "{{name}}",
     type: "midi",
     chains: ["midiin", "midiout"],
-    parameters: [{ id: "density", object: "live.dial", range: [0, 1], default: 0.5 }],
     unmatchedTo: "js",
   },
 ];

package/templates/starter/src/app/{{name}}/surface.ts

@@ -4,10 +4,10 @@
  * Push reads Live parameters, not your UI, so anything musically meaningful has
  * to exist here as well as in the app.
  *
- * Not wired up yet: this declaration is typechecked and validated, but the
- * codegen that turns it into live.* objects is not built. For now the parameters
- * Live sees come from `parameters` in patcher/devices.mjs, and the two have to
- * be kept in step by hand.
+ * This is the ONLY place they are declared. The build imports this file and
+ * generates the live.* objects from it, wired in both directions: a knob turn
+ * reaches the app as `<id> <value>`, and the app writes the parameter back with
+ * `set_<id> <value>` - which moves the dial, the automation lane and Push.
  */
 import { defineSurface, dial } from "@m4l-jweb/surface";
 

package/templates/starter/src/main.tsx

@@ -27,11 +27,32 @@ import App from "@device/App";
  */
 const DevHarness = import.meta.env.DEV ? (await import("@m4l-jweb/surface/dev")).DevHarness : null;
 
+/**
+ * The device's parameter surface, for the harness to render - the same
+ * declaration the Max objects are generated from, so the panel and the Push
+ * preview cannot drift from what Live will show.
+ *
+ * A GLOB rather than `import "@device/surface"`, because surface.ts is OPTIONAL:
+ * a device with no parameters has no such file, and a static import of a missing
+ * module is a build error, not an undefined.
+ *
+ * The glob sits INSIDE the `import.meta.env.DEV` branch, and that placement is
+ * load-bearing. A glob resolves to every match, so hoisting it to a `const` would
+ * put EVERY device's declaration in EVERY bundle - one device shipping its
+ * siblings' parameters - and the single-file build inlines dynamic chunks, so
+ * being lazy is not enough on its own. Written here, the whole expression is dead
+ * code once DEV is replaced by `false`, and rollup drops all of it.
+ * `tests/bundle.test.mjs` asserts a device carries no sibling's parameters.
+ */
+const surface = import.meta.env.DEV
+  ? (((await import.meta.glob("./app/*/surface.ts", { import: "default" })[`./app/${__DEVICE__}/surface.ts`]?.()) as never) ?? null)
+  : null;
+
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
     {DevHarness ? (
       <div className="dev-layout">
-        <DevHarness />
+        <DevHarness surface={surface} />
         <App />
       </div>
     ) : (

package/templates/starter/src/vite-env.d.ts

@@ -3,6 +3,11 @@
 // Injected by vite's `define` (see vite.config.ts) - the UI's own build stamp.
 declare const __APP_VERSION__: string;
 
+// Injected by vite's `define` - which device this bundle IS. Used to pick the
+// device's surface.ts out of a glob, since a static import cannot name a file
+// that some devices do not have.
+declare const __DEVICE__: string;
+
 declare module "*?worker&inline" {
   const workerConstructor: new () => Worker;
   export default workerConstructor;