@m4l-jweb/build 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
     "./chains": "./src/chains.mjs",
     "./surface": "./src/surface.mjs",
     "./watch": "./src/watch.mjs",
+    "./files": "./src/files.mjs",
     "./amxd": "./src/amxd.mjs",
     "./init": "./src/init.mjs"
   },
@@ -34,6 +35,6 @@
     "archiver": "^7.0.1",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "1.2.0"
+    "@m4l-jweb/wrapper": "1.3.0"
   }
 }

package/src/chains.mjs

@@ -112,42 +112,6 @@ export function claimAppMessages(ctx, routeId, unmatchedOutlet) {
 export const AUDIO_IN = "obj-plugin";
 export const AUDIO_OUT = "obj-plugout";
 
-/**
- * A [buffer~] name that is unique PER DEVICE INSTANCE.
- *
- * THE BUG THIS EXISTS TO KILL. Buffer names are GLOBAL to Max, and they used to be
- * generated from the device name alone (`buf-<device>-<slot>`) and frozen into the
- * patcher at BUILD time. So two copies of one device - a drum rack on two tracks, which
- * is the normal case, not an exotic one - named their buffers identically, and Max gave
- * both to whichever loaded last. One rack's samples silently became the other's. No
- * error, no console line: just the wrong sound.
- *
- * A name minted by the wrapper after load cannot reach a box frozen at build time (a
- * buffer takes its name from its creation argument and there is no documented runtime
- * rename), so the scoping has to be a load-time substitution Max itself performs.
- *
- * `#0` WAS TRIED AND DOES NOT WORK (spike run 2026-07-17 in Live; see
- * doc/MAX-FACTS.md). `#0` is documented for abstractions, and an .amxd device patcher turned out
- * not to count as one: the token stayed literal in every instance, so writer and
- * reader still agreed on one global name and the collision survived, silently.
- *
- * `---` IS THE MECHANISM BUILT FOR THIS. Max for Live replaces a leading `---` in a
- * name with an id unique to the DEVICE instance - and the scope is the whole device,
- * subpatchers and [poly~] voices included, not one patcher. That kills the `#0`/`#1`
- * hand-off the first attempt needed: the voice spells the SAME name the device does,
- * and no id has to travel through [poly~]'s arguments.
- *
- * OUTSIDE LIVE `---` stays literal (it is a Live-only substitution). Both writer and
- * reader keep agreeing, so a patcher opened in standalone Max degrades to the old
- * shared-name behavior instead of breaking - acceptable, since the devices only
- * meaningfully run in Live.
- */
-export const deviceBufName = (device, slot) => `---buf-${device?.name}-${slot}`;
-
-/** The same buffer, as a [poly~] voice spells it: identical - `---` scopes per DEVICE,
- * not per patcher, so the voice shares the expansion with the patcher that loaded it. */
-export const voiceBufName = (device, slot) => deviceBufName(device, slot);
-
 /**
  * How long a `remote` slot takes to slide to each new value, in ms.
  *

package/src/files.mjs

@@ -0,0 +1,87 @@
+/**
+ * files.mjs - the build side of defineFiles().
+ *
+ * The third of the same pipeline: import a device's declaration, and turn it into
+ * the two things Max needs. Unlike watch.mjs it produces BOTH kinds of output -
+ * data (the FILES_SPEC banner the wrapper reads) and a patcher CHAIN - because a
+ * device that writes files needs [maxurl] in the box graph and a folder in the
+ * page, and those two travelling separately is the failure the declaration exists
+ * to make impossible.
+ */
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The chain that owns [maxurl]. Every file-writing device needs it - see defineFiles. */
+export const FILES_CHAIN = "download";
+
+/**
+ * Load a device's `src/app/<uiDir>/files.ts`, or null if it declares none.
+ *
+ * Bundled with esbuild exactly like loadSurface and loadWatch, for the same
+ * reason: the declaration is TypeScript importing @m4l-jweb/surface, and Node
+ * cannot import that directly.
+ */
+export async function loadFiles(root, uiDir) {
+  const src = path.join(root, "src", "app", uiDir, "files.ts");
+  if (!existsSync(src)) return null;
+
+  const { build } = await import("esbuild");
+  const tmp = mkdtempSync(path.join(tmpdir(), "m4l-files-"));
+  const out = path.join(tmp, "files.mjs");
+  try {
+    await build({
+      entryPoints: [src],
+      outfile: out,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      logLevel: "silent",
+      external: ["react", "react-dom"],
+    });
+    const mod = await import(pathToFileURL(out).href);
+    const files = mod.default;
+    if (!files || typeof files.saves !== "boolean" || typeof files.fetches !== "boolean") {
+      throw new Error(`${src} must \`export default defineFiles({...})\``);
+    }
+    return files;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The chain list this device is actually built with.
+ *
+ * A declared file device gets `download` whether or not the manifest asked for it,
+ * appended LAST so it cannot displace an audio stage: `download` claims no stage of
+ * the signal path, but chain order IS the signal path, and inserting anywhere else
+ * would be a silent re-routing of a device that merely started writing files.
+ *
+ * Idempotent. A manifest that still lists `download` keeps exactly one - running the
+ * chain twice would emit the same box ids twice, which assertUniqueBoxIds rejects.
+ */
+export function effectiveChains(chains, files) {
+  const declared = chains ?? [];
+  if (!files) return declared;
+  return declared.includes(FILES_CHAIN) ? declared : [...declared, FILES_CHAIN];
+}
+
+/**
+ * The `var FILES_SPEC = {...}` banner prepended to a device's wrapper.js.
+ *
+ * Only what the wrapper ACTS on travels. `tellPage` gates the `device_folder`
+ * message at ui_ready; `saves` and `fetches` ride along because a device that has
+ * never written anything still says so in the Max console, and a wrapper reporting
+ * "this device writes no files" next to a save error is the cheapest possible answer
+ * to "is it even wired for this".
+ *
+ * A device with no declaration gets no banner ("") - `typeof FILES_SPEC === "undefined"`
+ * is exactly the guard the wrapper checks.
+ */
+export function filesSpecBanner(files) {
+  if (!files) return "";
+  const spec = { saves: !!files.saves, fetches: !!files.fetches, tellPage: !!files.tellPage };
+  return `var FILES_SPEC = ${JSON.stringify(spec)};\n`;
+}

package/src/index.mjs

@@ -18,6 +18,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { AMXD_TYPES, assertES5, buildAmxd, extraPayloadsJs, payloadJs } from "./amxd.mjs";
 import { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, resetLayout } from "./chains.mjs";
 import { applySurface, applyWindows, applyPersistence, loadSurface, parameterRegistry, surfaceContext } from "./surface.mjs";
+import { effectiveChains, filesSpecBanner, loadFiles } from "./files.mjs";
 import { loadWatch, watchSpecsBanner } from "./watch.mjs";
 
 const require = createRequire(import.meta.url);
@@ -157,7 +158,8 @@ async function loadDeviceChains(root) {
  *
  *   openAudio      the device's plugin~/plugout~, created ONCE, before any chain -
  *                  so a chain is a stage in the signal path, not the owner of it.
- *   the chains     in declaration order, each taking what the last one left.
+ *   the chains     in declaration order, each taking what the last one left, plus
+ *                  the `download` chain a files.ts declaration derives (files.mjs).
  *   applySurface   LAST of the message-stream claimants: it routes every `set_<id>`
  *                  off the app's stream and passes on what nobody claimed
  *                  (ui_ready, ...) to the wrapper. Doing it last means no chain has
@@ -166,7 +168,7 @@ async function loadDeviceChains(root) {
  *   assertUnique   two boxes with one id is a malformed patcher, and Max resolves
  *                  it however it likes. Nothing else would report it.
  */
-export function composePatcher(base, d, surface) {
+export function composePatcher(base, d, surface, files = null) {
   const amxdtype = AMXD_TYPES[d.type];
   if (!amxdtype) throw new Error(`unknown type "${d.type}" for device "${d.name}" (midi | audio | instrument)`);
 
@@ -184,6 +186,19 @@ export function composePatcher(base, d, surface) {
   const mode = d.mode ?? d.type;
   boxes.find((b) => b.box.id === "obj-js").box.text = `js wrapper.js ${mode}`;
 
+  /**
+   * The ring buffer between Chromium's audio thread and MSP, for the DEVICE PAGE's
+   * own `[jweb~]`.
+   *
+   * `window({ audio: true, latency })` has taken this since 1.1.0, and the device
+   * page could not - so a device that put its buffer at the documented maximum for
+   * its sounding WINDOW left its own page at the object default (~21 ms at 48 kHz)
+   * and went on dropping out. Two pages, one setting, and only one of them had it.
+   *
+   * Unset keeps the object's default. jweb~ clamps to 3x the minimum.
+   */
+  if (d.latency != null) boxes.find((b) => b.box.id === "obj-jweb").box.latency = d.latency;
+
   const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
 
   /**
@@ -207,7 +222,7 @@ export function composePatcher(base, d, surface) {
 
   openAudio(ctx);
 
-  for (const name of d.chains ?? []) {
+  for (const name of effectiveChains(d.chains, files)) {
     const chain = CHAINS[name];
     if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
     chain(ctx);
@@ -253,7 +268,8 @@ export async function generatePatchers(root) {
     }
 
     const surface = await loadSurface(root, d.ui ?? d.name);
-    const p = composePatcher(base, d, surface);
+    const files = await loadFiles(root, d.ui ?? d.name);
+    const p = composePatcher(base, d, surface, files);
 
     // A chain's frozen dependencies (e.g. a [poly~] voice patch) are written beside
     // the device patcher and their names recorded in a sidecar, so packageDevices -
@@ -266,7 +282,11 @@ export async function generatePatchers(root) {
 
     writeFileSync(path.join(outDir, `${d.name}.json`), JSON.stringify(p, null, "\t"));
     const params = surface ? surface.ids.join(", ") : "none";
-    console.log(`m4l-jweb: ${d.name}.json (${d.type}, chains: ${(d.chains ?? []).join(", ") || "none"}, params: ${params || "none"})`);
+    // The chains it was BUILT with, not the ones the manifest listed - a derived
+    // `download` that never appeared in the log would be the same invisible wiring
+    // this feature exists to end.
+    const chains = effectiveChains(d.chains, files).join(", ") || "none";
+    console.log(`m4l-jweb: ${d.name}.json (${d.type}, chains: ${chains}, params: ${params || "none"})`);
   }
   return devices;
 }
@@ -370,7 +390,11 @@ export async function packageDevices(root) {
     // The device's declared watches ride in as a data banner, like the build stamp:
     // WATCH_SPECS is what the packaged wrapper's setupWatches() attaches observers from.
     const watch = await loadWatch(root, d.ui ?? d.name);
-    let wrapperData = banner + watchSpecsBanner(watch) + siteWindowsBanner(root, outDir, d, await loadSurface(root, d.ui ?? d.name)) + wrapperJs;
+    // ...and so do its declared files: FILES_SPEC is what tells the packaged wrapper
+    // this device writes to disk, and therefore to hand the page its device folder.
+    const files = await loadFiles(root, d.ui ?? d.name);
+    let wrapperData =
+      banner + watchSpecsBanner(watch) + filesSpecBanner(files) + siteWindowsBanner(root, outDir, d, await loadSurface(root, d.ui ?? d.name)) + wrapperJs;
     const uiDirContent = readdirSync(path.join(dist, "ui", d.ui ?? d.name)).filter((f) => f.endsWith(".html"));
 
     // Main UI payload

package/templates/install-mac.sh

@@ -44,7 +44,9 @@ if [ ! -d "$user_lib" ]; then
 fi
 
 dest="$user_lib/Max For Live/$device_name"
-rm -rf "$dest"
+# The folder is NOT wiped first. It is the same folder the devices SAVE INTO - exports,
+# downloaded samples, anything a user dragged out of it - so clearing it to get a clean
+# install threw away their work. Overwrite what this build produces; leave the rest.
 mkdir -p "$dest"
 
 # Each .amxd is self-contained: the UI rides inside it as a payload in wrapper.js.
@@ -67,6 +69,9 @@ done
 # empty, and the wrapper says so in the Max console.
 for d in "$src"/*-site; do
 	[ -d "$d" ] || continue
+	# This one IS replaced wholesale: it is entirely build output, and a file dropped
+	# from the site between builds would otherwise linger and be served.
+	rm -rf "$dest/$(basename "$d")"
 	cp -R "$d" "$dest/"
 	echo "  installed $(basename "$d")/ (site sidecar)"
 done

package/templates/install-windows.ps1

@@ -49,13 +49,20 @@ if (-not (Test-Path $userLib)) {
 }
 
 $dest = Join-Path $userLib "Max For Live\$deviceName"
-if (Test-Path $dest) { Remove-Item $dest -Recurse -Force }
+# The folder is NOT wiped first. It is the same folder the devices SAVE INTO - exports,
+# downloaded samples, anything a user dragged out of it - so clearing it to get a clean
+# install threw away their work, and failed outright the moment Live held one of those
+# files open. Overwrite what this build produces; leave everything else alone.
 New-Item -ItemType Directory -Force $dest | Out-Null
 
 # Each .amxd is self-contained: the UI rides inside it as a payload in wrapper.js.
 foreach ($f in $devices) {
-    Copy-Item $f.FullName $dest -Force
-    Write-Host "  installed $($f.Name)"
+    try {
+        Copy-Item $f.FullName $dest -Force -ErrorAction Stop
+        Write-Host "  installed $($f.Name)"
+    } catch {
+        Write-Error "Could not replace $($f.Name) - it is open in Live. Close the set (or remove the device from the track) and run this again."
+    }
 }
 
 # Presets (hand-saved Live racks, packaged next to the devices by the build) go in
@@ -70,6 +77,10 @@ foreach ($f in @(Get-ChildItem (Join-Path $src "*.adg") -ErrorAction SilentlyCon
 # installed with it. Without the folder the device still plays; that window opens
 # empty, and the wrapper says so in the Max console.
 foreach ($d in @(Get-ChildItem (Join-Path $src "*-site") -Directory -ErrorAction SilentlyContinue)) {
+    # This one IS replaced wholesale: it is entirely build output, and a file dropped
+    # from the site between builds would otherwise linger and be served.
+    $siteTarget = Join-Path $dest $d.Name
+    if (Test-Path $siteTarget) { Remove-Item $siteTarget -Recurse -Force }
     Copy-Item $d.FullName $dest -Recurse -Force
     Write-Host "  installed $($d.Name)/ (site sidecar)"
 }

package/templates/starter/package.json

@@ -17,13 +17,13 @@
     "format": "prettier --write \"src/**/*.{ts,tsx,css}\" \"scripts/*.mjs\" \"patcher/*.mjs\""
   },
   "dependencies": {
-    "@m4l-jweb/bridge": "^1.2.0",
-    "@m4l-jweb/surface": "^1.2.0",
+    "@m4l-jweb/bridge": "^1.3.0",
+    "@m4l-jweb/surface": "^1.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^1.2.0",
+    "@m4l-jweb/build": "^1.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/starter/tsconfig.json

@@ -1,4 +1,4 @@
 {
 	"files": [],
-	"references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+	"references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }, { "path": "./tsconfig.test.json" }]
 }

package/templates/starter/tsconfig.test.json

@@ -0,0 +1,29 @@
+{
+	// The TESTS, which nothing typechecked before.
+	//
+	// `tsconfig.app.json` covers `src`, `tsconfig.node.json` covers the scripts and the
+	// patcher - and `tests/` fell between them. That is fine for the `.mjs` suites, but
+	// a `.ts` one carrying `expectTypeOf` assertions was checking nothing at all: the
+	// assertion is a TYPE error or it is nothing, so an unchecked type test passes for
+	// the same reason a deleted one does. Referenced from the root solution, so a plain
+	// `tsc -b` (which the build runs first) fails on it.
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["ES2023", "DOM", "DOM.Iterable"],
+		"module": "ESNext",
+		"skipLibCheck": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"resolveJsonModule": true,
+		"allowJs": true,
+		"isolatedModules": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"strict": true
+	},
+	// `vitest.config.ts` is listed alongside the tests, and not only to check it: a
+	// project whose include matches nothing at all is a tsc ERROR (TS18003), and a
+	// freshly scaffolded repo has no tests yet. One file that always exists keeps the
+	// project valid from the first minute.
+	"include": ["tests/**/*.ts", "vitest.config.ts"]
+}