@m4l-jweb/build 0.6.5 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.6.5",
+  "version": "0.9.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,7 @@
     ".": "./src/index.mjs",
     "./chains": "./src/chains.mjs",
     "./surface": "./src/surface.mjs",
+    "./watch": "./src/watch.mjs",
     "./amxd": "./src/amxd.mjs",
     "./init": "./src/init.mjs"
   },
@@ -33,6 +34,6 @@
     "archiver": "^7.0.1",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "0.6.5"
+    "@m4l-jweb/wrapper": "0.9.0"
   }
 }

package/src/chains.mjs

@@ -112,6 +112,54 @@ export function claimAppMessages(ctx, routeId, unmatchedOutlet) {
 export const AUDIO_IN = "obj-plugin";
 export const AUDIO_OUT = "obj-plugout";
 
+/**
+ * A [buffer~] name that is unique PER DEVICE INSTANCE.
+ *
+ * THE BUG THIS EXISTS TO KILL. Buffer names are GLOBAL to Max, and they used to be
+ * generated from the device name alone (`buf-<device>-<slot>`) and frozen into the
+ * patcher at BUILD time. So two copies of one device - a drum rack on two tracks, which
+ * is the normal case, not an exotic one - named their buffers identically, and Max gave
+ * both to whichever loaded last. One rack's samples silently became the other's. No
+ * error, no console line: just the wrong sound.
+ *
+ * A name minted by the wrapper after load cannot reach a box frozen at build time (a
+ * buffer takes its name from its creation argument and there is no documented runtime
+ * rename), so the scoping has to be a load-time substitution Max itself performs.
+ *
+ * `#0` WAS TRIED AND DOES NOT WORK (spike, doc/TODO.md item 0, run 2026-07-17 in
+ * Live). `#0` is documented for abstractions, and an .amxd device patcher turned out
+ * not to count as one: the token stayed literal in every instance, so writer and
+ * reader still agreed on one global name and the collision survived, silently.
+ *
+ * `---` IS THE MECHANISM BUILT FOR THIS. Max for Live replaces a leading `---` in a
+ * name with an id unique to the DEVICE instance - and the scope is the whole device,
+ * subpatchers and [poly~] voices included, not one patcher. That kills the `#0`/`#1`
+ * hand-off the first attempt needed: the voice spells the SAME name the device does,
+ * and no id has to travel through [poly~]'s arguments.
+ *
+ * OUTSIDE LIVE `---` stays literal (it is a Live-only substitution). Both writer and
+ * reader keep agreeing, so a patcher opened in standalone Max degrades to the old
+ * shared-name behavior instead of breaking - acceptable, since the devices only
+ * meaningfully run in Live.
+ */
+export const deviceBufName = (device, slot) => `---buf-${device?.name}-${slot}`;
+
+/** The same buffer, as a [poly~] voice spells it: identical - `---` scopes per DEVICE,
+ * not per patcher, so the voice shares the expansion with the patcher that loaded it. */
+export const voiceBufName = (device, slot) => deviceBufName(device, slot);
+
+/**
+ * How long a `remote` slot takes to slide to each new value, in ms.
+ *
+ * It is a RAMP TIME, not a rate: the app sends values on the transport tick, and each
+ * one is ramped to over this long. Exported because the number is only right in
+ * relation to the app's tick - it wants to be about one tick, so a ramp is still
+ * arriving when the next value lands and the slots join into a continuous line. Much
+ * shorter and the stepping it exists to remove comes back as a staircase with flat
+ * treads; much longer and the modulation lags visibly behind the pattern.
+ */
+export const REMOTE_RAMP_MS = 20;
+
 /** plugin~ hands us a stereo pair, so every stage is a pair of signal objects. */
 export const AUDIO_CHANNELS = 2;
 
@@ -470,6 +518,194 @@ function driveChain(ctx) {
   }
 }
 
