@m4l-jweb/wrapper 0.6.0 → 0.6.5

package/package.json

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

package/src/core.ts

@@ -76,15 +76,48 @@ function reload(): void {
  */
 function anything(): void {}
 
+/* ------------------------------------------------------------------ *
+ * Who to answer
+ *
+ * A reply normally goes out outlet 0, to the device's OWN [jweb]. But a floating
+ * window's [jweb] lives inside a subpatcher, so there is no cord to it - the
+ * wrapper reaches it BY NAME, through its [r window-read-<id>] (see loadWindows).
+ *
+ * So a handler must not hard-code outlet(0): when it is answering a WINDOW it has
+ * to route to that window's receiver instead. `window()` below sets replyWindow
+ * for the duration of a window message's dispatch, and reply() honours it - so the
+ * same get_state()/ui_ready() serve the device view AND any window, unchanged.
+ * ------------------------------------------------------------------ */
+
+/** The window a reply should go to, or null for the device's own [jweb] (outlet 0). */
+var replyWindow: string | null = null;
+
+/**
+ * outlet(0, selector, value) that follows replyWindow - to a window's
+ * [r window-read-<id>] when one is set, to the device's own [jweb] otherwise.
+ *
+ * It takes a FIXED (selector, value) rather than a rest arg, and that is
+ * deliberate: `outlet` and `messnamed` are Max HOST functions, and calling
+ * `.apply` on them is not reliable across Max builds - when it fails it fails
+ * SILENTLY, and an exception here takes the whole ui_ready handshake (mode, build,
+ * the state resend) down with it, with no symptom but a device that never fills in
+ * its header. Every reply the wrapper sends is one selector and one value, so this
+ * is all it ever needs.
+ */
+function reply(selector: string, value: unknown): void {
+  if (replyWindow !== null) messnamed("window-read-" + replyWindow, selector, value);
+  else outlet(0, selector, value);
+}
+
 /**
  * The UI announces it finished loading. The page loads asynchronously, so never
  * assume it was listening when state last changed - resend all of it.
  */
 function ui_ready(): void {
-  outlet(0, "mode", MODE);
+  reply("mode", MODE);
   // The UI shows this next to its own baked-in version: a mismatch means a
   // mixed install (stale .amxd instance vs newer extracted UI, or vice versa).
-  outlet(0, "build", buildStamp());
+  reply("build", buildStamp());
   sendCurrentTempo(); // liveapi.ts
   // The device resends its own state here. The page loads asynchronously, so
   // anything sent before it was listening is simply gone.
@@ -119,7 +152,7 @@ function get_state(id: string): void {
     // hands back is what came out of the set. An empty "{}" here after a reopen means
     // the [pattr] did not save - which is a failure with no other symptom.
     post("m4l-jweb: get_state " + id + " -> " + json + "\n");
-    outlet(0, "state_" + id, json);
+    reply("state_" + id, json);
   } catch (e) {
     post("m4l-jweb: get_state error for " + id + " - " + (e as Error).message + "\n");
   }
@@ -146,11 +179,66 @@ function sync_state(id: string): void {
     // bound to nothing), both look exactly like a successful write from here. What the
     // dict says it holds is the only evidence.
     post("m4l-jweb: sync_state " + id + " <- " + json + " (dict now " + d.stringify() + ")\n");
+    // BROADCAST the new value to every OTHER view - the device UI and any other
+    // window - so a live edit in one page appears in the rest at once. Without this
+    // a second page only sees a slot when it next asks for it (on load), which is
+    // why an edit in the floating window never reached the device view. The WRITER
+    // is skipped: it already applied the value optimistically, and echoing it back
+    // could revert the control mid-typing (stateStore has no echo guard).
+    broadcastState(id, d.stringify());
   } catch (e) {
     post("m4l-jweb: sync_state error for " + id + " - " + (e as Error).message + "\n");
   }
 }
 
+/**
+ * Push `state_<id> <json>` to every view except the one that wrote it (replyWindow:
+ * a window id, or null for the device view). A window is reached by name, the
+ * device view by outlet 0 - the same two paths reply() chooses between.
+ */
+function broadcastState(id: string, json: string): void {
+  if (replyWindow !== null) outlet(0, "state_" + id, json); // device view, unless it wrote
+  var ids = listWindowIds();
+  for (var i = 0; i < ids.length; i++) {
+    if (ids[i] !== replyWindow) messnamed("window-read-" + ids[i], "state_" + id, json);
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Floating-window messages
+ *
+ * A window's page uses the ORDINARY bridge (`outlet(sel, ...)`), so it emits bare
+ * selectors just like the device view. They cannot arrive here bare, though: this
+ * [js] already has a get_state/ui_ready/etc, and a window's must not be mistaken
+ * for the device view's. So the subpatcher TAGS them - `[prepend window <id>]` on
+ * the window's [jweb] outlet (see applyWindows in surface.mjs) - and they land
+ * here as `window <id> <selector> <args...>`, dispatched on the first word.
+ *
+ * We then dispatch the INNER selector through the very same handlers, with
+ * replyWindow set so any reply routes back to the window and not the device view.
+ * That is what gives a window access to the device's state: `get_state`/
+ * `sync_state` reach the shared [dict], and `state_<id>` comes back to the window.
+ * Anything the library does not know goes to the device's own onWindowMessage().
+ * ------------------------------------------------------------------ */
+
+function window(id: string): void {
+  var selector = String(arguments[1]);
+  var args: unknown[] = [];
+  for (var i = 2; i < arguments.length; i++) args.push(arguments[i]);
+
+  var prev = replyWindow;
+  replyWindow = id;
+  try {
+    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);
+    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 {
+    replyWindow = prev;
+  }
+}
+
 /* ------------------------------------------------------------------ *
  * The self-extracting UI payload
  *
@@ -179,29 +267,44 @@ function loadWebview(): void {
  *
  * A window's [jweb] lives inside a subpatcher, so there is no cord from this
  * [js] to it. `messnamed` reaches the [r window-read-<id>] the build put next to
- * it - naming the receiver instead of the cord.
- *
- * The window payloads are the extra payloads whose name is `<device>_<id>.html`
- * (packageDevices names them; the device's own UI is UI_PAYLOAD and is not in
- * this list). Strip that prefix EXPLICITLY: a regex like /^.*_/ is greedy, so a
- * window id with an underscore in it - `edit_grid` - would arrive as `grid`, and
- * the page would then load into a receiver nobody is listening on.
+ * it - naming the receiver instead of the cord. The ids come from listWindowIds().
  */
 function loadWindows(): void {
-  if (typeof EXTRA_PAYLOAD_NAMES === "undefined") return;
   var folder = deviceFolder();
   if (!folder) return;
 
-  var prefix = typeof UI_PAYLOAD_NAME !== "undefined" ? UI_PAYLOAD_NAME.replace(/\.html$/, "") + "_" : "";
+  var ids = listWindowIds();
+  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");
+  }
+}
+
+/** The `<device>_` prefix a window payload's name carries, so the device's own UI is not one. */
+function windowPrefix(): string {
+  return typeof UI_PAYLOAD_NAME !== "undefined" ? UI_PAYLOAD_NAME.replace(/\.html$/, "") + "_" : "";
+}
+
+/**
+ * The id of every floating window this device has, from its extracted payloads.
+ *
+ * Strip the `<device>_` prefix EXPLICITLY: a regex like /^.*_/ is greedy, so a
+ * window id with an underscore in it - `edit_grid` - would come back as `grid`.
+ */
+function listWindowIds(): string[] {
+  var ids: string[] = [];
+  if (typeof EXTRA_PAYLOAD_NAMES === "undefined") return ids;
+  var prefix = windowPrefix();
   for (var i = 0; i < EXTRA_PAYLOAD_NAMES.length; i++) {
     var name = EXTRA_PAYLOAD_NAMES[i];
     if (name.slice(-5) !== ".html") continue; // a sample, a preset, ...: not a window
     if (prefix && name.slice(0, prefix.length) !== prefix) continue;
-    var winId = name.slice(prefix.length, name.length - 5);
-    var winUrl = encodeURI("file:///" + folder + "/" + name) + "?v=" + encodeURIComponent(buildStamp());
-    messnamed("window-read-" + winId, "url", winUrl);
-    post("m4l-jweb: window " + winId + " -> " + winUrl + "\n");
+    ids.push(name.slice(prefix.length, name.length - 5));
   }
+  return ids;
 }
 
 function resolveUiUrl(): string | null {

package/src/max.d.ts

@@ -187,3 +187,12 @@ declare function onMaxurlReply(responseDictName: string): boolean;
 
 /** Live's tempo changed (and once on attach). */
 declare function onTempoChange(bpm: number): void;
+
+/**
+ * A floating window's page sent a selector the library does not handle itself
+ * (i.e. not ui_ready/get_state/sync_state). `windowId` is which window; reply with
+ * `outlet(0, ...)` and it routes back to that window automatically (see reply() in
+ * core.ts). This is how a window editor - a drum map, a browser - talks to the
+ * device beyond shared state.
+ */
+declare function onWindowMessage(windowId: string, selector: string, ...args: unknown[]): void;