@m4l-jweb/build 0.1.0 → 0.3.0

package/templates/starter/src/index.css

@@ -3,102 +3,180 @@
  * An overgrown layout does not scroll, it silently clips at the bottom.
  */
 :root {
-	--bg: #2f2f2f;
-	--fg: #d6d6d6;
-	--muted: #8a8a8a;
-	--accent: #6fd6a8;
-	--warn: #e8a33d;
+  --bg: #2f2f2f;
+  --fg: #d6d6d6;
+  --muted: #8a8a8a;
+  --accent: #6fd6a8;
+  --warn: #e8a33d;
 }
 
 * {
-	box-sizing: border-box;
-	margin: 0;
-	padding: 0;
+  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;
+  background: var(--bg);
+  color: var(--fg);
+  font:
+    11px/1.4 "Segoe UI",
+    system-ui,
+    sans-serif;
+  height: 169px;
+  overflow: hidden;
+}
+
+/*
+ * Dev only (@m4l-jweb/surface/dev). The harness renders beside the device, so
+ * the PAGE is no longer the device view - but the DEVICE still is. It keeps its
+ * real 169 px box, deliberately: a UI that clips in Live must clip here too, or
+ * the harness is lying to you about the one constraint that is cheapest to catch.
+ */
+body:has(.dev-layout) {
+  height: 100vh;
+}
+
+.dev-layout {
+  align-items: flex-start;
+  background: #0e1013;
+  display: flex;
+  height: 100vh;
+}
+
+.dev-layout .device {
+  border: 1px solid #262a31;
+  flex: 1;
+  height: 169px;
+  max-width: 640px;
 }
 
 .device {
-	display: flex;
-	flex-direction: column;
-	gap: 6px;
-	height: 100%;
-	padding: 8px 10px;
+  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;
+  align-items: center;
+  border-bottom: 1px solid #444;
+  display: flex;
+  gap: 8px;
+  padding-bottom: 5px;
 }
 
 h1 {
-	font-size: 12px;
-	letter-spacing: 0.08em;
+  font-size: 12px;
+  letter-spacing: 0.08em;
 }
 
 .badge {
-	border-radius: 3px;
-	font-size: 9px;
-	padding: 1px 5px;
-	text-transform: uppercase;
+  border-radius: 3px;
+  font-size: 9px;
+  padding: 1px 5px;
+  text-transform: uppercase;
 }
 .badge.live {
-	background: var(--accent);
-	color: #1a1a1a;
+  background: var(--accent);
+  color: #1a1a1a;
 }
 .badge.dev {
-	background: #555;
-	color: var(--fg);
+  background: #555;
+  color: var(--fg);
+}
+
+/* The build stamps, top right. Deliberately NOT in a footer: the device view is
+   a fixed ~169 px and clips at the bottom, so a footer stamp vanishes exactly
+   when the UI has grown enough for staleness to be worth checking. The stamps
+   are long (version + ISO timestamp), so they ellipsize - the full text is in
+   the title attribute, and the hover works in Max's jweb. */
+.stamp {
+  color: var(--muted);
+  display: flex;
+  font-size: 9px;
+  gap: 8px;
+  margin-left: auto;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 dl {
-	column-gap: 10px;
-	display: grid;
-	grid-template-columns: auto 1fr;
-	row-gap: 3px;
+  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;
+  color: var(--muted);
+  text-transform: uppercase;
+  font-size: 9px;
+  align-self: center;
 }
 
 dd {
-	font-variant-numeric: tabular-nums;
+  font-variant-numeric: tabular-nums;
 }
 
 .dot {
-	background: #666;
-	border-radius: 50%;
-	display: inline-block;
-	height: 6px;
-	width: 6px;
+  background: #666;
+  border-radius: 50%;
+  display: inline-block;
+  height: 6px;
+  width: 6px;
 }
 .dot.on {
-	background: var(--accent);
+  background: var(--accent);
+}
+
+.slider {
+  align-items: center;
+  cursor: pointer;
+  display: flex;
+  gap: 8px;
+}
+
+.slider input {
+  accent-color: var(--accent);
+  cursor: pointer;
+  margin: 0;
+  width: 120px;
+}
+
+.slider strong {
+  color: var(--accent);
+  min-width: 26px;
+}
+
+/* The transport belongs to Live, and nothing in the device starts it. */
+.row {
+  align-items: baseline;
+  display: flex;
+  gap: 8px;
+  justify-content: space-between;
+}
+
+.hint {
+  color: var(--warn);
+  font-size: 9px;
+  font-style: normal;
+  white-space: nowrap;
 }
 
 footer {
-	border-top: 1px solid #444;
-	color: var(--muted);
-	display: flex;
-	font-size: 9px;
-	gap: 10px;
-	margin-top: auto;
-	padding-top: 5px;
+  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);
+  color: var(--warn);
 }

package/templates/starter/src/main.tsx

@@ -1,10 +1,41 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import App from "./app/App";
 import "./index.css";
 
