@m4l-jweb/build 0.1.0

package/bin/m4l-jweb.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * m4l-jweb - the device build CLI.
+ *
+ *   m4l-jweb init       scaffold a new device repo from templates/starter/
+ *   m4l-jweb build      wrapper + patchers + package (the usual one)
+ *   m4l-jweb wrapper    compile wrapper/*.ts to one ES5 script, acorn-gated
+ *   m4l-jweb patchers   manifest -> one patcher JSON per device
+ *   m4l-jweb package    write each .amxd + the release zip
+ *   m4l-jweb install    copy the built devices into Ableton's User Library
+ *
+ * Run from a device repo. Bundling the UI (`vite build`) is the app's job and
+ * stays in the repo's own npm scripts; everything Max-shaped lives here.
+ */
+import { buildAll, buildWrapper, generatePatchers, installDevices, packageDevices } from "../src/index.mjs";
+import { initProject } from "../src/init.mjs";
+
+const commands = {
+	init: (root, args) => initProject(root, args),
+	build: buildAll,
+	wrapper: async (root) => void buildWrapper(root),
+	patchers: async (root) => void (await generatePatchers(root)),
+	package: packageDevices,
+	install: installDevices,
+};
+
+const cmd = process.argv[2] ?? "build";
+const run = commands[cmd];
+
+if (!run) {
+	console.error(`m4l-jweb: unknown command "${cmd}"\nusage: m4l-jweb [${Object.keys(commands).join(" | ")}]`);
+	process.exit(1);
+}
+
+try {
+	await run(process.cwd(), process.argv.slice(3));
+} catch (e) {
+	console.error(`m4l-jweb: ${e.message}`);
+	process.exit(1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@m4l-jweb/build",
+  "version": "0.1.0",
+  "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alienmind/m4l-jweb.git",
+    "directory": "packages/build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "m4l-jweb": "./bin/m4l-jweb.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./chains": "./src/chains.mjs",
+    "./amxd": "./src/amxd.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "dependencies": {
+    "acorn": "^8.17.0",
+    "archiver": "^7.0.1",
+    "typescript": "^5.7.0",
+    "@m4l-jweb/wrapper": "0.1.0"
+  }
+}

package/src/amxd.mjs

