@m4l-jweb/build 0.1.0

package/src/index.mjs

@@ -0,0 +1,325 @@
+/**
+ * index.mjs - the build pipeline: wrapper -> patchers -> package.
+ *
+ * Everything here is conventional over configurable. A device repo owns exactly
+ * two things: `src/app/` (the web app) and `patcher/devices.mjs` (the manifest).
+ * Optional escape hatches:
+ *   patcher/base.json  - override the patcher template
+ *   wrapper/device.ts  - extra [js] message handlers, concatenated last
+ */
+import archiver from "archiver";
+import { createReadStream, createWriteStream, existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { copyFile, rename, stat } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { AMXD_TYPES, assertES5, buildAmxd, extraPayloadsJs, payloadJs } from "./amxd.mjs";
+import { CHAINS, addParameters, resetLayout } from "./chains.mjs";
+
+const require = createRequire(import.meta.url);
+const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const templates = path.join(pkgDir, "templates");
+
+const UI_NAME = "ui.html";
+
+/* ------------------------------------------------------------------ *
+ * Step 1: the wrapper
+ * ------------------------------------------------------------------ */
+
+/**
+ * Compile the wrapper to ONE ES5 script.
+ *
+ * Max's [js] has no module system, so @m4l-jweb/wrapper ships SOURCES, not a
+ * library: core.ts + liveapi.ts (+ the device's own wrapper/device.ts) are
+ * compiled together as one TypeScript program - so they typecheck across the
+ * seam and see each other's globals - and their outputs are concatenated in
+ * order.
+ */
+export function buildWrapper(root) {
+	const { sources, types } = require("@m4l-jweb/wrapper/sources");
+	const deviceExt = path.join(root, "wrapper", "device.ts");
+	const files = [...sources, ...(existsSync(deviceExt) ? [deviceExt] : [])];
+
+	const outDir = path.join(root, "dist", "wrapper");
+	const tmp = path.join(root, "dist", ".wrapper-tsc");
+	rmSync(tmp, { recursive: true, force: true });
+	mkdirSync(tmp, { recursive: true });
+	mkdirSync(outDir, { recursive: true });
+
+	// Copy every source next to each other FIRST, then compile in place.
+	//
+	// tsc derives its output layout from the common root of its inputs. The
+	// packaged sources live in node_modules and the device's own device.ts lives
+	// in the repo, so that common root can be some ancestor of both - and the
+	// outputs land in a mirrored directory tree instead of flat. Staging them in
+	// one directory makes the output names predictable, which is what lets us
+	// concatenate them in order below.
+	const staged = files.map((f, i) => {
+		// Prefix with the index: order is the contract (core must precede the rest),
+		// and two sources could share a basename.
+		const dest = path.join(tmp, `${String(i).padStart(2, "0")}-${path.basename(f)}`);
+		writeFileSync(dest, readFileSync(f, "utf8"));
+		return dest;
+	});
+	const stagedTypes = path.join(tmp, path.basename(types));
+	writeFileSync(stagedTypes, readFileSync(types, "utf8"));
+
+	// The ES5 target is a build gate, not a style preference. `module: "none"`
+	// forbids imports, which is exactly the [js] constraint.
+	const tsconfig = path.join(tmp, "tsconfig.json");
+	writeFileSync(
+		tsconfig,
+		JSON.stringify({
+			compilerOptions: {
+				target: "ES5",
+				lib: ["ES5"],
+				module: "none",
+				outDir: tmp,
+				strict: true,
+				// At [js] global scope `this` IS the jsthis object - that is how
+				// `this.patcher.filepath` works.
+				noImplicitThis: false,
+				noImplicitAny: false,
+				skipLibCheck: true,
+				types: [],
+			},
+			files: [stagedTypes, ...staged],
+		}),
+	);
+
+	execFileSync(process.execPath, [require.resolve("typescript/bin/tsc"), "-p", tsconfig], { stdio: "inherit" });
+
+	// Concatenate the emitted scripts in source order: core's lifecycle first, the
+	// device's own handlers last.
+	const js = staged.map((f) => readFileSync(f.replace(/\.ts$/, ".js"), "utf8")).join("\n");
+	assertES5(js, "wrapper");
+
+	const out = path.join(outDir, "wrapper.js");
+	writeFileSync(out, js);
+	rmSync(tmp, { recursive: true, force: true });
+
+	console.log(`m4l-jweb: wrapper.js (${js.length} bytes, ES5 verified, from ${files.length} sources)`);
+	return out;
+}
+
+/* ------------------------------------------------------------------ *
+ * Step 2: the patchers
+ * ------------------------------------------------------------------ */
+
+async function readManifest(root) {
+	const p = path.join(root, "patcher", "devices.mjs");
+	if (!existsSync(p)) throw new Error("patcher/devices.mjs not found - a device repo needs a manifest");
+	return (await import(pathToFileURL(p).href)).default;
+}
+
+/** patcher/base.json in the device repo wins; otherwise the packaged template. */
+function readBase(root) {
+	const local = path.join(root, "patcher", "base.json");
+	const src = existsSync(local) ? local : path.join(templates, "base.json");
+	return JSON.parse(readFileSync(src, "utf8"));
+}
+
+/**
+ * A device repo may add its own chains in patcher/chains.mjs - importing it is
+ * enough, since registerChain() mutates the shared vocabulary:
+ *
+ *   import { registerChain, box, line } from "@m4l-jweb/build/chains";
+ *   registerChain("poly", ({ boxes, lines, jwebId }) => { ... });
+ *
+ * The canned chains cover the common shapes; anything device-specific (a
+ * synth voice bank, a sample player, an external host) belongs here rather than
+ * in the library.
+ */
+async function loadDeviceChains(root) {
+	const p = path.join(root, "patcher", "chains.mjs");
+	if (!existsSync(p)) return;
+	await import(pathToFileURL(p).href);
+	console.log("m4l-jweb: loaded device chains from patcher/chains.mjs");
+}
+
+export async function generatePatchers(root) {
+	const devices = await readManifest(root);
+	const base = readBase(root);
+	await loadDeviceChains(root);
+	const outDir = path.join(root, "dist", "patchers");
+	mkdirSync(outDir, { recursive: true });
+
+	for (const d of devices) {
+		const amxdtype = AMXD_TYPES[d.type];
+		if (!amxdtype) throw new Error(`unknown type "${d.type}" for device "${d.name}" (midi | audio | instrument)`);
+
+		const p = structuredClone(base);
+		const { boxes, lines } = p.patcher;
+		p.patcher.project.amxdtype = amxdtype;
+		resetLayout();
+
+		// The wrapper is mode-switched by its object-box argument. `mode` defaults
+		// to the device type, but they are not always the same thing: a sample
+		// player can be an audio-effect device ("type") that the wrapper must treat
+		// as a sampler ("mode").
+		//
+		// jsarguments[0] is the SCRIPT NAME, so the mode lands at jsarguments[1].
+		const mode = d.mode ?? d.type;
+		boxes.find((b) => b.box.id === "obj-js").box.text = `js wrapper.js ${mode}`;
+
+		const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
+
+		for (const name of d.chains ?? []) {
+			const chain = CHAINS[name];
+			if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
+			chain({ boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d });
+		}
+
+		// Parameters feed the UI: a knob move arrives as just another inlet message.
+		addParameters(boxes, lines, d.parameters ?? [], "obj-jweb");
+
+		writeFileSync(path.join(outDir, `${d.name}.json`), JSON.stringify(p, null, "\t"));
+		console.log(`m4l-jweb: ${d.name}.json (${d.type}, chains: ${(d.chains ?? []).join(", ") || "none"})`);
+	}
+	return devices;
+}
+
+/* ------------------------------------------------------------------ *
+ * Step 3: package
+ * ------------------------------------------------------------------ */
+
+/**
+ * Assemble dist/: the single-file UI, one .amxd per manifest entry, the
+ * installers, and a release zip.
+ *
+ * Each .amxd is self-contained - the UI travels inside it as a base64 payload in
+ * wrapper.js. The loose ui.html/wrapper.js are for inspection, not a runtime
+ * requirement.
+ */
+export async function packageDevices(root) {
+	const dist = path.join(root, "dist");
+	const { name, version } = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+	const devices = await readManifest(root);
+
+	const outDir = path.join(dist, name);
+	mkdirSync(outDir, { recursive: true });
+
+	// vite emits dist/index.html (everything inlined by vite-plugin-singlefile).
+	const uiPath = path.join(outDir, UI_NAME);
+	const viteOut = path.join(dist, "index.html");
+	if (existsSync(viteOut)) await rename(viteOut, uiPath);
+	if (!existsSync(uiPath)) throw new Error(`no UI at ${uiPath} - run \`vite build\` first`);
+
+	const uiHtml = readFileSync(uiPath);
+	const wrapperJs = readFileSync(path.join(dist, "wrapper", "wrapper.js"), "utf8");
+
+	// The build stamp is what makes a stale install visible: the wrapper posts it
+	// and the UI renders it. Live embeds a copy of the device in the set, so an
+	// instance already on a track does NOT update when you reinstall.
+	const stamp = `${version} ${new Date().toISOString()}`;
+	const banner = `var BUILD_STAMP = ${JSON.stringify(stamp)};\n`;
+
+	for (const d of devices) {
+		const deviceName = `${d.name}.amxd`;
+
+		/**
+		 * Payloads ride inside wrapper.js as base64 and are written to real files
+		 * next to the .amxd on first load, because Chromium and any external
+		 * process are blind to Max's frozen virtual filesystem. The UI is always
+		 * one; a device can declare more (`payloads: ["dist/foo.cjs"]`).
+		 */
+		let wrapperData = banner + wrapperJs + payloadJs("UI_PAYLOAD", UI_NAME, uiHtml);
+		const payloads = (d.payloads ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) }));
+		if (payloads.length) wrapperData += extraPayloadsJs(payloads);
+
+		const amxd = buildAmxd({
+			patcherJson: readFileSync(path.join(dist, "patchers", `${d.name}.json`), "utf8"),
+			wrapperJs: wrapperData,
+			deviceName,
+			// Frozen dependencies: readable by Max-native objects only (a poly~
+			// voice patcher, say), which is exactly why they can stay frozen.
+			extras: (d.extraFiles ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) })),
+		});
+		writeFileSync(path.join(outDir, deviceName), amxd);
+		console.log(`m4l-jweb: ${deviceName} (${d.type}, ${amxd.length} bytes)`);
+	}
+
+	await copyFile(path.join(dist, "wrapper", "wrapper.js"), path.join(outDir, "wrapper.js"));
+
+	/**
+	 * Loose files sit NEXT TO the .amxd in the installed folder, as real files.
+	 *
+	 * Needed when a Max object resolves a filename when it INSTANTIATES - before
+	 * the wrapper has run and before it could have extracted anything. Such an
+	 * object cannot be repointed at runtime, so the file has to be on disk under
+	 * exactly the name the object was created with. The embedded payload of the
+	 * same file is then only a fallback for a bare .amxd copied on its own.
+	 */
+	const loose = [...new Set(devices.flatMap((d) => d.looseFiles ?? []))];
+	for (const f of loose) {
+		await copyFile(path.join(root, f), path.join(outDir, path.basename(f)));
+		console.log(`m4l-jweb: ${path.basename(f)} -> dist/${name}/ (loose)`);
+	}
+
+	// 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));
+
+	const zipPath = path.join(dist, `${name}.zip`);
+	await new Promise((resolve, reject) => {
+		const output = createWriteStream(zipPath);
+		const archive = archiver("zip", { zlib: { level: 9 } });
+		output.on("close", resolve);
+		archive.on("error", reject);
+		archive.pipe(output);
+		const files = [...devices.map((d) => `${d.name}.amxd`), ...loose.map((f) => path.basename(f)), "wrapper.js", UI_NAME];
+		for (const f of files) {
+			archive.append(createReadStream(path.join(outDir, f)), { name: `${name}/${f}` });
+		}
+		for (const f of installers) {
+			archive.file(path.join(templates, f), { name: f, mode: 0o755 });
+		}
+		archive.finalize();
+	});
+
+	const { size } = await stat(zipPath);
+	console.log(`m4l-jweb: dist/${name}.zip (${size} bytes)`);
+}
+
+export async function buildAll(root) {
+	buildWrapper(root);
+	await generatePatchers(root);
+	await packageDevices(root);
+}
+
+/* ------------------------------------------------------------------ *
+ * Install
+ *
+ * Copy the built devices into Ableton's User Library. The per-platform scripts
+ * are the real implementation (they have to read Live's own config files to find
+ * the library); this just picks the right one and passes the device name.
+ *
+ * Live has no Linux build, so there is nothing to install there.
+ * ------------------------------------------------------------------ */
+export async function installDevices(root) {
+	const { name } = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+
+	if (!existsSync(path.join(root, "dist", name))) {
+		throw new Error(`nothing built at dist/${name} - run \`pnpm build\` first`);
+	}
+
+	// The packaged scripts are the real implementation - they have to read Live's
+	// own config files to locate the User Library. Pass the device name and the
+	// built folder explicitly, since the script does not live in the repo.
+	const src = path.join(root, "dist", name);
+	const runners = {
+		win32: [
+			"powershell",
+			["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", path.join(templates, "install-windows.ps1"), "-DeviceName", name, "-Src", src],
+		],
+		darwin: ["bash", [path.join(templates, "install-mac.sh"), name, src]],
+	};
+	const runner = runners[process.platform];
+	if (!runner) {
+		throw new Error(`no installer for ${process.platform} - Ableton Live runs on macOS and Windows only`);
+	}
+
+	execFileSync(runner[0], runner[1], { stdio: "inherit", cwd: root });
+}

