@m4l-jweb/surface 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Lopez (alienmind)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@m4l-jweb/surface",
+  "version": "0.2.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alienmind/m4l-jweb.git",
+    "directory": "packages/surface"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./dev": "./src/dev.tsx"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@m4l-jweb/bridge": "0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "sideEffects": false
+}

package/src/dev.tsx

@@ -0,0 +1,177 @@
+/**
+ * @m4l-jweb/surface/dev - a mocked Live, next to your app, in a browser tab.
+ *
+ * `pnpm dev` used to hand you `window.maxSimulate()` on the console. That is a
+ * shim, not an environment: to see a sequencer run you had to type ticks in by
+ * hand, and to see what your device was actually saying you had nothing at all.
+ *
+ * This is the other half of the device, mocked:
+ *
+ *   - A TRANSPORT. Play/stop and a BPM field driving a real clock that emits
+ *     `tick <playing> <beats>` and `tempo <bpm>` at the same 50 ms cadence the
+ *     wrapper polls Live at. A sequencer becomes developable without a DAW.
+ *   - A MESSAGE LOG. Every selector crossing the bridge, both directions. The
+ *     bridge is the only channel between the two halves of a device, so tapping
+ *     it shows you the device's entire contract, live. This is the single best
+ *     debugging tool the stack has and it costs almost nothing.
+ *
+ * THE HONEST LIMIT: a mock is a mock. It cannot tell you about MIDI timing
+ * jitter, real DSP, or LiveAPI's behaviour on a loaded set. What it gives you is
+ * the whole message-level contract, exercised without Live - which is the part
+ * that is tedious to test and easy to get wrong. Keep "load it in Live" for what
+ * genuinely needs Live.
+ *
+ * NEVER SHIPPED. This module must not appear in the bundle embedded in a .amxd.
+ * Import it only behind `import.meta.env.DEV` (see src/main.tsx), and note that
+ * tests/bundle.test.mjs asserts HARNESS_MARKER is absent from the built ui.html.
+ */
+import { useEffect, useRef, useState } from "react";
+import { simulate, tapMessages, type BridgeMessage } from "@m4l-jweb/bridge";
+
+/**
+ * A string that must never reach a production bundle. The build test greps the
+ * emitted ui.html for it: if this module survives tree-shaking, the test fails
+ * rather than a dev panel shipping inside someone's device.
+ */
+export const HARNESS_MARKER = "m4l-jweb:dev-harness:do-not-ship";
+
+/** The wrapper polls Live's transport at 20 Hz. The mock lies at the same rate. */
+const TICK_MS = 50;
+const LOG_LIMIT = 200;
+
+export function DevHarness() {
+  const [playing, setPlaying] = useState(false);
+  const [bpm, setBpm] = useState(120);
+  const [beats, setBeats] = useState(0);
+  const [log, setLog] = useState<BridgeMessage[]>([]);
+
+  // Log every message crossing the bridge, both directions.
+  useEffect(() => tapMessages((m) => setLog((prev) => [m, ...prev].slice(0, LOG_LIMIT))), []);
+
+  // Tempo is OBSERVED in the real device, not polled: it is sent once on attach
+  // and then only on change. Mirror that - send it when it changes, not on tick.
+  useEffect(() => simulate("tempo", bpm), [bpm]);
+
+  // The transport clock. `beats` advances in musical time, so changing the BPM
+  // mid-playback changes the rate, exactly as it does in Live.
+  const beatsRef = useRef(0);
+  const bpmRef = useRef(bpm);
+  bpmRef.current = bpm;
+
+  useEffect(() => {
+    if (!playing) {
+      // Live reports position 0 and is_playing 0 when stopped, and keeps
+      // reporting it - a device that only listens for changes must still see this.
+      simulate("tick", 0, beatsRef.current);
+      return;
+    }
+    const id = setInterval(() => {
+      beatsRef.current += (TICK_MS / 60000) * bpmRef.current;
+      setBeats(beatsRef.current);
+      simulate("tick", 1, beatsRef.current);
+    }, TICK_MS);
+    return () => clearInterval(id);
+  }, [playing]);
+
+  function stop() {
+    setPlaying(false);
+    beatsRef.current = 0;
+    setBeats(0);
+    simulate("tick", 0, 0);
+  }
+
+  return (
+    <aside data-harness={HARNESS_MARKER} style={S.panel}>
+      <h2 style={S.h2}>LIVE (mocked)</h2>
+
+      <section style={S.section}>
+        <div style={S.row}>
+          <button style={S.btn} onClick={() => setPlaying((p) => !p)}>
+            {playing ? "pause" : "play"}
+          </button>
+          <button style={S.btn} onClick={stop}>
+            stop
+          </button>
+          <label style={S.label}>
+            BPM
+            <input style={S.input} type="number" min={20} max={300} step={0.5} value={bpm} onChange={(e) => setBpm(Number(e.target.value))} />
+          </label>
+        </div>
+        <div style={S.readout}>
+          bar {Math.floor(beats / 4) + 1} | beat {(beats % 4).toFixed(2)}
+        </div>
+      </section>
+
+      <section style={S.section}>
+        <div style={S.row}>
+          <h2 style={S.h2}>messages</h2>
+          <button style={S.btn} onClick={() => setLog([])}>
+            clear
+          </button>
+        </div>
+        <ol style={S.log}>
+          {log.map((m, i) => (
+            <li key={`${m.at}-${i}`} style={S.line}>
+              <span style={m.direction === "in" ? S.arrowIn : S.arrowOut}>{m.direction === "in" ? "->" : "<-"}</span>
+              <span style={S.selector}>{m.selector}</span>
+              <span style={S.args}>{m.args.map(String).join(" ")}</span>
+            </li>
+          ))}
+          {!log.length && <li style={S.empty}>nothing yet - press play, or interact with the device</li>}
+        </ol>
+      </section>
+
+      <p style={S.note}>
+        Dev only. Not in the built device. A mock cannot tell you about MIDI jitter, DSP or a real Live set - load it in Live for those.
+      </p>
+    </aside>
+  );
+}
+
+const mono = "ui-monospace, SFMono-Regular, Menlo, monospace";
+
+const S: Record<string, React.CSSProperties> = {
+  panel: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 12,
+    padding: 12,
+    background: "#14161a",
+    color: "#c8ccd4",
+    font: `12px ${mono}`,
+    minWidth: 280,
+    maxWidth: 360,
+    borderRight: "1px solid #262a31",
+  },
+  h2: { margin: 0, font: `600 11px ${mono}`, letterSpacing: "0.08em", textTransform: "uppercase", color: "#7d8694" },
+  section: { display: "flex", flexDirection: "column", gap: 6 },
+  row: { display: "flex", gap: 6, alignItems: "center" },
+  btn: {
+    background: "#242932",
+    color: "#c8ccd4",
+    border: "1px solid #333a45",
+    borderRadius: 3,
+    padding: "3px 9px",
+    font: `11px ${mono}`,
+    cursor: "pointer",
+  },
+  label: { display: "flex", gap: 4, alignItems: "center", marginLeft: "auto", color: "#7d8694" },
+  input: {
+    width: 62,
+    background: "#0e1013",
+    color: "#c8ccd4",
+    border: "1px solid #333a45",
+    borderRadius: 3,
+    padding: "3px 5px",
+    font: `11px ${mono}`,
+  },
+  readout: { color: "#7d8694" },
+  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" },
+  arrowOut: { color: "#e6a15a" },
+  selector: { color: "#c8ccd4" },
+  args: { color: "#7d8694", overflow: "hidden", textOverflow: "ellipsis" },
+  empty: { color: "#4d5460" },
+  note: { margin: 0, color: "#4d5460", lineHeight: 1.4 },
+};

