@m4l-jweb/build 0.6.5 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,6 @@
     "archiver": "^7.0.1",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "0.6.5"
+    "@m4l-jweb/wrapper": "0.7.0"
   }
 }

package/src/surface.mjs

@@ -124,7 +124,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 +188,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 +237,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 +280,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 +293,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 +314,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 +346,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 +364,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 +406,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.

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