@m4l-jweb/build 0.1.0

package/templates/starter/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "{{name}}",
+	"private": true,
+	"version": "0.1.0",
+	"type": "module",
+	"description": "A Max for Live device built with M4L-JWEB.",
+	"scripts": {
+		"dev": "vite --host 127.0.0.1 --port 5175",
+		"build": "tsc -b && vite build && m4l-jweb build",
+		"build:wrapper": "m4l-jweb wrapper",
+		"build:patchers": "m4l-jweb patchers",
+		"install:device": "m4l-jweb install",
+		"preview": "vite preview --host 127.0.0.1 --port 4175",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@m4l-jweb/bridge": "^0.1.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"devDependencies": {
+		"@m4l-jweb/build": "^0.1.0",
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.0.0",
+		"@vitejs/plugin-react": "^4.3.4",
+		"typescript": "^5.7.0",
+		"vite": "^6.0.0",
+		"vite-plugin-singlefile": "^2.1.0",
+		"vitest": "^2.1.0"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"esbuild"
+		]
+	}
+}

package/templates/starter/patcher/devices.mjs

@@ -0,0 +1,32 @@
+/**
+ * devices.mjs - the device manifest. THIS is what you edit to change the shape
+ * of a device; the patcher itself is generated from it (see
+ * @m4l-jweb/build). Patch cords become code review.
+ *
+ * Fields
+ *   name        output basename -> dist/<pkg>/<name>.amxd
+ *   type        "midi" (MIDI effect) | "instrument" | "audio" (audio effect)
+ *   chains      canned wiring, applied in order. Vocabulary:
+ *                 "midiout"     jweb -> route midinote -> pipe -> makenote
+ *                               -> midiformat -> midiout. The app emits
+ *                               `midinote <pitch> <vel> <durMs> <chan> <delayMs>`;
+ *                               it computes WHEN, Max places it precisely.
+ *                 "passthrough" plugin~ -> plugout~ (an audio effect that
+ *                               passes its input through untouched).
+ *   parameters  real Live parameters: automatable, MIDI-mappable, and the ONLY
+ *               thing Push can show. Each becomes a live.* object wired into
+ *               the UI as `<id> <value>`. No custom UI reaches Push - not
+ *               yours, not anyone's - so put every musically meaningful control
+ *               here as well as in the web UI.
+ *   unmatchedTo where messages the chains did not consume go. "js" sends them
+ *               to the wrapper (ui_ready, write_clip, read_notes, ...).
+ */
+export default [
+	{
+		name: "{{name}}",
+		type: "midi",
+		chains: ["midiout"],
+		parameters: [{ id: "running", object: "live.toggle" }],
+		unmatchedTo: "js",
+	},
+];

package/templates/starter/src/app/App.tsx