package/src/index.ts

@@ -0,0 +1,166 @@
+/**
+ * @m4l-jweb/surface - declare a device's Live parameters once, as code.
+ *
+ * A device has TWO surfaces, and they are not competing - they are different
+ * projections of the same state:
+ *
+ *   the Surface (Max)                  the App (Chromium)
+ *   real Live parameters               your React UI
+ *   automatable, MIDI-mappable         canvas, WebGL, whatever
+ *   THE ONLY THING PUSH SEES           the deep editor on the laptop
+ *
+ * Push cannot see your React UI. Not yours, not anyone's - it reads Live
+ * parameters and nothing else. So every musically meaningful control has to
+ * exist as a `live.dial` / `live.toggle` / `live.menu` with `parameter_enable`
+ * on, which until now meant maintaining the same control in four places: the
+ * Max object, the patcher wiring, the app's protocol, and the app's state.
+ * Change a range and three of the four silently disagree.
+ *
+ * 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.
+ */
+
+/* ------------------------------------------------------------------ *
+ * Parameter kinds
+ * ------------------------------------------------------------------ */
+
+export interface DialSpec {
+  kind: "dial";
+  /** [min, max]. Live needs a bounded range; there is no unbounded parameter. */
+  range: [number, number];
+  default: number;
+  /** `step: 1` makes it an integer parameter (Max parameter_type 1). */
+  step?: number;
+  unit?: string;
+  /** 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. */
+  short: string;
+}
+
+export interface ToggleSpec {
+  kind: "toggle";
+  default: boolean;
+  short: string;
+}
+
+export interface MenuSpec<O extends string = string> {
+  kind: "menu";
+  options: readonly O[];
+  default: O;
+  short: string;
+}
+
+export type ParamSpec = DialSpec | ToggleSpec | MenuSpec;
+
+/** The value type a given parameter carries. `useParam` will be typed by this. */
+export type ParamValue<P extends ParamSpec> = P extends DialSpec ? number : P extends ToggleSpec ? boolean : P extends MenuSpec<infer O> ? O : never;
+
+export const dial = (spec: Omit<DialSpec, "kind">): DialSpec => ({
+  kind: "dial",
+  ...spec,
+});
+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 surface
+ * ------------------------------------------------------------------ */
+
+/** Push renders parameters in banks of eight. A bank is a page. */
+export interface Bank<K extends string> {
+  name: string;
+  /** At most 8 - Push has eight encoders, and a ninth is silently dropped. */
+  params: readonly K[];
+}
+
+export interface SurfaceDef<P extends Record<string, ParamSpec>> {
+  params: P;
+  banks?: readonly Bank<Extract<keyof P, string>>[];
+}
+
+export interface Surface<P extends Record<string, ParamSpec> = Record<string, ParamSpec>> extends SurfaceDef<P> {
+  /** Declaration order. This is also the order Push falls back to without banks. */
+  readonly ids: readonly Extract<keyof P, string>[];
+}
+
+/** Push has eight encoders per page. A ninth parameter in a bank is not an error in Max - it just never appears. */
+export const BANK_SIZE = 8;
+
+/**
+ * Declare the parameter surface.
+ *
+ * `banks` may only name parameters that exist - that one is enforced by the
+ * type system (`Extract<keyof P, string>`), so a renamed parameter breaks the
+ * build at the point of the typo.
+ *
+ * Bank size, duplicate membership and default-in-range are checked HERE, at
+ * call time, and throw. That is not a weaker guarantee than a type: the build
+ * imports this module to generate the patcher, so a violation fails `pnpm
+ * build` and fails CI. It is only a less pretty error message.
+ */
+export function defineSurface<const P extends Record<string, ParamSpec>>(def: SurfaceDef<P>): Surface<P> {
+  const ids = Object.keys(def.params) as Extract<keyof P, string>[];
+
+  for (const id of ids) {
+    const p = def.params[id];
+    if (p.kind === "dial") {
+      const [min, max] = p.range;
+      if (!(min < max)) throw new Error(`surface: "${id}" has an empty range [${min}, ${max}]`);
+      if (p.default < min || p.default > max) {
+        throw new Error(`surface: "${id}" default ${p.default} is outside its range [${min}, ${max}]`);
+      }
+    }
+    if (p.kind === "menu") {
+      if (!p.options.length) throw new Error(`surface: menu "${id}" has no options`);
+      if (!p.options.includes(p.default)) {
+        throw new Error(`surface: menu "${id}" default "${p.default}" is not one of its options`);
+      }
+    }
+    // Push truncates rather than errors, so a too-long short name is a silent
+    // display bug. Catch it where it is cheap to fix.
+    if (p.short.length > BANK_SIZE) {
+      throw new Error(`surface: "${id}" short name "${p.short}" is longer than ${BANK_SIZE} chars - Push will truncate it`);
+    }
+  }
+
+  const seen = new Set<string>();
+  for (const bank of def.banks ?? []) {
+    if (bank.params.length > BANK_SIZE) {
+      throw new Error(`surface: bank "${bank.name}" holds ${bank.params.length} params - Push shows ${BANK_SIZE} per page, the rest never appear`);
+    }
+    for (const id of bank.params) {
+      if (seen.has(id)) throw new Error(`surface: "${id}" appears in more than one bank`);
+      seen.add(id);
+    }
+  }
+
+  return { ...def, ids };
+}
+
+/** The default value of every parameter. The app's initial state, before Live replies. */
+export function defaults<P extends Record<string, ParamSpec>>(surface: Surface<P>): { [K in keyof P]: ParamValue<P[K]> } {
+  const out = {} as { [K in keyof P]: ParamValue<P[K]> };
+  for (const id of surface.ids) out[id] = surface.params[id].default as ParamValue<P[typeof id]>;
+  return out;
+}
+
+/** How a value is displayed - the parameter's own `format`, or a sane default. */
+export function formatValue(spec: ParamSpec, value: unknown): string {
+  if (spec.kind === "toggle") return value ? "on" : "off";
+  if (spec.kind === "menu") return String(value);
+  if (spec.format) return spec.format(Number(value));
+  const n = Number(value);
+  const text = spec.step === 1 ? String(Math.round(n)) : n.toFixed(2);
+  return spec.unit ? `${text}${spec.unit}` : text;
+}