@m4l-jweb/bridge 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/bridge",
-  "version": "1.0.0",
+  "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);