@m4l-jweb/wrapper 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Lopez (alienmind)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/wrapper",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "m4l-jweb: the Max for Live glue layer connecting a device to LiveAPI.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,7 @@
   },
   "files": [
     "src",
-    "sources.mjs"
+    "sources.mjs",
+    "LICENSE"
   ]
 }

package/src/core.ts

@@ -28,7 +28,7 @@ post("m4l-jweb: wrapper loaded (build " + buildStamp() + ", mode " + MODE + ")\n
 
 /** The build this device instance actually is. Injected by the build. */
 function buildStamp(): string {
-	return typeof BUILD_STAMP !== "undefined" ? BUILD_STAMP : "dev";
+  return typeof BUILD_STAMP !== "undefined" ? BUILD_STAMP : "dev";
 }
 
 /* ------------------------------------------------------------------ *
@@ -45,28 +45,28 @@ function buildStamp(): string {
 
 /** live.thisdevice -> the device is fully loaded. Everything LiveAPI starts here. */
 function bang(): void {
-	post("m4l-jweb: bang (device ready)\n");
-	extractExtraPayloads();
-	loadWebview();
-	setupTempoObserver(); // liveapi.ts
-	startTickPoll(); // liveapi.ts
-	// 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();
+  post("m4l-jweb: bang (device ready)\n");
+  extractExtraPayloads();
+  loadWebview();
+  setupTempoObserver(); // liveapi.ts
+  startTickPoll(); // liveapi.ts
+  // 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();
 }
 
 /** Patcher loaded. File work is safe here; LiveAPI is NOT. */
 function loadbang(): void {
-	post("m4l-jweb: loadbang\n");
-	extractExtraPayloads();
-	loadWebview();
+  post("m4l-jweb: loadbang\n");
+  extractExtraPayloads();
+  loadWebview();
 }
 
 /** Manual re-init, handy while developing. */
 function reload(): void {
-	loadWebview();
-	setupTempoObserver();
-	startTickPoll();
+  loadWebview();
+  setupTempoObserver();
+  startTickPoll();
 }
 
 /**
@@ -81,14 +81,14 @@ function anything(): void {}
  * assume it was listening when state last changed - resend all of it.
  */
 function ui_ready(): void {
-	outlet(0, "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());
-	sendCurrentTempo(); // liveapi.ts
-	// 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();
+  outlet(0, "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());
+  sendCurrentTempo(); // liveapi.ts
+  // 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();
 }
 
 /* ------------------------------------------------------------------ *
@@ -102,39 +102,39 @@ function ui_ready(): void {
  * ------------------------------------------------------------------ */
 
 function loadWebview(): void {
-	try {
-		var url = resolveUiUrl();
-		if (!url) return;
-		outlet(0, "url", url);
-		post("m4l-jweb: sent url " + url + "\n");
-	} catch (e) {
-		post("m4l-jweb: loadWebview error " + (e as Error).message + "\n");
-	}
+  try {
+    var url = resolveUiUrl();
+    if (!url) return;
+    outlet(0, "url", url);
+    post("m4l-jweb: sent url " + url + "\n");
+  } catch (e) {
+    post("m4l-jweb: loadWebview error " + (e as Error).message + "\n");
+  }
 }
 
 function resolveUiUrl(): string | null {
-	var folder = deviceFolder();
-	if (!folder) {
-		post("m4l-jweb: patcher not saved yet - UI path unknown\n");
-		return null;
-	}
-	var name = typeof UI_PAYLOAD_NAME !== "undefined" ? UI_PAYLOAD_NAME : "ui.html";
-	var target = folder + "/" + name;
+  var folder = deviceFolder();
+  if (!folder) {
+    post("m4l-jweb: patcher not saved yet - UI path unknown\n");
+    return null;
+  }
+  var name = typeof UI_PAYLOAD_NAME !== "undefined" ? UI_PAYLOAD_NAME : "ui.html";
+  var target = folder + "/" + name;
 
-	if (typeof UI_PAYLOAD_B64 !== "undefined" && typeof UI_PAYLOAD_BYTES !== "undefined") {
-		extractPayload(target, UI_PAYLOAD_B64, UI_PAYLOAD_BYTES);
-	} else {
-		post("m4l-jweb: no embedded payload (dev build) - using " + target + "\n");
-	}
-	// Cache-buster: the URL changes per build, so Chromium can never serve a page
-	// it cached from a previous build of the same file path.
-	return encodeURI("file:///" + target) + "?v=" + encodeURIComponent(buildStamp());
+  if (typeof UI_PAYLOAD_B64 !== "undefined" && typeof UI_PAYLOAD_BYTES !== "undefined") {
+    extractPayload(target, UI_PAYLOAD_B64, UI_PAYLOAD_BYTES);
+  } else {
+    post("m4l-jweb: no embedded payload (dev build) - using " + target + "\n");
+  }
+  // Cache-buster: the URL changes per build, so Chromium can never serve a page
+  // it cached from a previous build of the same file path.
+  return encodeURI("file:///" + target) + "?v=" + encodeURIComponent(buildStamp());
 }
 
 /** The folder the .amxd lives in, derived from the patcher's own path. */
 function deviceFolder(): string | null {
-	var fp: string = this.patcher.filepath;
-	return fp && fp.length ? fp.replace(/\/[^\/]*$/, "") : null;
+  var fp: string = this.patcher.filepath;
+  return fp && fp.length ? fp.replace(/\/[^\/]*$/, "") : null;
 }
 
 /**
@@ -146,23 +146,23 @@ function deviceFolder(): string | null {
  * size and build stamp already match.
  */
 function extractExtraPayloads(): void {
-	// The build emits all three together or none at all; bind them locally so the
-	// compiler can see that too.
-	if (typeof EXTRA_PAYLOAD_NAMES === "undefined" || typeof EXTRA_PAYLOAD_B64 === "undefined" || typeof EXTRA_PAYLOAD_BYTES === "undefined") {
-		return;
-	}
-	var names = EXTRA_PAYLOAD_NAMES;
-	var blobs = EXTRA_PAYLOAD_B64;
-	var sizes = EXTRA_PAYLOAD_BYTES;
+  // The build emits all three together or none at all; bind them locally so the
+  // compiler can see that too.
+  if (typeof EXTRA_PAYLOAD_NAMES === "undefined" || typeof EXTRA_PAYLOAD_B64 === "undefined" || typeof EXTRA_PAYLOAD_BYTES === "undefined") {
+    return;
+  }
+  var names = EXTRA_PAYLOAD_NAMES;
+  var blobs = EXTRA_PAYLOAD_B64;
+  var sizes = EXTRA_PAYLOAD_BYTES;
 
-	var folder = deviceFolder();
-	if (!folder) {
-		post("m4l-jweb: patcher path unknown - cannot extract payloads\n");
-		return;
-	}
-	for (var i = 0; i < names.length; i++) {
-		extractPayload(folder + "/" + names[i], blobs[i], sizes[i]);
-	}
+  var folder = deviceFolder();
+  if (!folder) {
+    post("m4l-jweb: patcher path unknown - cannot extract payloads\n");
+    return;
+  }
+  for (var i = 0; i < names.length; i++) {
+    extractPayload(folder + "/" + names[i], blobs[i], sizes[i]);
+  }
 }
 
 /**
@@ -173,72 +173,72 @@ function extractExtraPayloads(): void {
  * and leave a stale file that no longer matches the wrapper driving it.
  */
 function extractPayload(targetPath: string, b64chunks: string[], byteCount: number): void {
-	try {
-		var existing = new File(targetPath);
-		if (existing.isopen) {
-			var sameSize = existing.eof === byteCount;
-			existing.close();
-			if (sameSize && readTextFile(targetPath + ".stamp") === buildStamp()) return;
-		}
-	} catch (e) {
-		/* fall through and (re)write */
-	}
-	try {
-		var out = new File(targetPath, "write");
-		if (!out.isopen) out.open();
-		if (!out.isopen) {
-			post("m4l-jweb: cannot write " + targetPath + "\n");
-			return;
-		}
-		out.eof = 0;
-		// File.writebytes silently truncates large calls (observed ~16 KB cap), so
-		// write in small slices and verify the byte count afterwards.
-		var SLICE = 4096;
-		for (var i = 0; i < b64chunks.length; i++) {
-			var bytes = b64decode(b64chunks[i]);
-			for (var off = 0; off < bytes.length; off += SLICE) {
-				out.writebytes(bytes.slice(off, off + SLICE));
-			}
-		}
-		out.close();
+  try {
+    var existing = new File(targetPath);
+    if (existing.isopen) {
+      var sameSize = existing.eof === byteCount;
+      existing.close();
+      if (sameSize && readTextFile(targetPath + ".stamp") === buildStamp()) return;
+    }
+  } catch (e) {
+    /* fall through and (re)write */
+  }
+  try {
+    var out = new File(targetPath, "write");
+    if (!out.isopen) out.open();
+    if (!out.isopen) {
+      post("m4l-jweb: cannot write " + targetPath + "\n");
+      return;
+    }
+    out.eof = 0;
+    // File.writebytes silently truncates large calls (observed ~16 KB cap), so
+    // write in small slices and verify the byte count afterwards.
+    var SLICE = 4096;
+    for (var i = 0; i < b64chunks.length; i++) {
+      var bytes = b64decode(b64chunks[i]);
+      for (var off = 0; off < bytes.length; off += SLICE) {
+        out.writebytes(bytes.slice(off, off + SLICE));
+      }
+    }
+    out.close();
 
-		var check = new File(targetPath);
-		var written = check.isopen ? check.eof : -1;
-		if (check.isopen) check.close();
-		if (written === byteCount) {
-			post("m4l-jweb: extracted " + written + " bytes to " + targetPath + "\n");
-			writeTextFile(targetPath + ".stamp", buildStamp());
-		} else {
-			post("m4l-jweb: extract SIZE MISMATCH - wrote " + written + ", expected " + byteCount + "\n");
-		}
-	} catch (e2) {
-		post("m4l-jweb: extract failed - " + (e2 as Error).message + "\n");
-	}
+    var check = new File(targetPath);
+    var written = check.isopen ? check.eof : -1;
+    if (check.isopen) check.close();
+    if (written === byteCount) {
+      post("m4l-jweb: extracted " + written + " bytes to " + targetPath + "\n");
+      writeTextFile(targetPath + ".stamp", buildStamp());
+    } else {
+      post("m4l-jweb: extract SIZE MISMATCH - wrote " + written + ", expected " + byteCount + "\n");
+    }
+  } catch (e2) {
+    post("m4l-jweb: extract failed - " + (e2 as Error).message + "\n");
+  }
 }
 
 function readTextFile(p: string): string | null {
-	try {
-		var f = new File(p);
-		if (!f.isopen) return null;
-		var s = f.readstring(Math.min(f.eof, 256));
-		f.close();
-		return s;
-	} catch (e) {
-		return null;
-	}
+  try {
+    var f = new File(p);
+    if (!f.isopen) return null;
+    var s = f.readstring(Math.min(f.eof, 256));
+    f.close();
+    return s;
+  } catch (e) {
+    return null;
+  }
 }
 
 function writeTextFile(p: string, s: string): void {
-	try {
-		var f = new File(p, "write");
-		if (!f.isopen) f.open();
-		if (!f.isopen) return;
-		f.eof = 0;
-		f.writestring(s);
-		f.close();
-	} catch (e) {
-		/* non-fatal */
-	}
+  try {
+    var f = new File(p, "write");
+    if (!f.isopen) f.open();
+    if (!f.isopen) return;
+    f.eof = 0;
+    f.writestring(s);
+    f.close();
+  } catch (e) {
+    /* non-fatal */
+  }
 }
 
 var B64CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -246,22 +246,22 @@ var b64lookup: { [c: string]: number } | null = null;
 
 /** Base64 -> array of byte values. Max's [js] has no atob. */
 function b64decode(s: string): number[] {
-	if (!b64lookup) {
-		b64lookup = {};
-		for (var i = 0; i < B64CHARS.length; i++) b64lookup[B64CHARS.charAt(i)] = i;
-	}
-	var out: number[] = [];
-	var buffer = 0;
-	var bits = 0;
-	for (var j = 0; j < s.length; j++) {
-		var c = s.charAt(j);
-		if (c === "=") break;
-		buffer = (buffer << 6) | b64lookup[c];
-		bits += 6;
-		if (bits >= 8) {
-			bits -= 8;
-			out.push((buffer >> bits) & 0xff);
-		}
-	}
-	return out;
+  if (!b64lookup) {
+    b64lookup = {};
+    for (var i = 0; i < B64CHARS.length; i++) b64lookup[B64CHARS.charAt(i)] = i;
+  }
+  var out: number[] = [];
+  var buffer = 0;
+  var bits = 0;
+  for (var j = 0; j < s.length; j++) {
+    var c = s.charAt(j);
+    if (c === "=") break;
+    buffer = (buffer << 6) | b64lookup[c];
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buffer >> bits) & 0xff);
+    }
+  }
+  return out;
 }

