@m4l-jweb/wrapper 0.7.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/wrapper",
-  "version": "0.7.0",
+  "version": "0.9.1",
   "description": "m4l-jweb: the Max for Live glue layer connecting a device to LiveAPI.",
   "type": "module",
   "license": "MIT",

package/sources.mjs

@@ -24,4 +24,5 @@ export const types = src("max.d.ts");
 export const sources = [
 	src("core.ts"), // build stamp, lifecycle, the anything() guard, payload extraction
 	src("liveapi.ts"), // transport poll, tempo observer, clip I/O
+	src("watch.ts"), // defineWatch() observers - after liveapi, it calls observeProperty()
 ];

package/src/core.ts

@@ -50,6 +50,7 @@ function bang(): void {
   loadWebview();
   setupTempoObserver(); // liveapi.ts
   startTickPoll(); // liveapi.ts
+  setupWatches(); // watch.ts - the device's declared defineWatch() observers
   // A device's own wrapper/device.ts hooks in here: this is the ONLY safe place
   // to create LiveAPI objects (see the loadbang trap above).
   if (typeof onDeviceReady === "function") onDeviceReady();
@@ -67,6 +68,7 @@ function reload(): void {
   loadWebview();
   setupTempoObserver();
   startTickPoll();
+  setupWatches(); // watch.ts
 }
 
 /**
@@ -119,6 +121,7 @@ function ui_ready(): void {
   // mixed install (stale .amxd instance vs newer extracted UI, or vice versa).
   reply("build", buildStamp());
   sendCurrentTempo(); // liveapi.ts
+  resendWatches(); // watch.ts - the current value of every declared watch, for a late page
   // The device resends its own state here. The page loads asynchronously, so
   // anything sent before it was listening is simply gone.
   if (typeof onUiReady === "function") onUiReady();
@@ -251,6 +254,109 @@ function setNativeHidden(varname: string, hidden: number): void {
   }
 }
 
+/* ------------------------------------------------------------------ *
+ * Parameter LOM ids - what the `remote` chain binds to
+ *
+ * `get_param_id <id>` from the app; `param_id <id> <lomId>` back, 0 if unresolved.
+ *
+ * WHY THE WRAPPER AND NOT THE APP. A live.remote~ is bound by LOM id, and only [js]
+ * can ask Live for one. The app knows the NAME of the parameter it declared; the LOM
+ * knows ids and a `name` per DeviceParameter. This is the one place that can join
+ * those, because the build wrote `parameter_longname: <id>` from the same surface
+ * declaration the app imports - so a surface id IS the Live parameter's name, and the
+ * match needs no second table anyone has to keep in step.
+ *
+ * WHY IT IS ASKED FOR, NOT PUSHED. LOM ids are handles into the running set and are
+ * NOT stable across reloads, so there is no moment at which a list of them could be
+ * cached and trusted. The app asks when it binds, and asks again on the next load;
+ * anything else persists an id, which is the documented way to modulate the wrong
+ * parameter after a set reopens.
+ *
+ * THE REPLY GOES TO THE DEVICE VIEW, not to a window, and it is `outlet(0, ...)` for
+ * the same reason `buffer_error` and `fetch_done` are: reply() carries ONE value by
+ * fixed arity (a Max host function will not take .apply - it fails silently in Live,
+ * which is how the whole ui_ready handshake was once lost), and this answer is a pair.
+ * A window is an editor, not an engine - `tick` never reaches one either, and it is the
+ * tick that a bound slot is streamed on.
+ * ------------------------------------------------------------------ */
+
+function get_param_id(id: string): void {
+  // `this_device` resolves to the device this [js] lives in. Its `parameters` are the
+  // live.* objects the surface generated, in the order they were created - but ORDER
+  // IS NOT A CONTRACT (add a dial and every index shifts), so match on a name.
+  //
+  // WHICH name is the hard-won part. The build stores the surface id as the
+  // parameter's longname, and the box KEEPS it (`_parameter_longname` reads back
+  // "cutoff") - but Live's parameter registration names the DeviceParameter after
+  // the SHORTNAME anyway, and no patcher data we found overrides that. So do not
+  // bet on either policy: ask the BOX for both of its names and accept whichever
+  // one Live used. The surface id stays the only key an app ever passes; the
+  // display names never leave this function.
+  var found = 0;
+  try {
+    var dev = new LiveAPI("this_device");
+    if (!dev || !dev.id) {
+      post("m4l-jweb: get_param_id " + id + " -> no this_device (called during load?)\n");
+      outlet(0, "param_id", id, 0);
+      return;
+    }
+
+    // The box is the authority on its own names - reading them here (instead of
+    // shipping a second id->shortname table) means a renamed dial cannot drift
+    // out of step with this lookup.
+    var accept: string[] = [id];
+    try {
+      var mobj = this.patcher.getnamed("param-" + id);
+      if (mobj) {
+        var ln = mobj.getattr("_parameter_longname");
+        var sn = mobj.getattr("_parameter_shortname");
+        if (ln !== null && ln !== undefined) accept.push(String(ln));
+        if (sn !== null && sn !== undefined) accept.push(String(sn));
+      }
+    } catch (eb) {
+      /* no box, no extra candidates - the surface id alone still gets a chance */
+    }
+
+    var n = dev.getcount("parameters");
+    var seen: string[] = [];
+    for (var i = 0; i < n; i++) {
+      var p = new LiveAPI("this_device parameters " + i);
+      if (!p || !p.id) continue;
+      var pname = String(p.get("name"));
+      var hit = false;
+      for (var k = 0; k < accept.length; k++) {
+        if (pname === accept[k]) {
+          hit = true;
+          break;
+        }
+      }
+      if (hit) {
+        if (found) {
+          // Two parameters wearing one accepted name: refuse to guess. Binding a
+          // live.remote~ to the wrong parameter is a modulation on someone else's
+          // control, which is worse than no modulation.
+          post("m4l-jweb: get_param_id " + id + ' -> AMBIGUOUS: two parameters answer to "' + pname + '". Give them distinct short names.\n');
+          found = 0;
+          break;
+        }
+        found = p.id;
+      } else {
+        seen.push(pname);
+      }
+    }
+    // Print what IS there: "no parameter of that name" alone cannot distinguish a
+    // renamed parameter from an empty list from a shifted path.
+    if (!found) {
+      post(
+        "m4l-jweb: get_param_id " + id + " -> no match (accepted: " + accept.join(" | ") + ") among " + n + " parameters: " + seen.join(", ") + "\n",
+      );
+    }
+  } catch (e) {
+    post("m4l-jweb: get_param_id " + id + " error: " + (e as Error).message + "\n");
+  }
+  outlet(0, "param_id", id, found);
+}
+
 /* ------------------------------------------------------------------ *
  * Floating-window messages
  *

package/src/liveapi.ts

@@ -103,15 +103,21 @@ function sendCurrentTempo(): void {
  * observeProperty("live_set", "scale_name", "scale") forwards every change to
  * the UI as `scale <value>`. Returns the LiveAPI object so you can keep it
  * alive; drop it and the observer dies with it.
+ *
+ * The value is the property's FIRST atom - a watch is scalar (a tempo, a
+ * numerator, a name), which is every real Live property one wants to observe.
+ * That is not a shortcut: it is forced by how `outlet` must be called. `outlet`
+ * is a Max HOST function, and `.apply`-ing it to spread a variadic message is
+ * unreliable - it errors "jsliveapi: bad outlet index 0" from inside a LiveAPI
+ * callback in Live, killing the notification. So the value goes out fixed-arity,
+ * exactly as the tempo observer's `outlet(0, "tempo", a[1])` does - the one shape
+ * that works. A property with several atoms forwards its first.
  */
 function observeProperty(objectPath: string, property: string, selector: string): LiveAPI | null {
   try {
     var api = new LiveAPI(function (a: unknown[]) {
-      if (a && a[0] == property) {
-        var args: unknown[] = [0, selector];
-        for (var i = 1; i < a.length; i++) args.push(a[i]);
-        (outlet as Function).apply(this, args);
-      }
+      // a = [property, value] for a scalar property. Fixed-arity, never outlet.apply.
+      if (a && a[0] == property) outlet(0, selector, a[1]);
     }, objectPath);
     api.property = property;
     return api;
@@ -133,9 +139,26 @@ interface LiveNote {
   mute?: number;
 }
 
-/** The LiveAPI for the track this device sits on. */
+/**
+ * The LiveAPI for the TRACK this device sits on - clip I/O belongs to the track.
+ *
+ * `this_device canonical_parent` is the track ONLY when the device sits directly on
+ * it. Inside a Rack it is the CHAIN the device is in, and a Chain has no `clip_slots` -
+ * so `getcount("clip_slots")` on it throws "invalid property name" once a second (the
+ * clip-availability poll), and clip read/write silently target the wrong object. So
+ * climb the `canonical_parent` chain until a Track is reached, which handles a device
+ * on a bare track (no climb), in a rack (one hop), and in a nested rack (several).
+ */
 function ownTrack(): LiveAPI {
-  return new LiveAPI("this_device canonical_parent");
+  var api = new LiveAPI("this_device canonical_parent");
+  var guard = 0;
+  // id 0 is an unresolved path; stop rather than build "... canonical_parent" onto
+  // nothing. The guard is a backstop against a parent cycle the LOM should never have.
+  while (api && api.id && api.type !== "Track" && guard < 12) {
+    api = new LiveAPI(api.unquotedpath + " canonical_parent");
+    guard++;
+  }
+  return api;
 }
 
 /**
@@ -148,9 +171,20 @@ function write_clip(): void {
   var lengthBeats = a[0];
   var n = Number(a[1]);
 
+  // No reachable Track is a STRUCTURAL failure (clip I/O is impossible here), distinct
+  // from a track whose slots are all full. The UI disables clip export on the former
+  // and only reports the latter, so `write_error` says which.
+  var track = ownTrack();
+  if (!track || !track.id || track.type !== "Track") {
+    post("m4l-jweb: write_clip - no reachable track (device not on a track?)\n");
+    outlet(0, "write_error", "no_track");
+    return;
+  }
+
   var slot = firstEmptySlot();
   if (!slot) {
     post("m4l-jweb: no empty clip slot on this track\n");
+    outlet(0, "write_error", "no_slot");
     return;
   }
   slot.call("create_clip", lengthBeats);
@@ -171,6 +205,7 @@ function write_clip(): void {
     clip.call("add_new_notes", { notes: notes });
   } catch (e) {
     post("m4l-jweb: add_new_notes failed - " + (e as Error).message + "\n");
+    outlet(0, "write_error", "add_failed");
     return;
   }
   post("m4l-jweb: wrote " + n + " notes over " + lengthBeats + " beats\n");
@@ -192,17 +227,64 @@ function firstEmptySlot(): LiveAPI | null {
 }
 
 /**
- * read_notes - pick a clip on this device's track (the playing one, else the
- * first found), read its notes and send them to the UI as
+ * read_notes - pick a clip on this device's TRACK (the playing one, else the first
+ * found), read its notes and send them to the UI as
  * "notes <loopEnd> <n> <pitch start duration> ...".
+ *
+ * This ignores the Live SELECTION on purpose: a device that reads/writes its own
+ * track's pattern (m4l-strudel) wants its track's clip, not wherever the cursor
+ * happens to be. For the selection-driven case use read_selected_clip below.
  */
 function read_notes(): void {
+  // Structural failure (no reachable track) is reported distinctly from "a track with
+  // no clip", so the UI can disable clip import where it is impossible and merely say
+  // "no clip" where it is not.
+  var track = ownTrack();
+  if (!track || !track.id || track.type !== "Track") {
+    post("m4l-jweb: read_notes - no reachable track (device not on a track?)\n");
+    outlet(0, "read_error", "no_track");
+    return;
+  }
   var clip = pickClip();
   if (!clip) {
     post("m4l-jweb: no clip found on this track\n");
     outlet(0, "read_error", "no_clip");
     return;
   }
+  emitClipNotes(clip);
+}
+
+/**
+ * read_selected_clip - read the clip the CURSOR is on (Live's highlighted clip slot),
+ * whichever track and scene that is. An empty highlighted slot is "no clip", which is
+ * what makes clicking an empty slot and reading report nothing rather than falling
+ * back to some other clip on the track. Same reply shape as read_notes.
+ */
+function read_selected_clip(): void {
+  var clip = selectedClip();
+  if (!clip) {
+    post("m4l-jweb: highlighted clip slot is empty (or none)\n");
+    outlet(0, "read_error", "no_selection");
+    return;
+  }
+  emitClipNotes(clip);
+}
+
+/** The clip in Live's highlighted clip slot, or null if that slot is empty. */
+function selectedClip(): LiveAPI | null {
+  try {
+    var slot = new LiveAPI("live_set view highlighted_clip_slot");
+    if (!slot || !slot.id || Number(slot.id) === 0) return null;
+    if (parseInt(String(slot.get("has_clip")), 10) !== 1) return null;
+    return new LiveAPI(slot.unquotedpath + " clip");
+  } catch (e) {
+    post("m4l-jweb: selectedClip error " + (e as Error).message + "\n");
+    return null;
+  }
+}
+
+/** Send a clip's notes to the UI: "notes <loopEnd> <n> <pitch start duration> ...". */
+function emitClipNotes(clip: LiveAPI): void {
   var loopEnd = parseFloat(String(clip.get("loop_end")));
   var notes = getNotes(clip, loopEnd);
   if (!notes) return;
@@ -211,9 +293,12 @@ function read_notes(): void {
   for (var i = 0; i < notes.length; i++) {
     out.push(notes[i].pitch, notes[i].start_time, notes[i].duration);
   }
-  // A note list is variadic, so the message has to be spread with apply().
-  // outlet()'s typed signature cannot express that; go through Function.
-  (outlet as Function).apply(this, ([0] as unknown[]).concat(out));
+  // A note list is variadic. Do NOT spread it with `outlet.apply` - `outlet` is a Max
+  // HOST function, and calling `.apply` on it faults the [js] engine (js.mxe64) with an
+  // access violation, taking Live down; "jsliveapi: bad outlet index 0" is its warning
+  // shot. Max outputs an ARRAY passed as the single argument as a list, first atom the
+  // selector - so `outlet(0, ["notes", ...])` sends the same message, no apply.
+  outlet(0, out);
   post("m4l-jweb: read " + notes.length + " notes (loop_end " + loopEnd + ")\n");
 }
 

package/src/max.d.ts

@@ -131,6 +131,28 @@ declare class LiveAPI {
   constructor(pathOrCallback: string | ((args: unknown[]) => void), path?: string);
   property: string;
   unquotedpath: string;
+  /**
+   * The object's LOM id, and the FIRST thing to check on anything you construct: a
+   * path that does not resolve gives you an object with id 0 rather than an error,
+   * and every get() on it then returns nothing, quietly. `if (!api.id)` is the guard.
+   *
+   * NOT STABLE ACROSS SET RELOADS. An id is a handle into the running set, not a
+   * name - never persist one (see the `remote` chain, which binds by id and therefore
+   * makes re-binding on load the app's job).
+   */
+  readonly id: number;
+  /** The canonical path this object resolved to - not necessarily the one you asked for. */
+  readonly path: string;
+  /** The LOM class name, e.g. "Track", "DeviceParameter". */
+  readonly type: string;
+  /**
+   * What this object actually HAS - its properties, children and methods, as text.
+   *
+   * The honest way to ask whether a method exists before calling it: a blind call
+   * cannot tell "no such method" from "the method failed", and the LOM is only
+   * partly documented. Worth a post() when you are exploring.
+   */
+  readonly info: string;
   get(prop: string): unknown;
   set(prop: string, value: unknown): void;
   getcount(child: string): number;
@@ -154,6 +176,13 @@ declare const EXTRA_PAYLOAD_NAMES: string[] | undefined;
 declare const EXTRA_PAYLOAD_BYTES: number[] | undefined;
 declare const EXTRA_PAYLOAD_B64: string[][] | undefined;
 
+/**
+ * Injected by @m4l-jweb/build from the device's `defineWatch()`: the Live
+ * properties to observe. The packaged wrapper attaches an observer per entry from
+ * bang() (setupWatches, watch.ts) - undefined for a device that declares none.
+ */
+declare const WATCH_SPECS: { key: string; path: string; property: string }[] | undefined;
+
 /*
  * Device hooks.
  *

package/src/watch.ts

@@ -0,0 +1,70 @@
+/**
+ * watch.ts - the observers a device DECLARED with defineWatch(), created here.
+ *
+ * Concatenated after liveapi.ts, so it can call observeProperty(). The list of
+ * what to observe is injected by the build as WATCH_SPECS (like BUILD_STAMP and
+ * the payloads) - one array per device, from its src/app/<device>/watch.ts. This
+ * file is generic: it observes whatever the array names, and a device that
+ * declared no watches ships an undefined WATCH_SPECS and this does nothing.
+ *
+ * WHY THE DECLARATION EXISTS AT ALL. A LiveAPI observer built during loadbang is
+ * DEAD - it constructs without error and notifies nothing, forever (hard rule 4).
+ * The only safe moment is live.thisdevice's bang. So the observers are not
+ * hand-written in a device's wrapper/device.ts, where the trap is one typo away;
+ * they are declared as data and created HERE, from bang(), unconditionally - which
+ * is the one place, and the one way, that is correct by construction.
+ */
+
+/**
+ * The attached observers, kept alive for the life of the device: drop the LiveAPI
+ * and its observer dies with it. Recreated (not reused) on every bang - an object
+ * from a previous, loading context is dead and must not be trusted.
+ */
+var watchObservers: (LiveAPI | null)[] = [];
+
+/** Attach every declared observer. Call from bang() (and reload()), never loadbang(). */
+function setupWatches(): void {
+  if (typeof WATCH_SPECS === "undefined") return;
+  // Recreate unconditionally - a guard like `if (watchObservers.length) return`
+  // would make hard rule 4 permanent, keeping a dead observer forever.
+  watchObservers = [];
+  for (var i = 0; i < WATCH_SPECS.length; i++) {
+    var w = WATCH_SPECS[i];
+    // observeProperty forwards every change as `watch_<key> <value...>` - the same
+    // shape a parameter uses, so the app binds it exactly like `useParam`'s inlet.
+    watchObservers.push(observeProperty(w.path, w.property, "watch_" + w.key));
+  }
+  if (WATCH_SPECS.length) post("m4l-jweb: watching " + WATCH_SPECS.length + " Live propert" + (WATCH_SPECS.length === 1 ? "y" : "ies") + "\n");
+}
+
+/**
+ * Send each watched property's CURRENT value once, on ui_ready.
+ *
+ * The observer's first callback can beat the page's binding - the page loads
+ * asynchronously and long after bang() attached the observer - so the app would
+ * miss the value it had at load. This is the watch twin of sendCurrentTempo(): a
+ * fresh read, straight to the device view. It goes out outlet(0) like tick and
+ * tempo, not through reply(): a watch streams to the device UI, and a window is an
+ * editor that never receives the transport clock either.
+ */
+function resendWatches(): void {
+  if (typeof WATCH_SPECS === "undefined") return;
+  for (var i = 0; i < WATCH_SPECS.length; i++) {
+    var w = WATCH_SPECS[i];
+    try {
+      var api = new LiveAPI(w.path);
+      var v = api.get(w.property);
+      // LiveAPI.get returns an array for a multi-atom property and a bare value for a
+      // scalar; take the first atom either way. Duck-typed, not `instanceof Array`: a
+      // Max array is not a JS Array instance, nor is one crossing a vm realm in tests.
+      if (v !== null && typeof v === "object" && typeof (v as { length?: unknown }).length === "number") {
+        v = (v as unknown[])[0];
+      }
+      // Fixed-arity, never outlet.apply - the same rule observeProperty follows, and for
+      // the same reason: apply on the host outlet errors "bad outlet index 0" in Live.
+      outlet(0, "watch_" + w.key, v);
+    } catch (e) {
+      post("m4l-jweb: watch resend failed for " + w.key + " - " + (e as Error).message + "\n");
+    }
+  }
+}