@m4l-jweb/surface 0.9.9 → 1.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @m4l-jweb/surface
+
+Declare a device's Live parameters once, as code, and get the real thing: native `live.dial` / `live.text` objects in the patcher, automatable lanes, MIDI mapping, and Push. Plus React hooks to read and write them, and a mocked-Live harness so the UI runs in an ordinary browser.
+
+Part of **[m4l-jweb](https://github.com/alienmind/m4l-jweb)** - build Ableton Live devices (`.amxd`) from a TypeScript repo: React UI, LiveAPI glue, CI builds, no Max editor.
+
+## Install
+
+```bash
+pnpm add @m4l-jweb/surface
+```
+
+## Usage
+
+```ts
+// surface.ts - the declaration
+import { defineSurface } from "@m4l-jweb/surface";
+
+export default defineSurface({
+  params: {
+    cutoff: { type: "float", min: 20, max: 18000, unit: "Hz", default: 18000, exponent: 3 },
+    play:   { type: "bool", default: 0 },
+  },
+});
+
+// App.tsx - the same parameter, from React
+import { useParam, useStateSync } from "@m4l-jweb/surface/react";
+
+const [cutoff, setCutoff] = useParam(surface, "cutoff");   // a real Live parameter
+const [notes, setNotes]   = useStateSync(surface, "notes"); // arbitrary JSON, saved in the Set
+```
+
+## Notes
+
+- A parameter declared here is generated into the patcher AND into the wrapper - one declaration, both sides, so they cannot disagree.
+- `useStateSync()` persists arbitrary JSON into the Ableton Live Set itself, per device instance, restored on load.
+- `@m4l-jweb/surface/dev` renders the device against a mocked Live, so the UI is developed with hot reload in a browser rather than by reopening Live.
+
+## Requirements
+
+Ableton Live 12 with Max 9. Devices are built on `[jweb~]`, the browser view with signal outlets; older hosts are unverified.
+
+## Links
+
+- [Repository and full README](https://github.com/alienmind/m4l-jweb)
+- [Architecture](https://github.com/alienmind/m4l-jweb/blob/main/doc/ARCHITECTURE.md)
+- [What Max actually does: the measured facts](https://github.com/alienmind/m4l-jweb/blob/main/doc/MAX-FACTS.md)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/surface",
-  "version": "0.9.9",
+  "version": "1.1.0",
   "description": "m4l-jweb: declare a device's Live parameters as code - the surface Push actually sees - plus a mocked-Live dev harness.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@m4l-jweb/bridge": "0.9.9"
+    "@m4l-jweb/bridge": "1.1.0"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/index.ts

@@ -23,11 +23,11 @@
  * @m4l-jweb/build). Declaring a parameter here makes a dial appear in Live, and
  * `patcher/devices.mjs` has no `parameters` field any more.
  *
- * The APP side is not generated yet - `useParam()` / `useSurface()` and the
- * generated protocol selectors are Stages 2.2 and 2.3 of doc/TODO.md - so a
- * device still names its parameters in its own `protocol.ts` and sends `set_<id>`
- * through the bridge itself. Push banks are deferred (3.3); until then Live falls
- * back to declaration order, and Push shows every parameter.
+ * The APP side is generated too now: `useParam()` / `useSurface()` read a declared
+ * parameter in React (@m4l-jweb/surface/react) and the selectors come from the
+ * declaration, so a device does not retype `set_<id>` in its own `protocol.ts`. Push
+ * banks ship as well - a surface that declares none falls back to declaration order,
+ * and Push shows every parameter.
  */
 
 /* ------------------------------------------------------------------ *
@@ -141,7 +141,38 @@ export interface WindowSpec {
   title: string;
   width: number;
   height: number;
-  entry: string;
+  /**
+   * The component to bundle, from the device's own folder. Mutually exclusive
+   * with `site`: a window's content is either one of our components or a
+   * prebuilt directory, never both.
+   */
+  entry?: string;
+  /**
+   * The window's page is a SOUND SOURCE.
+   *
+   * It compiles to `[jweb~]` instead of `[jweb]`, and the page's L/R signal
+   * outlets leave the subpatcher on a pair of `[outlet]`s and are summed into the
+   * device's audio path at the same `[+~]` stage shape the `webaudio` chain uses.
+   * The device must therefore be an `audio` or `instrument` device; a MIDI device
+   * has no signal path and the build says so.
+   *
+   * A window that makes sound cannot wait to be opened before it loads: the page
+   * is pulsed open-then-closed once at device load (`loadbang`), so its
+   * AudioContext exists whether or not anyone ever looks at the window.
+   *
+   * The plain `[jweb]` window is untouched by this - `audio` ADDS a second
+   * primitive rather than changing the first.
+   */
+  audio?: boolean;
+  /**
+   * Window content from a PREBUILT static directory rather than a component of
+   * ours - a whole site, built by something else (its own Astro/vite build), and
+   * delivered as a folder next to the `.amxd` instead of base64 inside it.
+   *
+   * The path is relative to the device repo root and must contain `index.html`.
+   * Mutually exclusive with `entry`.
+   */
+  site?: string;
   /**
    * Keep the window in FRONT of Live, instead of behind it the moment Live is clicked.
    *
@@ -192,6 +223,32 @@ export const dial = (spec: Omit<DialSpec, "kind">): DialSpec => ({
   kind: "dial",
   ...spec,
 });
+
+/**
+ * A POOL of interchangeable native dials, for a device whose real controls are not
+ * known until it runs.
+ *
+ * A `live.dial` is stamped into the frozen `.amxd` at build time, so a device cannot
+ * grow one when the user's code asks for a control. What it can do is reserve a
+ * fixed number of them and lend them out - `slider()` calls in a pattern, the
+ * parameters of whatever effect was just loaded - and that borrowing is the same
+ * problem in every device that has it.
+ *
+ *   params: { ...knobPool(8) }        // s1..s8, all 0..1
+ *
+ * The dials are declared 0..1 because a borrower's real range is not known here.
+ * `useControls()` in ./react then hands them out in order, tells Live what each one
+ * currently IS (name, unit, range - see describeParam in @m4l-jweb/bridge), and
+ * keeps the scaling straight.
+ */
+export const knobPool = <N extends number>(count: N, prefix = "s"): Record<string, DialSpec> => {
+  const out: Record<string, DialSpec> = {};
+  for (let i = 1; i <= count; i++) {
+    // The short name is what Push prints when nothing has borrowed the slot yet.
+    out[`${prefix}${i}`] = dial({ range: [0, 1], default: 0, short: `${prefix.toUpperCase()}${i}` });
+  }
+  return out;
+};
 export const toggle = (spec: Omit<ToggleSpec, "kind">): ToggleSpec => ({
   kind: "toggle",
   ...spec,
@@ -243,10 +300,20 @@ export interface NativeLayout<K extends string = string> {
    */
   params: readonly K[];
   /**
-   * Max rows per column. Default 3 - the device view is a fixed ~169 px tall and a
-   * `live.dial` needs a 56 px pitch, so only 3 fit vertically.
+   * How the controls are arranged. Default 3.
+   *
+   * A NUMBER is rows per column, filled column-major: three down, then the next
+   * column. Adding a parameter never reshuffles the ones before it.
+   *
+   * AN ARRAY is the size of each row, filled left to right - `[1, 4, 4]` puts one
+   * control on the first row and four on each of the next two. Column-major cannot
+   * express that, and it is what a panel usually wants to say: a transport button
+   * ABOVE two banks of dials, rather than interleaved with them.
+   *
+   * Either way the device view is a fixed ~169 px tall and a `live.dial` needs a
+   * 56 px pitch, so three rows is the ceiling.
    */
-  rows?: number;
+  rows?: number | number[];
   /**
    * LAYERED "two screens" instead of side-by-side. When true, `[jweb]` is built
    * full-width and the dials OVERLAP its left, and the app flips between them with
@@ -349,6 +416,19 @@ export function defineSurface<
     }
   }
 
+  // A window holds EITHER a component of ours or a prebuilt site. Both is
+  // ambiguous (which one loads?) and neither is an empty window - and both would
+  // otherwise fail deep in the build, as a vite entry that does not resolve or a
+  // page that never gets a url.
+  for (const [id, w] of Object.entries(def.windows ?? {})) {
+    if (w.entry && w.site) {
+      throw new Error(`surface: window "${id}" declares both entry "${w.entry}" and site "${w.site}" - a window holds one or the other`);
+    }
+    if (!w.entry && !w.site) {
+      throw new Error(`surface: window "${id}" declares neither entry nor site - it would open empty`);
+    }
+  }
+
   // A native layout may only name parameters that exist, and may not ask for more
   // rows than the device view holds. Both throw here, at build time, for the same
   // reason the bank checks do: a typo would otherwise generate a cord from a box
@@ -359,7 +439,12 @@ export function defineSurface<
       if (!def.params[id]) throw new Error(`surface: layout.native names "${id}", which is not a declared parameter`);
     }
     const rows = native.rows ?? 3;
-    if (rows < 1 || rows > 3) throw new Error(`surface: layout.native.rows must be 1..3 - the device view is 169 px tall`);
+    if (Array.isArray(rows)) {
+      if (rows.length > 3) throw new Error(`surface: layout.native.rows has ${rows.length} rows - the device view is 169 px tall and holds 3`);
+      if (rows.some((n) => !(n > 0))) throw new Error(`surface: layout.native.rows must be positive counts, e.g. [1, 4, 4]`);
+    } else if (rows < 1 || rows > 3) {
+      throw new Error(`surface: layout.native.rows must be 1..3 - the device view is 169 px tall`);
+    }
     if (native.switch !== undefined && !def.params[native.switch]) {
       throw new Error(`surface: layout.native.switch names "${native.switch}", which is not a declared parameter`);
     }

package/src/react.tsx

@@ -16,8 +16,8 @@
  * The state itself, the wire encoding and the echo guard live in `store.ts`, which
  * has no React in it and is tested without a DOM. This file is the hook.
  */
-import { useCallback, useMemo, useSyncExternalStore } from "react";
-import { outlet } from "@m4l-jweb/bridge";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { describeParam, onParamRange, outlet } from "@m4l-jweb/bridge";
 import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, Watch, WatchSpec, WatchValue, WindowSpec } from "./index";
 import { JWEB_VARNAME } from "./index";
 import { paramStore, stateStore, watchStore } from "./store";
@@ -158,3 +158,141 @@ export function useStateSync<
   const set = useCallback((value: StateValue<S[K]>) => store.write(id, value), [store, id]);
   return [values[id] as StateValue<S[K]>, set];
 }
+
+/* ------------------------------------------------------------------ *
+ * Borrowing from a native knob pool
+ * ------------------------------------------------------------------ */
+
+/** A control a device wants on a native dial, described as well as it can. */
+export interface BorrowedControl {
+  /** What to call it - the user's own term where the device can infer one. */
+  name: string;
+  /** Its real travel. The dial is declared 0..1; this is what the value means. */
+  min: number;
+  max: number;
+  /** How Live should print it ("Hz", "dB", "%"...). Optional; see describeParam. */
+  unit?: string;
+  /** Where it starts, in real units, the first time it takes a slot. */
+  value?: number;
+}
+
+/** A borrowed control, wired to the dial that is carrying it. */
+export interface PooledControl extends BorrowedControl {
+  /** Position 0..1, for drawing a fader. */
+  norm: number;
+  /** The value the device should use, in the control's own units. */
+  raw: number;
+  /** Move it, from a 0..1 position. */
+  set: (norm: number) => void;
+  /** Which pool slot it landed on (1-based), for a tooltip. */
+  slot: number;
+  /** The parameter id behind it, for anything that needs to name it. */
+  param: string;
+}
+
+/**
+ * Hand a device's dynamic controls to a fixed pool of native dials.
+ *
+ * A device whose controls come from the user's code - a pattern's `slider()`s, the
+ * parameters of an effect just loaded - cannot declare them: a `live.dial` is
+ * stamped into the frozen `.amxd` at build time. So it declares a POOL
+ * (`knobPool(8)`) and borrows: control 1 takes the first slot, control 2 the
+ * second, and a control that goes away returns its slot. Order is the mapping,
+ * which means re-editing a line keeps the same knob on the same control.
+ *
+ * WHAT THIS OWNS, so no device has to:
+ *
+ * 1. The by-order borrowing, and seeding a freshly borrowed dial with the
+ *    control's own starting value rather than leaving it at 0.
+ * 2. Telling Live what each dial currently IS - name, unit, range - so the panel
+ *    stops reading `S1` and the readout stops reading `0.44` for 600 Hz.
+ * 3. THE SCALING, which is the part that bites. Live accepts a runtime range, and
+ *    the parameter then reports IN THAT RANGE. A device that goes on normalizing
+ *    0..1 would scale an already-scaled value and the knob would stick at its
+ *    minimum - the bug that got an earlier attempt at this reverted. The wrapper
+ *    answers whether each range took, and this hook scales exactly once either way.
+ *
+ * KNOWN LIMIT, measured in Live: the name reaches the DEVICE PANEL, not Live's
+ * parameter registry or a Rack macro picker, which keep the pool's own `S1..S8`.
+ * A frozen device cannot rename a parameter there. So render the name in your own
+ * UI as well - never rely on the dial to carry it.
+ */
+export function useControls<P extends Record<string, ParamSpec>>(
+  surface: Surface<P>,
+  controls: readonly BorrowedControl[],
+  poolIds: readonly Extract<keyof P, string>[],
+): PooledControl[] {
+  /* eslint-disable react-hooks/rules-of-hooks */
+  // A pool is dials, so its values are numbers - but `P` is the whole surface and
+  // the compiler cannot know the caller passed dial ids. Narrowed once, here,
+  // rather than at every write below.
+  const params = poolIds.map((id) => useParam(surface, id)) as unknown as [number, (v: number) => void][];
+  /* eslint-enable react-hooks/rules-of-hooks */
+
+  /** Which dials Live actually widened. Until it says so, the dial is 0..1. */
+  const [real, setReal] = useState<boolean[]>([]);
+  useEffect(() => {
+    onParamRange((id, took) => {
+      const i = poolIds.indexOf(id as Extract<keyof P, string>);
+      if (i < 0) return;
+      setReal((prev) => {
+        if (prev[i] === took) return prev;
+        const next = prev.slice();
+        next[i] = took;
+        return next;
+      });
+    });
+    // The pool is a declaration; it does not change at runtime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Say what each slot is now carrying, on change only: describeParam writes Live
+  // parameter attributes, and a device re-rendering is not news.
+  const described = useRef<string[]>([]);
+  useEffect(() => {
+    for (let i = 0; i < poolIds.length; i++) {
+      const c = controls[i];
+      const key = c ? `${c.name} ${c.min} ${c.max} ${c.unit ?? ""}` : "";
+      if (described.current[i] === key) continue;
+      described.current[i] = key;
+      // A slot nobody is borrowing goes back to its declared identity, or it would
+      // keep the name of a control that is no longer there.
+      if (c) describeParam(poolIds[i], { name: c.name, unit: c.unit, range: [c.min, c.max] });
+      else describeParam(poolIds[i], { name: String(poolIds[i]).toUpperCase(), range: [0, 1] });
+    }
+  }, [controls, poolIds]);
+
+  // Seed a slot the first time a given control takes it, so an untouched dial reads
+  // what the control says rather than 0.
+  const seeded = useRef<string[]>([]);
+  useEffect(() => {
+    controls.forEach((c, i) => {
+      if (i >= poolIds.length || c.value === undefined) return;
+      const key = `${c.name} ${c.min} ${c.max}`;
+      if (seeded.current[i] === key) return;
+      seeded.current[i] = key;
+      const span = c.max - c.min || 1;
+      params[i][1](real[i] ? c.value : (c.value - c.min) / span);
+    });
+    seeded.current.length = controls.length;
+    // `params` is rebuilt every render by design; the seed is guarded by `seeded`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [controls, real]);
+
+  return controls.slice(0, poolIds.length).map((c, i) => {
+    const span = c.max - c.min || 1;
+    const held = Number(params[i][0] ?? 0);
+    const norm = real[i] ? (held - c.min) / span : held;
+    return {
+      ...c,
+      norm: Math.min(1, Math.max(0, norm)),
+      raw: real[i] ? held : c.min + held * span,
+      set: (n: number) => {
+        const clamped = Math.min(1, Math.max(0, n));
+        params[i][1](real[i] ? c.min + clamped * span : clamped);
+      },
+      slot: i + 1,
+      param: String(poolIds[i]),
+    };
+  });
+}