@m4l-jweb/build 1.3.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/build",
-  "version": "1.3.1",
+  "version": "1.6.0",
   "description": "m4l-jweb: the CLI that builds and packages a device repo into installable Max for Live devices.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,8 @@
   "exports": {
     ".": "./src/index.mjs",
     "./chains": "./src/chains.mjs",
+    "./controls": "./src/controls.mjs",
+    "./target": "./src/target.mjs",
     "./surface": "./src/surface.mjs",
     "./watch": "./src/watch.mjs",
     "./files": "./src/files.mjs",
@@ -35,6 +37,6 @@
     "archiver": "^7.0.1",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.0",
-    "@m4l-jweb/wrapper": "1.3.1"
+    "@m4l-jweb/wrapper": "1.6.0"
   }
 }

package/src/chains.mjs

@@ -100,7 +100,10 @@ export function claimAppMessages(ctx, routeId, unmatchedOutlet) {
 
   removeLine(ctx.lines, srcId, ctx.unmatchedId);
   ctx.lines.push(line(srcId, srcOutlet, routeId, 0));
-  ctx.lines.push(line(routeId, unmatchedOutlet, ctx.unmatchedId, 0));
+  // A HEADLESS device has nowhere to pass the tail on TO: `[js]` is already the far
+  // end of this stream, so the last route's unmatched outlet is left unconnected
+  // rather than wired back into the box the messages came from.
+  if (ctx.unmatchedId) ctx.lines.push(line(routeId, unmatchedOutlet, ctx.unmatchedId, 0));
   ctx.appOut = [routeId, unmatchedOutlet];
 }
 