@@ -0,0 +1,178 @@
+/**
+ * amxd.mjs - write a Max for Live .amxd container, headless. No Max in the loop.
+ *
+ * The format is undocumented but simple, reverse-engineered from devices saved
+ * by Max 8/9:
+ *
+ *   'ampf' <u32le 4> <'aaaa'|'mmmm'|'iiii'>   audio / midi / instrument
+ *   'meta' <u32le 4> <u32le 7>
+ *   'ptch' <u32le size-to-EOF>
+ *     'mx@c' <u32be 16> <u32be 0> <u32be 16 + payload sizes (excl. dlst)>
+ *     <patcher JSON> <dependency payloads...>
+ *     'dlst' <u32be chunk size incl. header>   directory: one 'dire' per file
+ *
+ * The device is written "frozen", with the wrapper embedded (the same shape Max
+ * produces when you freeze), so Max never resolves it via a search path. The
+ * internal main-patcher name is set to the output file's basename.
+ *
+ * This is the piece that removes Max from the loop entirely.
+ */
+import { parse } from "acorn";
+
+/** 'aaaa' audio effect / 'mmmm' MIDI effect / 'iiii' instrument. */
+export const AMXD_TYPES = {
+	midi: 0x6d6d6d6d,
+	audio: 0x61616161,
+	instrument: 0x69696969,
+};
+
+const TAG_BY_CODE = { 0x61616161: "aaaa", 0x6d6d6d6d: "mmmm", 0x69696969: "iiii" };
+
+/**
+ * Max's [js] is an ES5-era interpreter: one modern token (an arrow function, a
+ * `const`, a trailing comma in a call) kills the whole script at load with a
+ * bare "syntax error" and no stack. So ES5 is a build GATE, not a style
+ * preference. Call this on the exact bytes that will ship.
+ */
+export function assertES5(js, label = "wrapper") {
+	try {
+		parse(js, { ecmaVersion: 5 });
+	} catch (e) {
+		throw new Error(`${label} is not valid ES5: ${e.message}`);
+	}
+}
+
+/**
+ * Encode a Buffer as base64 chunks assigned to `<prefix>_B64`, plus its name and
+ * byte count, as ES5 source appended to the wrapper.
+ *
+ * Why: Chromium (jweb) cannot read Max's frozen virtual filesystem, so a UI
+ * frozen into the device is invisible to it. The wrapper, however, always runs -
+ * so it carries the payload and writes it to a real file on first load.
+ */
+export function payloadJs(prefix, name, buf) {
+	const CHUNK = 30000; // multiple of 3 -> each chunk is padding-free base64
+	const chunks = [];
+	for (let i = 0; i < buf.length; i += CHUNK) {
+		chunks.push(JSON.stringify(buf.subarray(i, i + CHUNK).toString("base64")));
+	}
+	return (
+		`\n// ---- generated: embedded ${prefix} payload ----\n` +
+		`var ${prefix}_NAME = ${JSON.stringify(name)};\n` +
+		`var ${prefix}_BYTES = ${buf.length};\n` +
+		`var ${prefix}_B64 = [\n${chunks.join(",\n")}\n];\n`
+	);
+}
+
+/**
+ * Additional self-extracting payloads, beyond the UI.
+ *
+ * Same reasoning as the UI payload: anything that is NOT a Max-native object
+ * (an external process, a Node bundle, a data file read by the web app) cannot
+ * see a frozen dependency, so it has to become a real file on disk. The wrapper
+ * writes each of these next to the .amxd on load - see extractExtraPayloads() in
+ * the wrapper's core.ts.
+ */
+export function extraPayloadsJs(payloads) {
+	const names = payloads.map((p) => JSON.stringify(p.name));
+	const bytes = payloads.map((p) => p.data.length);
+	const blobs = payloads.map((p) => {
+		const CHUNK = 30000;
+		const chunks = [];
+		for (let i = 0; i < p.data.length; i += CHUNK) {
+			chunks.push(JSON.stringify(p.data.subarray(i, i + CHUNK).toString("base64")));
+		}
+		return `[\n${chunks.join(",\n")}\n]`;
+	});
+	return (
+		`\n// ---- generated: ${payloads.length} extra payload(s) ----\n` +
+		`var EXTRA_PAYLOAD_NAMES = [${names.join(", ")}];\n` +
+		`var EXTRA_PAYLOAD_BYTES = [${bytes.join(", ")}];\n` +
+		`var EXTRA_PAYLOAD_B64 = [\n${blobs.join(",\n")}\n];\n`
+	);
+}
+
+const u32be = (n) => {
+	const b = Buffer.alloc(4);
+	b.writeUInt32BE(n >>> 0);
+	return b;
+};
+const u32le = (n) => {
+	const b = Buffer.alloc(4);
+	b.writeUInt32LE(n >>> 0);
+	return b;
+};
+const field = (tag, payload) => Buffer.concat([Buffer.from(tag, "latin1"), u32be(8 + payload.length), payload]);
+const paddedName = (name) => {
+	const raw = Buffer.from(name + "\0", "latin1");
+	return Buffer.concat([raw, Buffer.alloc((4 - (raw.length % 4)) % 4)]);
+};
+
+/**
+ * Build the .amxd bytes.
+ *
+ * @param {object}   o
+ * @param {string}   o.patcherJson  the patcher, as JSON text
+ * @param {string}   o.wrapperJs    the ES5 wrapper (payloads already appended)
+ * @param {string}   o.deviceName   basename of the output file, e.g. "my-device.amxd"
+ * @param {Array<{name,data,type?}>} [o.extras]  extra frozen dependencies
+ * @returns {Buffer}
+ */
+export function buildAmxd({ patcherJson, wrapperJs, deviceName, extras = [] }) {
+	assertES5(wrapperJs, "wrapper.js");
+
+	const amxdtype = JSON.parse(patcherJson).patcher?.project?.amxdtype;
+	const deviceTag = TAG_BY_CODE[amxdtype];
+	if (!deviceTag) throw new Error(`unknown project.amxdtype ${amxdtype}`);
+
+	const macDate = Math.floor(Date.now() / 1000) + 2082844800; // secs since 1904-01-01
+
+	const files = [
+		{ type: "JSON", name: deviceName, data: Buffer.from(patcherJson, "utf8"), flag: 0x11 },
+		{ type: "TEXT", name: "wrapper.js", data: Buffer.from(wrapperJs, "utf8"), flag: 0 },
+		...extras.map((e) => ({
+			type: e.type ?? (/\.(maxpat|json)$/.test(e.name) ? "JSON" : "TEXT"),
+			name: e.name,
+			data: e.data,
+			flag: 0,
+		})),
+	];
+
+	// Payload region: the patcher JSON first, at offset 16 (right after mx@c).
+	let offset = 16;
+	const entries = [];
+	for (const f of files) {
+		const at = offset;
+		offset += f.data.length;
+		entries.push(
+			field(
+				"dire",
+				Buffer.concat([
+					field("type", Buffer.from(f.type, "latin1")),
+					field("fnam", paddedName(f.name)),
+					field("sz32", u32be(f.data.length)),
+					field("of32", u32be(at)),
+					field("vers", u32be(0)),
+					field("flag", u32be(f.flag)),
+					field("mdat", u32be(macDate)),
+				]),
+			),
+		);
+	}
+
+	const payload = Buffer.concat(files.map((f) => f.data));
+	const mxc = Buffer.concat([Buffer.from("mx@c", "latin1"), u32be(16), u32be(0), u32be(16 + payload.length)]);
+	const ptchBody = Buffer.concat([mxc, payload, field("dlst", Buffer.concat(entries))]);
+
+	return Buffer.concat([
+		Buffer.from("ampf", "latin1"),
+		u32le(4),
+		Buffer.from(deviceTag, "latin1"),
+		Buffer.from("meta", "latin1"),
+		u32le(4),
+		u32le(7),
+		Buffer.from("ptch", "latin1"),
+		u32le(ptchBody.length),
+		ptchBody,
+	]);
+}