+/**
+ * "hpf" - a high-pass next to `lowpass`, and a WIRE at 0 Hz.
+ *
+ *   dry --+--------------------> [-~] --> out
+ *         |                       ^
+ *         +--> [onepole~] --------+       (the low end, subtracted away)
+ *
+ * WHY A SUBTRACTION AND NOT A HIGHPASS OBJECT. `onepole~` is lowpass-only, and the
+ * one-pole highpass is its exact complement: everything the lowpass keeps is what a
+ * highpass throws away, so `dry - lowpass(dry)` IS the highpass, sample for sample.
+ * No second filter design, no new object, and the same 6 dB/octave slope, resonance-
+ * free and impossible to blow up, that `lowpass` was chosen for.
+ *
+ * IT IS ALSO WHAT MAKES 0 HZ A REAL NEUTRAL, which is the frozen-graph law's whole
+ * demand (CHAIN_NEUTRAL below). A one-pole lowpass at cutoff 0 has nothing to pass:
+ * its output is silence, so the subtraction reads `dry - 0` and the stage is the
+ * input, bit for bit. A highpass object would instead be neutral at its cutoff floor,
+ * where it is NOT a wire - it still turns DC and the bottom octave, which is a
+ * colouration a device could not switch off. The complement has no such setting.
+ *
+ * NOT a wet/dry send, despite the shape: there is no mix gain, and the parameter that
+ * reaches neutral is the CUTOFF itself. It is naturally transparent, like `lowpass` -
+ * see the two kinds of neutral in CHAIN_NEUTRAL.
+ *
+ * The cutoff is in Hz and the chain does no arithmetic on it - the range, unit and
+ * curve ride the PARAMETER, exactly as in `lowpass`.
+ *
+ * Requires a parameter named `hpfreq` (or pass `device.hpfreqParam`), in Hz.
+ */
+function hpfChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const paramId = requireParam(ctx, "hpf", device?.hpfreqParam ?? "hpfreq", "hpfreqParam");
+
+  for (const [ch, s] of [
+    [0, "l"],
+    [1, "r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    const lp = `obj-hpf-lp-${s}`;
+    const sub = `obj-hpf-sub-${s}`;
+
+    // The low end to remove. A float argument (0.) so the stage starts as a wire
+    // before any parameter loads, and the right inlet stays in float mode.
+    boxes.push(box(lp, "onepole~ 0.", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+    boxes.push(box(sub, "-~", { numinlets: 2, numoutlets: 1, outlettype: ["signal"] }));
+
+    lines.push(line(srcId, srcOut, lp, 0));
+    lines.push(line(srcId, srcOut, sub, 0)); // dry at unity, into the LEFT inlet
+    lines.push(line(lp, 0, sub, 1)); // minus the low end
+    fanParamInto(ctx, paramId, lp, 1);
+    ctx.setAudioOut(ch, sub, 0);
+  }
+}
+
+/**
+ * "crush" - bit-depth reduction (`degrade~`), neutral at full depth.
+ *
+ * `degrade~` takes a sample-rate RATIO (inlet 1, 1.0 = untouched) and a BIT DEPTH
+ * (inlet 2). This chain drives the bit depth only and leaves the ratio at 1.0: two
+ * knobs on one stage would be a second parameter the fx line has no word for -
+ * Strudel's `.crush(n)` is bit depth, and `.coarse()` is the rate reduction, a
+ * separate effect and a separate chain when someone wants it.
+ *
+ * THE NEUTRAL IS FULL DEPTH, NOT STRUDEL'S 16. Strudel calls `.crush(16)` "minimum
+ * crush", but 16-bit quantisation is not a wire - it is a quiet crush, and a stage
+ * that is always in the path (the frozen-graph law) must have a setting where it does
+ * NOTHING. So the parameter's range runs to the object's full 24 bits and rests
+ * there, where degrade~ passes its input through. A user who types `.crush(16)` gets
+ * 16-bit quantisation - the same sound superdough's crush(16) makes - and a user who
+ * never types `.crush()` at all gets their signal back untouched. Both are honest;
+ * only the second is possible with a neutral of 16.
+ *
+ * The depth is in BITS and the chain does no arithmetic on it - the range rides the
+ * parameter, as everywhere else.
+ *
+ * Requires a parameter named `crush` (or pass `device.crushParam`), in bits.
+ */
+function crushChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const paramId = requireParam(ctx, "crush", device?.crushParam ?? "crush", "crushParam");
+
+  for (const [ch, s] of [
+    [0, "l"],
+    [1, "r"],
+  ]) {
+    const [srcId, srcOut] = ctx.audioIn(ch);
+    const id = `obj-crush-${s}`;
+
+    // `degrade~ 1. 24.` - rate ratio 1.0 (untouched), 24 bits (full depth): a wire
+    // until the parameter says otherwise.
+    boxes.push(box(id, "degrade~ 1. 24.", { numinlets: 3, numoutlets: 1, outlettype: ["signal"] }));
+    lines.push(line(srcId, srcOut, id, 0));
+    ctx.setAudioOut(ch, id, 0);
+    // Bit depth into inlet 2. Inlet 1 (the rate ratio) is left at its argument.
+    fanParamInto(ctx, paramId, id, 2);
+  }
+}
+
+/**
+ * "remote" - `live.remote~`, so a PATTERN can modulate a Live parameter.
+ *
+ *   app -> remote_bind <slot> <lomId>  -> [route <slot>] -> [prepend id] -> [live.remote~]
+ *          remote_val  <slot> <v>      -> [route <slot>] -> [pack f 20]  -> [line~] -> ^
+ *
+ * WHY THIS EXISTS AT ALL. `.lpf(sine.range(200, 2000))` describes something
+ * CONTINUOUS. The obvious implementation - have the app read the pattern on the
+ * transport tick and write the parameter - produces about 20 values a second, and it
+ * is wrong three times over: the steps are audible, every write fights the automation
+ * lane for ownership of the parameter, and the lane fills with the app's own noise.
+ * `live.remote~` is Live's answer to exactly this: it takes a SIGNAL and modulates the
+ * parameter without writing automation, which is what a modulation source is meant to
+ * do.
+ *
+ * THE `[line~]` IS THE WHOLE TRICK, and it is why this is a chain rather than a bridge
+ * call. The app is still control-rate: it can only send a value per tick, and a bare
+ * number into live.remote~ would step exactly as badly as a parameter write. A
+ * `[line~]` given a 20 ms ramp turns each of those values into a SIGNAL that slides to
+ * the next one, so the control-rate stream becomes signal-rate at the Max end and the
+ * stepping disappears. The ramp is about one tick long by design: it is still arriving
+ * when the next value does, so the ramps chain into a continuous line rather than a
+ * staircase with pauses in it.
+ *
+ * BIND BY LOM ID, AND THE APP OWNS THE BINDING. live.remote~ names its target with an
+ * `id <lomId>` message, so the chain does not know or care WHICH parameter a slot
+ * drives - the app resolves that (our own filter, or an Auto Filter the user placed by
+ * hand) and says so. That is what makes this bigger than an LFO on our own DSP: a slot
+ * can point at any parameter in the set. **LOM ids are not stable across set reloads**,
+ * so the app must re-bind on load and must never persist a raw id - see the diff rules
+ * in doc/TODO.md item 1.
+ *
+ * NOT IN THE SIGNAL PATH. It touches no audio: `ctx.audioIn`/`setAudioOut` are never
+ * called, so `remote` composes with any chain list without taking a stage. It has no
+ * neutral for the same reason - an unbound slot modulates nothing.
+ *
+ * `remotes: <n>` in the manifest declares how many slots. There is no default: a
+ * device that asks for this chain and forgets the count would build a patcher with no
+ * live.remote~ in it and fail silently at runtime, which is the failure this repo
+ * exists to prevent.
+ */
+function remoteChain(ctx) {
+  const { boxes, lines, device } = ctx;
+  const n = device?.remotes;
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(
+      `chain "remote" on device "${device?.name}" needs \`remotes: <n>\` in the manifest ` +
+        `(got ${JSON.stringify(n)}). It is the number of live.remote~ slots to generate, ` +
+        `and there is no sensible default - 0 slots is a chain that silently does nothing.`,
+    );
+  }
+
+  const slots = Array.from({ length: n }, (_, i) => i);
+  const slotList = slots.join(" ");
+  // `route` needs an outlet per slot, plus the unmatched one it never uses here.
+  const slotRoute = { numoutlets: n + 1, outlettype: slots.map(() => "").concat("") };
+
+  boxes.push(box("obj-remote-route", "route remote_bind remote_val", { numoutlets: 3, outlettype: ["", "", ""] }));
+  claimAppMessages(ctx, "obj-remote-route", 2);
+
+  // `route` strips the selector, so the SLOT is now the first word of both messages
+  // and a second route dispatches on it.
+  boxes.push(box("obj-remote-bindroute", `route ${slotList}`, slotRoute));
+  boxes.push(box("obj-remote-valroute", `route ${slotList}`, slotRoute));
+  lines.push(line("obj-remote-route", 0, "obj-remote-bindroute", 0));
+  lines.push(line("obj-remote-route", 1, "obj-remote-valroute", 0));
+
+  for (const slot of slots) {
+    const bind = `obj-remote-bind-${slot}`;
+    const pack = `obj-remote-pack-${slot}`;
+    const ramp = `obj-remote-line-${slot}`;
+    const rem = `obj-remote-${slot}`;
+
+    // The binding: `id <lomId>` is how live.remote~ is told what to modulate.
+    boxes.push(box(bind, "prepend id"));
+    // `<target> <rampMs>` is line~'s list form - the pack is what makes the ramp time
+    // ride along with every value, rather than being set once and forgotten.
+    boxes.push(box(pack, `pack f ${REMOTE_RAMP_MS}`, { numinlets: 2, numoutlets: 1 }));
+    boxes.push(box(ramp, "line~", { numinlets: 2, numoutlets: 2, outlettype: ["signal", "bang"] }));
+    boxes.push(box(rem, "live.remote~", { numinlets: 1, numoutlets: 0 }));
+
+    lines.push(line("obj-remote-bindroute", slot, bind, 0));
+    lines.push(line(bind, 0, rem, 0));
+
+    lines.push(line("obj-remote-valroute", slot, pack, 0));
+    lines.push(line(pack, 0, ramp, 0));
+    lines.push(line(ramp, 0, rem, 0));
+  }
+}
+
 /**
  * "download" - `[maxurl]`, so the app can fetch a file to DISK.
  *
@@ -557,10 +793,10 @@ function downloadChain(ctx) {
  * of its own: on an audio effect the preview plays over the track's audio, and on an
  * instrument there is nothing at the input to add.
  *
- * The buffer NAMES are global to Max, and they are generated from the device name
- * (`buf-<device>-<slot>`), so two INSTANCES of the same device on two tracks name
- * their buffers alike - and Max hands the name to whichever loaded last. Not
- * verified in Live yet; a preview device you drag onto one track is unaffected.
+ * The buffer names are INSTANCE-SCOPED (`deviceBufName`, `---buf-<device>-<slot>`), so
+ * two copies of this device on two tracks own separate buffers. They used to be global
+ * to Max and generated from the device name alone, which meant the second copy loaded
+ * silently stole the first's samples.
  *
  * Slots default to one, named "preview". `slots: ["kick", "snare"]` in the manifest
  * gives you more.
@@ -568,7 +804,10 @@ function downloadChain(ctx) {
 function samplesChain(ctx) {
   const { boxes, lines, device, jwebId, unmatchedId } = ctx;
   const slots = device?.slots ?? ["preview"];
-  const bufName = (slot) => `buf-${device?.name}-${slot}`;
+  // Instance-scoped, for the same reason the instrument's are: two copies of a preview
+  // device on two tracks are two devices, and a global name would hand both the same
+  // buffer. `---` expands per device instance in Live - see deviceBufName.
+  const bufName = (slot) => deviceBufName(device, slot);
 
   // `buffer_load` is NOT claimed from [jweb]. It goes on to the wrapper, which
   // resolves the path and hands it back on its AUX OUTLET as `buffer_replace <slot>
@@ -987,9 +1226,10 @@ function instrumentVoicePatch(bufNames) {
  * which is the app's decision, not the chain's.
  *
  * `slots: ["c", "e", "g"]` in the manifest is three buffers; the default is one
- * ("voice"). The buffer NAMES are `buf-<device>-<slot>`, global to Max - so two copies
- * of the device on two tracks name their buffers alike (harmless for a demo, the drum-
- * rack instance problem noted in doc/TODO.md).
+ * ("voice"). The buffer names are INSTANCE-SCOPED (`deviceBufName`): each copy of the
+ * device owns its own, which is what lets a drum rack exist on two tracks at once.
+ * `---` scopes per DEVICE, so the voice spells the same name the device does - see
+ * deviceBufName.
  *
  * It SUMS into the signal path ([+~]): an instrument makes sound where there was none
  * at its input, so there is nothing to claim a stage over.
@@ -997,13 +1237,14 @@ function instrumentVoicePatch(bufNames) {
 function instrumentChain(ctx) {
   const { boxes, lines, device, jwebId, unmatchedId } = ctx;
   const slots = device?.slots ?? ["voice"];
-  const bufName = (slot) => `buf-${device?.name}-${slot}`;
+  const bufName = (slot) => deviceBufName(device, slot);
   const voices = device?.voices ?? 8;
   const voiceFile = `${device?.name}-voice.maxpat`;
 
   // The frozen voice patch (a keymap of every slot's buffer), and the [poly~] that
-  // loads N copies of it.
-  ctx.extras.push({ name: voiceFile, data: instrumentVoicePatch(slots.map(bufName)) });
+  // loads N copies of it. The voice spells the buffers exactly as the device does:
+  // `---` is device-scoped, so no id travels through poly~'s arguments.
+  ctx.extras.push({ name: voiceFile, data: instrumentVoicePatch(slots.map((s) => voiceBufName(device, s))) });
   // [poly~]'s name is the file WITHOUT its extension, per Max's abstraction lookup.
   boxes.push(
     box(`obj-instr-poly`, `poly~ ${voiceFile.replace(/\.maxpat$/, "")} ${voices}`, {
@@ -1079,9 +1320,12 @@ export const CHAINS = {
   passthrough: passthroughChain,
   gain: gainChain,
   lowpass: lowpassChain,
+  hpf: hpfChain,
   drive: driveChain,
+  crush: crushChain,
   delay: delayChain,
   reverb: reverbChain,
+  remote: remoteChain,
   download: downloadChain,
 };
 
@@ -1095,7 +1339,8 @@ export const CHAINS = {
  * Two kinds of stage reach neutral two ways:
  *
  *   naturally transparent - `gain` (1.0), `lowpass` (18 kHz, nothing left to remove),
- *     `drive` (1x): the DSP object itself is a wire at that value.
+ *     `drive` (1x), `crush` (24 bits, full depth), `hpf` (0 Hz, where its subtracted
+ *     low end is silence): the DSP object itself is a wire at that value.
  *   send-style wet/dry - `delay` (0), `reverb` (0): the wet branch is scaled to 0.0
  *     and summed onto an untouched dry path, so the output is `dry + 0`. A WET-ONLY
  *     object (cverb~) has NO neutral of its own - it must carry this dry/wet, which
@@ -1109,7 +1354,9 @@ export const CHAINS = {
 export const CHAIN_NEUTRAL = {
   gain: { gain: 1 },
   lowpass: { cutoff: 18000 },
+  hpf: { hpfreq: 0 },
   drive: { drive: 1 },
+  crush: { crush: 24 },
   delay: { delay: 0 },
   reverb: { room: 0 },
 };

package/src/index.mjs

@@ -17,7 +17,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { AMXD_TYPES, assertES5, buildAmxd, extraPayloadsJs, payloadJs } from "./amxd.mjs";
 import { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, resetLayout } from "./chains.mjs";
-import { applySurface, applyWindows, applyPersistence, loadSurface, surfaceContext } from "./surface.mjs";
+import { applySurface, applyWindows, applyPersistence, loadSurface, parameterRegistry, surfaceContext } from "./surface.mjs";
+import { loadWatch, watchSpecsBanner } from "./watch.mjs";
 
 const require = createRequire(import.meta.url);
 const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -218,6 +219,12 @@ export function composePatcher(base, d, surface) {
   closeAudio(ctx);
   assertUniqueBoxIds(boxes, d.name);
 
+  // The patcher-level parameter registry - without it Live ignores every
+  // parameter_longname and renames the parameters after their shortnames,
+  // which breaks resolveParamId's contract. See parameterRegistry().
+  const registry = parameterRegistry(surface);
+  if (registry) p.patcher.parameters = registry;
+
   // Ride the chain-contributed extras out on the returned object. Destructuring
   // `{ patcher }` (the tests, the writer) ignores it; the packager reads it.
   p.extras = extras;
@@ -323,7 +330,10 @@ export async function packageDevices(root) {
      * process are blind to Max's frozen virtual filesystem.
      * We embed ALL .html files found in the UI directory (including the main UI and any windows).
      */
-    let wrapperData = banner + wrapperJs;
+    // The device's declared watches ride in as a data banner, like the build stamp:
+    // WATCH_SPECS is what the packaged wrapper's setupWatches() attaches observers from.
+    const watch = await loadWatch(root, d.ui ?? d.name);
+    let wrapperData = banner + watchSpecsBanner(watch) + wrapperJs;
     const uiDirContent = readdirSync(path.join(dist, "ui", d.ui ?? d.name)).filter((f) => f.endsWith(".html"));
 
     // Main UI payload
@@ -375,6 +385,17 @@ export async function packageDevices(root) {
     console.log(`m4l-jweb: ${path.basename(f)} -> dist/${name}/ (loose)`);
   }
 
+  // Presets ride along with the devices. A consumer repo's `presets/` holds
+  // hand-saved Live files (an .adg rack is gzipped XML, undocumented - committed,
+  // never generated); they land next to the .amxd in dist, the zip and the User
+  // Library, all through this one list so the three cannot skew.
+  const presetsDir = path.join(root, "presets");
+  const presets = existsSync(presetsDir) ? readdirSync(presetsDir).filter((f) => f.endsWith(".adg") || f.endsWith(".adv")) : [];
+  for (const f of presets) {
+    await copyFile(path.join(presetsDir, f), path.join(outDir, f));
+    console.log(`m4l-jweb: ${f} -> dist/${name}/ (preset)`);
+  }
+
   // Installers go next to the devices so `dist/install-*.ps1` just works.
   const installers = ["install-windows.ps1", "install-mac.sh"];
   for (const f of installers) await copyFile(path.join(templates, f), path.join(dist, f));
@@ -390,6 +411,7 @@ export async function packageDevices(root) {
       ...devices.map((d) => `${d.name}.amxd`),
       ...devices.map((d) => `${d.name}.html`), // each device's own UI, for inspection
       ...loose.map((f) => path.basename(f)),
+      ...presets,
       "wrapper.js",
     ];
     for (const f of files) {

package/src/surface.mjs

@@ -59,6 +59,48 @@ export const paramObject = (id) => `obj-param-${id}`;
  */
 export const paramValue = (surface, id) => [SURFACE_ROUTE, surface.ids.indexOf(id)];
 
+/**
+ * The patcher-level `parameters` registry - the block Max itself writes into any
+ * patcher that has parameter-enabled boxes, mapping box id -> [longname,
+ * shortname, type].
+ *
+ * IT IS NOT OPTIONAL DECORATION. Live reads THIS registry for parameter names at
+ * device load; the per-box `saved_attribute_attributes.valueof.parameter_longname`
+ * alone is ignored, and Live regenerates every longname from the shortname. That
+ * is how `resolveParamId("cutoff")` came back 0 on a device whose dial plainly
+ * said `parameter_longname: "cutoff"`: the DeviceParameter's runtime name was
+ * "Cutoff". Emitting the registry is what makes the longname the surface id -
+ * the contract resolveParamId and every automation lane name rides on.
+ *
+ * The pattr state blobs are in it too (type 3), same as Max would write them.
+ *
+ * `parameterbanks` is the Push/controller paging, from the surface's `banks`: a
+ * bank is `{ index, name, parameters }` with EIGHT longname entries, the unused
+ * tail padded with "-" - the shape read off devices Max itself saved. Without
+ * banks Live falls back to declaration-order pages of eight.
+ */
+export function parameterRegistry(surface) {
+  const out = {};
+  for (const id of surface?.ids ?? []) {
+    const spec = surface.params[id];
+    out[paramObject(id)] = [id, spec.short ?? id, parameterType(spec)];
+  }
+  for (const id of surface?.state ? Object.keys(surface.state) : []) {
+    const pattrId = `obj-pattr-${id}`;
+    out[pattrId] = [pattrId, `st_${id}`.slice(0, 8), 3];
+  }
+  if (!Object.keys(out).length) return null;
+
+  const parameterbanks = {};
+  (surface.banks ?? []).forEach((bank, i) => {
+    const params = bank.params.slice(0, 8);
+    while (params.length < 8) params.push("-");
+    parameterbanks[String(i)] = { index: i, name: bank.name, parameters: params };
+  });
+
+  return { ...out, parameterbanks, inherited_shortname: 1 };
+}
+
 /**
  * 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
@@ -124,7 +166,61 @@ export async function loadSurface(root, uiDir) {
  * Generating the objects
  * ------------------------------------------------------------------ */
 
-const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu" };
+const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu", button: "live.text" };
+
+/* ------------------------------------------------------------------ *
+ * Native declarative layout (surface `layout.native`)
+ *
+ * A parameter listed in `layout.native` renders as a native `live.*` object IN
+ * THE DEVICE VIEW, next to a `[jweb]` shifted right to make room. This is a pure
+ * PRESENTATION overlay: the dial the compiler already emits gains three keys
+ * (`presentation`, `presentation_rect`, `varname`) and nothing about its wiring,
+ * its fan-out or the app's `set_<id>` route changes. A dial that carries no rect
+ * is exactly today's invisible object.
+ * ------------------------------------------------------------------ */
+
+// The device view Live gives an M4L device. Height is fixed at ~169 px; the width
+// is whatever the presentation content needs, which is the whole mechanism this
+// relies on (Live recomputes device width from the presentation rects).
+const DEVICE_H = 169;
+const MARGIN = 8;
+// Per-kind native sizes, from Max's own live.* defaults. A live.dial includes its
+// own label under the knob, which is why it is taller than a bare toggle.
+const NATIVE_SIZE = { dial: [44, 48], toggle: [44, 15], menu: [100, 15], button: [48, 15] };
+// Vertical pitch: a dial is 48 px tall and wants 8 px of air beneath its label.
+const PITCH_Y = 56;
+
+/**
+ * `id -> presentation_rect` for every native parameter, plus the zone's total
+ * width (how far `[jweb]` shifts right). A pure function of the declaration, so
+ * `tests/` can drive it directly.
+ *
+ * Column-major: fills `rows` down the first column, then starts a new column to
+ * the right. Adding a parameter at the end therefore never reshuffles the ones
+ * before it - the reading order stays stable.
+ */
+export function computeNativeSlots(surface) {
+  const native = surface?.layout?.native;
+  if (!native || native.params.length === 0) return { slots: new Map(), width: 0 };
+  const rows = native.rows ?? 3;
+  const slots = new Map();
+  let row = 0;
+  let colW = 0;
+  let x = MARGIN;
+  for (const id of native.params) {
+    const [w, h] = NATIVE_SIZE[surface.params[id].kind];
+    if (row >= rows) {
+      // Column full: step right by the widest box in the column just finished.
+      row = 0;
+      x += colW + MARGIN;
+      colW = 0;
+    }
+    slots.set(id, [x, MARGIN + row * PITCH_Y, w, h]);
+    colW = Math.max(colW, w);
+    row += 1;
+  }
+  return { slots, width: x + colW + MARGIN };
+}
 
 /**
  * Max's `parameter_type`: 0 = float, 1 = int, 2 = enum.
@@ -134,7 +230,7 @@ const MAXCLASS = { dial: "live.dial", toggle: "live.toggle", menu: "live.menu" }
  * 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;
+  if (spec.kind === "menu" || spec.kind === "toggle" || spec.kind === "button") return 2;
   return spec.step === 1 ? 1 : 0;
 }
 
@@ -183,7 +279,7 @@ function unitAttrs(spec) {
 
 /** 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 === "toggle" || spec.kind === "button") return spec.default ? 1 : 0;
   if (spec.kind === "menu") return spec.options.indexOf(spec.default);
   return spec.default;
 }
@@ -226,7 +322,7 @@ function parameterAttrs(id, spec) {
     if (spec.steps !== undefined) attrs.parameter_steps = spec.steps;
   }
 
-  if (spec.kind === "toggle") {
+  if (spec.kind === "toggle" || spec.kind === "button") {
     attrs.parameter_mmax = 1;
     attrs.parameter_enum = ["off", "on"];
   }
@@ -239,6 +335,16 @@ function parameterAttrs(id, spec) {
   return attrs;
 }
 
+/**
+ * Box-level (not parameter) attributes a kind needs. A `button` is a `live.text`,
+ * which unlike a `live.toggle` carries VISIBLE TEXT: `text`/`texton` is the label it
+ * shows off/on, and `mode: 1` makes it a toggle rather than a momentary button.
+ */
+function kindBoxAttrs(spec) {
+  if (spec.kind === "button") return { text: spec.label, texton: spec.label, mode: 1 };
+  return {};
+}
+
 /**
  * Compile the Surface into the patcher.
  *
@@ -250,9 +356,29 @@ export function applySurface(ctx) {
   const { boxes, lines, surface, jwebId } = ctx;
   if (!surface || surface.ids.length === 0) return;
 
+  // Where the native dials go, if any were declared. `slots` is empty for a
+  // surface with no `layout`, and then this whole feature is inert - a param
+  // carries no presentation rect and stays the invisible object it is today.
+  const native = surface.layout?.native;
+  const { slots, width: nativeW } = computeNativeSlots(surface);
+
+  // The view switch (panel layouts) is NOT a grid dial: it is pinned to the
+  // top-right, over where the web UI paints its own switch button, so the control
+  // stays in one place when the app flips between the two views. It is excluded from
+  // `computeNativeSlots` (it is not in `native.params`), so give it a rect here.
+  const switchId = native?.switch;
+  const jwebBox = boxes.find((b) => b.box.id === jwebId)?.box;
+  const [, , jpw] = jwebBox?.presentation_rect ?? [0, 0, 420, DEVICE_H];
+  let switchRect = null;
+  if (switchId) {
+    const [sw, sh] = NATIVE_SIZE[surface.params[switchId].kind];
+    switchRect = [jpw - sw - MARGIN, MARGIN, sw, sh];
+  }
+
   let x = 480;
   for (const id of surface.ids) {
     const spec = surface.params[id];
+    const rect = id === switchId ? switchRect : slots.get(id);
     boxes.push({
       box: {
         id: paramObject(id),
@@ -262,6 +388,13 @@ export function applySurface(ctx) {
         outlettype: [""],
         parameter_enable: 1,
         patching_rect: [x, 300, 44, 48],
+        ...kindBoxAttrs(spec),
+        // A native param is shown in the device view: it gets a presentation rect
+        // and a scripting name (prefixed `param-` so it cannot collide with a state
+        // dict's `obj-state-<id>` varname). Everything else about the box - the
+        // wiring below, the fan-out, useParam() - is UNCHANGED. Presentation is
+        // purely a display overlay on the same graph.
+        ...(rect ? { presentation: 1, presentation_rect: rect, varname: `param-${id}` } : {}),
         saved_attribute_attributes: { valueof: parameterAttrs(id, spec) },
       },
     });
@@ -273,6 +406,26 @@ export function applySurface(ctx) {
     x += 56;
   }
 
+  // Position [jweb] for the native layout. WIDTH is preserved (React layouts were
+  // built for 420 px). A surface with no native content leaves [jweb] where the
+  // template put it.
+  if ((nativeW > 0 || switchId) && jwebBox) {
+    const [, py, pw, ph] = jwebBox.presentation_rect ?? [0, 0, 420, DEVICE_H];
+    if (native.panel) {
+      // LAYERED two-screen: [jweb] covers the whole device and the dials overlap its
+      // left. The app shows one layer at a time (useNativePanel), so the overlap is
+      // never seen - web mode fills the full width, no reserved strip.
+      jwebBox.presentation_rect = [0, py, Math.max(pw, nativeW), ph];
+    } else {
+      // Side-by-side: the dials to the left, [jweb] shifted right, both visible.
+      jwebBox.presentation_rect = [nativeW, py, pw, ph];
+    }
+    // Give [jweb] a scripting name so the wrapper can hide/show it at runtime
+    // (useNativePanel). Must equal JWEB_VARNAME in @m4l-jweb/surface - the one string
+    // the app and this codegen must agree on.
+    jwebBox.varname = "obj-jweb";
+  }
+
   // 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.
@@ -295,6 +448,36 @@ export function applySurface(ctx) {
   });
 }
 
+/**
+ * Runtime show/hide of native dials - the `layout.native` visibility override.
+ *
+ * `layout.native` makes a parameter a native `live.*` object, and its presentation
+ * is STATIC: `presentation: 1` is stamped into the .amxd at build time, so every
+ * listed dial is always visible. A device like the fx line wants the opposite - a
+ * stage the current line does not name should not clutter the view, the way its old
+ * HTML slider was simply not rendered. React can hide a slider; a native object
+ * cannot hide itself, so the app drives it from outside via `native_show`/
+ * `native_hide <varname>` (useNativeVisibility).
+ *
+ * ------------------------------------------------------------------------------
+ * THIS IS A SPIKE, and its FIRST mechanism already FAILED IN LIVE.
+ *
+ * Attempt 1 (this codegen, now retired): a `[thispatcher]` running `script hide
+ * <varname>`. Verified in Live - the dials did NOT disappear. `script hide` acts on
+ * the PATCHING canvas; the M4L device view is the PRESENTATION, and `script` has no
+ * documented reach into it.
+ *
+ * Attempt 2 (current): the wrapper's [js] handles `native_show`/`native_hide` and
+ * manipulates the object through the Maxobj API (`this.patcher.getnamed(varname)`),
+ * with console diagnostics. So this codegen no longer claims the messages - it lets
+ * them fall through to the wrapper. See `native_show`/`native_hide` in core.ts.
+ *
+ * If attempt 2 also fails to reach the presentation, the honest conclusion is that a
+ * frozen M4L device cannot hide a native object at runtime, and the fallback is a
+ * build-time choice (fewer native params, or a device keeps HTML controls).
+ * ------------------------------------------------------------------------------
+ */
+
 /**
  * Compile a declared `window` into the patcher: a subpatcher holding its own
  * [jweb], and a [pcontrol] that opens it when the app asks.
@@ -323,6 +506,47 @@ export function applySurface(ctx) {
  * failed to exist.
  * ------------------------------------------------------------------------------
  */
+
+/**
+ * `alwaysOnTop` - keep the window in FRONT of Live rather than behind it.
+ *
+ * A window you READ while working (a reference) is useless without this: clicking back
+ * into the device to type is exactly what buries it. A window you work IN (an editor)
+ * wants the default, which is why this is opt-in.
+ *
+ * `[thispatcher]` + `window flags ... , window exec` is Max's documented route - the
+ * flags do not take effect until `exec`, which is why it is two messages and not one.
+ *
+ * **`window flags` REPLACES the whole list; it does not add to it.** So `float` alone
+ * would produce a window with no close box, no title bar and no resize - a reference
+ * card the user cannot get rid of. `grow close title` are named alongside it to put
+ * back the ones a window is expected to have.
+ *
+ * A `loadbang` inside the SUBPATCHER fires when the subpatcher is loaded (with the
+ * device), not when its window is opened - which is what we want: the flags are a
+ * property of the window, set once, whether or not anyone ever opens it.
+ */
+const FLOAT_MSG = "window flags grow close title float, window exec";
+
+function floatBoxes(spec) {
+  if (!spec.alwaysOnTop) return [];
+  const y = 96 + spec.height + 80;
+  return [
+    { box: { id: "obj-float-loadbang", maxclass: "newobj", text: "loadbang", numinlets: 1, numoutlets: 1, outlettype: ["bang"], patching_rect: [220, y, 60, 22] } },
+    // A MESSAGE box - the comma is what makes it two messages, which is the point.
+    { box: { id: "obj-float-msg", maxclass: "message", text: FLOAT_MSG, numinlets: 2, numoutlets: 1, outlettype: [""], patching_rect: [220, y + 30, 280, 22] } },
+    { box: { id: "obj-float-thispatcher", maxclass: "newobj", text: "thispatcher", numinlets: 1, numoutlets: 2, outlettype: ["", ""], patching_rect: [220, y + 60, 80, 22] } },
+  ];
+}
+
+function floatLines(spec) {
+  if (!spec.alwaysOnTop) return [];
+  return [
+    { patchline: { source: ["obj-float-loadbang", 0], destination: ["obj-float-msg", 0] } },
+    { patchline: { source: ["obj-float-msg", 0], destination: ["obj-float-thispatcher", 0] } },
+  ];
+}
+
 export function applyWindows(ctx) {
   const { boxes, lines, surface, unmatchedId } = ctx;
   const windowIds = surface?.windows ? Object.keys(surface.windows) : [];
@@ -442,12 +666,14 @@ export function applyWindows(ctx) {
               },
             },
             { box: { id: "obj-out", maxclass: "outlet", patching_rect: [16, 96 + spec.height + 48, 30, 30], numinlets: 1, numoutlets: 0 } },
+            ...floatBoxes(spec),
           ],
           lines: [
             { patchline: { source: ["obj-recv", 0], destination: ["obj-jweb", 0] } },
             // [jweb] outlet 0 is the page's messages; tag them and send them out.
             { patchline: { source: ["obj-jweb", 0], destination: ["obj-tag", 0] } },
             { patchline: { source: ["obj-tag", 0], destination: ["obj-out", 0] } },
+            ...floatLines(spec),
           ],
         },
       },