@@ -232,7 +235,7 @@ export function assertUniqueBoxIds(boxes, deviceName, scope = "the patcher") {
  * 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 }) {
+function midiInChain({ boxes, lines, appIn }) {
   removeLine(lines, "obj-midiin", "obj-midiout");
   boxes.push(
     box("obj-midiparse", "midiparse", {
@@ -244,7 +247,10 @@ function midiInChain({ boxes, lines, jwebId }) {
   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));
+  // The APP endpoint - `[jweb]` under the default target, `[js]` under headless. A
+  // played note reaches a React `onNote()` or a `function notein()` in [js], and this
+  // chain does not know or care which.
+  lines.push(line("obj-noteinmsg", 0, appIn, 0));
 }
 
 /**
@@ -854,6 +860,15 @@ function reverbChain(ctx) {
  */
 function webaudioChain(ctx) {
   const { boxes, lines, jwebId } = ctx;
+  // The signal comes out of the PAGE's own outlets. There is no page in a headless
+  // device, so this is not a stage that can be claimed - say so here rather than
+  // emit a cord from a box that is not in the patcher.
+  if (!jwebId) {
+    throw new Error(
+      `chain "webaudio" on device "${ctx.device?.name}" takes its signal from the page's [jweb~] outlets, ` +
+        `and target "headless" has no page. Write the audio in MSP (a chain), or drop \`target: "headless"\`.`,
+    );
+  }
 
   for (const ch of [0, 1]) {
     const [srcId, srcOut] = ctx.audioIn(ch);

package/src/controls.mjs

@@ -0,0 +1,209 @@
+/**
+ * controls.mjs - the build side of defineControls().
+ *
+ * The fourth of the same pipeline (surface.mjs, watch.mjs, files.mjs), and like
+ * files.mjs it produces BOTH kinds of output: a patcher CHAIN and a data banner.
+ * The declaration itself rides on the Surface - `defineSurface({ controls })` - so
+ * there is nothing to import here that `loadSurface()` has not already loaded.
+ *
+ * ------------------------------------------------------------------------------
+ * WHERE THE WORK LIVES, and why it is split where it is.
+ *
+ * doc/TODO.md asked for discovery, grab, release and the value observer in
+ * the chain, with the frame diff and `send_value` in the wrapper. The line moved,
+ * and it moved for one reason: EVERY MEASURED FACT ABOUT THIS API WAS MEASURED
+ * THROUGH `[js]`. `push-probe` resolved the surface, grabbed by name, painted and
+ * observed from LiveAPI in the wrapper, and doc/MAX-FACTS.md's numbers are that
+ * path's numbers. A patcher rewrite of the same steps is unmeasured code in an API
+ * that reports NOTHING when it is wrong - so the parts that only [js] can do at all
+ * stayed in [js], and the part the constraint is actually about moved out of it:
+ *
+ *   the chain     THE INPUT PATH. One `[live.observer value]` per declared control,
+ *                 straight into `[jweb]`. A press crosses no [js] at all. Plus the
+ *                 two takeover parameters, tapped into [js] so the grab follows the
+ *                 dial even with the page closed or dead.
+ *
+ *   the wrapper   discovery (walking `live_app`'s `control_surfaces` is a LOOP, and
+ *                 a loop in a patcher is [uzi] + [zl] that nothing can test without
+ *                 the hardware), resolving each role against `get_control_names`,
+ *                 grab, release, the focus policy, the frame buffer and its per-cell
+ *                 diff, and `send_value`.
+ *
+ * The constraint that carries a failure mode - a grabbed pad must not wait on
+ * anything the page is doing - is met. The constraint that was a preference is not,
+ * and this comment is the record of the trade rather than a silent divergence.
+ * ------------------------------------------------------------------------------
+ */
+import { box, fanParamInto, line } from "./chains.mjs";
+
+/** Must match FOCUS_OPTIONS in @m4l-jweb/surface - the menu's value is its index. */
+const FOCUS_OPTIONS = ["Device", "Track", "Always"];
+
+/** The chain that owns the observers. Every device that declares controls needs it. */
+export const CONTROLS_CHAIN = "takeover";
+
+/** The parameters defineControls() contributes. Must match TAKEOVER_PARAM / FOCUS_PARAM in @m4l-jweb/surface. */
+export const TAKEOVER_PARAM = "takeover";
+export const FOCUS_PARAM = "focus";
+
+/**
+ * The chain list this device is actually built with.
+ *
+ * A device that declares controls gets `takeover` whether or not the manifest asked
+ * for it, appended LAST for the same reason `download` is: it claims no stage of the
+ * signal path, but chain order IS the signal path and inserting anywhere else would
+ * silently re-route a device that merely started using the pads.
+ *
+ * Idempotent - a manifest that lists it keeps exactly one, since running the chain
+ * twice emits the same box ids twice and assertUniqueBoxIds rejects that.
+ */
+export function withControlsChain(chains, surface) {
+  const declared = chains ?? [];
+  if (!surface?.controls) return declared;
+  return declared.includes(CONTROLS_CHAIN) ? declared : [...declared, CONTROLS_CHAIN];
+}
+
+/**
+ * The `var CONTROLS_SPEC = {...}` banner prepended to a device's wrapper.js.
+ *
+ * Only what the wrapper ACTS on travels: the key (which is the selector suffix and
+ * the argument the chain routes on), the kind, the size of the frame buffer, and the
+ * CANDIDATE NAMES to resolve the role against. The role name itself rides along
+ * because it is what a console line has to say when a role does not resolve, and
+ * "matrix" is what the device author wrote.
+ *
+ * A device with no declaration gets no banner ("") - `typeof CONTROLS_SPEC ===
+ * "undefined"` is exactly the guard the wrapper checks.
+ */
+export function controlsSpecBanner(surface) {
+  const controls = surface?.controls;
+  if (!controls) return "";
+  const spec = {
+    surface: controls.surface,
+    /**
+     * The declared `focus` default, as the menu INDEX Max stores it as.
+     *
+     * The wrapper needs it because a `live.menu` does not necessarily announce its
+     * value at load - and a wrapper that assumed 0 would treat a device declared
+     * `Track` as `Device` until somebody touched the menu, which is a takeover that
+     * silently does not happen on a track the user has selected.
+     */
+    focus: FOCUS_OPTIONS.indexOf(controls.defaultFocus),
+    controls: controls.keys.map((key) => {
+      const c = controls.controls[key];
+      return {
+        key,
+        kind: c.kind,
+        role: c.role,
+        rows: c.kind === "grid" ? c.rows : 1,
+        cols: c.kind === "grid" ? c.cols : 1,
+        // Stamped onto the spec by defineControls() from its own ROLE_NAMES table,
+        // so this file never reimplements it. See ControlBase in controls.ts.
+        names: c.names ?? [],
+      };
+    }),
+  };
+  return `var CONTROLS_SPEC = ${JSON.stringify(spec)};\n`;
+}
+
+/** The per-key selector the wrapper addresses the chain with: `tk_<key> id <n>`. */
+export const controlIdSelector = (key) => `tk_${key}`;
+
+/**
+ * "takeover" - the pads' INPUT PATH, and the two parameters that switch it on.
+ *
+ * ```
+ *   [js] outlet 1 -> [route tk_pads ...] -> id <n> -> right inlet of
+ *                                                    [live.observer value]
+ *                                                          |
+ *                                       [prepend pad_pads] -+
+ *                                                          |
+ *                                                       [jweb]
+ * ```
+ *
+ * THE OBSERVER IS THE WHOLE POINT OF THE CHAIN. A press reaches the page through
+ * `[live.observer]` -> `[prepend]` -> `[jweb]` and touches no [js] on the way, so the
+ * one thing that must never queue behind anything else does not.
+ *
+ * `live.observer`'s LEFT OUTLET CARRIES THE VALUE AND NOTHING ELSE - read off Max's
+ * own reference on disk (`refpages/m4l-ref/live.observer.maxref.xml`: "The left
+ * outlet is reserved for value messages, all other output is sent to the right
+ * outlet"), which is NOT the shape [js] sees. A [js] callback is handed
+ * `["value", ...]`; this is the atoms alone. The page is written against the atoms.
+ *
+ * ...and it fires ONCE ON ATTACH, with the property's current value, which for a
+ * control nobody has touched is not a press. That reaches the page as a `pad_<key>`
+ * with no arguments and `padStore` drops it on arity - the same trap the probe hit
+ * as a press at (undefined, undefined).
+ *
+ * THE TWO PARAMETERS ARE TAPPED INTO `[js]`, not read out of the page. `takeover`
+ * decides whether this device holds the hardware, and a device whose grid dies
+ * because its Chromium view is closed is a device that fails exactly when the user
+ * is looking at the Push instead of the screen. `fanParamInto` wires BOTH of a
+ * parameter's sources - the object's own outlet (a knob turn, an automation lane,
+ * Push) and the route outlet carrying what the app wrote - because the app's write
+ * reaches the object as `set`, which updates it without producing output.
+ */
+export function takeoverChain(ctx) {
+  const { boxes, lines, appIn, surface, device } = ctx;
+  // The wrapper's own box, not `ctx.unmatchedId` - which is null under the headless
+  // target, where there is no separate far end to pass a tail on to. The id for the
+  // observer comes off [js]'s AUX outlet either way.
+  const jsId = "obj-js";
+  const controls = surface?.controls;
+  if (!controls) {
+    throw new Error(
+      `chain "${CONTROLS_CHAIN}" on device "${device?.name}" needs a defineControls() declaration - ` +
+        `pass it to defineSurface({ ..., controls }) in src/app/${device?.ui ?? device?.name}/surface.ts.`,
+    );
+  }
+  for (const id of [TAKEOVER_PARAM, FOCUS_PARAM]) {
+    if (!surface.params?.[id]) {
+      throw new Error(
+        `chain "${CONTROLS_CHAIN}" on device "${device?.name}" expected the generated parameter "${id}". ` +
+          `defineSurface() adds it when a \`controls\` declaration is present - this surface has ${surface.ids.join(", ") || "none"}.`,
+      );
+    }
+  }
+
+  const keys = controls.keys;
+  const routeId = "obj-tk-route";
+
+  // [js]'s AUX outlet, the same one the `download` chain takes [maxurl]'s requests
+  // from. Two routes hang off it in parallel and that is safe here where it is not
+  // safe on [jweb]'s outlet: neither of them forwards what it did not match, so a
+  // message is delivered once or dropped, never twice.
+  boxes.push(
+    box(routeId, `route ${keys.map(controlIdSelector).join(" ")}`, {
+      numoutlets: keys.length + 1,
+      outlettype: keys.map(() => "").concat(""),
+    }),
+  );
+  lines.push(line(jsId, 1, routeId, 0));
+
+  keys.forEach((key, i) => {
+    const obs = `obj-tk-obs-${key}`;
+    const tag = `obj-tk-pad-${key}`;
+    boxes.push(box(obs, "live.observer value", { numinlets: 2, numoutlets: 2, outlettype: ["", ""] }));
+    // The RIGHT inlet takes `id <n>` - the reference is explicit that the id goes
+    // there, and [route] has already stripped the `tk_<key>` word by the time it
+    // arrives, leaving exactly that message.
+    lines.push(line(routeId, i, obs, 1));
+    boxes.push(box(tag, `prepend pad_${key}`));
+    lines.push(line(obs, 0, tag, 0));
+    // The APP endpoint. Under the default target a press lands in the page with no
+    // [js] in the way; under headless the page is not there and it lands in [js],
+    // which is where the game already was.
+    lines.push(line(tag, 0, appIn, 0));
+  });
+
+  for (const [param, selector] of [
+    [TAKEOVER_PARAM, "controls_takeover"],
+    [FOCUS_PARAM, "controls_focus"],
+  ]) {
+    const id = `obj-tk-${param}`;
+    boxes.push(box(id, `prepend ${selector}`));
+    lines.push(line(id, 0, jsId, 0));
+    fanParamInto(ctx, param, id, 0);
+  }
+}

package/src/index.mjs

@@ -16,11 +16,18 @@ import path from "node:path";
 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 { CHAINS, assertUniqueBoxIds, closeAudio, openAudio, registerChain, resetLayout } from "./chains.mjs";
+import { CONTROLS_CHAIN, controlsSpecBanner, takeoverChain, withControlsChain } from "./controls.mjs";
+import { deviceTarget, isHeadless, openApp } from "./target.mjs";
 import { applySurface, applyWindows, applyPersistence, loadSurface, parameterRegistry, surfaceContext } from "./surface.mjs";
 import { effectiveChains, filesSpecBanner, loadFiles } from "./files.mjs";
 import { loadWatch, watchSpecsBanner } from "./watch.mjs";
 
+// The takeover chain lives in controls.mjs beside the rest of defineControls()'s
+// build half, and joins the vocabulary here rather than in chains.mjs - which it
+// imports for box()/line()/fanParamInto(), and which must not import it back.
+registerChain(CONTROLS_CHAIN, takeoverChain);
+
 const require = createRequire(import.meta.url);
 const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const templates = path.join(pkgDir, "templates");
@@ -113,6 +120,76 @@ export function buildWrapper(root) {
   return out;
 }
 
+/**
+ * Compile ONE headless device's own `[js]` logic to ES5.
+ *
+ * `src/app/<device>/headless.ts` is what `App.tsx` is for a jweb device: the thing the
+ * device actually does. It is concatenated after the packaged wrapper, so it sees the
+ * wrapper's globals (`post`, `outlet`, `Task`, `LiveAPI`, `MODE`) and typechecks
+ * against them - which is why the wrapper sources are in the program even though only
+ * this file's output is kept.
+ *
+ * ONE PROGRAM PER DEVICE, deliberately. Compiling every device's headless source
+ * together would put them all in one global scope, where two devices could not both
+ * declare a `var step` - a constraint invented by the build, paid by the author, for
+ * nothing. A tsc run is about a second.
+ *
+ * The ES5 gate is the same one the wrapper passes and for the same reason: Max's [js]
+ * is an ES5-era interpreter, and this file runs inside it.
+ */
+export function buildHeadless(root, uiDir) {
+  const src = path.join(root, "src", "app", uiDir, "headless.ts");
+  if (!existsSync(src)) return null;
+
+  const { sources, types } = require("@m4l-jweb/wrapper/sources");
+  const deviceExt = path.join(root, "wrapper", "device.ts");
+  const context = [...sources, ...(existsSync(deviceExt) ? [deviceExt] : [])];
+
+  const tmp = path.join(root, "dist", `.headless-${uiDir}`);
+  rmSync(tmp, { recursive: true, force: true });
+  mkdirSync(tmp, { recursive: true });
+
+  // Staged flat, like buildWrapper: tsc derives its output layout from the common root
+  // of its inputs, and the packaged sources live in node_modules while this one lives
+  // in the repo.
+  const staged = context.map((f, i) => {
+    const dest = path.join(tmp, `${String(i).padStart(2, "0")}-${path.basename(f)}`);
+    writeFileSync(dest, readFileSync(f, "utf8"));
+    return dest;
+  });
+  const mine = path.join(tmp, "device-headless.ts");
+  writeFileSync(mine, readFileSync(src, "utf8"));
+  const stagedTypes = path.join(tmp, path.basename(types));
+  writeFileSync(stagedTypes, readFileSync(types, "utf8"));
+
+  const tsconfig = path.join(tmp, "tsconfig.json");
+  writeFileSync(
+    tsconfig,
+    JSON.stringify({
+      compilerOptions: {
+        target: "ES5",
+        lib: ["ES5"],
+        module: "none",
+        outDir: tmp,
+        strict: true,
+        noImplicitThis: false,
+        alwaysStrict: false,
+        noImplicitAny: false,
+        skipLibCheck: true,
+        types: [],
+      },
+      files: [stagedTypes, ...staged, mine],
+    }),
+  );
+  execFileSync(process.execPath, [require.resolve("typescript/bin/tsc"), "-p", tsconfig], { stdio: "inherit" });
+
+  const js = readFileSync(mine.replace(/\.ts$/, ".js"), "utf8");
+  assertES5(js, `headless logic for ${uiDir}`);
+  rmSync(tmp, { recursive: true, force: true });
+  console.log(`m4l-jweb: headless logic for ${uiDir} (${js.length} bytes, ES5 verified)`);
+  return js;
+}
+
 /* ------------------------------------------------------------------ *
  * Step 2: the patchers
  * ------------------------------------------------------------------ */
@@ -143,6 +220,32 @@ async function readDocs(root) {
   return Array.isArray(mod.docs) ? mod.docs : [];
 }
 
+/**
+ * Release BUNDLES: a zip for one device, or a few, on its own.
+ *
+ * The repo zip is for somebody installing the whole library. A bundle is for somebody who
+ * wants ONE device and has never heard of the library - a game, an instrument, a thing
+ * with its own name and its own audience. They get a zip with that device in it and
+ * nothing else.
+ *
+ * Declared as a named export beside the manifest:
+ *
+ *   export const bundles = [
+ *     { name: "push-snake", title: "Snake for Push", devices: ["push-snake"], readme: "doc/SNAKE.md" }
+ *   ];
+ *
+ * `readme` is written into the zip as `README.md`, because that is the file a person
+ * opens. Everything the named devices need travels with them: their `looseFiles`, and the
+ * sidecar folder of any `site:` window. An `.amxd` that embeds its own assets - which is
+ * every device that does not declare those two things - needs nothing else at all.
+ */
+async function readBundles(root) {
+  const p = path.join(root, "patcher", "devices.mjs");
+  if (!existsSync(p)) return [];
+  const mod = await import(pathToFileURL(p).href);
+  return Array.isArray(mod.bundles) ? mod.bundles : [];
+}
+
 /** patcher/base.json in the device repo wins; otherwise the packaged template. */
 function readBase(root) {
   const local = path.join(root, "patcher", "base.json");
@@ -217,7 +320,29 @@ export function composePatcher(base, d, surface, files = null) {
    *
    * Unset keeps the object's default. jweb~ clamps to 3x the minimum.
    */
-  if (d.latency != null) boxes.find((b) => b.box.id === "obj-jweb").box.latency = d.latency;
+  if (d.latency != null) {
+    // A headless device has no [jweb~] to buffer, and a `latency` on one is a setting
+    // for a thing that is not there - worth saying, not ignoring.
+    if (isHeadless(d)) {
+      throw new Error(`device "${d.name}" is target "headless" and sets \`latency\` - there is no [jweb~] to give a ring buffer to.`);
+    }
+    boxes.find((b) => b.box.id === "obj-jweb").box.latency = d.latency;
+  }
+
+  /**
+   * `mpe: true` - ask Live to send this device MPE.
+   *
+   * `is_mpe` is a PATCHER attribute, not a box one, and it is a declaration rather
+   * than machinery: Max's own reference says "If enabled, a Max for Live device will
+   * receive MPE data from Live", and a shipping device that carries the MPE badge
+   * sets it to 1 while parsing the result with ordinary `midiin` / `midiparse` (see
+   * doc/MAX-FACTS.md). The template writes 0, so a device that wants it says so here
+   * and something still has to READ the stream - the `mpein` chain, or `midiin`.
+   *
+   * Off by default. A device declaring MPE it does not handle is a device Live sends
+   * per-note channels to for no reason, and the badge tells the user a lie.
+   */
+  if (d.mpe) p.patcher.is_mpe = 1;
 
   const unmatchedId = d.unmatchedTo === "js" ? "obj-js" : (d.unmatchedTo ?? "obj-js");
 
@@ -238,11 +363,21 @@ export function composePatcher(base, d, surface, files = null) {
   // voice abstraction). A chain pushes { name, data } here; generatePatchers writes
   // each next to the device patcher and packageDevices freezes it into the container.
   const extras = [];
-  const ctx = { boxes, lines, jwebId: "obj-jweb", unmatchedId, device: d, extras, ...surfaceContext(surface) };
-
+  const ctx = { boxes, lines, unmatchedId, device: d, extras, ...surfaceContext(surface) };
+
+  // WHERE THE LOGIC RUNS, decided once and before anything else touches the graph.
+  // It sets `ctx.appIn` / `ctx.appOut` - the endpoint every chain reaches "the app"
+  // through - and, for a headless device, deletes [jweb] and both of its cords. A
+  // chain claims a stage in a stream it did not create and must not know which target
+  // created it (target.mjs).
+  openApp(ctx);
   openAudio(ctx);
 
-  for (const name of effectiveChains(d.chains, files)) {
+  // A declared takeover contributes its chain the way a declared files.ts
+  // contributes `download`: derived from the declaration, never from the manifest
+  // remembering to ask. A device whose observers were missing would load, grab, and
+  // report every press to nobody.
+  for (const name of withControlsChain(effectiveChains(d.chains, files), surface)) {
     const chain = CHAINS[name];
     if (!chain) throw new Error(`unknown chain "${name}" for device "${d.name}" (known: ${Object.keys(CHAINS).join(", ")})`);
     chain(ctx);
@@ -305,8 +440,9 @@ export async function generatePatchers(root) {
     // 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"})`);
+    const chains = withControlsChain(effectiveChains(d.chains, files), surface).join(", ") || "none";
+    const target = deviceTarget(d);
+    console.log(`m4l-jweb: ${d.name}.json (${d.type}/${target}, chains: ${chains}, params: ${params || "none"})`);
   }
   return devices;
 }
@@ -391,15 +527,17 @@ export async function packageDevices(root) {
      * disk was stale. The symptom would be a device showing its sibling's
      * interface.
      */
+    const headless = isHeadless(d);
     const uiName = `${d.name}.html`;
-    const uiSrc = path.join(dist, "ui", d.ui ?? d.name, "index.html");
-    const legacy = path.join(dist, "index.html"); // single-UI repos (the starter template)
-    const uiFrom = existsSync(uiSrc) ? uiSrc : legacy;
-    if (!existsSync(uiFrom)) {
-      throw new Error(`no UI for "${d.name}" at ${uiSrc} - run \`pnpm build\` (scripts/build-ui.mjs) first`);
+    if (!headless) {
+      const uiSrc = path.join(dist, "ui", d.ui ?? d.name, "index.html");
+      const legacy = path.join(dist, "index.html"); // single-UI repos (the starter template)
+      const uiFrom = existsSync(uiSrc) ? uiSrc : legacy;
+      if (!existsSync(uiFrom)) {
+        throw new Error(`no UI for "${d.name}" at ${uiSrc} - run \`pnpm build\` (scripts/build-ui.mjs) first`);
+      }
+      await copyFile(uiFrom, path.join(outDir, uiName));
     }
-    const uiHtml = readFileSync(uiFrom);
-    await copyFile(uiFrom, path.join(outDir, uiName));
 
     /**
      * Payloads ride inside wrapper.js as base64 and are written to real files
@@ -413,19 +551,40 @@ export async function packageDevices(root) {
     // ...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);
+    // ...and its declared CONTROLS: CONTROLS_SPEC is the role table the packaged
+    // wrapper resolves against the connected hardware's own get_control_names.
+    const deviceSurface = await loadSurface(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"));
+      banner +
+      // The one thing that tells the packaged wrapper there is no page: no [jweb] to
+      // point at a URL, no payload to extract, no window sizes to follow. Everything
+      // else about the wrapper is unchanged, which is the point of the target being a
+      // seam rather than a second wrapper.
+      (headless ? "var HEADLESS = 1;\n" : "") +
+      watchSpecsBanner(watch) +
+      filesSpecBanner(files) +
+      controlsSpecBanner(deviceSurface) +
+      siteWindowsBanner(root, outDir, d, deviceSurface) +
+      wrapperJs;
 
-    // Main UI payload
-    wrapperData += payloadJs("UI_PAYLOAD", uiName, readFileSync(path.join(dist, "ui", d.ui ?? d.name, "index.html")));
-
-    // Additional window payloads
-    const extraWindows = uiDirContent.filter((f) => f !== "index.html");
     const payloads = (d.payloads ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) }));
 
-    for (const winHtml of extraWindows) {
-      payloads.push({ name: `${d.name}_${winHtml}`, data: readFileSync(path.join(dist, "ui", d.ui ?? d.name, winHtml)) });
+    if (headless) {
+      // The device's OWN [js], where a jweb device would have had a bundle. Nothing
+      // else is appended: a headless .amxd contains a patcher and one script, and that
+      // is the whole claim the target makes.
+      const own = buildHeadless(root, d.ui ?? d.name);
+      if (own) wrapperData += "\n" + own;
+    } else {
+      const uiDirContent = readdirSync(path.join(dist, "ui", d.ui ?? d.name)).filter((f) => f.endsWith(".html"));
+
+      // Main UI payload
+      wrapperData += payloadJs("UI_PAYLOAD", uiName, readFileSync(path.join(dist, "ui", d.ui ?? d.name, "index.html")));
+
+      // Additional window payloads
+      for (const winHtml of uiDirContent.filter((f) => f !== "index.html")) {
+        payloads.push({ name: `${d.name}_${winHtml}`, data: readFileSync(path.join(dist, "ui", d.ui ?? d.name, winHtml)) });
+      }
     }
 
     if (payloads.length) wrapperData += extraPayloadsJs(payloads);
@@ -446,7 +605,7 @@ export async function packageDevices(root) {
       extras: [...(d.extraFiles ?? []).map((f) => ({ name: path.basename(f), data: readFileSync(path.join(root, f)) })), ...chainExtras],
     });
     writeFileSync(path.join(outDir, deviceName), amxd);
-    console.log(`m4l-jweb: ${deviceName} (${d.type}, ${amxd.length} bytes)`);
+    console.log(`m4l-jweb: ${deviceName} (${d.type}/${deviceTarget(d)}, ${amxd.length} bytes)`);
   }
 
   await copyFile(path.join(dist, "wrapper", "wrapper.js"), path.join(outDir, "wrapper.js"));
@@ -503,7 +662,10 @@ export async function packageDevices(root) {
     archive.pipe(output);
     const files = [
       ...devices.map((d) => `${d.name}.amxd`),
-      ...devices.map((d) => `${d.name}.html`), // each device's own UI, for inspection
+      // Each device's own UI, for inspection - a HEADLESS device has none, and there
+      // is nothing missing: the .amxd holds the patcher and one script, which is the
+      // whole of it.
+      ...devices.filter((d) => !isHeadless(d)).map((d) => `${d.name}.html`),
       ...loose.map((f) => path.basename(f)),
       ...presets,
       ...docs,
@@ -528,6 +690,79 @@ export async function packageDevices(root) {
 
   const { size } = await stat(zipPath);
   console.log(`m4l-jweb: dist/${name}.zip (${size} bytes)`);
+
+  await packageBundles(root, dist, outDir, devices);
+}
+
+/**
+ * One zip per declared bundle, beside the repo zip.
+ *
+ * A bundle names devices that must exist - a typo here would otherwise produce a zip that
+ * is missing the very thing it is named after, and nothing would say so until somebody
+ * downloaded it.
+ */
+async function packageBundles(root, dist, outDir, devices) {
+  const bundles = await readBundles(root);
+  const known = new Set(devices.map((d) => d.name));
+
+  for (const bundle of bundles) {
+    const named = bundle.devices ?? [];
+    for (const d of named) {
+      if (!known.has(d)) {
+        throw new Error(`bundle "${bundle.name}" lists device "${d}", which patcher/devices.mjs does not declare (${[...known].join(", ")}).`);
+      }
+    }
+    if (!named.length) throw new Error(`bundle "${bundle.name}" names no devices - a zip of nothing is not a release`);
+
+    const zipPath = path.join(dist, `${bundle.name}.zip`);
+    const entries = [];
+
+    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);
+
+      for (const d of named) {
+        const device = devices.find((x) => x.name === d);
+        archive.file(path.join(outDir, `${d}.amxd`), { name: `${bundle.name}/${d}.amxd` });
+        entries.push(`${d}.amxd`);
+
+        // Whatever that device cannot embed. A loose file is one a Max object resolves
+        // when it INSTANTIATES, before any code has run, so it has to be a real file next
+        // to the .amxd; a `site:` window's folder is too big to be a payload.
+        for (const f of device.looseFiles ?? []) {
+          archive.file(path.join(outDir, path.basename(f)), { name: `${bundle.name}/${path.basename(f)}` });
+          entries.push(path.basename(f));
+        }
+        const site = path.join(outDir, `${d}-site`);
+        if (existsSync(site)) {
+          archive.directory(site, `${bundle.name}/${d}-site`);
+          entries.push(`${d}-site/`);
+        }
+      }
+
+      // The file a person opens, under the name they will look for.
+      if (bundle.readme && existsSync(path.join(root, bundle.readme))) {
+        archive.file(path.join(root, bundle.readme), { name: `${bundle.name}/README.md` });
+        entries.push("README.md");
+      }
+      for (const f of bundle.docs ?? []) {
+        const from = path.join(root, f);
+        if (!existsSync(from)) {
+          console.warn(`m4l-jweb: bundle "${bundle.name}" doc ${f} is not there - skipped`);
+          continue;
+        }
+        archive.file(from, { name: `${bundle.name}/${path.basename(f)}` });
+        entries.push(path.basename(f));
+      }
+      archive.finalize();
+    });
+
+    const { size } = await stat(zipPath);
+    console.log(`m4l-jweb: dist/${bundle.name}.zip (${size} bytes: ${entries.join(", ")})`);
+  }
 }
 
 export async function buildAll(root) {

package/src/surface.mjs

@@ -389,7 +389,7 @@ function kindBoxAttrs(spec) {
  * wrapper. Doing it last means no chain has to know the Surface exists.
  */
 export function applySurface(ctx) {
-  const { boxes, lines, surface, jwebId } = ctx;
+  const { boxes, lines, surface, jwebId, appIn } = ctx;
   if (!surface || surface.ids.length === 0) return;
 
   // Where the native dials go, if any were declared. `slots` is empty for a
@@ -403,7 +403,8 @@ export function applySurface(ctx) {
   // stays in one place when the app flips between the two views. It is excluded from
   // `computeNativeSlots` (it is not in `native.params`), so give it a rect here.
   const switchId = native?.switch;
-  const jwebBox = boxes.find((b) => b.box.id === jwebId)?.box;
+  // Null under the headless target: there is no page to lay out around.
+  const jwebBox = jwebId ? boxes.find((b) => b.box.id === jwebId)?.box : null;
   const [, , jpw] = jwebBox?.presentation_rect ?? [0, 0, 420, DEVICE_H];
   let switchRect = null;
   if (switchId) {
@@ -435,16 +436,19 @@ export function applySurface(ctx) {
       },
     });
     // Read direction: a knob turn reaches the app as `<id> <value>`. A parameter
-    // is just another inlet message.
+    // is just another inlet message - and under the headless target the app IS the
+    // wrapper, so the same cord lands on a `function <id>()` in [js] instead of on
+    // a `useParam()` in React.
     boxes.push(box(`obj-prepend-${id}`, `prepend ${id}`));
     lines.push(line(paramObject(id), 0, `obj-prepend-${id}`, 0));
-    lines.push(line(`obj-prepend-${id}`, 0, jwebId, 0));
+    lines.push(line(`obj-prepend-${id}`, 0, appIn, 0));
     x += 56;
   }
 
   // Position [jweb] for the native layout. WIDTH is preserved (React layouts were
   // built for 420 px). A surface with no native content leaves [jweb] where the
-  // template put it.
+  // template put it - and a HEADLESS device has no [jweb] at all, so the dials are
+  // the whole device view and nothing needs shifting out of their way.
   if ((nativeW > 0 || switchId) && jwebBox) {
     const [, py, pw, ph] = jwebBox.presentation_rect ?? [0, 0, 420, DEVICE_H];
     if (native.panel) {
@@ -724,6 +728,18 @@ export function applyWindows(ctx) {
   const windowIds = surface?.windows ? Object.keys(surface.windows) : [];
   if (windowIds.length === 0) return;
 
+  // A window IS a second page - its own [jweb] in a subpatcher, its own bundle. There
+  // is no page under the headless target, so this is not a thing that can be built
+  // quietly smaller: say so, at the declaration, rather than emit a subpatcher whose
+  // whole contents are a box that target does not have.
+  if (ctx.target === "headless") {
+    throw new Error(
+      `device "${ctx.device?.name}" is target "headless" and declares window(s) ${windowIds.join(", ")} in its surface.ts. ` +
+        `A window is a second [jweb] page, which that target has no browser for. ` +
+        `Use layout.native for a device view, or drop \`target: "headless"\`.`,
+    );
+  }
+
   const selectors = windowIds.flatMap((id) => [`window_${id}_open`, `window_${id}_close`]);
 
   const routeId = "obj-windows-route";

package/src/target.mjs

@@ -0,0 +1,116 @@
+/**
+ * target.mjs - WHERE a device's logic runs, and what the patcher therefore contains.
+ *
+ * Until now there was one answer and it was wired into everything: the logic is a
+ * React app inside `[jweb]`, so the patcher has a `[jweb]`, the `.amxd` carries a
+ * base64 HTML payload, and every chain that wants to reach "the app" sends to that
+ * box. A device could not opt out, and the library was named after the assumption.
+ *
+ * A TARGET is that assumption, made explicit and given a second value:
+ *
+ *   jweb       the device page runs in Max's embedded Chromium. React, Web Audio,
+ *              Workers, a UI you can look at. What every device shipped before this.
+ *   headless   there is no browser at all. The device declares its interface in
+ *              TypeScript exactly as it does today - `defineSurface`, `defineControls`,
+ *              `defineWatch` - and the build emits ONLY the `[js]` wrapper and the
+ *              patcher. The device's own logic is `src/app/<device>/headless.ts`,
+ *              compiled to ES5 and concatenated after the wrapper.
+ *
+ * ------------------------------------------------------------------------------
+ * WHY HEADLESS IS WORTH A SEAM, and none of it is speculation (doc/TODO.md item 3):
+ *
+ *   - THE PAD TAKEOVER NEEDS NO BROWSER. The grab, the paint and the value observer
+ *     are `live.object` / `live.observer` and `[js]`; the page was never in that path.
+ *     A grid device's logic is a control plane, and `[js]` plus `Task` is a BETTER
+ *     clock than a Chromium page nobody is looking at - the Worker in `push-snake`
+ *     exists to dodge throttling that only a hidden page suffers.
+ *   - AUDIO WITHOUT `[jweb~]` is a path this repo has already walked: bytes to disk,
+ *     played through `[buffer~]`/`[groove~]`. Retired for ergonomics, not because it
+ *     failed - and for a device holding two decoded FLACs the trade inverts, because
+ *     half a gigabyte inside Chromium inside Live is not a thing `[buffer~]` suffers.
+ *
+ * ------------------------------------------------------------------------------
+ * THE ONE THING THE SEAM IS: `ctx.appIn` and `ctx.appOut`.
+ *
+ * Every chain that reaches "the app" used to name `[jweb]`. Now it names the APP
+ * ENDPOINT, which is `[jweb]` under one target and `[js]` under the other - and that
+ * substitution is the whole port. A `[prepend notein]` feeds `ctx.appIn` either way; a
+ * `[route midinote]` claims from `ctx.appOut` either way. Nothing else in the chain
+ * vocabulary had to know.
+ *
+ * What headless GIVES UP is real and belongs here rather than in a surprise: no React
+ * device view (native `live.*` objects only, which `defineSurface` already generates),
+ * no Web Audio, no Workers, no floating windows, and ES5 in the emitted output.
+ */
+import { removeBox } from "./chains.mjs";
+
+/** The `[jweb]` box the template ships. Only a jweb-target device has one. */
+export const JWEB_ID = "obj-jweb";
+/** The `[js]` box, which EVERY device has - it is the wrapper. */
+export const JS_ID = "obj-js";
+
+export const TARGETS = ["jweb", "headless"];
+
+/** A device's target, defaulting to the one every device had before there was a choice. */
+export function deviceTarget(d) {
+  const target = d?.target ?? "jweb";
+  if (!TARGETS.includes(target)) {
+    throw new Error(`device "${d?.name}" declares target "${target}" - known targets are ${TARGETS.join(", ")}`);
+  }
+  return target;
+}
+
+export const isHeadless = (d) => deviceTarget(d) === "headless";
+
+/**
+ * Point the context's app endpoint at whatever this device's target is, and delete
+ * what the other one would have needed.
+ *
+ * Called by `composePatcher` BEFORE any chain, for the same reason `openAudio` is:
+ * a chain claims a stage in a stream it did not create, and it must not have to know
+ * which target created it.
+ *
+ * THE HEADLESS CASE REMOVES `[jweb]` OUTRIGHT, both cords with it - the template's
+ * `[js] -> [jweb]` and `[jweb] -> [js]`. A box left in place with nothing wired to it
+ * would still load Chromium, which is the entire cost the target exists to avoid.
+ *
+ * `appOut` is seeded rather than left null for headless, because `claimAppMessages`
+ * falls back to `[jweb]`'s outlet 2 when it is null - the one place the old assumption
+ * was a literal.
+ */
+export function openApp(ctx) {
+  const target = deviceTarget(ctx.device);
+
+  if (target === "jweb") {
+    ctx.target = "jweb";
+    ctx.jwebId = JWEB_ID;
+    ctx.appIn = JWEB_ID;
+    // Left null on purpose: claimAppMessages reads [jweb]'s outlet 2 as the head of
+    // the unclaimed stream, and asserts the template's cord to [js] is still there.
+    ctx.appOut = null;
+    return;
+  }
+
+  ctx.target = "headless";
+  removeBox(ctx.boxes, ctx.lines, JWEB_ID);
+  // Nothing may reach for `[jweb]` from here on. It is null rather than absent so the
+  // few genuinely jweb-only things (the `webaudio` chain, a declared window, the
+  // presentation rect applySurface gives the page) fail on a name rather than wire a
+  // cord to a box that is not in the patcher.
+  ctx.jwebId = null;
+  ctx.appIn = JS_ID;
+  // The wrapper's outlet 0 IS the app's outlet here: what a page would have sent
+  // across the bridge, `[js]` sends out of the same port, into the same routes.
+  ctx.appOut = [JS_ID, 0];
+  // ...and there is nowhere to pass the unmatched tail ON to, because [js] is already
+  // the far end. A route's unmatched outlet is simply left unconnected.
+  ctx.unmatchedId = null;
+}
+
+/** The message a jweb-only feature should refuse a headless device with. */
+export function refuseHeadless(ctx, what, instead) {
+  return new Error(
+    `device "${ctx.device?.name}" is target "headless", and ${what} needs the browser. ` +
+      `${instead} Drop \`target: "headless"\` from patcher/devices.mjs, or drop ${what}.`,
+  );
+}

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.3.0",
-    "@m4l-jweb/surface": "^1.3.0",
+    "@m4l-jweb/bridge": "^1.6.0",
+    "@m4l-jweb/surface": "^1.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@m4l-jweb/build": "^1.3.0",
+    "@m4l-jweb/build": "^1.6.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/starter/scripts/devices.mjs

@@ -17,8 +17,15 @@ export const devices = (await import(pathToFileURL(path.join(root, "patcher/devi
 /** The folder under src/app/ holding a device's UI. */
 export const uiDir = (d) => d.ui ?? d.name;
 
-/** Every distinct UI that has to be built (two devices may share one). */
-export const uiDirs = [...new Set(devices.map(uiDir))];
+/**
+ * Every distinct UI that has to be built (two devices may share one).
+ *
+ * A `target: "headless"` device has none - no [jweb], no page, no bundle - so it is not
+ * in this list and `pnpm dev:<it>` has nothing to serve. Its interface is its
+ * `surface.ts` and its logic is `headless.ts`, both of which the .amxd build reads
+ * directly.
+ */
+export const uiDirs = [...new Set(devices.filter((d) => d.target !== "headless").map(uiDir))];
 
 /** Validate a device name from the command line, with a useful error. */
 export function resolveDevice(arg) {
@@ -27,7 +34,17 @@ export function resolveDevice(arg) {
   if (!known.includes(name)) {
     throw new Error(`unknown device "${name}" - patcher/devices.mjs declares: ${known.join(", ")}`);
   }
-  const dir = uiDir(devices.find((d) => d.name === name));
+  const d = devices.find((x) => x.name === name);
+  // A HEADLESS device has no page to serve, and the harness exists to run one beside a
+  // mocked Live. Say that, rather than start a dev server on a folder with no App.tsx
+  // in it and fail somewhere inside vite.
+  if (d.target === "headless") {
+    throw new Error(
+      `device "${name}" is target "headless" - it has no page, so there is nothing for the dev harness to serve. ` +
+        `Its logic is src/app/${uiDir(d)}/headless.ts, which runs in Max's [js]: build it and load the .amxd.`,
+    );
+  }
+  const dir = uiDir(d);
   if (!existsSync(path.join(root, "src/app", dir))) {
     throw new Error(`device "${name}" has no UI at src/app/${dir}/`);
   }

package/templates/starter/tsconfig.app.json

@@ -24,5 +24,13 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["src"]
+  "include": ["src"],
+  /*
+   * A HEADLESS device's `headless.ts` is NOT app code. It is a Max `[js]` script -
+   * ES5, no modules, and its globals are `post`/`outlet`/`Task`/`LiveAPI` from the
+   * wrapper's max.d.ts, none of which exist here. The build compiles it in its own
+   * program (buildHeadless in @m4l-jweb/build), which is where it is typechecked;
+   * leaving it in this one reports every Max global as an undefined name.
+   */
+  "exclude": ["src/app/*/headless.ts"]
 }

package/templates/starter/tsconfig.test.json

@@ -19,11 +19,22 @@
 		"isolatedModules": true,
 		"moduleDetection": "force",
 		"noEmit": true,
+		// A test that RENDERS a component reaches a .tsx module, and tsc refuses to
+		// resolve one without a jsx setting even when the test itself is plain .ts.
+		// Matches tsconfig.app.json, and vitest.config.ts sets the same automatic
+		// runtime for its own esbuild pass.
+		"jsx": "react-jsx",
 		"strict": true
 	},
 	// `vitest.config.ts` is listed alongside the tests, and not only to check it: a
 	// project whose include matches nothing at all is a tsc ERROR (TS18003), and a
 	// freshly scaffolded repo has no tests yet. One file that always exists keeps the
 	// project valid from the first minute.
-	"include": ["tests/**/*.ts", "vitest.config.ts"]
+	// `src/vite-env.d.ts` is here for its `/// <reference types="vite/client" />`, not
+	// to be checked. A test that imports app code pulls that module into THIS program,
+	// and app code imports assets - `import track from "./x.ogg"` - whose ambient
+	// declarations live in vite's client types. Without them the test project reports
+	// "cannot find module ./x.ogg" for a file the app compiles fine, and only under
+	// `tsc -b`, which is the one that runs in CI.
+	"include": ["tests/**/*.ts", "vitest.config.ts", "src/vite-env.d.ts"]
 }

package/templates/starter/vitest.config.ts

@@ -5,6 +5,12 @@ export default defineConfig({
 	resolve: {
 		alias: [{ find: "@", replacement: fileURLToPath(new URL("./src", import.meta.url)) }],
 	},
+	// The app and the packages are compiled with tsconfig's "jsx": "react-jsx" - the
+	// AUTOMATIC runtime, where a component file imports no React at all. vitest's own
+	// esbuild pass defaults to the classic runtime, so a test that renders any component
+	// dies on "React is not defined" inside a file that is perfectly correct. Match the
+	// app.
+	esbuild: { jsx: "automatic" },
 	test: {
 		include: ["tests/**/*.test.{ts,mjs}", "packages/*/tests/**/*.test.{ts,mjs}", "src/**/*.test.{ts,tsx}"],
 		environment: "node",