package/src/chains.mjs

@@ -0,0 +1,184 @@
+/**
+ * chains.mjs - the box()/line() DSL and the canned chain vocabulary.
+ *
+ * A patcher is just JSON: `boxes` (objects, e.g. "route midinote flush") and
+ * `lines` (cords: [sourceBox, outlet] -> [destBox, inlet]). So we never draw
+ * one - we generate it. Patch cords become code review.
+ *
+ * A chain is a small function that claims [jweb]'s outlet, routes the selectors
+ * it owns, and passes everything else on to `unmatchedTo`. Add your own with
+ * `registerChain()`; keep them small and named after what they do.
+ */
+
+let y = 300; // stack generated objects below the hand-made ones
+
+/** Reset the layout cursor. The build calls this once per device. */
+export function resetLayout() {
+	y = 300;
+}
+
+export const box = (id, text, extra = {}) => ({
+	box: {
+		id,
+		maxclass: "newobj",
+		text,
+		numinlets: 1,
+		numoutlets: 1,
+		outlettype: [""],
+		patching_rect: [16, (y += 32), 220, 20],
+		...extra,
+	},
+});
+
+export const line = (srcId, srcOut, dstId, dstIn) => ({
+	patchline: { source: [srcId, srcOut], destination: [dstId, dstIn] },
+});
+
+/** Drop every cord touching a box, then the box. */
+export function removeBox(boxes, lines, id) {
+	const i = boxes.findIndex((b) => b.box.id === id);
+	if (i >= 0) boxes.splice(i, 1);
+	for (let j = lines.length - 1; j >= 0; j--) {
+		const pl = lines[j].patchline;
+		if (pl.source[0] === id || pl.destination[0] === id) lines.splice(j, 1);
+	}
+}
+
+/** Drop a specific cord (used when a chain takes over jweb's output). */
+export function removeLine(lines, srcId, dstId) {
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const pl = lines[i].patchline;
+		if (pl.source[0] === srcId && pl.destination[0] === dstId) lines.splice(i, 1);
+	}
+}
+
+/**
+ * "midiin" - feed incoming MIDI notes to the app as `notein <pitch> <velocity>`.
+ *
+ * Also CUTS the template's direct midiin -> midiout thru cord: a device that
+ * transforms notes must not also leak the untransformed ones.
+ */
+function midiInChain({ boxes, lines, jwebId }) {
+	removeLine(lines, "obj-midiin", "obj-midiout");
+	boxes.push(
+		box("obj-midiparse", "midiparse", {
+			numinlets: 1,
+			numoutlets: 8,
+			outlettype: ["list", "list", "int", "int", "int", "list", "int", ""],
+		}),
+	);
+	boxes.push(box("obj-noteinmsg", "prepend notein"));
+	lines.push(line("obj-midiin", 0, "obj-midiparse", 0));
+	lines.push(line("obj-midiparse", 0, "obj-noteinmsg", 0)); // outlet 0 = note: pitch, velocity
+	lines.push(line("obj-noteinmsg", 0, jwebId, 0));
+}
+
+/**
+ * "midiout" - the app emits `midinote <pitch> <vel> <durMs> <chan> <delayMs>`
+ * and `flush`. Compute WHEN in your app; let Max place the note precisely.
+ */
+function midiOutChain({ boxes, lines, jwebId, unmatchedId }) {
+	// This chain consumes jweb's output, so the template's direct jweb -> js cord
+	// is replaced by the route's unmatched outlet.
+	removeLine(lines, jwebId, unmatchedId);
+
+	boxes.push(box("obj-route", "route midinote flush", { numoutlets: 3, outlettype: ["", "", ""] }));
+	// Explicit unpack instead of letting pipe spread the list: unpack fires
+	// right-to-left, so the delay (outlet 4) lands in pipe's delay inlet BEFORE
+	// the pitch (outlet 0) hits the hot inlet.
+	boxes.push(
+		box("obj-unpack", "unpack 0 0 0 0 0", {
+			numinlets: 1,
+			numoutlets: 5,
+			outlettype: ["int", "int", "int", "int", "int"],
+		}),
+	);
+	boxes.push(
+		box("obj-pipe", "pipe 0 0 0 0 0", {
+			numinlets: 5, // 4 data inlets + delay
+			numoutlets: 4,
+			outlettype: ["int", "int", "int", "int"],
+		}),
+	);
+	boxes.push(box("obj-makenote", "makenote 100 250", { numinlets: 3, numoutlets: 2, outlettype: ["int", "int"] }));
+	boxes.push(box("obj-packnote", "pack 0 0", { numinlets: 2, numoutlets: 1, outlettype: [""] }));
+	boxes.push(box("obj-fmt", "midiformat", { numinlets: 7, numoutlets: 1, outlettype: ["int"] }));
+	// `route` STRIPS the selector: a bare "flush" emerges from outlet 1 as a bang,
+	// which makenote ignores. Re-materialize the word with a message box so
+	// makenote actually releases hanging notes.
+	boxes.push(box("obj-flushmsg", "flush", { maxclass: "message", numinlets: 2, numoutlets: 1 }));
+
+	lines.push(line(jwebId, 0, "obj-route", 0));
+	lines.push(line("obj-route", 0, "obj-unpack", 0));
+	lines.push(line("obj-route", 1, "obj-flushmsg", 0));
+	lines.push(line("obj-flushmsg", 0, "obj-makenote", 0));
+	for (let i = 0; i < 5; i++) lines.push(line("obj-unpack", i, "obj-pipe", i));
+	lines.push(line("obj-pipe", 0, "obj-makenote", 0)); // pitch
+	lines.push(line("obj-pipe", 1, "obj-makenote", 1)); // velocity
+	lines.push(line("obj-pipe", 2, "obj-makenote", 2)); // duration ms
+	lines.push(line("obj-pipe", 3, "obj-fmt", 6)); // channel
+	lines.push(line("obj-makenote", 0, "obj-packnote", 0));
+	lines.push(line("obj-makenote", 1, "obj-packnote", 1));
+	lines.push(line("obj-packnote", 0, "obj-fmt", 0));
+	lines.push(line("obj-fmt", 0, "obj-midiout", 0));
+	// Unmatched selectors (ui_ready, write_clip, read_notes...) carry on.
+	lines.push(line("obj-route", 2, unmatchedId, 0));
+}
+
+/** "passthrough" - an audio effect that passes its input through untouched. */
+function passthroughChain({ boxes, lines }) {
+	// An audio effect has no MIDI ports.
+	removeBox(boxes, lines, "obj-midiin");
+	removeBox(boxes, lines, "obj-midiout");
+	boxes.push(box("obj-plugin", "plugin~", { numinlets: 1, numoutlets: 2, outlettype: ["signal", "signal"] }));
+	boxes.push(box("obj-plugout", "plugout~", { numinlets: 2, numoutlets: 0 }));
+	lines.push(line("obj-plugin", 0, "obj-plugout", 0));
+	lines.push(line("obj-plugin", 1, "obj-plugout", 1));
+}
+
+export const CHAINS = {
+	midiin: midiInChain,
+	midiout: midiOutChain,
+	passthrough: passthroughChain,
+};
+
+/** Add a chain to the vocabulary. Called before generatePatchers(). */
+export function registerChain(name, fn) {
+	CHAINS[name] = fn;
+}
+
+/**
+ * Real Live parameters: automatable, MIDI-mappable, and the ONLY thing Push can
+ * display. Each becomes a live.* object wired into the UI as `<id> <value>`, so
+ * a parameter change is just another inlet message to your app.
+ */
+export function addParameters(boxes, lines, params, dstId) {
+	let x = 480;
+	for (const p of params) {
+		const objId = `obj-param-${p.id}`;
+		const prependId = `obj-prepend-${p.id}`;
+		boxes.push({
+			box: {
+				id: objId,
+				maxclass: p.object, // live.dial | live.toggle | live.menu
+				numinlets: 1,
+				numoutlets: 1,
+				outlettype: [""],
+				parameter_enable: 1,
+				patching_rect: [x, 300, 44, 48],
+				saved_attribute_attributes: {
+					valueof: {
+						parameter_longname: p.id,
+						parameter_shortname: p.id.slice(0, 8), // Push shows short names
+						parameter_type: p.object === "live.toggle" ? 2 : 0, // 2 = enum, 0 = float
+						...(p.range ? { parameter_range: p.range } : {}),
+					},
+				},
+			},
+		});
+		boxes.push(box(prependId, `prepend ${p.id}`));
+		lines.push(line(objId, 0, prependId, 0));
+		lines.push(line(prependId, 0, dstId, 0));
+		x += 56;
+	}
+}