@m4l-jweb/wrapper 0.9.5 → 1.0.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.5",
+  "version": "1.0.0",
   "description": "m4l-jweb: the Max for Live glue layer connecting a device to LiveAPI.",
   "type": "module",
   "license": "MIT",

package/src/core.ts

@@ -690,6 +690,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 +808,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 +842,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 +852,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,100 +873,12 @@ 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;
 }
 
-/* ------------------------------------------------------------------ *
- * Samples - the `samples` chain
- * ------------------------------------------------------------------ */
-
-/**
- * The app: `buffer_load <slot> <path>` - read a file into that slot's [buffer~].
- *
- * WHY THIS GOES THROUGH [js] AT ALL, when the chain could route it straight to the
- * buffer: because the path the app wrote is not a path [buffer~] can open, and it
- * fails in the two ways this file exists to prevent.
- *
- * A RELATIVE path is resolved against the device's folder - the same resolution
- * `fetch_to_file` does, and it has to be the same one or the app downloads a file to
- * one place and loads it from another. [buffer~] does not resolve it that way: a bare
- * name is looked up in MAX's SEARCH PATH, which does not contain the device's folder,
- * so `preview.wav` - freshly downloaded, right there next to the .amxd - reports
- * "can't open" and the promise times out.
- *
- * ...and the resolved path CONTAINS SPACES on a normal Live install ("Ableton
- * Library", "Max For Live"). A message travelling through the patcher as text would
- * split there into three atoms and [buffer~] would open the first one. Handed out of
- * [js] as a string, it stays ONE symbol all the way to `replace`.
- *
- * The file is checked before the buffer is asked for it, because a missing file makes
- * [buffer~] print to the Max console and stay silent - there is no failure bang to
- * bind to, and the app would learn nothing until the timeout. `buffer_error` says so
- * at once.
- */
-function buffer_load(slot: string, path: string): void {
-  var resolved = resolveFetchPath(path); // the same folder the download wrote to
-  var f: File | null = null;
-  try {
-    f = new File(resolved, "read");
-  } catch (e) {
-    f = null;
-  }
-  if (!f || !f.isopen) {
-    outlet(0, "buffer_error", slot, "no file at " + resolved);
-    return;
-  }
-  var bytes = f.eof;
-  f.close();
-  if (!bytes) {
-    outlet(0, "buffer_error", slot, "empty file at " + resolved);
-    return;
-  }
-
-  // Outlet 1 is the aux outlet; the `samples` chain routes `buffer_replace` off it,
-  // exactly as the `download` chain routes `maxurl`. Outlet 0 belongs to [jweb].
-  post("m4l-jweb: buffer_load " + slot + " -> " + resolved + "\n");
-  outlet(1, "buffer_replace", slot, resolved);
-}
-
-/**
- * The app: `render_load <slot> <path> <lengthBeats>` - read a rendered WAV into a
- * renderplay slot's [buffer~].
- *
- * Same path problem, same fix as buffer_load: a relative path is resolved against the
- * device folder (where saveToFile wrote it), and the resolved path - which contains
- * spaces on a normal Live install - is handed out of [js] as ONE symbol via the aux
- * outlet, so `replace` sees a single file rather than three atoms. The loop length rides
- * alongside as `render_len` for the chain's transport-lock detector.
- */
-function render_load(slot: string, path: string, lengthBeats: number): void {
-  var resolved = resolveFetchPath(path);
-  var f: File | null = null;
-  try {
-    f = new File(resolved, "read");
-  } catch (e) {
-    f = null;
-  }
-  if (!f || !f.isopen) {
-    outlet(0, "render_error", slot, "no file at " + resolved);
-    return;
-  }
-  var bytes = f.eof;
-  f.close();
-  if (!bytes) {
-    outlet(0, "render_error", slot, "empty file at " + resolved);
-    return;
-  }
-  post("m4l-jweb: render_load " + slot + " -> " + resolved + " (" + lengthBeats + " beats)\n");
-  // Aux outlet (1): the renderplay chain routes render_replace and render_len off it,
-  // the same way the download chain routes maxurl. Outlet 0 belongs to [jweb].
-  outlet(1, "render_len", slot, lengthBeats);
-  outlet(1, "render_replace", slot, resolved);
-}
-
 /** The app: `fetch_to_file <requestId> <url> <destPath>`. */
 function fetch_to_file(requestId: string, url: string, destPath: string): void {
   fetchQueue.push({ requestId: requestId, url: url, destPath: destPath, partBytes: 0 });