+/**
+ * ONE DEVICE PER BUNDLE.
+ *
+ * `@device` is an alias resolved in vite.config.ts to `src/app/<device>/`, where
+ * <device> comes from the dev/build script (see scripts/). So this entry point is
+ * shared but contains no branching, and each bundle holds exactly one device: a
+ * MIDI device's bundle carries no audio code, and vice versa.
+ *
+ * That separation is not tidiness. Every .amxd embeds its own UI bundle, so a
+ * device ships what it is, not what its siblings are.
+ */
+import App from "@device/App";
+
+/**
+ * The mocked-Live dev harness renders BESIDE the app in dev, and must never reach
+ * a device.
+ *
+ * `import.meta.env.DEV` is replaced by the literal `false` in a production build,
+ * so this branch - and with it the only reference to @m4l-jweb/surface/dev -
+ * becomes dead code that rollup drops before the bundle is inlined into the
+ * .amxd. tests/bundle.test.mjs asserts it actually did: a dev panel shipped
+ * inside someone's device throws no error, it just sits there, in Live.
+ */
+const DevHarness = import.meta.env.DEV ? (await import("@m4l-jweb/surface/dev")).DevHarness : null;
+
 createRoot(document.getElementById("root")!).render(
-	<StrictMode>
-		<App />
-	</StrictMode>,
+  <StrictMode>
+    {DevHarness ? (
+      <div className="dev-layout">
+        <DevHarness />
+        <App />
+      </div>
+    ) : (
+      <App />
+    )}
+  </StrictMode>,
 );

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

@@ -4,6 +4,6 @@
 declare const __APP_VERSION__: string;
 
 declare module "*?worker&inline" {
-	const workerConstructor: new () => Worker;
-	export default workerConstructor;
+  const workerConstructor: new () => Worker;
+  export default workerConstructor;
 }

package/templates/starter/tsconfig.app.json

@@ -1,24 +1,28 @@
 {
-	"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"]
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable", "WebWorker"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "paths": {
+      "@/*": ["./src/*"],
+      // vite rebinds this per build (see vite.config.ts). tsc cannot, so it
+      // typechecks src/main.tsx against ONE device. Every device's app lives
+      // under src/ and is typechecked on its own regardless.
+      "@device/*": ["./src/app/{{name}}/*"]
+    },
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
 }

package/templates/starter/tsconfig.node.json

@@ -11,5 +11,5 @@
 		"noEmit": true,
 		"strict": true
 	},
-	"include": ["vite.config.ts", "patcher/**/*.mjs"]
+	"include": ["vite.config.ts", "scripts/**/*.mjs", "patcher/**/*.mjs"]
 }

package/templates/starter/vite.config.ts

@@ -1,34 +1,67 @@
-import { defineConfig } from "vite";
+import { defineConfig, type UserConfig } 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";
+import { devices, uiDir } from "./scripts/devices.mjs";
 
-// 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,
-	},
+/**
+ * ONE BUILD PER DEVICE.
+ *
+ * A repo can hold several devices, each .amxd embeds its OWN UI bundle, and a
+ * device should ship what it is - not its siblings' code. So the app to bundle is
+ * chosen here, by DEVICE, and src/main.tsx imports it through the `@device`
+ * alias. There is no `if (mode === ...)` anywhere in the app.
+ *
+ * DEVICE is set by scripts/dev.mjs and scripts/build-ui.mjs (which read the
+ * device list from patcher/devices.mjs). It is an env var rather than vite's
+ * `--mode` deliberately: `--mode` also flips `import.meta.env.DEV`, and a build
+ * with DEV=true would ship the dev harness inside the device.
+ */
+//
+// NOTE this is a FACTORY, not a plain object. scripts/build-ui.mjs sets DEVICE
+// and calls vite's build() once per device in the same process; a top-level
+// `const DEVICE = process.env.DEVICE` would be evaluated once, when the module
+// was first loaded, and every device after the first would be built from the
+// first one's sources. Vite invokes the factory on each config load, so reading
+// the env var HERE is what makes the loop work.
+export default defineConfig(() => {
+  // Falls back to the first device in the manifest, so a bare `vite` still runs
+  // something and this config carries no device name of its own.
+  const DEVICE = process.env.DEVICE ?? uiDir(devices[0]);
+
+  // 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.
+  const config: UserConfig = {
+    base: "./",
+  plugins: [react(), viteSingleFile()],
+  resolve: {
+    alias: [
+      { find: "@device", replacement: fileURLToPath(new URL(`./src/app/${DEVICE}`, import.meta.url)) },
+      { find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) },
+    ],
+  },
+  define: {
+    __APP_VERSION__: JSON.stringify(pkg.version),
+    __DEVICE__: JSON.stringify(DEVICE),
+  },
+  // A compute worker (src/app/shared/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: {
+      // dist/ui/<device>/index.html - one per device, picked up by `m4l-jweb build`.
+      outDir: `dist/ui/${DEVICE}`,
+      emptyOutDir: true,
+    },
+  };
+  return config;
 });

package/templates/starter/vitest.config.ts

@@ -6,7 +6,7 @@ export default defineConfig({
 		alias: [{ find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) }],
 	},
 	test: {
-		include: ["src/**/*.test.{ts,tsx}"],
+		include: ["tests/**/*.test.{ts,mjs}", "packages/*/tests/**/*.test.{ts,mjs}", "src/**/*.test.{ts,tsx}"],
 		environment: "node",
 	},
 });

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

@@ -1,87 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/**
- * 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];