@m4l-jweb/build 1.2.1 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "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.1"
+    "@m4l-jweb/wrapper": "1.3.1"
   }
 }

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);
@@ -122,6 +123,26 @@ async function readManifest(root) {
   return (await import(pathToFileURL(p).href)).default;
 }
 
+/**
+ * Files that ride along with the release without being part of any device.
+ *
+ * A user manual, a licence, a chart - things a person opens, not things Max loads. They
+ * are declared as a named `docs` export next to the manifest:
+ *
+ *   export const docs = ["USERSMANUAL.md", "dist/manual/USERSMANUAL.pdf"];
+ *
+ * MISSING IS NOT FATAL, and that is the whole reason this is a list rather than a
+ * `looseFiles` entry: a generated doc (a PDF rendered by a headless browser) may not
+ * exist on a machine that has no browser, and a manual is never worth failing a build
+ * that produced every device correctly. What is missing is named in the log.
+ */
+async function readDocs(root) {
+  const p = path.join(root, "patcher", "devices.mjs");
+  if (!existsSync(p)) return [];
+  const mod = await import(pathToFileURL(p).href);
+  return Array.isArray(mod.docs) ? mod.docs : [];
+}
+
 /** patcher/base.json in the device repo wins; otherwise the packaged template. */
 function readBase(root) {
   const local = path.join(root, "patcher", "base.json");
@@ -157,7 +178,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 +188,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)`);
 
@@ -220,7 +242,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);
@@ -266,7 +288,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 -
@@ -279,7 +302,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;
 }
@@ -383,7 +410,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
@@ -446,6 +477,19 @@ export async function packageDevices(root) {
     console.log(`m4l-jweb: ${f} -> dist/${name}/ (preset)`);
   }
 
+  // Documentation for the human, alongside the devices for Max. See readDocs.
+  const docs = [];
+  for (const f of await readDocs(root)) {
+    const from = path.join(root, f);
+    if (!existsSync(from)) {
+      console.warn(`m4l-jweb: doc ${f} is not there - skipped (it is not part of any device)`);
+      continue;
+    }
+    await copyFile(from, path.join(outDir, path.basename(f)));
+    docs.push(path.basename(f));
+    console.log(`m4l-jweb: ${path.basename(f)} -> dist/${name}/ (doc)`);
+  }
+
   // Installers go next to the devices so `dist/install-*.ps1` just works.
   const installers = ["install-windows.ps1", "install-mac.sh"];
   for (const f of installers) await copyFile(path.join(templates, f), path.join(dist, f));
@@ -462,6 +506,7 @@ export async function packageDevices(root) {
       ...devices.map((d) => `${d.name}.html`), // each device's own UI, for inspection
       ...loose.map((f) => path.basename(f)),
       ...presets,
+      ...docs,
       "wrapper.js",
     ];
     for (const f of files) {

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.1",
-    "@m4l-jweb/surface": "^1.2.1",
+    "@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.1",
+    "@m4l-jweb/build": "^1.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",