package/src/liveapi.ts

@@ -23,30 +23,30 @@ var tickPoll = new Task(pollTransport, this);
 var liveSetApi: LiveAPI | null = null;
 
 function startTickPoll(): void {
-	try {
-		liveSetApi = new LiveAPI("live_set");
-	} catch (e) {
-		post("m4l-jweb: tick poll unavailable - " + (e as Error).message + "\n");
-		return;
-	}
-	tickPoll.cancel();
-	tickPoll.interval = 50;
-	tickPoll.repeat();
-	post("m4l-jweb: transport poll on\n");
+  try {
+    liveSetApi = new LiveAPI("live_set");
+  } catch (e) {
+    post("m4l-jweb: tick poll unavailable - " + (e as Error).message + "\n");
+    return;
+  }
+  tickPoll.cancel();
+  tickPoll.interval = 50;
+  tickPoll.repeat();
+  post("m4l-jweb: transport poll on\n");
 }
 
 function pollTransport(): void {
-	if (!liveSetApi) return;
-	try {
-		var playing = parseInt(String(liveSetApi.get("is_playing")), 10);
-		var beats = parseFloat(String(liveSetApi.get("current_song_time")));
-		outlet(0, "tick", playing, beats);
-		// A device with a second consumer (another engine on outlet 1) mirrors the
-		// clock here rather than polling Live twice.
-		if (typeof onTick === "function") onTick(playing, beats);
-	} catch (e) {
-		/* transient - the next poll retries */
-	}
+  if (!liveSetApi) return;
+  try {
+    var playing = parseInt(String(liveSetApi.get("is_playing")), 10);
+    var beats = parseFloat(String(liveSetApi.get("current_song_time")));
+    outlet(0, "tick", playing, beats);
+    // A device with a second consumer (another engine on outlet 1) mirrors the
+    // clock here rather than polling Live twice.
+    if (typeof onTick === "function") onTick(playing, beats);
+  } catch (e) {
+    /* transient - the next poll retries */
+  }
 }
 
 /* ------------------------------------------------------------------ *
@@ -59,36 +59,36 @@ function pollTransport(): void {
 var tempoObs: LiveAPI | null = null;
 
 function setupTempoObserver(): void {
-	// Recreate unconditionally: an object left over from a loading context is
-	// dead and must not block the real one.
-	try {
-		tempoObs = new LiveAPI(onTempo, "live_set");
-		tempoObs.property = "tempo";
-		post("m4l-jweb: tempo observer on (current " + tempoObs.get("tempo") + ")\n");
-	} catch (e) {
-		post("m4l-jweb: tempo observer unavailable - " + (e as Error).message + "\n");
-	}
+  // Recreate unconditionally: an object left over from a loading context is
+  // dead and must not block the real one.
+  try {
+    tempoObs = new LiveAPI(onTempo, "live_set");
+    tempoObs.property = "tempo";
+    post("m4l-jweb: tempo observer on (current " + tempoObs.get("tempo") + ")\n");
+  } catch (e) {
+    post("m4l-jweb: tempo observer unavailable - " + (e as Error).message + "\n");
+  }
 }
 
 function onTempo(a: unknown[]): void {
-	if (a && a[0] == "tempo") {
-		outlet(0, "tempo", a[1]);
-		if (typeof onTempoChange === "function") onTempoChange(Number(a[1]));
-	}
+  if (a && a[0] == "tempo") {
+    outlet(0, "tempo", a[1]);
+    if (typeof onTempoChange === "function") onTempoChange(Number(a[1]));
+  }
 }
 
 /** The observer's first callback can beat the page's binding - ui_ready re-reads. */
 function sendCurrentTempo(): void {
-	try {
-		var api = new LiveAPI("live_set");
-		var t = parseFloat(String(api.get("tempo")));
-		if (t > 0) {
-			outlet(0, "tempo", t);
-			if (typeof onTempoChange === "function") onTempoChange(t);
-		}
-	} catch (e) {
-		post("m4l-jweb: tempo read failed - " + (e as Error).message + "\n");
-	}
+  try {
+    var api = new LiveAPI("live_set");
+    var t = parseFloat(String(api.get("tempo")));
+    if (t > 0) {
+      outlet(0, "tempo", t);
+      if (typeof onTempoChange === "function") onTempoChange(t);
+    }
+  } catch (e) {
+    post("m4l-jweb: tempo read failed - " + (e as Error).message + "\n");
+  }
 }
 
 /* ------------------------------------------------------------------ *
@@ -105,20 +105,20 @@ function sendCurrentTempo(): void {
  * alive; drop it and the observer dies with it.
  */
 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);
