@m4l-jweb/surface 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/surface",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -14,6 +14,8 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./store": "./src/store.ts",
+    "./react": "./src/react.tsx",
     "./dev": "./src/dev.tsx"
   },
   "files": [
@@ -22,7 +24,7 @@
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@m4l-jweb/bridge": "0.3.0"
+    "@m4l-jweb/bridge": "0.4.0"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/dev.tsx

@@ -27,6 +27,8 @@
  */
 import { useEffect, useRef, useState } from "react";
 import { simulate, tapMessages, type BridgeMessage } from "@m4l-jweb/bridge";
+import { BANK_SIZE, formatValue, type ParamSpec, type Surface } from "./index";
+import { useSurface } from "./react";
 
 /**
  * A string that must never reach a production bundle. The build test greps the
@@ -39,7 +41,9 @@ export const HARNESS_MARKER = "m4l-jweb:dev-harness:do-not-ship";
 const TICK_MS = 50;
 const LOG_LIMIT = 200;
 
-export function DevHarness() {
+type AnySurface = Surface<Record<string, ParamSpec>>;
+
+export function DevHarness({ surface }: { surface?: AnySurface | null }) {
   const [playing, setPlaying] = useState(false);
   const [bpm, setBpm] = useState(120);
   const [beats, setBeats] = useState(0);
@@ -102,6 +106,13 @@ export function DevHarness() {
         </div>
       </section>
 
+      {surface && surface.ids.length > 0 && (
+        <>
+          <Params surface={surface} />
+          <PushPreview surface={surface} />
+        </>
+      )}
+
       <section style={S.section}>
         <div style={S.row}>
           <h2 style={S.h2}>messages</h2>
@@ -128,6 +139,122 @@ export function DevHarness() {
   );
 }
 
+/**
+ * THE DEVICE PARAMETERS - the half of the device that is real to Push.
+ *
+ * Rendered from the SAME declaration the Max objects are generated from, and
+ * driven through the SAME store the app's `useParam` uses. So moving a control
+ * here is not a simulation of a parameter change: it goes through the bridge as
+ * `set_<id>`, exactly as the app's own controls do, and the app sees it come back
+ * as a parameter change. What a `[live.dial]` would do, minus Live.
+ */
+function Params({ surface }: { surface: AnySurface }) {
+  const [values, set] = useSurface(surface);
+
+  return (
+    <section style={S.section}>
+      <h2 style={S.h2}>device parameters</h2>
+      {surface.ids.map((id) => {
+        const spec = surface.params[id];
+        const value = values[id];
+        return (
+          <div key={id} style={S.paramRow}>
+            <span style={S.paramName} title={id}>
+              {spec.short}
+            </span>
+
+            {spec.kind === "dial" && (
+              <input
+                style={S.range}
+                type="range"
+                min={spec.range[0]}
+                max={spec.range[1]}
+                // A float parameter needs a fine grain, or the harness quantises
+                // what Live would not. `step` on the declaration means the
+                // parameter is genuinely stepped.
+                step={spec.step ?? (spec.range[1] - spec.range[0]) / 1000}
+                value={Number(value)}
+                onChange={(e) => set(id, Number(e.target.value))}
+              />
+            )}
+
+            {spec.kind === "toggle" && <input style={S.check} type="checkbox" checked={Boolean(value)} onChange={(e) => set(id, e.target.checked)} />}
+
+            {spec.kind === "menu" && (
+              <select style={S.select} value={String(value)} onChange={(e) => set(id, e.target.value)}>
+                {spec.options.map((o) => (
+                  <option key={o} value={o}>
+                    {o}
+                  </option>
+                ))}
+              </select>
+            )}
+
+            <span style={S.paramValue}>{formatValue(spec, value)}</span>
+          </div>
+        );
+      })}
+    </section>
+  );
+}
+
+/**
+ * THE PUSH PREVIEW - what a performer will actually be looking at.
+ *
+ * Eight encoders to a page, `short` names above, `format`ted values below. Push
+ * shows Live parameters and nothing else, so this is the whole of your device as
+ * far as the hardware is concerned. Getting it wrong - a label truncated to
+ * gibberish, a value that reads "0" when it means 280 Hz - is normally a
+ * hardware-in-the-loop discovery. Here it is a browser tab.
+ *
+ * With no banks declared, Live falls back to declaration order, and so does this.
+ */
+function PushPreview({ surface }: { surface: AnySurface }) {
+  const [values] = useSurface(surface);
+  const [page, setPage] = useState(0);
+
+  const banks = surface.banks?.length
+    ? surface.banks.map((b) => ({ name: b.name, ids: [...b.params] }))
+    : chunk(surface.ids, BANK_SIZE).map((ids, i) => ({ name: `Bank ${i + 1}`, ids }));
+
+  const bank = banks[Math.min(page, banks.length - 1)];
+
+  return (
+    <section style={S.section}>
+      <div style={S.row}>
+        <h2 style={S.h2}>push preview</h2>
+        <span style={S.bankName}>
+          {bank.name} ({Math.min(page, banks.length - 1) + 1}/{banks.length})
+        </span>
+        {banks.length > 1 && (
+          <button style={S.btn} onClick={() => setPage((p) => (p + 1) % banks.length)}>
+            next
+          </button>
+        )}
+      </div>
+      <div style={S.push}>
+        {bank.ids.map((id) => {
+          const spec = surface.params[id];
+          return (
+            <div key={id} style={S.cell}>
+              {/* Push gives an encoder ~8 characters. defineSurface() rejects a
+                  longer `short` outright, so this cannot silently truncate. */}
+              <div style={S.cellName}>{spec.short}</div>
+              <div style={S.cellValue}>{formatValue(spec, values[id])}</div>
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  );
+}
+
+const chunk = <T,>(xs: readonly T[], n: number): T[][] => {
+  const out: T[][] = [];
+  for (let i = 0; i < xs.length; i += n) out.push(xs.slice(i, i + n) as T[]);
+  return out;
+};
+
 const mono = "ui-monospace, SFMono-Regular, Menlo, monospace";
 
 const S: Record<string, React.CSSProperties> = {
@@ -166,6 +293,24 @@ const S: Record<string, React.CSSProperties> = {
     font: `11px ${mono}`,
   },
   readout: { color: "#7d8694" },
+  paramRow: { display: "grid", gridTemplateColumns: "52px 1fr 64px", gap: 6, alignItems: "center" },
+  paramName: { color: "#7d8694", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
+  paramValue: { color: "#8fd0a4", textAlign: "right", overflow: "hidden", whiteSpace: "nowrap" },
+  range: { width: "100%", accentColor: "#8fd0a4" },
+  check: { justifySelf: "start", accentColor: "#8fd0a4" },
+  select: {
+    background: "#0e1013",
+    color: "#c8ccd4",
+    border: "1px solid #333a45",
+    borderRadius: 3,
+    padding: "2px 4px",
+    font: `11px ${mono}`,
+  },
+  bankName: { color: "#7d8694", marginLeft: "auto" },
+  push: { display: "grid", gridTemplateColumns: "repeat(4, 1fr)", gap: 2 },
+  cell: { background: "#0e1013", border: "1px solid #262a31", borderRadius: 2, padding: "4px 5px", overflow: "hidden" },
+  cellName: { color: "#7d8694", fontSize: 10, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
+  cellValue: { color: "#8fd0a4", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
   log: { listStyle: "none", margin: 0, padding: 0, overflowY: "auto", maxHeight: 260, display: "flex", flexDirection: "column", gap: 1 },
   line: { display: "flex", gap: 6, whiteSpace: "nowrap" },
   arrowIn: { color: "#5aa9e6" },

package/src/index.ts

@@ -18,27 +18,61 @@
  *
  * This file is the one declaration all four are derived from.
  *
- * STATUS - read this before you reach for it. Shipped today (Stage 0.3 of
- * doc/TODO.md): the declaration, its types, and its validation. NOT shipped:
- * the codegen that turns it into Max objects and wiring (Stage 2). So a Surface
- * currently type-checks, validates, and drives the dev harness - but the
- * parameters Live actually sees still come from `parameters` in
- * `patcher/devices.mjs`. Declaring one does not yet make a dial appear in Live.
- * Keep the two in step by hand until Stage 2 lands and deletes the manifest field.
+ * STATUS. The Max side is generated: the build imports this declaration and emits
+ * the `live.*` objects and their wiring in both directions (`applySurface()` in
+ * @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.
  */
 
 /* ------------------------------------------------------------------ *
  * Parameter kinds
  * ------------------------------------------------------------------ */
 
+/**
+ * The units Live knows how to print. Anything else is a CUSTOM unit: Live shows
+ * the number and appends your string, and a sprintf pattern works too
+ * (`"%0.2f Bogons"`).
+ *
+ * Declaring one is not decoration. With no unit, a float parameter is printed
+ * with Max's default unit style, which is INTEGER - so a 0-1 cutoff reads "0" or
+ * "1" on a Push while sweeping perfectly smoothly underneath. Say `unit: "Hz"`
+ * and the same parameter reads "7.3 kHz".
+ */
+export type Unit = "Hz" | "dB" | "ms" | "%" | "st" | "pan" | "midi" | (string & {});
+
 export interface DialSpec {
   kind: "dial";
-  /** [min, max]. Live needs a bounded range; there is no unbounded parameter. */
+  /**
+   * [min, max], IN REAL UNITS. Live needs a bounded range; there is no unbounded
+   * parameter.
+   *
+   * Declare the range the parameter actually has - `[40, 18000]` for a cutoff,
+   * not `[0, 1]` with the mapping hidden in a chain. Live's automation lane, Push
+   * and your app then all read Hz, and the DSP takes the value directly.
+   */
   range: [number, number];
   default: number;
   /** `step: 1` makes it an integer parameter (Max parameter_type 1). */
   step?: number;
-  unit?: string;
+  /** What Live prints. Omit only for a bare number. See {@link Unit}. */
+  unit?: Unit;
+  /**
+   * Bend the knob's travel: > 1 gives the BOTTOM of the range more of the sweep.
+   *
+   * Frequency and time want this, because hearing is logarithmic - a linear sweep
+   * of 40 Hz to 18 kHz spends almost all its travel in the top octave, where you
+   * cannot hear anything happening, and races through the bottom, where everything
+   * does. It changes the mapping of rotation to value, never the value itself.
+   */
+  exponent?: number;
+  /** Quantise the range into N settings. */
+  steps?: number;
   /** What the dev harness and the Push preview print under the encoder. */
   format?: (v: number) => string;
   /** Push has ~8 characters per encoder label. Longer names are truncated. */
@@ -71,7 +105,18 @@ export const toggle = (spec: Omit<ToggleSpec, "kind">): ToggleSpec => ({
   kind: "toggle",
   ...spec,
 });
-export const menu = <O extends string>(spec: Omit<MenuSpec<O>, "kind">): MenuSpec<O> => ({ kind: "menu", ...spec });
+/**
+ * The options are spelled out rather than written as `Omit<MenuSpec<O>, "kind">`,
+ * and that is not a style choice: TypeScript cannot infer `O` THROUGH an `Omit`,
+ * so it falls back to the constraint and every menu's value type widens to
+ * `string`. The whole point of a menu is that `useParam(surface, "rate")` gives
+ * you `"off" | "1/4" | ...` and a typo fails the build, so the inference is the
+ * feature.
+ */
+export const menu = <const O extends string>(spec: { options: readonly O[]; default: O; short: string }): MenuSpec<O> => ({
+  kind: "menu",
+  ...spec,
+});
 
 /* ------------------------------------------------------------------ *
  * The surface

package/src/react.tsx

@@ -0,0 +1,45 @@
+/**
+ * @m4l-jweb/surface/react - bind a declared parameter to React, in both directions.
+ *
+ *   const [cutoff, setCutoff] = useParam(surface, "cutoff");
+ *
+ * That is a two-way binding to a REAL Live parameter, typed from the declaration:
+ * `number` for a dial, `boolean` for a toggle, the union of the options for a
+ * menu. Turning a Push encoder moves the React state; moving the React control
+ * moves the Live parameter, so automation, MIDI mapping and Push all follow.
+ *
+ * The component names no selectors. `cutoff` and `set_cutoff` are derived from the
+ * declaration, exactly as the patcher's `[prepend cutoff]` and `[route set_cutoff]`
+ * are - one declaration, one name, both sides. `tests/protocol.test.mjs` fails if a
+ * device re-declares one by hand.
+ *
+ * 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 type { ParamSpec, ParamValue, Surface } from "./index";
+import { paramStore } from "./store";
+
+/**
+ * A two-way binding to one Live parameter. `[value, setValue]`, like useState -
+ * except the state lives in Live, and so do automation, MIDI mapping and Push.
+ */
+export function useParam<P extends Record<string, ParamSpec>, K extends Extract<keyof P, string>>(
+  surface: Surface<P>,
+  id: K,
+): [ParamValue<P[K]>, (value: ParamValue<P[K]>) => void] {
+  const store = useMemo(() => paramStore(surface), [surface]);
+  const values = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const set = useCallback((value: ParamValue<P[K]>) => store.write(id, value), [store, id]);
+  return [values[id] as ParamValue<P[K]>, set];
+}
+
+/** Every parameter at once, for the component that wants the whole bag - the dev harness's panel, say. */
+export function useSurface<P extends Record<string, ParamSpec>>(
+  surface: Surface<P>,
+): [{ [K in keyof P]: ParamValue<P[K]> }, <K extends Extract<keyof P, string>>(id: K, value: ParamValue<P[K]>) => void] {
+  const store = useMemo(() => paramStore(surface), [surface]);
+  const values = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const set = useCallback(<K extends Extract<keyof P, string>>(id: K, value: ParamValue<P[K]>) => store.write(id, value), [store]);
+  return [values as { [K in keyof P]: ParamValue<P[K]> }, set];
+}

package/src/store.ts

@@ -0,0 +1,135 @@
+/**
+ * store.ts - the parameter state behind useParam(), with no React in it.
+ *
+ * Separate from react.tsx on purpose. Everything subtle about a two-way parameter
+ * binding lives here - the wire encoding, the echo guard - and none of it needs a
+ * DOM, so all of it is testable (tests/surface-store.test.mjs). React gets a thin
+ * useSyncExternalStore wrapper over this.
+ *
+ * ------------------------------------------------------------------------------
+ * ONE STORE PER SURFACE, and it is not an optimisation.
+ *
+ * The bridge holds ONE handler per selector: a second `bindInlet("cutoff", ...)`
+ * silently REPLACES the first. Two components each binding the parameter they
+ * read would mean one of them never updates again, with no error anywhere. So a
+ * surface binds each parameter exactly once, here, and fans out to subscribers.
+ *
+ * ------------------------------------------------------------------------------
+ * THE ECHO GUARD, and what it is actually for.
+ *
+ * It is NOT for our own writes coming back. They do not: the patcher feeds the
+ * live.* object a `set <value>`, which updates it without producing outlet output
+ * (see surface.mjs). That is the defence at the source, and it is the load-bearing
+ * one.
+ *
+ * This is the defence at the DESTINATION, against a different failure: a value
+ * arriving *while the user is dragging*. Live sends one whenever it likes - an
+ * automation lane is playing, someone turned the dial in Live, a Push encoder
+ * moved - and applying it mid-drag makes the control jump backwards under the
+ * mouse. So for a short window after a local write, an inbound value is dropped:
+ * the user's hand wins, and the next value after the window lands normally.
+ */
+import { bindInlet, outlet } from "@m4l-jweb/bridge";
+import { defaults, type ParamSpec, type Surface } from "./index";
+
+/** How long the user's hand beats an inbound value: long enough to cover the gaps between drag events, short enough to be imperceptible. */
+export const GUARD_MS = 120;
+
+/** Floats do not survive a round trip exactly. Anything closer than this is the same value. */
+const EPSILON = 1e-6;
+
+/** Max stores every parameter as a NUMBER. A menu is an index into its options; a toggle is 0/1. */
+export function toWire(spec: ParamSpec, value: unknown): number {
+  if (spec.kind === "toggle") return value ? 1 : 0;
+  if (spec.kind === "menu") {
+    const i = spec.options.indexOf(String(value));
+    return i < 0 ? 0 : i;
+  }
+  return Number(value);
+}
+
+/** ...and back. An out-of-range menu index falls back to the default rather than `undefined`. */
+export function fromWire(spec: ParamSpec, wire: number): unknown {
+  if (spec.kind === "toggle") return wire >= 0.5;
+  if (spec.kind === "menu") return spec.options[Math.round(wire)] ?? spec.default;
+  return wire;
+}
+
+export type Values = Record<string, unknown>;
+
+export interface ParamStore {
+  get(): Values;
+  subscribe(fn: () => void): () => void;
+  write(id: string, value: unknown): void;
+}
+
+const stores = new WeakMap<object, ParamStore>();
+
+/**
+ * The store for a surface - created once, never torn down. The bridge's bindings
+ * are process-wide, so tearing one down would unbind a parameter another component
+ * still reads.
+ */
+export function paramStore<P extends Record<string, ParamSpec>>(surface: Surface<P>): ParamStore {
+  const existing = stores.get(surface);
+  if (existing) return existing;
+
+  // The app's state before Live has replied: the declared defaults, which are also
+  // what the live.* objects load with.
+  let values: Values = { ...(defaults(surface) as Values) };
+  const listeners = new Set<() => void>();
+  const pending = new Map<string, { wire: number; at: number }>();
+
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+  const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+
+  for (const id of surface.ids) {
+    const spec = surface.params[id];
+    // `<id> <value>` - out of the live.* object, via [prepend <id>].
+    bindInlet(id, (raw) => {
+      const wire = Number(raw);
+      const p = pending.get(id);
+      if (p) {
+        // Our own value, come back around (Live CAN echo one: a `set` write is
+        // silent, but a value we sent while automation was writing the same
+        // parameter may still return). Nothing to apply, and clearing the guard
+        // early lets the next genuine value through sooner.
+        if (Math.abs(wire - p.wire) <= EPSILON) {
+          pending.delete(id);
+          return;
+        }
+        // A DIFFERENT value, arriving while the user is still moving the control.
+        // Dropping it is the point - see the note at the top of this file.
+        if (now() - p.at < GUARD_MS) return;
+        pending.delete(id);
+      }
+      values = { ...values, [id]: fromWire(spec, wire) };
+      notify();
+    });
+  }
+
+  const store: ParamStore = {
+    get: () => values,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    write(id, value) {
+      const spec = surface.params[id];
+      if (!spec) return;
+      const wire = toWire(spec, value);
+      // Optimistic: the control follows the hand at once rather than waiting for
+      // Live - which, because the patcher writes with `set`, would never send this
+      // value back anyway.
+      values = { ...values, [id]: value };
+      pending.set(id, { wire, at: now() });
+      notify();
+      outlet(`set_${id}`, wire);
+    },
+  };
+
+  stores.set(surface, store);
+  return store;
+}