@@ -501,7 +727,25 @@ export function applyPersistence(ctx) {
     // it binds to a NAMED object in the patcher, not to a box id (which is ours, and
     // which Max is free to renumber). The dict's own name argument is what [js]
     // addresses with `new Dict("obj-state-<id>")`, so all three agree.
-    boxes.push(box(dictId, `dict ${dictId}`, { varname: dictId, numinlets: 2, numoutlets: 4, outlettype: ["dictionary", "", "", ""] }));
+    //
+    // THE SEED: `@embed 1` plus box-level `data` is how a Max-saved patcher embeds
+    // a dict's contents (the shape read off dict.maxhelp), and it is what makes a
+    // declared `default` mean what it says on a FRESH instance - without it the
+    // dict loads empty and the app's default is all the truth there is, which held
+    // only because the app also knew the default. Enveloped like every other value
+    // (`{"__value": ...}`), so the read path cannot tell a seed from a write. A
+    // restored [pattr] value overwrites the seed at load, which is the required
+    // order: restore beats seed, seed beats nothing.
+    boxes.push(
+      box(dictId, `dict ${dictId} @embed 1`, {
+        varname: dictId,
+        numinlets: 2,
+        numoutlets: 4,
+        outlettype: ["dictionary", "", "", ""],
+        data: { __value: surface.state[id].default },
+        saved_object_attributes: { embed: 1 },
+      }),
+    );
 
     const pattrId = `obj-pattr-${id}`;
     boxes.push(

package/src/watch.mjs

@@ -0,0 +1,71 @@
+/**
+ * watch.mjs - the build side of defineWatch().
+ *
+ * The twin of surface.mjs's loadSurface: it imports a device's watch declaration
+ * and turns it into the WATCH_SPECS the packaged wrapper reads. The wrapper is
+ * generic; this is where a device's specific list of Live properties to observe
+ * enters, as an injected data banner - exactly as BUILD_STAMP and the payloads do.
+ *
+ * There is no patcher wiring here, and that is the point: an observer is pure
+ * LiveAPI, created in [js] from bang(), so nothing crosses into the patcher graph.
+ * The declaration produces DATA, not boxes.
+ */
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Load a device's `src/app/<uiDir>/watch.ts`, or null if it declares none.
+ *
+ * Bundled with esbuild exactly like loadSurface, for the same reason: the
+ * declaration is TypeScript importing @m4l-jweb/surface, and Node cannot import
+ * that directly.
+ */
+export async function loadWatch(root, uiDir) {
+  const src = path.join(root, "src", "app", uiDir, "watch.ts");
+  if (!existsSync(src)) return null;
+
+  const { build } = await import("esbuild");
+  const tmp = mkdtempSync(path.join(tmpdir(), "m4l-watch-"));
+  const out = path.join(tmp, "watch.mjs");
+  try {
+    await build({
+      entryPoints: [src],
+      outfile: out,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      logLevel: "silent",
+      external: ["react", "react-dom"],
+    });
+    const mod = await import(pathToFileURL(out).href);
+    const watch = mod.default;
+    if (!watch?.keys) {
+      throw new Error(`${src} must \`export default defineWatch({...})\``);
+    }
+    return watch;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The `var WATCH_SPECS = [...]` banner prepended to a device's wrapper.js.
+ *
+ * Only what the wrapper needs to ATTACH the observer travels: the selector key,
+ * the LOM path, the property. The `default` is the app's business (it seeds
+ * useWatch before Live replies) and never reaches Max, so it is dropped here -
+ * shipping it would be dead weight inside every .amxd.
+ *
+ * A device with no watches gets no banner ("") - `typeof WATCH_SPECS === "undefined"`
+ * is exactly the guard the wrapper's setupWatches() checks.
+ */
+export function watchSpecsBanner(watch) {
+  if (!watch || !watch.keys.length) return "";
+  const specs = watch.keys.map((key) => {
+    const w = watch.watches[key];
+    return { key, path: w.path, property: w.property };
+  });
+  return `var WATCH_SPECS = ${JSON.stringify(specs)};\n`;
+}

package/templates/install-mac.sh

@@ -53,6 +53,14 @@ for f in "$src"/*.amxd; do
 	echo "  installed $(basename "$f")"
 done
 
+# Presets (hand-saved Live racks, packaged next to the devices by the build) go in
+# the same folder, so a rack that names these devices finds them one drag away.
+for f in "$src"/*.adg "$src"/*.adv; do
+	[ -e "$f" ] || continue
+	cp "$f" "$dest/"
+	echo "  installed $(basename "$f") (preset)"
+done
+
 echo "Installed to $dest"
 echo "In Live: User Library > Max For Live > $device_name"
 echo "NOTE: Live embeds a copy of the device in the set. Instances already"

package/templates/install-windows.ps1

@@ -58,6 +58,13 @@ foreach ($f in $devices) {
     Write-Host "  installed $($f.Name)"
 }
 
+# Presets (hand-saved Live racks, packaged next to the devices by the build) go in
+# the same folder, so a rack that names these devices finds them one drag away.
+foreach ($f in @(Get-ChildItem (Join-Path $src "*.adg") -ErrorAction SilentlyContinue) + @(Get-ChildItem (Join-Path $src "*.adv") -ErrorAction SilentlyContinue)) {
+    Copy-Item $f.FullName $dest -Force
+    Write-Host "  installed $($f.Name) (preset)"
+}
+
 Write-Host "Installed to $dest"
 Write-Host "In Live: User Library > Max For Live > $deviceName"
 Write-Host "NOTE: Live embeds a copy of the device in the set. Instances already"

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