-			}
-		}, objectPath);
-		api.property = property;
-		return api;
-	} catch (e) {
-		post("m4l-jweb: cannot observe " + objectPath + " " + property + " - " + (e as Error).message + "\n");
-		return 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);
+      }
+    }, objectPath);
+    api.property = property;
+    return api;
+  } catch (e) {
+    post("m4l-jweb: cannot observe " + objectPath + " " + property + " - " + (e as Error).message + "\n");
+    return null;
+  }
 }
 
 /* ------------------------------------------------------------------ *
@@ -126,16 +126,16 @@ function observeProperty(objectPath: string, property: string, selector: string)
  * ------------------------------------------------------------------ */
 
 interface LiveNote {
-	pitch: number;
-	start_time: number;
-	duration: number;
-	velocity: number;
-	mute?: number;
+  pitch: number;
+  start_time: number;
+  duration: number;
+  velocity: number;
+  mute?: number;
 }
 
 /** The LiveAPI for the track this device sits on. */
 function ownTrack(): LiveAPI {
-	return new LiveAPI("this_device canonical_parent");
+  return new LiveAPI("this_device canonical_parent");
 }
 
 /**
@@ -143,52 +143,52 @@ function ownTrack(): LiveAPI {
  * Creates a clip in the first empty slot on this device's track and fills it.
  */
 function write_clip(): void {
-	var a = arrayfromargs(arguments);
-	if (a.length < 2) return;
-	var lengthBeats = a[0];
-	var n = Number(a[1]);
-
-	var slot = firstEmptySlot();
-	if (!slot) {
-		post("m4l-jweb: no empty clip slot on this track\n");
-		return;
-	}
-	slot.call("create_clip", lengthBeats);
-	var clip = new LiveAPI(slot.unquotedpath + " clip");
-
-	var notes: LiveNote[] = [];
-	for (var k = 0; k < n; k++) {
-		var o = 2 + k * 4;
-		notes.push({
-			pitch: Number(a[o]),
-			start_time: Number(a[o + 1]),
-			duration: Number(a[o + 2]),
-			velocity: Number(a[o + 3]),
-			mute: 0,
-		});
-	}
-	try {
-		clip.call("add_new_notes", { notes: notes });
-	} catch (e) {
-		post("m4l-jweb: add_new_notes failed - " + (e as Error).message + "\n");
-		return;
-	}
-	post("m4l-jweb: wrote " + n + " notes over " + lengthBeats + " beats\n");
+  var a = arrayfromargs(arguments);
+  if (a.length < 2) return;
+  var lengthBeats = a[0];
+  var n = Number(a[1]);
+
+  var slot = firstEmptySlot();
+  if (!slot) {
+    post("m4l-jweb: no empty clip slot on this track\n");
+    return;
+  }
+  slot.call("create_clip", lengthBeats);
+  var clip = new LiveAPI(slot.unquotedpath + " clip");
+
+  var notes: LiveNote[] = [];
+  for (var k = 0; k < n; k++) {
+    var o = 2 + k * 4;
+    notes.push({
+      pitch: Number(a[o]),
+      start_time: Number(a[o + 1]),
+      duration: Number(a[o + 2]),
+      velocity: Number(a[o + 3]),
+      mute: 0,
+    });
+  }
+  try {
+    clip.call("add_new_notes", { notes: notes });
+  } catch (e) {
+    post("m4l-jweb: add_new_notes failed - " + (e as Error).message + "\n");
+    return;
+  }
+  post("m4l-jweb: wrote " + n + " notes over " + lengthBeats + " beats\n");
 }
 
 function firstEmptySlot(): LiveAPI | null {
-	try {
-		var track = ownTrack();
-		var count = parseInt(String(track.getcount("clip_slots")), 10);
-		for (var i = 0; i < count; i++) {
-			var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
-			if (parseInt(String(s.get("has_clip")), 10) === 0) return s;
-		}
-		return null;
-	} catch (e) {
-		post("m4l-jweb: firstEmptySlot error " + (e as Error).message + "\n");
-		return null;
-	}
+  try {
+    var track = ownTrack();
+    var count = parseInt(String(track.getcount("clip_slots")), 10);
+    for (var i = 0; i < count; i++) {
+      var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
+      if (parseInt(String(s.get("has_clip")), 10) === 0) return s;
+    }
+    return null;
+  } catch (e) {
+    post("m4l-jweb: firstEmptySlot error " + (e as Error).message + "\n");
+    return null;
+  }
 }
 
 /**
@@ -197,54 +197,54 @@ function firstEmptySlot(): LiveAPI | null {
  * "notes <loopEnd> <n> <pitch start duration> ...".
  */
 function read_notes(): void {
-	var clip = pickClip();
-	if (!clip) {
-		post("m4l-jweb: no clip found on this track\n");
-		outlet(0, "read_error", "no_clip");
-		return;
-	}
-	var loopEnd = parseFloat(String(clip.get("loop_end")));
-	var notes = getNotes(clip, loopEnd);
-	if (!notes) return;
-
-	var out: unknown[] = ["notes", loopEnd, notes.length];
-	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));
-	post("m4l-jweb: read " + notes.length + " notes (loop_end " + loopEnd + ")\n");
+  var clip = pickClip();
+  if (!clip) {
+    post("m4l-jweb: no clip found on this track\n");
+    outlet(0, "read_error", "no_clip");
+    return;
+  }
+  var loopEnd = parseFloat(String(clip.get("loop_end")));
+  var notes = getNotes(clip, loopEnd);
+  if (!notes) return;
+
+  var out: unknown[] = ["notes", loopEnd, notes.length];
+  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));
+  post("m4l-jweb: read " + notes.length + " notes (loop_end " + loopEnd + ")\n");
 }
 
 function pickClip(): LiveAPI | null {
-	try {
-		var track = ownTrack();
-		var count = parseInt(String(track.getcount("clip_slots")), 10);
-		var firstWithClip: LiveAPI | null = null;
-		for (var i = 0; i < count; i++) {
-			var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
-			if (parseInt(String(s.get("has_clip")), 10) === 1) {
-				var c = new LiveAPI(s.unquotedpath + " clip");
-				if (parseInt(String(c.get("is_playing")), 10) === 1) return c;
-				if (!firstWithClip) firstWithClip = c;
-			}
-		}
-		return firstWithClip;
-	} catch (e) {
-		post("m4l-jweb: pickClip error " + (e as Error).message + "\n");
-		return null;
-	}
+  try {
+    var track = ownTrack();
+    var count = parseInt(String(track.getcount("clip_slots")), 10);
+    var firstWithClip: LiveAPI | null = null;
+    for (var i = 0; i < count; i++) {
+      var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
+      if (parseInt(String(s.get("has_clip")), 10) === 1) {
+        var c = new LiveAPI(s.unquotedpath + " clip");
+        if (parseInt(String(c.get("is_playing")), 10) === 1) return c;
+        if (!firstWithClip) firstWithClip = c;
+      }
+    }
+    return firstWithClip;
+  } catch (e) {
+    post("m4l-jweb: pickClip error " + (e as Error).message + "\n");
+    return null;
+  }
 }
 
 function getNotes(clip: LiveAPI, loopEnd: number): LiveNote[] | null {
-	// Live 11+: get_notes_extended returns a JSON string.
-	try {
-		var d = clip.call("get_notes_extended", 0, 128, 0, loopEnd);
-		var obj = typeof d === "string" ? JSON.parse(d) : d;
-		if (obj && obj.notes) return obj.notes;
-	} catch (e) {
-		post("m4l-jweb: get_notes_extended failed - " + (e as Error).message + "\n");
-	}
-	return null;
+  // Live 11+: get_notes_extended returns a JSON string.
+  try {
+    var d = clip.call("get_notes_extended", 0, 128, 0, loopEnd);
+    var obj = typeof d === "string" ? JSON.parse(d) : d;
+    if (obj && obj.notes) return obj.notes;
+  } catch (e) {
+    post("m4l-jweb: get_notes_extended failed - " + (e as Error).message + "\n");
+  }
+  return null;
 }

