@m4l-jweb/wrapper 1.2.1 → 1.3.1

package/package.json

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

package/src/core.ts

@@ -124,6 +124,8 @@ function ui_ready(): void {
   reply("build", buildStamp());
   sendCurrentTempo(); // liveapi.ts
   resendWatches(); // watch.ts - the current value of every declared watch, for a late page
+  sendDeviceFolder(); // where this device's files land, for a device that declares any
+  sendTrackKind(); // liveapi.ts - audio | midi | none, which decides what clips it can make
   // 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();
@@ -761,6 +763,27 @@ function deviceFolder(): string | null {
   return fp && fp.length ? fp.replace(/\/[^\/]*$/, "") : null;
 }
 
+/**
+ * Tell the page where its files land - the folder half of defineFiles().
+ *
+ * A page cannot know its own device's folder: it is a `file://` document extracted
+ * from the .amxd, and nothing in it names the .amxd. So the wrapper says, at
+ * ui_ready, and it is the SAME resolution the save used - which is what makes the
+ * path the page shows the real one rather than a plausible one.
+ *
+ * It goes out as ONE symbol. A real install has spaces in this path ("Ableton
+ * Library"), and a path travelling as message text would split there into atoms.
+ *
+ * No folder means an UNSAVED patcher, and that is worth a console line rather than
+ * silence: every relative path the device writes then resolves against nowhere.
+ */
+function sendDeviceFolder(): void {
+  if (typeof FILES_SPEC === "undefined" || !FILES_SPEC.tellPage) return;
+  var folder = deviceFolder();
+  if (folder) reply("device_folder", folder);
+  else post("m4l-jweb: patcher is not saved - no device folder, and every relative path resolves against nowhere\n");
+}
+
 /**
  * Write every non-UI payload the build embedded (manifest `payloads`) next to
  * the .amxd. Same reason as the UI: anything that is not a Max-native object is
@@ -966,6 +989,24 @@ function partPath(destPath: string): string {
   return destPath + ".part";
 }
 
+/**
+ * The `file://` SOURCE of an atomic place, for [maxurl]'s request dict.
+ *
+ * PERCENT-ENCODED, and it has to be: libcurl parses this as a URL, and a raw space
+ * is not a URL. Handing it the plain path comes back as
+ *
+ *   error URL using bad/illegal format or missing URL
+ *
+ * which is CURLE_URL_MALFORMAT, measured in Live. Whether maxurl then DECODES what
+ * it parsed is a separate question and an open one - a spaced device folder has also
+ * been seen failing with `Couldn't open file <the encoded path>`, and the conformance
+ * check in `wrapper/device.ts` does the same thing and passes. Do not change the
+ * encoding again without measuring both.
+ */
+function placeUrl(path: string): string {
+  return encodeURI("file:///" + path);
+}
+
 /**
  * Where a SAVE lands before it has earned its destination - and deliberately NOT
  * `<dest>.part`.
@@ -1007,12 +1048,23 @@ var currentFetch: ActiveFetch | null = null;
  * A relative path is resolved against the DEVICE's folder - the one place a
  * device can always write, and the same folder the UI payload is extracted into.
  * An absolute path (POSIX `/...`, or Windows `C:/...`) is passed through.
+ *
+ * NULL when it cannot be resolved, and the caller must then refuse to write. A bare
+ * relative name handed to `[js]`'s `File` is not created in the current directory -
+ * it is created in MAX'S OWN FOLDER, and from that moment the name exists on Max's
+ * search path, so every later `new File(<absolute path>, "write")` for that name
+ * resolves to the stray and writes THERE instead. The file the wrapper then verifies
+ * is the stray (`File` in read mode searches the same path and finds it at the right
+ * size), while `[maxurl]`, which takes the literal path, correctly reports nothing
+ * there. One save from an unsaved patcher poisons that filename permanently, for
+ * every device on the machine. This is the whole of doc/MAX-FACTS.md's stray-file
+ * entry, and it cost weeks.
  */
-function resolveFetchPath(destPath: string): string {
+function resolveFetchPath(destPath: string): string | null {
   var isAbsolute = destPath.indexOf("/") === 0 || destPath.indexOf(":") === 1;
   if (isAbsolute) return destPath;
   var folder = deviceFolder();
-  return folder ? folder + "/" + destPath : destPath;
+  return folder ? folder + "/" + destPath : null;
 }
 
 /** PHASE 1: download the URL to `<dest>.part`. Nothing touches `<dest>` yet. */
@@ -1021,7 +1073,11 @@ function processNextFetch(): void {
   var next = fetchQueue.shift();
   if (!next) return;
   currentFetch = next;
-  next.destPath = resolveFetchPath(next.destPath);
+  var fetchDest = resolveFetchPath(next.destPath);
+  if (fetchDest === null) {
+    return failFetch(next, "the patcher is not saved, so there is no folder to fetch into - save the Live set first");
+  }
+  next.destPath = fetchDest;
 
   var reqDict = new Dict();
   reqDict.set("url", next.url);
@@ -1043,7 +1099,7 @@ function processNextFetch(): void {
  */
 function placeFetch(fetched: ActiveFetch): void {
   var reqDict = new Dict();
-  reqDict.set("url", encodeURI("file:///" + partPath(fetched.destPath)));
+  reqDict.set("url", placeUrl(partPath(fetched.destPath)));
   reqDict.set("http_method", "get");
   reqDict.set("filename_out", fetched.destPath);
   reqDict.set("overwrite_output_file", 1);
@@ -1070,21 +1126,55 @@ interface ActiveSave {
   destPath: string;
   /** Bytes the app promised in save_begin - the size the .part must match. */
   expect: number;
-  /** Bytes actually written so far, for the verify. */
+  /** Bytes actually written, once save_end has written them. */
   written: number;
-  /** The open .part file, held across the chunk messages. */
-  file: File | null;
+  /** The base64 slices as they arrive, held until save_end writes the file. */
+  chunks: string[];
 }
 
 var activeSave: ActiveSave | null = null;
 
-/** The app: `save_begin <requestId> <destPath> <byteCount>` - open the .part file. */
+/**
+ * The app: `save_begin <requestId> <destPath> <byteCount>` - start collecting.
+ *
+ * The bytes are held and written in one go by `save_end`, so the `.part` File is
+ * opened and closed inside a single call. That is a simplification, not a fix: the
+ * bug it was written for turned out to be a stray file on Max's search path (see
+ * `resolveFetchPath`), and streaming across the chunk messages would work too. It
+ * costs about 1.33x the payload in [js] memory until the save completes, which is
+ * worth revisiting for large exports - doc/TODO.md carries it.
+ *
+ * A save with no resolvable folder is REFUSED here rather than written relative,
+ * because writing relative is what creates the stray in the first place.
+ */
 function save_begin(requestId: string, destPath: string, byteCount: number): void {
-  // A save already in flight is abandoned - its .part is left for the next place/overwrite.
-  if (activeSave && activeSave.file && activeSave.file.isopen) activeSave.file.close();
-
   var resolved = resolveFetchPath(destPath);
-  var target = savePartPath(resolved);
+  if (resolved === null) {
+    outlet(0, "save_error", requestId, "the patcher is not saved, so there is no folder to save into - save the Live set first");
+    activeSave = null;
+    return;
+  }
+  // Every step of a save posts what it MEASURED, not what it attempted. A save that
+  // fails at the place step looks identical to one that never wrote a byte, and the
+  // console was the only place that could tell them apart - it could not.
+  post("m4l-jweb: save begin " + savePartPath(resolved) + " (expect " + Number(byteCount) + " bytes)\n");
+  activeSave = { requestId: requestId, destPath: resolved, expect: Number(byteCount), written: 0, chunks: [] };
+}
+
+/** The app: `save_chunk <requestId> <base64>` - hold one slice for save_end. */
+function save_chunk(requestId: string, b64: string): void {
+  if (!activeSave || activeSave.requestId !== requestId) return;
+  activeSave.chunks.push(b64);
+}
+
+/** The app: `save_end <requestId>` - write the whole .part, verify, place atomically. */
+function save_end(requestId: string): void {
+  if (!activeSave || activeSave.requestId !== requestId) return;
+  var save = activeSave;
+  var target = savePartPath(save.destPath);
+
+  // The entire life of this File - open, write, close - happens inside this one call.
+  // See save_begin for what happens when it does not.
   var f: File | null = null;
   try {
     f = new File(target, "write");
@@ -1098,40 +1188,32 @@ function save_begin(requestId: string, destPath: string, byteCount: number): voi
     return;
   }
   f.eof = 0;
-  activeSave = { requestId: requestId, destPath: resolved, expect: Number(byteCount), written: 0, file: f };
-}
-
-/** The app: `save_chunk <requestId> <base64>` - write one slice. */
-function save_chunk(requestId: string, b64: string): void {
-  if (!activeSave || activeSave.requestId !== requestId || !activeSave.file) return;
-  var bytes = b64decode(b64);
   var SLICE = 4096; // File.writebytes truncates large calls (~16 KB cap) - same as extractPayload
-  for (var off = 0; off < bytes.length; off += SLICE) {
-    activeSave.file.writebytes(bytes.slice(off, off + SLICE));
+  for (var c = 0; c < save.chunks.length; c++) {
+    var bytes = b64decode(save.chunks[c]);
+    for (var off = 0; off < bytes.length; off += SLICE) {
+      f.writebytes(bytes.slice(off, off + SLICE));
+    }
+    save.written += bytes.length;
   }
-  activeSave.written += bytes.length;
-}
-
-/** The app: `save_end <requestId>` - close, verify size, place atomically. */
-function save_end(requestId: string): void {
-  if (!activeSave || activeSave.requestId !== requestId) return;
-  var save = activeSave;
-  if (save.file && save.file.isopen) save.file.close();
+  f.close();
+  save.chunks = []; // the payload is on disk now - do not hold a second copy of it
 
   var onDisk = fileSize(savePartPath(save.destPath));
+  post("m4l-jweb: save wrote " + save.written + " bytes, " + onDisk + " on disk, expected " + save.expect + "\n");
   if (onDisk !== save.expect) {
     outlet(0, "save_error", requestId, "size mismatch: wrote " + onDisk + " bytes, expected " + save.expect);
     activeSave = null;
     return;
   }
-  // PHASE 3: place the verified .part over the destination via [maxurl]. NOTE the
-  // 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:///" + savePartPath(save.destPath));
-  post("m4l-jweb: save place " + placeUrl + " -> " + save.destPath + "\n");
+  // PHASE 3: place the verified .part over the destination via [maxurl]. Keep destPath
+  // a FLAT name in the device folder - not because a subdirectory is known to fail (that
+  // was measured against the stray-file bug and never held up), but because flat is the
+  // only shape measured working. See doc/ARCHITECTURE.md before adding an option.
+  var source = placeUrl(savePartPath(save.destPath));
+  post("m4l-jweb: save place " + source + " -> " + save.destPath + "\n");
   var reqDict = new Dict();
-  reqDict.set("url", placeUrl);
+  reqDict.set("url", source);
   reqDict.set("http_method", "get");
   reqDict.set("filename_out", save.destPath);
   reqDict.set("overwrite_output_file", 1);
@@ -1143,8 +1225,26 @@ function save_end(requestId: string): void {
 function finishSavePlace(): void {
   if (!activeSave) return;
   var save = activeSave;
+  // What maxurl SAID, before what the disk shows. The place was validated on bytes
+  // alone, so a reply carrying an explicit error was thrown away and the failure
+  // arrived as a bare `-1 bytes at destination` with no cause attached.
+  var reply = new Dict(SAVE_PLACE_RESPONSE_DICT);
+  post(
+    "m4l-jweb: save place reply status " +
+      String(reply.get("status")) +
+      ", error " +
+      String(reply.get("error")) +
+      ", part now " +
+      fileSize(savePartPath(save.destPath)) +
+      " bytes\n",
+  );
   var placed = fileSize(save.destPath);
   if (placed !== save.expect) {
+    // `Couldn't read a file:// file` here means the .part is not where this says it
+    // is: [js] wrote it to a STRAY of the same name earlier on Max's search path, and
+    // fileSize() found that stray rather than nothing. Naming it costs one line and
+    // saves the week it took to find the first time.
+    post("m4l-jweb: the .part is not at that path. Look for a stray m4l-jweb-save.part in Max's own folder and remove it.\n");
     outlet(0, "save_error", save.requestId, "could not place save: " + placed + " bytes at destination, expected " + save.expect);
     activeSave = null;
     return;

package/src/liveapi.ts

@@ -131,6 +131,33 @@ function observeProperty(objectPath: string, property: string, selector: string)
  * Clip I/O
  * ------------------------------------------------------------------ */
 
+/**
+ * Tell the page which CONTAINER it is in: `track_kind <audio|midi|none>`.
+ *
+ * A page cannot see its own track, and what a device may do depends on it - an audio clip
+ * only lands on an audio track, a MIDI clip only on a MIDI one. Baking the answer into the
+ * build instead would mean two builds differing in a fact Live already knows, and a
+ * manifest that can lie. Sent at ui_ready, alongside the device folder.
+ *
+ * `has_audio_input` is the audio-track test and `has_midi_input` the MIDI one; a MIDI
+ * track hosting an instrument still answers `has_audio_input 0`, which is the distinction
+ * that matters here.
+ */
+function sendTrackKind(): void {
+  try {
+    var track = ownTrack();
+    if (!track || !track.id || track.type !== "Track") {
+      reply("track_kind", "none");
+      return;
+    }
+    var kind = Number(track.get("has_audio_input")) === 1 ? "audio" : Number(track.get("has_midi_input")) === 1 ? "midi" : "none";
+    reply("track_kind", kind);
+    post("m4l-jweb: this device is on " + (kind === "none" ? "no reachable track" : "a " + kind + " track") + "\n");
+  } catch (e) {
+    post("m4l-jweb: track_kind unavailable - " + (e as Error).message + "\n");
+  }
+}
+
 interface LiveNote {
   pitch: number;
   start_time: number;
@@ -322,6 +349,247 @@ function pickClip(): LiveAPI | null {
   }
 }
 
+/* ------------------------------------------------------------------ *
+ * A file on disk INTO an audio clip
+ *
+ * `create_audio_clip <requestId> <base64 spec>`; `clip_created <requestId>` or
+ * `clip_error <requestId> <reason> <msg...>` back. `createAudioClip()` in the bridge is
+ * the shaped API, and the spec is base64 JSON because a path and a clip name BOTH
+ * contain spaces in practice - two variadic fields cannot be recovered from one flat
+ * Max message.
+ *
+ * WHY THIS IS GATED ON A VERSION READ AND NOT ON A TRY/CATCH. `create_audio_clip` is
+ * documented well before Live 12.0.5 and does nothing there - so the failure to design
+ * around is a call that raises nothing and leaves the slot empty, which is
+ * indistinguishable from a slot that was already empty. Ask Live what it is.
+ *
+ * WHAT THE TARGET MUST BE: an audio track, not frozen, not being recorded into. An
+ * instrument device can never satisfy that from its own view - it sits on a MIDI track,
+ * and the highlighted slot is always one of its own, because a device's UI is only on
+ * screen while its track is selected. Hence `target: "new"`, and hence the audio-effect
+ * flavour of a device that wants to bounce into the track it is already on.
+ * ------------------------------------------------------------------ */
+
+/** Live's version, read once. null when neither spelling of the getter answered. */
+var liveVersionCache: number[] | null = null;
+var liveVersionAsked = false;
+
+/**
+ * [major, minor, bugfix], or null.
+ *
+ * TWO SPELLINGS ARE TRIED, and that is not hedging: the LOM's Application functions are
+ * `get_major_version` in Live's own documentation, and this repo has been wrong about a
+ * name it never looked up more than once (see MAX-FACTS on names Max does not validate).
+ * Whichever answers is posted, so the console says which one this Live has.
+ */
+function liveVersion(): number[] | null {
+  if (liveVersionAsked) return liveVersionCache;
+  liveVersionAsked = true;
+  var spellings = [
+    ["get_major_version", "get_minor_version", "get_bugfix_version"],
+    ["get_version_major", "get_version_minor", "get_version_bugfix"],
+  ];
+  try {
+    var app = new LiveAPI("live_app");
+    for (var i = 0; i < spellings.length; i++) {
+      try {
+        var major = Number(app.call(spellings[i][0]));
+        var minor = Number(app.call(spellings[i][1]));
+        var bugfix = Number(app.call(spellings[i][2]));
+        if (major > 0) {
+          liveVersionCache = [major, minor, bugfix];
+          post("m4l-jweb: Live " + major + "." + minor + "." + bugfix + " (via " + spellings[i][0] + ")\n");
+          return liveVersionCache;
+        }
+      } catch (inner) {
+        /* the other spelling gets its turn */
+      }
+    }
+    post("m4l-jweb: could not read Live's version - neither get_major_version nor get_version_major answered\n");
+  } catch (e) {
+    post("m4l-jweb: live_app unavailable - " + (e as Error).message + "\n");
+  }
+  return null;
+}
+
+/** Is this Live new enough for create_audio_clip to DO anything? Unknown counts as yes. */
+function hasAudioClipApi(): boolean {
+  var v = liveVersion();
+  if (!v) return true; // cannot tell: attempt, and report what the slot says afterwards
+  if (v[0] > 12) return true;
+  if (v[0] < 12) return false;
+  if (v[1] > 0) return true;
+  return v[2] >= 5;
+}
+
+/** base64 -> string, UTF-8 aware. b64decode (core.ts) gives bytes; this reads them. */
+function b64ToString(b64: string): string {
+  var bytes = b64decode(b64);
+  var out = "";
+  for (var i = 0; i < bytes.length; i++) {
+    var c = bytes[i];
+    if (c < 0x80) out += String.fromCharCode(c);
+    else if (c < 0xe0) out += String.fromCharCode(((c & 0x1f) << 6) | (bytes[++i] & 0x3f));
+    else if (c < 0xf0) out += String.fromCharCode(((c & 0x0f) << 12) | ((bytes[++i] & 0x3f) << 6) | (bytes[++i] & 0x3f));
+    else {
+      // Outside the BMP: rebuild the surrogate pair, or a name with an emoji in it
+      // silently becomes garbage rather than the character the user typed.
+      var cp = ((c & 0x07) << 18) | ((bytes[++i] & 0x3f) << 12) | ((bytes[++i] & 0x3f) << 6) | (bytes[++i] & 0x3f);
+      cp -= 0x10000;
+      out += String.fromCharCode(0xd800 + (cp >> 10), 0xdc00 + (cp & 0x3ff));
+    }
+  }
+  return out;
+}
+
+interface AudioClipSpec {
+  path: string;
+  target: string;
+  track?: number;
+  slot?: number;
+  name?: string;
+  warp?: boolean;
+  warpMode?: number;
+  loopEnd?: number;
+}
+
+function clipError(requestId: string, reason: string, message: string): void {
+  post("m4l-jweb: create_audio_clip " + reason + " - " + message + "\n");
+  // Fixed arity, never outlet.apply - see emitClipNotes. The reason is its own atom so
+  // the app can branch on it without parsing the human sentence beside it.
+  outlet(0, "clip_error", requestId, reason, message);
+}
+
+function create_audio_clip(requestId: string, b64: string): void {
+  var spec: AudioClipSpec;
+  try {
+    spec = JSON.parse(b64ToString(String(b64)));
+  } catch (e) {
+    return clipError(String(requestId), "failed", "could not read the request: " + (e as Error).message);
+  }
+
+  if (!hasAudioClipApi()) {
+    var v = liveVersion();
+    return clipError(
+      String(requestId),
+      "needs_live_1205",
+      "this Live is " + (v ? v.join(".") : "older than 12.0.5") + "; ClipSlot.create_audio_clip does nothing before 12.0.5",
+    );
+  }
+
+  // The same resolution a save uses, so a device passes back exactly the name it wrote.
+  var path = resolveFetchPath(String(spec.path));
+  if (path === null) {
+    return clipError(String(requestId), "no_file", "the patcher is not saved, so a relative path resolves against nowhere");
+  }
+  // Ask the filesystem before asking Live. A missing file makes create_audio_clip fail in
+  // a way that reads exactly like a wrong target, and this is one line.
+  if (fileSize(path) <= 0) {
+    return clipError(String(requestId), "no_file", "nothing on disk at " + path);
+  }
+
+  var slot = resolveClipSlot(spec);
+  if (!slot || !slot.id) {
+    return clipError(String(requestId), "no_slot", spec.target === "selected" ? "no clip slot is highlighted in Live" : "no clip slot at that index");
+  }
+
+  var track = new LiveAPI(slot.unquotedpath + " canonical_parent");
+  if (Number(track.get("has_audio_input")) !== 1) {
+    return clipError(
+      String(requestId),
+      "not_audio_track",
+      "the target is not an audio track - an audio clip can only be created on one",
+    );
+  }
+  if (Number(track.get("is_frozen")) === 1) {
+    return clipError(String(requestId), "track_busy", "that track is frozen");
+  }
+  try {
+    if (Number(slot.get("is_recording")) === 1) {
+      return clipError(String(requestId), "track_busy", "that slot is being recorded into");
+    }
+  } catch (eRec) {
+    /* an older ClipSlot may not carry is_recording; the call below still refuses */
+  }
+
+  post("m4l-jweb: create_audio_clip -> " + slot.unquotedpath + " <- " + path + "\n");
+  try {
+    slot.call("create_audio_clip", path);
+  } catch (eCall) {
+    return clipError(String(requestId), "failed", (eCall as Error).message);
+  }
+
+  // The slot is the evidence, not the call. A LOM method that declines prints to the Max
+  // window and returns nothing, so "it did not throw" is not "there is a clip".
+  if (Number(slot.get("has_clip")) !== 1) {
+    return clipError(String(requestId), "failed", "the call ran and the slot is still empty - see the Max window for Live's own error");
+  }
+
+  setupAudioClip(new LiveAPI(slot.unquotedpath + " clip"), spec);
+  post("m4l-jweb: created an audio clip in " + slot.unquotedpath + "\n");
+  outlet(0, "clip_created", requestId);
+}
+
+/** The slot a spec names, creating a track for `target: "new"`. */
+function resolveClipSlot(spec: AudioClipSpec): LiveAPI | null {
+  try {
+    if (spec.target === "new") {
+      var song = new LiveAPI("live_set");
+      // -1 appends. The new track is therefore the last one, and asking for the count
+      // AFTER the call is what identifies it - there is no return value to trust.
+      song.call("create_audio_track", -1);
+      var last = song.getcount("tracks") - 1;
+      if (last < 0) return null;
+      // Select it, so the bounce is where the user is looking rather than somewhere
+      // off the right edge of a wide set.
+      try {
+        new LiveAPI("live_set view").set("selected_track", "id " + new LiveAPI("live_set tracks " + last).id);
+      } catch (eSel) {
+        /* cosmetic */
+      }
+      return new LiveAPI("live_set tracks " + last + " clip_slots 0");
+    }
+    if (spec.target === "track") {
+      return new LiveAPI("live_set tracks " + Number(spec.track) + " clip_slots " + Number(spec.slot));
+    }
+    return new LiveAPI("live_set view highlighted_clip_slot");
+  } catch (e) {
+    post("m4l-jweb: create_audio_clip target error - " + (e as Error).message + "\n");
+    return null;
+  }
+}
+
+/**
+ * Name it, warp it, and give it the loop the render actually has.
+ *
+ * Every write is individually guarded and NONE of them fails the request: the clip is
+ * already in the slot by the time this runs, and a bounce that landed under the wrong
+ * name is not a bounce that failed. What did not take is posted.
+ *
+ * ORDER MATTERS. `warping` comes first - loop points on an unwarped clip are in seconds
+ * of sample time, not beats - and the END markers are widened before the loop is set,
+ * because Live clamps a loop to the markers it currently has.
+ */
+function setupAudioClip(clip: LiveAPI, spec: AudioClipSpec): void {
+  if (!clip || !clip.id) return;
+  var writes: unknown[][] = [];
+  if (spec.warp !== false) writes.push(["warping", 1]);
+  if (spec.warpMode !== undefined) writes.push(["warp_mode", Number(spec.warpMode)]);
+  if (spec.loopEnd !== undefined && Number(spec.loopEnd) > 0) {
+    writes.push(["end_marker", Number(spec.loopEnd)], ["loop_end", Number(spec.loopEnd)], ["start_marker", 0], ["loop_start", 0], ["looping", 1]);
+  }
+  // Last, so a name is not lost to an exception thrown by a loop point.
+  if (spec.name) writes.push(["name", String(spec.name)]);
+
+  for (var i = 0; i < writes.length; i++) {
+    try {
+      clip.set(String(writes[i][0]), writes[i][1]);
+    } catch (e) {
+      post("m4l-jweb: clip " + writes[i][0] + " = " + writes[i][1] + " did not take - " + (e as Error).message + "\n");
+    }
+  }
+}
+
 function getNotes(clip: LiveAPI, loopEnd: number): LiveNote[] | null {
   // Live 11+: get_notes_extended returns a JSON string.
   try {

package/src/max.d.ts

@@ -203,6 +203,14 @@ declare const EXTRA_PAYLOAD_B64: string[][] | undefined;
  */
 declare const WATCH_SPECS: { key: string; path: string; property: string }[] | undefined;
 
+/**
+ * Injected by @m4l-jweb/build from the device's `defineFiles()`: what this device
+ * does with disk. Undefined for a device that declares none - which is also a
+ * device with no [maxurl], because the declaration is what derives the `download`
+ * chain (files.mjs).
+ */
+declare const FILES_SPEC: { saves: boolean; fetches: boolean; tellPage: boolean } | 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.