@m4l-jweb/wrapper 0.9.9 → 1.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @m4l-jweb/wrapper
+
+The Max-side glue: the ES5 `[js]` script that owns a device's lifecycle, its LiveAPI work, transport polling, clip I/O and file writes. You do not usually import this - `@m4l-jweb/build` compiles it into every device it produces.
+
+Part of **[m4l-jweb](https://github.com/alienmind/m4l-jweb)** - build Ableton Live devices (`.amxd`) from a TypeScript repo: React UI, LiveAPI glue, CI builds, no Max editor.
+
+## Install
+
+```bash
+pnpm add @m4l-jweb/wrapper
+```
+
+## Usage
+
+```ts
+// Only a device repo extending the wrapper needs this: wrapper/device.ts is
+// compiled together with the packaged sources into one ES5 script.
+//
+// Everything here must be ES5 - Max's [js] is not a modern JavaScript engine, and the
+// build proves it with acorn before packaging.
+```
+
+## Notes
+
+- `[js]` runs even inside a frozen device, and it is the only place LiveAPI exists - which is why the lifecycle lives here rather than in the browser.
+- This package exists mainly so the build can find the wrapper sources (`@m4l-jweb/wrapper/sources`). It has no browser-facing API of its own.
+- **`[node.script]` is never used.** It proved unstable in the field - silent non-start, then a full Live crash.
+
+## Requirements
+
+Ableton Live 12 with Max 9. Devices are built on `[jweb~]`, the browser view with signal outlets; older hosts are unverified.
+
+## Links
+
+- [Repository and full README](https://github.com/alienmind/m4l-jweb)
+- [Architecture](https://github.com/alienmind/m4l-jweb/blob/main/doc/ARCHITECTURE.md)
+- [What Max actually does: the measured facts](https://github.com/alienmind/m4l-jweb/blob/main/doc/MAX-FACTS.md)
+
+## License
+
+MIT

package/package.json

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

package/src/core.ts

@@ -51,6 +51,7 @@ function bang(): void {
   setupTempoObserver(); // liveapi.ts
   startTickPoll(); // liveapi.ts
   setupWatches(); // watch.ts - the device's declared defineWatch() observers
+  followWindowSizes(); // a resized window resizes its page
   // 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();
@@ -65,6 +66,7 @@ function loadbang(): void {
 
 /** Manual re-init, handy while developing. */
 function reload(): void {
+  sentWindowUrls = {}; // a manual reload MEANS re-fetch, dedupe or not
   loadWebview();
   setupTempoObserver();
   startTickPoll();
@@ -127,6 +129,38 @@ function ui_ready(): void {
   if (typeof onUiReady === "function") onUiReady();
 }
 
+/**
+ * One page hands a message to another page's window.
+ *
+ * The two pages of a device are separate Chromium contexts and share nothing -
+ * no globals, no memory, no events. State slots already cross that gap, but a
+ * slot SAVES WITH THE SET, so it is the wrong home for anything continuous: a
+ * knob being turned would write the Live set sixty times a second.
+ *
+ * This is the other half - a message that crosses and is not remembered. The
+ * device view sends `window_send <winId> <selector> <value>` and the page in that
+ * window receives `<selector> <value>` on the inlet it bound, exactly as if the
+ * wrapper had sent it. One selector and one value, for the reason reply() gives.
+ */
+function window_send(winId: string, selector: string, value: unknown): void {
+  messnamed("window-read-" + winId, selector, value);
+}
+
+/**
+ * How loud a sounding window is, on its way to the DEVICE VIEW's page.
+ *
+ * The patcher sends this, not a page: a `[peakamp~]` on the window's own outlets
+ * (see applyWindows). It exists because [jweb~] has no signal inlet - "Web browser
+ * with audio output" - so a page can never be handed audio, and a device view that
+ * wants to show what its window is playing has to be told in messages.
+ *
+ * Straight to outlet 0 and not through reply(): the destination is the device view
+ * by definition, whoever happens to be mid-dispatch.
+ */
+function window_level(winId: string, left: number, right: number): void {
+  outlet(0, "level_" + winId, left, right);
+}
+
 /* ------------------------------------------------------------------ *
  * State persistence
  *
@@ -254,6 +288,102 @@ function setNativeHidden(varname: string, hidden: number): void {
   }
 }
 
+/* ------------------------------------------------------------------ *
+ * What a parameter IS, said at RUNTIME
+ *
+ * A surface declares a parameter's name, unit and range at build time, which is
+ * right whenever the device knows what its own controls do. It does not when the
+ * control is whatever the user's code just asked for - a pattern's `slider()`, a
+ * modulation slot pointed somewhere new - and an unnamed 0..1 dial then says
+ * nothing about the sound it is moving, on the panel or on Push.
+ *
+ * `describeParam()` in @m4l-jweb/bridge is the app side. What is measured, in Live:
+ *
+ *   name   reaches the DEVICE PANEL, and NOT Live's parameter registry or the Rack
+ *          macro picker - a frozen device cannot rename a parameter there.
+ *   unit   takes: the unit STYLE, so a readout says "600 Hz" and not "600".
+ *   range  takes, AND CHANGES THE DOMAIN THE PARAMETER REPORTS. A page still
+ *          normalizing 0..1 would then scale an already-scaled value and the
+ *          control sticks at its minimum - which is exactly how the first attempt
+ *          at this failed and was reverted. So it is ANSWERED, and the caller
+ *          stops normalizing when the answer is yes.
+ * ------------------------------------------------------------------ */
+
+/** Max's unit styles, in the order its own reference lists them. 9 = Custom. */
+var UNITSTYLE: { [name: string]: number } = { int: 0, float: 1, ms: 2, Hz: 3, dB: 4, "%": 5, pan: 6, st: 7, midi: 8 };
+var UNITSTYLE_CUSTOM = 9;
+
+/** The live.* object a surface id compiles to. Mirrors applySurface's varname. */
+function paramBox(id: string): Maxobj | null {
+  try {
+    var obj = this.patcher.getnamed("param-" + id);
+    if (!obj) post("m4l-jweb: param " + id + " -> getnamed('param-" + id + "') null\n");
+    return obj || null;
+  } catch (e) {
+    post("m4l-jweb: param " + id + " lookup error: " + (e as Error).message + "\n");
+    return null;
+  }
+}
+
+/** Write an attribute whichever way this Max build offers. */
+function setAttr(obj: Maxobj, attr: string, a: unknown, b?: unknown): void {
+  if (typeof obj.setattr === "function") {
+    if (b === undefined) obj.setattr(attr, a);
+    else obj.setattr(attr, a, b);
+  } else {
+    if (b === undefined) obj.message(attr, a);
+    else obj.message(attr, a, b);
+  }
+}
+
+function param_label(id: string, ...rest: unknown[]): void {
+  // A name with a space in it arrives as several arguments; put it back together.
+  var label = Array.prototype.slice.call(arguments, 1).join(" ");
+  if (!id || !label) return;
+  var obj = paramBox(id);
+  if (!obj) return;
+  var before = obj.getattr("_parameter_shortname");
+  if (String(before) === label) return;
+  setAttr(obj, "_parameter_shortname", label);
+  var after = obj.getattr("_parameter_shortname");
+  // The device view is told as well: its own controls should show what the code
+  // called this, not the declared short name.
+  outlet(0, "param_desc", id, label);
+  post(
+    "m4l-jweb: param_label " + id + " '" + before + "' -> '" + after + "'" + (String(after) === label ? "" : " (did NOT take)") + "\n",
+  );
+}
+
+function param_unit(id: string, ...rest: unknown[]): void {
+  var unit = Array.prototype.slice.call(arguments, 1).join(" ");
+  if (!id || !unit) return;
+  var obj = paramBox(id);
+  if (!obj) return;
+  var known = UNITSTYLE[unit];
+  var style = known === undefined ? UNITSTYLE_CUSTOM : known;
+  setAttr(obj, "_parameter_unitstyle", style);
+  // A unit Max does not know still prints, as a custom suffix.
+  if (style === UNITSTYLE_CUSTOM) setAttr(obj, "_parameter_units", unit);
+  var after = Number(obj.getattr("_parameter_unitstyle"));
+  post("m4l-jweb: param_unit " + id + " '" + unit + "' -> style " + after + (after === style ? "" : " (did NOT take)") + "\n");
+}
+
+function param_range(id: string, lo: number, hi: number): void {
+  var min = Number(lo);
+  var max = Number(hi);
+  if (!id || !(max > min)) return;
+  var obj = paramBox(id);
+  if (!obj) return;
+  setAttr(obj, "_parameter_range", min, max);
+  var after = obj.getattr("_parameter_range");
+  var took = !!after && Number(after[0]) === min && Number(after[1]) === max;
+  // WHO SCALES. The answer goes back to whoever asked (a window included), and the
+  // device view is told too, because its own controls have the same question.
+  reply(took ? "param_range_ok" : "param_range_failed", id);
+  outlet(0, "param_desc_range", id, min, max, took ? 1 : 0);
+  post("m4l-jweb: param_range " + id + " -> " + String(after) + (took ? "" : " (did NOT take)") + "\n");
+}
+
 /* ------------------------------------------------------------------ *
  * Parameter LOM ids - what the `remote` chain binds to
  *
@@ -385,6 +515,16 @@ function window(id: string): void {
     if (selector === "ui_ready") ui_ready();
     else if (selector === "get_state") get_state(String(args[0]));
     else if (selector === "sync_state") (sync_state as any).apply(null, args);
+    // A window's page owns the code in devices like this one, so it is the page
+    // that knows what a parameter now IS. Same handlers, and param_range's answer
+    // rides replyWindow back to the window that asked.
+    // PLAIN CALLS, with the arguments already flattened. `.apply(null, ...)` would
+    // hand these functions a `this` with no patcher on it - at [js] global scope the
+    // global object IS the jsthis, and only a plain call inherits it. A spread would
+    // compile to the same .apply, so the label is joined here instead.
+    else if (selector === "param_label") param_label(String(args[0]), args.slice(1).join(" "));
+    else if (selector === "param_unit") param_unit(String(args[0]), args.slice(1).join(" "));
+    else if (selector === "param_range") param_range(String(args[0]), Number(args[1]), Number(args[2]));
     else if (typeof onWindowMessage === "function") (onWindowMessage as any).apply(null, [id, selector].concat(args as any[]));
     else post("m4l-jweb: window " + id + " sent unhandled '" + selector + "'\n");
   } finally {
@@ -430,9 +570,137 @@ function loadWindows(): void {
   var prefix = windowPrefix();
   for (var i = 0; i < ids.length; i++) {
     var winId = ids[i];
-    var winUrl = encodeURI("file:///" + folder + "/" + prefix + winId + ".html") + "?v=" + encodeURIComponent(buildStamp());
-    messnamed("window-read-" + winId, "url", winUrl);
-    post("m4l-jweb: window " + winId + " -> " + winUrl + "\n");
+    // listWindowIds() includes the `site:` windows, because everything else that
+    // walks the windows (the state fan-out) must see them. They have no extracted
+    // payload though, so pointing one at `<device>_<id>.html` would load a file
+    // that is not there - and then the real url below would load the page a second
+    // time.
+    if (isSiteWindow(winId)) continue;
+    sendWindowUrl(winId, folder + "/" + prefix + winId + ".html");
+  }
+
+  // A `site:` window's page is not an extracted payload - it is a folder that
+  // shipped alongside the .amxd, so its URL is built from SITE_WINDOWS instead.
+  if (typeof SITE_WINDOWS !== "undefined") {
+    for (var siteId in SITE_WINDOWS) {
+      if (!SITE_WINDOWS.hasOwnProperty(siteId)) continue;
+      var target = folder + "/" + SITE_WINDOWS[siteId];
+      if (!fileExists(target)) {
+        // Not fatal - the device plays on, the window just opens empty - but it
+        // is invisible without saying it: nothing else in Max reports a page that
+        // did not load.
+        post(
+          "m4l-jweb: window '" + siteId + "' is missing its sidecar folder - expected " + target +
+            ". Install the whole '<device>-site' folder NEXT TO the .amxd.\n",
+        );
+      }
+      sendWindowUrl(siteId, target);
+    }
+  }
+}
+
+/**
+ * Point one window's [jweb] at a file, ONCE per url.
+ *
+ * loadbang and live.thisdevice both call loadWebview (they must: either can be
+ * the one that runs in a given load), so without this every page is fetched
+ * twice. For a small window that is waste; for a `site:` window it is tens of MB
+ * and a visible second load.
+ */
+function sendWindowUrl(winId: string, target: string): void {
+  var url = encodeURI("file:///" + target) + "?v=" + encodeURIComponent(buildStamp());
+  if (sentWindowUrls[winId] === url) return;
+  sentWindowUrls[winId] = url;
+  messnamed("window-read-" + winId, "url", url);
+  post("m4l-jweb: window " + winId + " -> " + url + "\n");
+}
+
+/** What each window was last pointed at, so a second load does not re-fetch it. */
+var sentWindowUrls: { [id: string]: string } = {};
+
+/* ------------------------------------------------------------------ *
+ * A window's page follows the window's size - SPIKE
+ *
+ * A floating window can be dragged bigger, and its [jweb] does not care: the box
+ * has the size the build gave it, so the page keeps its original width and the
+ * rest of the window is empty grey. For a reference card that is tolerable; for a
+ * window you WORK in (an editor, a whole REPL) it makes resizing pointless.
+ *
+ * Max has no resize NOTIFICATION - `window getsize` is a query, and [thispatcher]
+ * reports only what it is asked. So this polls, cheaply, and only while the window
+ * is actually open.
+ *
+ * WHY IT MAY NOT WORK, and what to watch. This repo has already measured that
+ * setting `presentation_rect` at runtime is accepted but NOT redrawn in a frozen
+ * M4L device (see setNativeHidden). That was the device view, which is Live's
+ * presentation; a floating subpatcher window is an ordinary patcher window, so the
+ * same call may well take here. It logs the first size it applies per window, so
+ * the Max console says whether it did.
+ * ------------------------------------------------------------------ */
+
+var resizeTask: Task | null = null;
+/** The last size applied per window, so the log is one line and not one per poll. */
+var appliedSize: { [id: string]: string } = {};
+
+function followWindowSizes(): void {
+  var ids = listWindowIds();
+  if (!ids.length) return;
+  if (resizeTask) resizeTask.cancel();
+  resizeTask = new Task(function () {
+    for (var i = 0; i < ids.length; i++) fitWindowPage(ids[i]);
+  }, this);
+  resizeTask.interval = 500;
+  resizeTask.repeat();
+}
+
+function fitWindowPage(winId: string): void {
+  try {
+    var box = this.patcher.getnamed("window-" + winId);
+    if (!box) return;
+    var sub = box.subpatcher();
+    if (!sub) return;
+    var wind = sub.wind;
+    // A closed window has nothing to fit, and reading a hidden one every half
+    // second for no reason is the kind of cost that only shows up in someone's CPU
+    // meter.
+    if (!wind || !wind.visible) return;
+
+    // Max reports [width, height] here, but be liberal: a 4-number rect would
+    // otherwise be applied as a nonsense size.
+    var size = wind.size;
+    if (!size || size.length < 2) return;
+    var w = size.length >= 4 ? size[2] - size[0] : size[0];
+    var h = size.length >= 4 ? size[3] - size[1] : size[1];
+    if (!(w > 0 && h > 0)) return;
+
+    var key = w + "x" + h;
+    if (appliedSize[winId] === key) return;
+    appliedSize[winId] = key;
+
+    var page = sub.getnamed("obj-jweb");
+    if (!page) return;
+    page.rect = [0, 0, w, h];
+    page.presentation_rect = [0, 0, w, h];
+    post("m4l-jweb: window " + winId + " page fitted to " + key + "\n");
+  } catch (e) {
+    post("m4l-jweb: window " + winId + " resize error: " + (e as Error).message + "\n");
+  }
+}
+
+/** Is this window's content a sidecar folder rather than an extracted payload? */
+function isSiteWindow(winId: string): boolean {
+  return typeof SITE_WINDOWS !== "undefined" && SITE_WINDOWS.hasOwnProperty(winId);
+}
+
+/** Does a path exist on disk? Max's File opens what is there and nothing else. */
+function fileExists(target: string): boolean {
+  try {
+    var f = new File(target, "read");
+    var open = f.isopen;
+    if (open) f.close();
+    return open;
+  } catch (e) {
+    return false;
   }
 }
 
@@ -449,6 +717,14 @@ function windowPrefix(): string {
  */
 function listWindowIds(): string[] {
   var ids: string[] = [];
+  // A `site:` window has no payload to be listed from, but it is a window like any
+  // other everywhere else - state fan-out included, which is how a page in one
+  // window learns what a page in another just wrote.
+  if (typeof SITE_WINDOWS !== "undefined") {
+    for (var siteId in SITE_WINDOWS) {
+      if (SITE_WINDOWS.hasOwnProperty(siteId)) ids.push(siteId);
+    }
+  }
   if (typeof EXTRA_PAYLOAD_NAMES === "undefined") return ids;
   var prefix = windowPrefix();
   for (var i = 0; i < EXTRA_PAYLOAD_NAMES.length; i++) {
@@ -690,6 +966,28 @@ function partPath(destPath: string): string {
   return destPath + ".part";
 }
 
+/**
+ * Where a SAVE lands before it has earned its destination - and deliberately NOT
+ * `<dest>.part`.
+ *
+ * `[js]` cannot delete a file, so a spent `.part` is truncated to zero bytes and left.
+ * For a download that is harmless: the destination is derived from the URL, so the same
+ * sample re-fetched reuses (and overwrites) the same scratch file. A SAVE has no such
+ * guarantee - an audio export names its file after the moment it was rendered, so every
+ * bounce would strand another 0-byte `superdough-export-<n>.wav.part` next to the real
+ * one, forever.
+ *
+ * One fixed scratch name per device folder instead: reused, overwritten, and never more
+ * than a single stray zero-byte file however many exports are made. Safe because saves
+ * are strictly one at a time (`activeSave`), and separate from the fetch scratch so a
+ * download in flight cannot collide with a save.
+ */
+function savePartPath(destPath: string): string {
+  var cut = destPath.lastIndexOf("/");
+  var dir = cut < 0 ? "" : destPath.slice(0, cut + 1);
+  return dir + "m4l-jweb-save.part";
+}
+
 interface ActiveFetch {
   requestId: string;
   url: string;
@@ -786,7 +1084,7 @@ function save_begin(requestId: string, destPath: string, byteCount: number): voi
   if (activeSave && activeSave.file && activeSave.file.isopen) activeSave.file.close();
 
   var resolved = resolveFetchPath(destPath);
-  var target = partPath(resolved);
+  var target = savePartPath(resolved);
   var f: File | null = null;
   try {
     f = new File(target, "write");
@@ -820,7 +1118,7 @@ function save_end(requestId: string): void {
   var save = activeSave;
   if (save.file && save.file.isopen) save.file.close();
 
-  var onDisk = fileSize(partPath(save.destPath));
+  var onDisk = fileSize(savePartPath(save.destPath));
   if (onDisk !== save.expect) {
     outlet(0, "save_error", requestId, "size mismatch: wrote " + onDisk + " bytes, expected " + save.expect);
     activeSave = null;
@@ -830,7 +1128,7 @@ function save_end(requestId: string): void {
   // destPath must be a FLAT filename in the device folder - maxurl (libcurl) and Max's
   // [js] File resolve a subdirectory differently, so `sub/x.wav` writes the .part where
   // File agrees but maxurl cannot reach it, and the place returns -1. Keep saves flat.
-  var placeUrl = encodeURI("file:///" + partPath(save.destPath));
+  var placeUrl = encodeURI("file:///" + savePartPath(save.destPath));
   post("m4l-jweb: save place " + placeUrl + " -> " + save.destPath + "\n");
   var reqDict = new Dict();
   reqDict.set("url", placeUrl);
@@ -851,7 +1149,7 @@ function finishSavePlace(): void {
     activeSave = null;
     return;
   }
-  truncate(partPath(save.destPath)); // [js] cannot delete; zero it
+  truncate(savePartPath(save.destPath)); // [js] cannot delete; zero it, and reuse it
   post("m4l-jweb: saved " + placed + " bytes to " + save.destPath + "\n");
   outlet(0, "save_done", save.requestId, placed);
   activeSave = null;

package/src/max.d.ts

@@ -40,6 +40,26 @@ declare let outlets: number;
  * disk. (Hence `noImplicitThis: false` in wrapper/tsconfig.json.)
  */
 
+/**
+ * A box in the patcher, reached with `this.patcher.getnamed("<varname>")`.
+ *
+ * Only what the wrapper actually uses is declared. `setattr` is the documented
+ * writer and `message` the older form; both are present in the wild, so the
+ * wrapper tries one and falls back to the other.
+ */
+declare interface Maxobj {
+  /** Hide or show in the device (presentation) view. Works at runtime; position does not. */
+  hidden: number;
+  /** Patching-canvas rect [left, top, right, bottom]. */
+  rect: number[];
+  /** Presentation rect. Accepted at runtime but never redrawn - see MAX-FACTS.md. */
+  presentation_rect: number[];
+  getattr(name: string): unknown;
+  setattr(name: string, ...values: unknown[]): void;
+  message(selector: string, ...args: unknown[]): void;
+  subpatcher(): { wind?: { visible: boolean; size: number[] }; getnamed(varname: string): Maxobj | null } | null;
+}
+
 /** Max's scheduler. There is no `setTimeout` in [js]. */
 declare class Task {
   constructor(fn: () => void, ctx: unknown);
@@ -58,7 +78,7 @@ declare class Task {
  * something has to build that dict, and [js] is the only thing in the patcher
  * that can.
  *
- * VERIFIED in Live (doc/TODO.md - what the spikes found, 1.3): [js] built a maxurl request dict
+ * VERIFIED in Live (doc/MAX-FACTS.md): [js] built a maxurl request dict
  * and read the response dict back. `constructor`, `set`, `clear` and `stringify`
  * all behave as declared. `get`, `parse` and `freepeer` were not exercised.
  */
@@ -101,7 +121,7 @@ declare class File {
  * ASYNCHRONOUS: framecount() right after it still reads the old size. Come back
  * on a Task.
  *
- * VERIFIED in Live (doc/TODO.md - what the spikes found, 1.2): an empty buffer~ went to 124439
+ * VERIFIED in Live (doc/MAX-FACTS.md): an empty buffer~ went to 124439
  * frames, 1 channel, midsample -0.0319 after `send("replace", "jongly.aif")`.
  * `send`, `framecount`, `channelcount` and `peek` are all real and behave as
  * declared. `poke` is the one member here still taken on faith from the docs.
@@ -183,6 +203,17 @@ declare const EXTRA_PAYLOAD_B64: string[][] | undefined;
  */
 declare const WATCH_SPECS: { key: string; path: string; property: string }[] | undefined;
 
+/**
+ * Injected by @m4l-jweb/build for every window declared with `site:` - window id
+ * -> the path of its index.html RELATIVE to the device folder.
+ *
+ * Such a window's content is a whole prebuilt site, far too big to ride inside
+ * wrapper.js as base64, so it ships as a folder next to the .amxd instead. That
+ * is the one case where a device is not self-contained: the folder must travel
+ * with the .amxd, and the wrapper says so if it does not.
+ */
+declare const SITE_WINDOWS: { [id: string]: string } | undefined;
+
 /*
  * Device hooks.
  *