@m4l-jweb/bridge 0.9.9 → 1.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @m4l-jweb/bridge
+
+The browser half of a device. Your React UI runs inside `[jweb~]`, Max's embedded Chromium; this is how it talks to the Max patcher around it - messages out, messages in, MIDI, clip I/O, and files.
+
+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/bridge
+```
+
+## Usage
+
+```ts
+import { bindInlet, outlet, onNote, onNoteOff, sendNote, uiReady } from "@m4l-jweb/bridge";
+
+// Tell the wrapper the page is up, and ask for current state.
+uiReady();
+
+// Incoming MIDI (needs the `midiin` chain). Both binders share one subscription.
+onNote((pitch, velocity) => voiceOn(pitch, velocity));
+onNoteOff((pitch) => voiceOff(pitch));
+
+// Outgoing MIDI (needs the `midiout` chain). Max applies the delay, not the browser,
+// so note timing does not depend on a Chromium timer.
+sendNote({ pitch: 60, velocity: 100, durationMs: 250, delayMs: 80 });
+
+// Anything else you route yourself.
+bindInlet("tick", (playing, beats) => setTransport(Boolean(playing), Number(beats)));
+outlet("my_selector", 1, "two");
+```
+
+## Notes
+
+- **Audio does not go through here.** Under `[jweb~]` the page's Web Audio output is carried on the object's signal outlets, straight into the track. The bridge is a control plane; sound never crosses it as messages.
+- `fetchToFile()` and `saveToFile()` move bytes between the page and disk via Max's `[maxurl]`, so large files never travel through the message bridge either.
+- `tapMessages()` observes every message in both directions - the whole contract of a device, 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/bridge",
-  "version": "0.9.9",
+  "version": "1.1.0",
   "description": "m4l-jweb: the browser-side bridge connecting a device's web UI to Max for Live.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -127,6 +127,22 @@ export function uiReady(): void {
   outlet("ui_ready");
 }
 
+/**
+ * Send a message to the page in another of this device's windows.
+ *
+ * Two pages of one device are two Chromium contexts: no shared globals, no
+ * shared memory, no events between them. They talk through Max, and this is the
+ * message that does not persist - the receiving page gets `<selector> <value>` on
+ * the inlet it bound with `bindInlet`, and nothing is written to the Live set.
+ *
+ * Use a STATE SLOT instead for anything that must survive a save (the pattern,
+ * a preset). Use this for what is happening NOW: a transport change, a knob
+ * position, a nudge to re-read something.
+ */
+export function sendToWindow(windowId: string, selector: string, value: unknown): void {
+  outlet("window_send", windowId, selector, value);
+}
+
 /* ------------------------------------------------------------------ *
  * The chain contract
  *
@@ -218,14 +234,69 @@ export const STATE_OUT = {
 export const PARAM_OUT = {
   /** UI -> wrapper: `get_param_id <id>` - what is this parameter's LOM id? Reply on `param_id`. */
   get_param_id: "get_param_id",
+  /** UI -> wrapper: `param_label <id> <name>` - rename the dial on the device panel. */
+  param_label: "param_label",
+  /** UI -> wrapper: `param_unit <id> <unit>` - how Live PRINTS the value. */
+  param_unit: "param_unit",
+  /** UI -> wrapper: `param_range <id> <lo> <hi>` - the dial's travel. Answered. */
+  param_range: "param_range",
 } as const;
 
 /** ...and the reply. */
 export const PARAM_IN = {
   /** wrapper -> UI: `param_id <id> <lomId>` - 0 means no parameter of that name resolved. */
   param_id: "param_id",
+  /** wrapper -> UI: `param_range_ok <id>` - Live took the range; the parameter now carries it. */
+  param_range_ok: "param_range_ok",
+  /** wrapper -> UI: `param_range_failed <id>` - it did not; the parameter is still as declared. */
+  param_range_failed: "param_range_failed",
+  /** wrapper -> device view: `param_desc <id> <name>` - what some page called this parameter. */
+  param_desc: "param_desc",
+  /** wrapper -> device view: `param_desc_range <id> <lo> <hi> <took>` - and its travel. */
+  param_desc_range: "param_desc_range",
 } as const;
 
+/**
+ * Say what a parameter IS, at runtime: its name, how Live should print it, and the
+ * travel it should have.
+ *
+ * A surface declares all three at BUILD time, which is right when the device knows
+ * what its controls do. It does not when the control is whatever the user's code
+ * just asked for - a pattern's `slider()`, a modulation slot pointed at something
+ * new - and then the dial reads `S1`, travels 0..1 and says nothing about the sound
+ * it is moving.
+ *
+ * ------------------------------------------------------------------------------
+ * WHAT TAKES, AND WHAT DOES NOT - measured in Live, not assumed.
+ *
+ * `name`  reaches the DEVICE PANEL. It does NOT reach Live's parameter registry or
+ *         the Rack macro picker, which keep the declared short name: a frozen
+ *         device cannot rename a parameter there.
+ * `unit`  takes. It is the unit STYLE, so the readout says "600 Hz" and not "600";
+ *         anything outside Max's list becomes a custom unit and still prints.
+ * `range` takes, AND CHANGES THE DOMAIN THE PARAMETER REPORTS. That is the trap:
+ *         a page that goes on normalizing 0..1 will scale a value that is already
+ *         scaled, and the control sticks at its minimum. So the wrapper ANSWERS -
+ *         `param_range_ok` or `param_range_failed` - and the caller must stop
+ *         normalizing when it took. `onParamRange()` below is that answer.
+ */
+export function describeParam(id: string, desc: { name?: string; unit?: string; range?: [number, number] }): void {
+  if (desc.name) outlet(PARAM_OUT.param_label, id, desc.name);
+  if (desc.unit) outlet(PARAM_OUT.param_unit, id, desc.unit);
+  if (desc.range && desc.range[1] > desc.range[0]) outlet(PARAM_OUT.param_range, id, desc.range[0], desc.range[1]);
+}
+
+/**
+ * Hear whether a `describeParam` range took, per parameter.
+ *
+ * Until this says yes, the parameter is still in its declared domain and the page
+ * owns the scaling. Exactly one scaling, wherever it ends up living.
+ */
+export function onParamRange(fn: (id: string, took: boolean) => void): void {
+  bindInlet(PARAM_IN.param_range_ok, (id) => fn(String(id), true));
+  bindInlet(PARAM_IN.param_range_failed, (id) => fn(String(id), false));
+}
+
 /**
  * Selectors the WRAPPER handles for reading and writing the CLIP on this device's
  * track (`read_notes`/`write_clip` in liveapi.ts). Wrapper-owned, like DEVICE_IN -
@@ -470,7 +541,8 @@ export function saveToFile(destPath: string, bytes: ArrayBuffer): Promise<{ byte
  * running set, not names: they are not stable across a set reload, so an id saved
  * yesterday points at whatever occupies that slot today - or at nothing. Persist how
  * you FOUND the parameter (the device's position, the parameter's name) and resolve it
- * again; that is the same rule Translate mode's reconciler follows (doc/TODO.md item 1).
+ * again. (Translate mode's reconciler followed the same rule; that mode was settled as
+ * adopt-only, permanently - Live's Browser is unreachable from [js].)
  */
 export function bindRemote(slot: number, lomId: number | string): void {
   outlet(CHAIN_OUT.remote_bind, slot, lomId);