@@ -0,0 +1,87 @@
+/**
+ * App.tsx - the jweb UI. A hello-world React page wired to the Max bridge.
+ *
+ * It demonstrates the whole device loop end to end:
+ *   - announce `ui_ready` on mount and show the state the wrapper replies with
+ *     (mode, build stamp, tempo, transport ticks);
+ *   - forward each transport tick into an optional Web Worker and render the
+ *     count the worker sends back;
+ *   - flag a stale install when the wrapper's build stamp does not match the
+ *     one baked into this page.
+ *
+ * Replace the body with your device UI. The bridge surface never changes.
+ */
+import { useEffect, useRef, useState } from "react";
+import { bindInlet, inJweb, uiReady } from "@m4l-jweb/bridge";
+import { IN } from "./protocol";
+import DemoWorker from "./worker.ts?worker&inline";
+
+declare const __APP_VERSION__: string;
+
+export default function App() {
+	const [mode, setMode] = useState("dev");
+	const [wrapperBuild, setWrapperBuild] = useState<string | null>(null);
+	const [tempo, setTempo] = useState<number | null>(null);
+	const [playing, setPlaying] = useState(false);
+	const [beats, setBeats] = useState(0);
+	const [workerTicks, setWorkerTicks] = useState(0);
+	const workerRef = useRef<Worker | null>(null);
+
+	useEffect(() => {
+		const worker = new DemoWorker();
+		worker.onmessage = (e: MessageEvent) => {
+			const [type, value] = e.data as [string, number];
+			if (type === "ticks") setWorkerTicks(value);
+		};
+		workerRef.current = worker;
+
+		bindInlet(IN.mode, (m) => setMode(String(m)));
+		bindInlet(IN.build, (b) => setWrapperBuild(String(b)));
+		bindInlet(IN.tempo, (bpm) => setTempo(Number(bpm)));
+		bindInlet(IN.tick, (isPlaying, position) => {
+			setPlaying(Number(isPlaying) === 1);
+			setBeats(Number(position));
+			worker.postMessage(["tick"]);
+		});
+
+		// Handshake: the page loads asynchronously, so never assume the wrapper
+		// already sent state - announce readiness and let it reply.
+		uiReady();
+
+		return () => worker.terminate();
+	}, []);
+
+	// The wrapper stamp is "<version> <iso date>"; the UI only bakes in the
+	// version. A mismatch means a mixed install: Live embeds a copy of the
+	// device in the set, so a reinstalled .amxd does NOT update instances
+	// already on tracks.
+	const stale = wrapperBuild !== null && wrapperBuild.split(" ")[0] !== __APP_VERSION__;
+
+	return (
+		<main className="device">
+			<header>
+				<h1>{{name}}</h1>
+				<span className={`badge ${inJweb ? "live" : "dev"}`}>{inJweb ? "in Max" : "browser dev"}</span>
+			</header>
+
+			<dl>
+				<dt>mode</dt>
+				<dd>{mode}</dd>
+				<dt>tempo</dt>
+				<dd>{tempo === null ? "-" : `${tempo.toFixed(1)} BPM`}</dd>
+				<dt>transport</dt>
+				<dd>
+					<span className={playing ? "dot on" : "dot"} /> {playing ? "playing" : "stopped"} @ {beats.toFixed(2)} beats
+				</dd>
+				<dt>worker ticks</dt>
+				<dd>{workerTicks}</dd>
+			</dl>
+
+			<footer>
+				<span>ui {__APP_VERSION__}</span>
+				<span>wrapper {wrapperBuild ?? "-"}</span>
+				{stale && <span className="warn">stale install - delete and re-drag the device</span>}
+			</footer>
+		</main>
+	);
+}

package/templates/starter/src/app/protocol.ts

@@ -0,0 +1,32 @@
+/**
+ * protocol.ts - the typed list of selectors crossing the UI <-> device bridge.
+ *
+ * This is the single source of truth for BOTH sides of the bridge:
+ *   - the web app binds/emits these selectors (via @m4l-jweb/bridge)
+ *   - the [js] wrapper and the generated patcher route these selectors
+ *
+ * A Max message is a selector word followed by arguments
+ * (e.g. `tick 1 12.5`). Keep selectors here so a CI lint can assert every one
+ * appears in a route or handler on the patcher/wrapper side.
+ */
+
+/** Selectors the DEVICE sends INTO the UI (bindInlet these). */
+export const IN = {
+	/** wrapper -> UI: current run mode (midi | audio | instrument). */
+	mode: "mode",
+	/** wrapper -> UI: build stamp, for the stale-install check. */
+	build: "build",
+	/** wrapper -> UI: transport state. args: `<playing 0|1> <beats>`. */
+	tick: "tick",
+	/** wrapper -> UI: Live tempo in BPM. args: `<bpm>`. */
+	tempo: "tempo",
+} as const;
+
+/** Selectors the UI sends OUT to the device (outlet these). */
+export const OUT = {
+	/** UI -> wrapper: page finished loading; reply with current state. */
+	ui_ready: "ui_ready",
+} as const;
+
+export type InSelector = (typeof IN)[keyof typeof IN];
+export type OutSelector = (typeof OUT)[keyof typeof OUT];

package/templates/starter/src/app/worker.ts

@@ -0,0 +1,26 @@
+/**
+ * worker.ts - optional compute worker (inlined into the single-file build).
+ *
+ * The place for anything that must not fight the UI thread: sequencers,
+ * analyzers, DSP-adjacent math. Dedicated workers are also exempt from the
+ * timer throttling Chromium applies to hidden pages - and a device's view is
+ * often not visible.
+ *
+ * This hello-world worker just counts the transport ticks it is fed and posts
+ * the running total back. Replace it with your own message-driven engine
+ * (Live pushes time in, you push events out) and delete it if you do not need
+ * a worker at all.
+ */
+
+let ticks = 0;
+
+self.onmessage = (e: MessageEvent) => {
+	const [type] = e.data as [string, ...unknown[]];
+	if (type === "tick") {
+		ticks += 1;
+		self.postMessage(["ticks", ticks]);
+	} else if (type === "reset") {
+		ticks = 0;
+		self.postMessage(["ticks", ticks]);
+	}
+};

package/templates/starter/src/index.css