package/src/max.d.ts

@@ -32,34 +32,99 @@ declare let outlets: number;
 
 /** Max's scheduler. There is no `setTimeout` in [js]. */
 declare class Task {
-	constructor(fn: () => void, ctx: unknown);
-	interval: number;
-	repeat(count?: number): void;
-	schedule(delayMs?: number): void;
-	cancel(): void;
+  constructor(fn: () => void, ctx: unknown);
+  interval: number;
+  repeat(count?: number): void;
+  schedule(delayMs?: number): void;
+  cancel(): void;
+}
+
+/**
+ * A named Max dictionary, addressed from [js].
+ *
+ * The reason this exists here at all is [maxurl]: downloading to a FILE is not
+ * expressible as a flat Max message. Per the reference, the file form is a
+ * `dictionary <name>` message carrying a dict with a `filename_out` key - so
+ * something has to build that dict, and [js] is the only thing in the patcher
+ * that can.
+ *
+ * VERIFIED in Live (doc/SPIKES.md spike 1.3): [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.
+ */
+declare class Dict {
+  constructor(name?: string);
+  name: string;
+  set(key: string, value: unknown): void;
+  /** UNVERIFIED - the spike only ever wrote, and read back via stringify(). */
+  get(key: string): unknown;
+  /** The whole dict as JSON - the cheapest way to see what maxurl replied. */
+  stringify(): string;
+  /** UNVERIFIED. */
+  parse(json: string): void;
+  clear(): void;
+  /** Release the dict's reference. Max dictionaries are refcounted. UNVERIFIED. */
+  freepeer(): void;
 }
 
 /** Max's file object. Note: `writebytes` truncates silently past ~16 KB. */
 declare class File {
-	constructor(path: string, mode?: "read" | "write" | "readwrite");
-	isopen: boolean;
-	eof: number;
-	open(): void;
-	close(): void;
-	readstring(count: number): string;
-	writestring(s: string): void;
-	writebytes(bytes: number[]): void;
+  constructor(path: string, mode?: "read" | "write" | "readwrite");
+  isopen: boolean;
+  eof: number;
+  open(): void;
+  close(): void;
+  readstring(count: number): string;
+  writestring(s: string): void;
+  writebytes(bytes: number[]): void;
+}
+
+/**
+ * A named [buffer~] in the patcher, addressed from [js].
+ *
+ * This is the seam that makes "disk is the audio transport" work: [js] tells a
+ * buffer~ to `replace` a file on disk and MSP plays it from there, so audio
+ * never crosses the Max message bridge (a text-parsed protocol) as data.
+ *
+ * The buffer~ must ALREADY EXIST in the patcher under this name - `new Buffer`
+ * binds to one, it does not create one. And `send("replace", path)` is
+ * ASYNCHRONOUS: framecount() right after it still reads the old size. Come back
+ * on a Task.
+ *
+ * VERIFIED in Live (doc/SPIKES.md spike 1.2): 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.
+ *
+ * `replace` on a file buffer~ cannot decode is a SILENT NO-OP: no error, and the
+ * buffer keeps whatever it held before. So a frame count on its own never means
+ * "the read worked" - it only means something next to what the count was before.
+ *
+ * `replace` also adopts the FILE's channel count, whatever the buffer~ was
+ * declared with (a stereo .wav gave channelcount() === 2 from a buffer~ created
+ * with no arguments). Never assume mono. Ask.
+ */
+declare class Buffer {
+  constructor(name: string);
+  /** Send a message to the buffer~ itself, e.g. `send("replace", "/path/x.wav")`. */
+  send(message: string, ...args: unknown[]): void;
+  framecount(): number;
+  channelcount(): number;
+  /** peek(channel, frameIndex, count) - channels and frames are 1-indexed. */
+  peek(channel: number, index: number, count?: number): number;
+  /** UNVERIFIED - spike 1.2 exercised everything above this, but not poke. */
+  poke(channel: number, index: number, value: number): void;
 }
 
 /** The Live object model. The whole reason [js] still exists in this stack. */
 declare class LiveAPI {
-	constructor(pathOrCallback: string | ((args: unknown[]) => void), path?: string);
-	property: string;
-	unquotedpath: string;
-	get(prop: string): unknown;
-	set(prop: string, value: unknown): void;
-	getcount(child: string): number;
-	call(method: string, ...args: unknown[]): unknown;
+  constructor(pathOrCallback: string | ((args: unknown[]) => void), path?: string);
+  property: string;
+  unquotedpath: string;
+  get(prop: string): unknown;
+  set(prop: string, value: unknown): void;
+  getcount(child: string): number;
+  call(method: string, ...args: unknown[]): unknown;
 }
 
 /** Injected by @m4l-jweb/build: "<version> <iso date>". */