package/src/init.mjs

@@ -0,0 +1,52 @@
+/**
+ * init.mjs - `m4l-jweb init [dir] [--name <name>]`: scaffold a new device repo.
+ *
+ * The template lives in templates/starter/ and is not a hand-maintained copy:
+ * it mirrors this repo's own root app (src/app/, patcher/devices.mjs, the
+ * config files), which is itself a working hello-world device built on
+ * @m4l-jweb/bridge and @m4l-jweb/build. Keeping the template that close to a
+ * real, CI-built app is what keeps it from drifting out of sync with the
+ * library - change the shape of a real device, then port the same change
+ * into templates/starter/ in the same commit.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const starter = path.join(pkgDir, "templates", "starter");
+
+function walk(dir) {
+	const out = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(p));
+		else out.push(p);
+	}
+	return out;
+}
+
+export async function initProject(cwd, args = []) {
+	const positional = args.filter((a) => !a.startsWith("--"));
+	const nameFlagIndex = args.indexOf("--name");
+	const target = positional[0] ? path.resolve(cwd, positional[0]) : cwd;
+	const name = nameFlagIndex >= 0 ? args[nameFlagIndex + 1] : path.basename(target);
+
+	if (existsSync(target) && readdirSync(target).length > 0) {
+		throw new Error(`${target} is not empty - init needs an empty (or new) directory`);
+	}
+	mkdirSync(target, { recursive: true });
+
+	const files = walk(starter);
+	for (const src of files) {
+		const rel = path.relative(starter, src);
+		const dest = path.join(target, rel);
+		mkdirSync(path.dirname(dest), { recursive: true });
+		const contents = readFileSync(src, "utf8").replaceAll("{{name}}", name);
+		writeFileSync(dest, contents);
+	}
+
+	console.log(`m4l-jweb: scaffolded "${name}" at ${target} (${files.length} files)`);
+	console.log(`m4l-jweb: next steps:\n  cd ${path.relative(cwd, target) || "."}\n  pnpm install\n  pnpm dev`);
+	return target;
+}

package/templates/base.json

@@ -0,0 +1,120 @@
+{
+	"patcher": {
+		"fileversion": 1,
+		"appversion": {
+			"major": 9,
+			"minor": 1,
+			"revision": 4,
+			"architecture": "x64",
+			"modernui": 1
+		},
+		"classnamespace": "box",
+		"rect": [100.0, 100.0, 700.0, 360.0],
+		"openinpresentation": 1,
+		"openrect": [0.0, 0.0, 0.0, 169.0],
+		"openrectmode": 0,
+		"default_fontsize": 10.0,
+		"default_fontname": "Arial Bold",
+		"gridsize": [8.0, 8.0],
+		"boxanimatetime": 500,
+		"boxes": [
+			{
+				"box": {
+					"id": "obj-midiin",
+					"maxclass": "newobj",
+					"numinlets": 1,
+					"numoutlets": 1,
+					"outlettype": ["int"],
+					"patching_rect": [480.0, 24.0, 40.0, 20.0],
+					"text": "midiin"
+				}
+			},
+			{
+				"box": {
+					"id": "obj-midiout",
+					"maxclass": "newobj",
+					"numinlets": 1,
+					"numoutlets": 0,
+					"patching_rect": [480.0, 64.0, 47.0, 20.0],
+					"text": "midiout"
+				}
+			},
+			{
+				"box": {
+					"id": "obj-thisdevice",
+					"maxclass": "newobj",
+					"numinlets": 1,
+					"numoutlets": 3,
+					"outlettype": ["bang", "int", "int"],
+					"patching_rect": [16.0, 24.0, 71.0, 20.0],
+					"text": "live.thisdevice"
+				}
+			},
+			{
+				"box": {
+					"id": "obj-js",
+					"maxclass": "newobj",
+					"numinlets": 1,
+					"numoutlets": 2,
+					"outlettype": ["", ""],
+					"patching_rect": [16.0, 64.0, 78.0, 20.0],
+					"saved_object_attributes": {
+						"filename": "wrapper.js",
+						"parameter_enable": 0
+					},
+					"text": "js wrapper.js"
+				}
+			},
+			{
+				"box": {
+					"disablefind": 0,
+					"id": "obj-jweb",
+					"maxclass": "jweb",
+					"numinlets": 1,
+					"numoutlets": 1,
+					"outlettype": [""],
+					"patching_rect": [16.0, 104.0, 400.0, 169.0],
+					"presentation": 1,
+					"presentation_rect": [0.0, 0.0, 420.0, 169.0],
+					"rendermode": 1
+				}
+			}
+		],
+		"lines": [
+			{ "patchline": { "destination": ["obj-midiout", 0], "source": ["obj-midiin", 0] } },
+			{ "patchline": { "destination": ["obj-js", 0], "source": ["obj-thisdevice", 0] } },
+			{ "patchline": { "destination": ["obj-jweb", 0], "source": ["obj-js", 0] } },
+			{ "patchline": { "destination": ["obj-js", 0], "source": ["obj-jweb", 0] } }
+		],
+		"latency": 0,
+		"is_mpe": 0,
+		"external_mpe_tuning_enabled": 0,
+		"minimum_live_version": "",
+		"minimum_max_version": "",
+		"platform_compatibility": 0,
+		"project": {
+			"version": 1,
+			"creationdate": 3864900000,
+			"modificationdate": 3864900000,
+			"viewrect": [0.0, 0.0, 300.0, 500.0],
+			"autoorganize": 1,
+			"hideprojectwindow": 1,
+			"showdependencies": 1,
+			"autolocalize": 0,
+			"contents": {
+				"patchers": {}
+			},
+			"layout": {},
+			"searchpath": {},
+			"detailsvisible": 0,
+			"amxdtype": 1835887981,
+			"readonly": 0,
+			"devpathtype": 0,
+			"devpath": ".",
+			"sortmode": 0,
+			"viewmode": 0,
+			"includepackages": 0
+		},
+		"autosave": 0
+	}
+}

package/templates/install-mac.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# install-mac.sh - copy the built devices into the Ableton User Library
+# (Max For Live/m4l-jweb), replacing any previous install.
+#
+# The User Library path is read from the newest Live preferences file
+# (~/Library/Preferences/Ableton/Live */Library.cfg, <ProjectPath>); Live's
+# default location is the fallback.
+#
+# The device-folder name defaults to this repo's, and `m4l-jweb install` passes
+# the package name explicitly - so a repo scaffolded under another name works.
+#
+# usage: install-mac.sh [device-name] [src-dir]
+# `m4l-jweb install` passes both; standalone (from the zip) both are inferred.
+set -euo pipefail
+device_name="${1:-m4l-jweb}"
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source: an explicit second argument, else ./<name> next to this script (zip and
+# dist layouts), else ../dist/<name> (running it straight from a repo checkout).
+src="${2:-}"
+if [ -z "$src" ]; then
+	src="$here/$device_name"
+	[ -d "$src" ] || src="$(dirname "$here")/dist/$device_name"
+fi
+if ! compgen -G "$src/*.amxd" > /dev/null; then
+	echo "No .amxd found next to this script or in dist/. Run 'pnpm build' first." >&2
+	exit 1
+fi
+
+user_lib=""
+cfg="$(ls -t ~/Library/Preferences/Ableton/Live\ */Library.cfg 2>/dev/null | head -1 || true)"
+if [ -n "$cfg" ]; then
+	p="$(sed -n 's/.*<ProjectPath Value="\([^"]*\)".*/\1/p' "$cfg" | head -1)"
+	if [ -n "$p" ] && [ -d "$p/User Library" ]; then
+		user_lib="$p/User Library"
+	elif [ -n "$p" ] && [ -d "$p" ]; then
+		user_lib="$p"
+	fi
+fi
+[ -n "$user_lib" ] || user_lib="$HOME/Music/Ableton/User Library"
+if [ ! -d "$user_lib" ]; then
+	echo "Ableton User Library not found ($user_lib). Is Live installed?" >&2
+	exit 1
+fi
+
+dest="$user_lib/Max For Live/$device_name"
+rm -rf "$dest"
+mkdir -p "$dest"
+
+# Each .amxd is self-contained: the UI rides inside it as a payload in wrapper.js.
+for f in "$src"/*.amxd; do
+	cp "$f" "$dest/"
+	echo "  installed $(basename "$f")"
+done
+
+echo "Installed to $dest"
+echo "In Live: User Library > Max For Live > $device_name"
+echo "NOTE: Live embeds a copy of the device in the set. Instances already"
+echo "      on a track will NOT update - delete and re-drag them."

package/templates/install-windows.ps1

@@ -0,0 +1,64 @@
+# install-windows.ps1 - copy the built devices into the Ableton User Library
+# (Max For Live\m4l-jweb), replacing any previous install.
+#
+# The User Library path is read from the newest Live preferences file
+# (%APPDATA%\Ableton\Live <version>\Preferences\Library.cfg, <ProjectPath>);
+# Live's default location is the fallback. No registry or env vars are involved -
+# Live keeps all of this in plain config files.
+#
+# The device-folder name defaults to this repo's, and `m4l-jweb install` passes
+# the package name explicitly - so a repo scaffolded under another name works.
+# -Src is passed by `m4l-jweb install`; standalone (from the zip) it is found
+# next to this script.
+param([string]$DeviceName = "m4l-jweb", [string]$Src = "")
+$ErrorActionPreference = "Stop"
+$deviceName = $DeviceName
+
+# Source: an explicit -Src, else ./<name> next to this script (zip and dist
+# layouts), else ../dist/<name> (running it straight from a repo checkout).
+$src = $Src
+if (-not $src) {
+    $src = Join-Path $PSScriptRoot $deviceName
+    if (-not (Test-Path $src)) {
+        $src = Join-Path (Split-Path $PSScriptRoot) "dist\$deviceName"
+    }
+}
+$devices = @(Get-ChildItem (Join-Path $src "*.amxd") -ErrorAction SilentlyContinue)
+if ($devices.Count -eq 0) {
+    Write-Error "No .amxd found next to this script or in dist\. Run 'pnpm build' first."
+}
+
+# User Library: newest Library.cfg wins.
+$userLib = $null
+$cfg = Get-ChildItem "$env:APPDATA\Ableton\Live *\Preferences\Library.cfg" -ErrorAction SilentlyContinue |
+    Sort-Object LastWriteTime -Descending | Select-Object -First 1
+if ($cfg) {
+    $m = [regex]::Match((Get-Content $cfg.FullName -Raw), '<ProjectPath Value="([^"]+)"')
+    if ($m.Success) {
+        $p = $m.Groups[1].Value -replace "/", "\"
+        # ProjectPath may point at the library root that contains "User Library".
+        if (Test-Path (Join-Path $p "User Library")) { $userLib = Join-Path $p "User Library" }
+        elseif (Test-Path $p) { $userLib = $p }
+    }
+}
+if (-not $userLib) {
+    $userLib = Join-Path ([Environment]::GetFolderPath("MyDocuments")) "Ableton\User Library"
+}
+if (-not (Test-Path $userLib)) {
+    Write-Error "Ableton User Library not found ($userLib). Is Live installed?"
+}
+
+$dest = Join-Path $userLib "Max For Live\$deviceName"
+if (Test-Path $dest) { Remove-Item $dest -Recurse -Force }
+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)"
+}
+
+Write-Host "Installed to $dest"
+Write-Host "In Live: User Library > Max For Live > $deviceName"
+Write-Host "NOTE: Live embeds a copy of the device in the set. Instances already"
+Write-Host "      on a track will NOT update - delete and re-drag them."

package/templates/starter/README.md

@@ -0,0 +1,21 @@
+# {{name}}
+
+A Max for Live device, scaffolded with `m4l-jweb init`. See the
+[M4L-JWEB docs](https://github.com/alienmind/m4l-jweb) for the architecture
+this repo builds on.
+
+```bash
+pnpm install
+pnpm dev              # browser dev with the Max bridge simulated
+pnpm build            # emits dist/{{name}}/<device>.amxd + release zip
+pnpm test             # ES5 gate + protocol lint
+pnpm install:device    # copy the built device into Ableton's User Library
+```
+
+You edit two places:
+
+- `src/app/` - the web app (UI, optional worker, `protocol.ts`).
+- `patcher/devices.mjs` - the device manifest (name, type, chains, parameters).
+
+Everything else (`@m4l-jweb/wrapper`, `@m4l-jweb/build`) is packaged
+infrastructure you should rarely need to touch.

package/templates/starter/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>{{name}}</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>