@@ -0,0 +1,104 @@
+/*
+ * The Live device view is a FIXED height (about 169 px) - budget every row.
+ * An overgrown layout does not scroll, it silently clips at the bottom.
+ */
+:root {
+	--bg: #2f2f2f;
+	--fg: #d6d6d6;
+	--muted: #8a8a8a;
+	--accent: #6fd6a8;
+	--warn: #e8a33d;
+}
+
+* {
+	box-sizing: border-box;
+	margin: 0;
+	padding: 0;
+}
+
+body {
+	background: var(--bg);
+	color: var(--fg);
+	font: 11px/1.4 "Segoe UI", system-ui, sans-serif;
+	height: 169px;
+	overflow: hidden;
+}
+
+.device {
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+	height: 100%;
+	padding: 8px 10px;
+}
+
+header {
+	align-items: center;
+	border-bottom: 1px solid #444;
+	display: flex;
+	gap: 8px;
+	padding-bottom: 5px;
+}
+
+h1 {
+	font-size: 12px;
+	letter-spacing: 0.08em;
+}
+
+.badge {
+	border-radius: 3px;
+	font-size: 9px;
+	padding: 1px 5px;
+	text-transform: uppercase;
+}
+.badge.live {
+	background: var(--accent);
+	color: #1a1a1a;
+}
+.badge.dev {
+	background: #555;
+	color: var(--fg);
+}
+
+dl {
+	column-gap: 10px;
+	display: grid;
+	grid-template-columns: auto 1fr;
+	row-gap: 3px;
+}
+
+dt {
+	color: var(--muted);
+	text-transform: uppercase;
+	font-size: 9px;
+	align-self: center;
+}
+
+dd {
+	font-variant-numeric: tabular-nums;
+}
+
+.dot {
+	background: #666;
+	border-radius: 50%;
+	display: inline-block;
+	height: 6px;
+	width: 6px;
+}
+.dot.on {
+	background: var(--accent);
+}
+
+footer {
+	border-top: 1px solid #444;
+	color: var(--muted);
+	display: flex;
+	font-size: 9px;
+	gap: 10px;
+	margin-top: auto;
+	padding-top: 5px;
+}
+
+.warn {
+	color: var(--warn);
+}

package/templates/starter/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./app/App";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+	<StrictMode>
+		<App />
+	</StrictMode>,
+);

package/templates/starter/src/vite-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+// Injected by vite's `define` (see vite.config.ts) - the UI's own build stamp.
+declare const __APP_VERSION__: string;
+
+declare module "*?worker&inline" {
+	const workerConstructor: new () => Worker;
+	export default workerConstructor;
+}

package/templates/starter/tsconfig.app.json

@@ -0,0 +1,24 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"useDefineForClassFields": true,
+		"lib": ["ES2020", "DOM", "DOM.Iterable", "WebWorker"],
+		"module": "ESNext",
+		"skipLibCheck": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"resolveJsonModule": true,
+		"paths": {
+			"@/*": ["./src/*"]
+		},
+		"isolatedModules": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"jsx": "react-jsx",
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true
+	},
+	"include": ["src"]
+}

package/templates/starter/tsconfig.json

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

package/templates/starter/tsconfig.node.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["ES2023"],
+		"module": "ESNext",
+		"skipLibCheck": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"strict": true
+	},
+	"include": ["vite.config.ts", "patcher/**/*.mjs"]
+}

package/templates/starter/vite.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig } from "vite";
+import { fileURLToPath, URL } from "node:url";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+import pkg from "./package.json";
+
+// The device UI is bundled into ONE self-contained index.html (every script,
+// style and asset inlined) so it can be embedded in the .amxd as a base64
+// payload and extracted to a real file:// path that jweb (Chromium) reads.
+export default defineConfig({
+	base: "./",
+	plugins: [react(), viteSingleFile()],
+	resolve: {
+		alias: [{ find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) }],
+	},
+	define: {
+		__APP_VERSION__: JSON.stringify(pkg.version),
+	},
+	// A compute worker (src/app/worker.ts) is inlined into the single chunk:
+	// a ?worker&inline blob URL cannot resolve relative chunk imports at
+	// runtime, so bundle dynamic imports in too.
+	worker: {
+		format: "es",
+		rollupOptions: {
+			output: {
+				inlineDynamicImports: true,
+			},
+		},
+	},
+	build: {
+		outDir: "dist",
+		emptyOutDir: true,
+	},
+});

package/templates/starter/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+import { fileURLToPath, URL } from "node:url";
+
+export default defineConfig({
+	resolve: {
+		alias: [{ find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) }],
+	},
+	test: {
+		include: ["src/**/*.test.{ts,tsx}"],
+		environment: "node",
+	},
+});