@m4l-jweb/build 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0"
+    "@m4l-jweb/wrapper": "0.4.0"
   }
 }

package/src/chains.mjs

@@ -52,6 +52,50 @@ 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];
+}
+
 /**
  * "midiin" - feed incoming MIDI notes to the app as `notein <pitch> <velocity>`.
  *
@@ -77,10 +121,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 +150,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,8 +167,6 @@ 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));
 }
 
 /**
@@ -154,22 +198,20 @@ 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 }) {
+function gainChain(ctx) {
+  const { boxes, lines, device } = ctx;
   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)`);
-  }
+  const paramId = requireParam(ctx, "gain", device?.gainParam ?? "gain", "gainParam");
 
   boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
   boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
@@ -183,83 +225,43 @@ function gainChain({ boxes, lines, device }) {
     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));
+    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.
+ * Wire a parameter into the thing it controls, from BOTH of its sources:
  *
- *    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 OBJECT's outlet - a knob turn, an automation lane, a Push encoder.
+ *   the ROUTE's outlet  - the value the app wrote.
  *
- *    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.
+ * 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.
  *
- * 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.
+ * 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.
  */
-function writableParams({ boxes, lines, jwebId, unmatchedId }, ids) {
-  removeLine(lines, jwebId, unmatchedId);
-
-  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));
+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));
+}
 
-  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;
 }
 
 /**
@@ -279,53 +281,26 @@ 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:
+ * 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.
  *
- *     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.
- *
- * 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);
+  const paramId = requireParam(ctx, "lowpass", device?.cutoffParam ?? "cutoff", "cutoffParam");
 
   boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
   boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
 
-  // 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));
-
   // 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 [
@@ -335,10 +310,10 @@ function lowpassChain(ctx) {
     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));
+    // 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);
   }
 }
 
@@ -356,48 +331,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.
+ * 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()`).
  *
- * `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".
+ * 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, 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)), "..");
@@ -164,17 +165,46 @@ export async function generatePatchers(root) {
 
     const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
 
+    /**
+     * The device's parameters, declared once in src/app/<ui>/surface.ts. A chain
+     * that drives DSP from a parameter needs two things from it, and needs BOTH:
+     *
+     *   paramObject(id)  the live.* object's outlet - a knob turn, an automation
+     *                    lane, a Push encoder.
+     *   paramValue(id)   the route outlet carrying what the APP wrote. Not
+     *                    redundant: the app's write reaches the object as `set`,
+     *                    which updates it WITHOUT output, so the object would
+     *                    never pass that value on. See surface.mjs.
+     */
+    // The manifest carried `parameters` until 0.4.0. It is now declared in
+    // src/app/<ui>/surface.ts and generated from there - so a leftover field is not
+    // a harmless extra key, it is a device whose parameters have SILENTLY
+    // 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/SURFACE.md.`,
+      );
+    }
+
+    const surface = await loadSurface(root, d.ui ?? d.name);
+    const ctx = { boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d, ...surfaceContext(surface) };
+
     for (const name of d.chains ?? []) {
       const chain = CHAINS[name];
       if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
-      chain({ boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d });
+      chain(ctx);
     }
 
-    // Parameters feed the UI: a knob move arrives as just another inlet message.
-    addParameters(boxes, lines, d.parameters ?? [], "obj-jweb");
+    // AFTER the chains: the Surface routes every `set_<id>` off the app's message
+    // stream, and passes on what nobody claimed (ui_ready, ...) to the wrapper.
+    applySurface(ctx);
 
     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.2.0",
-    "@m4l-jweb/surface": "^0.2.0",
+    "@m4l-jweb/bridge": "^0.4.0",
+    "@m4l-jweb/surface": "^0.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^0.2.0",
+    "@m4l-jweb/build": "^0.4.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/starter/patcher/devices.mjs

@@ -19,15 +19,14 @@
  *                               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>`.
- *
- *               Set `default`. Without it the object loads at the BOTTOM of its
- *               range, which for many parameters is a broken device.
  *   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 +34,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/shared/Frame.tsx

@@ -1,11 +1,17 @@
 /**
  * shared/Frame.tsx - the chrome every device wears: a title, a where-am-I badge,
- * and a footer carrying the two build stamps.
+ * and the two build stamps.
  *
- * The footer is not decoration. Live embeds a COPY of a device into the set, so
+ * The stamps are not decoration. Live embeds a COPY of a device into the set, so
  * reinstalling does not update instances already on tracks - and a stale device
  * behaves like a bug in code you have already fixed. The stamps make that
  * visible instead of mysterious.
+ *
+ * They live in the HEADER, top right, and that placement is load-bearing: the
+ * device view is a fixed ~169 px and overgrown UI clips silently at the BOTTOM.
+ * A stamp in a footer is a staleness check that disappears exactly when the
+ * device has grown enough to be worth checking. Anchored to the header, it
+ * survives whatever the device does below it.
  */
 import type { ReactNode } from "react";
 import { inJweb } from "@m4l-jweb/bridge";
@@ -19,15 +25,19 @@ export function Frame({ title, device, children }: { title: string; device: Devi
       <header>
         <h1>{title}</h1>
         <span className={`badge ${inJweb ? "live" : "dev"}`}>{inJweb ? "in Max" : "browser dev"}</span>
+        <span className="stamp" title={`ui ${__APP_VERSION__} / wrapper ${device.build ?? "-"}`}>
+          {device.stale ? (
+            <span className="warn">stale - delete and re-drag the device</span>
+          ) : (
+            <>
+              <span>ui {__APP_VERSION__}</span>
+              <span>wrapper {device.build ?? "-"}</span>
+            </>
+          )}
+        </span>
       </header>
 
       <dl>{children}</dl>
-
-      <footer>
-        <span>ui {__APP_VERSION__}</span>
-        <span>wrapper {device.build ?? "-"}</span>
-        {device.stale && <span className="warn">stale install - delete and re-drag the device</span>}
-      </footer>
     </main>
   );
 }

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/index.css

@@ -87,6 +87,23 @@ h1 {
   color: var(--fg);
 }
 
+/* The build stamps, top right. Deliberately NOT in a footer: the device view is
+   a fixed ~169 px and clips at the bottom, so a footer stamp vanishes exactly
+   when the UI has grown enough for staleness to be worth checking. The stamps
+   are long (version + ISO timestamp), so they ellipsize - the full text is in
+   the title attribute, and the hover works in Max's jweb. */
+.stamp {
+  color: var(--muted);
+  display: flex;
+  font-size: 9px;
+  gap: 8px;
+  margin-left: auto;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 dl {
   column-gap: 10px;
   display: grid;

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;