@m4l-jweb/surface 0.7.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/surface",
-  "version": "0.7.0",
+  "version": "0.9.1",
   "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.7.0"
+    "@m4l-jweb/bridge": "0.9.1"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/index.ts

@@ -142,6 +142,20 @@ export interface WindowSpec {
   width: number;
   height: number;
   entry: string;
+  /**
+   * Keep the window in FRONT of Live, instead of behind it the moment Live is clicked.
+   *
+   * For a window you read WHILE working in Live - a reference, a cheatsheet - the
+   * default behaviour makes it useless: clicking back into the device to type is
+   * exactly what sends the window behind the main window. For a window you work IN (an
+   * editor), the default is right and this should stay off.
+   *
+   * It compiles to `[thispatcher]` <- `window flags ... float, window exec`, which is
+   * Max's documented route. **The flag list is a REPLACEMENT, not an addition** - that
+   * is why the generated message names `grow`, `close` and `title` alongside `float`.
+   * Send `float` alone and the window comes up with no close box.
+   */
+  alwaysOnTop?: boolean;
 }
 
 /**
@@ -375,6 +389,75 @@ export function defaults<P extends Record<string, ParamSpec>>(surface: Surface<P
   return out;
 }
 
+/* ------------------------------------------------------------------ *
+ * defineWatch - declare what to OBSERVE in Live, once, as code.
+ *
+ * The twin of defineSurface, and it exists to kill hard rule 4 BY CONSTRUCTION.
+ * A LiveAPI observer built during `loadbang` is dead forever; the only safe place
+ * to create one is `live.thisdevice`'s bang. That is a trap a hand-written
+ * observer falls into silently - the object constructs without error and then
+ * notifies nothing. So no device writes the observer at all: it DECLARES the LOM
+ * path and property, the build injects the list as data, and the packaged wrapper
+ * creates every observer from bang() (see setupWatches in @m4l-jweb/wrapper). The
+ * one place LiveAPI is safe is the one place the observers are made.
+ *
+ * Each change reaches the UI as `watch_<key> <value...>`, exactly as a parameter
+ * reaches it as `<id> <value>` - one declaration, one name, both sides. `useWatch`
+ * binds it; the app never types the selector.
+ *
+ * This is READ-ONLY: an observed property flows Live -> UI and nowhere back. A
+ * value the app can also WRITE is a parameter (`defineSurface`), not a watch.
+ * ------------------------------------------------------------------ */
+
+/** One observed Live property. `T` is the value the app sees, so `useWatch` is typed from it. */
+export interface WatchSpec<T = unknown> {
+  /** The LOM object path, e.g. `"live_set"` or `"live_set view selected_track"`. */
+  path: string;
+  /** An OBSERVABLE property on that object, e.g. `"tempo"`, `"scale_name"`, `"is_playing"`. */
+  property: string;
+  /** What the app shows before Live has replied - the same role a parameter's `default` plays. */
+  default: T;
+}
+
+/** The value type a watch carries. `useWatch` is typed by this. */
+export type WatchValue<S extends WatchSpec> = S extends WatchSpec<infer T> ? T : never;
+
+/**
+ * Declare one watch. `watch<string>({ path: "live_set", property: "scale_name", default: "C" })`
+ * carries the value type through, so `useWatch(w, "scale")` is `string` with nothing to cast.
+ */
+export const watch = <T>(spec: WatchSpec<T>): WatchSpec<T> => ({ ...spec });
+
+export interface WatchDef<W extends Record<string, WatchSpec>> {
+  watches: W;
+}
+
+export interface Watch<W extends Record<string, WatchSpec> = Record<string, WatchSpec>> extends WatchDef<W> {
+  /** Declaration order - the order the build emits WATCH_SPECS and the wrapper attaches observers. */
+  readonly keys: readonly Extract<keyof W, string>[];
+}
+
+/**
+ * Declare the watch surface.
+ *
+ * Like defineSurface, the checks run HERE, at call time, and throw - the build
+ * imports this module to emit the observer list, so a bad declaration fails
+ * `pnpm build` and CI. A key becomes the selector suffix `watch_<key>`, so it may
+ * not carry whitespace (Max would split the message on it); a path or property
+ * left blank would attach an observer to nothing, silently, which is the exact
+ * failure this API exists to prevent.
+ */
+export function defineWatch<const W extends Record<string, WatchSpec>>(def: WatchDef<W>): Watch<W> {
+  const keys = Object.keys(def.watches) as Extract<keyof W, string>[];
+  for (const key of keys) {
+    if (/\s/.test(key)) throw new Error(`watch: key "${key}" has whitespace - it becomes the selector watch_${key}, which Max would split`);
+    const w = def.watches[key];
+    if (!w.path) throw new Error(`watch: "${key}" has no path - an observer with no LOM object attaches to nothing`);
+    if (!w.property) throw new Error(`watch: "${key}" has no property - an observer with no property notifies nothing`);
+  }
+  return { ...def, keys };
+}
+
 /** 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" || spec.kind === "button") return value ? "on" : "off";

package/src/react.tsx

@@ -18,9 +18,9 @@
  */
 import { useCallback, useMemo, useSyncExternalStore } from "react";
 import { outlet } from "@m4l-jweb/bridge";
-import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, WindowSpec } from "./index";
+import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, Watch, WatchSpec, WatchValue, WindowSpec } from "./index";
 import { JWEB_VARNAME } from "./index";
-import { paramStore, stateStore } from "./store";
+import { paramStore, stateStore, watchStore } from "./store";
 
 /**
  * A two-way binding to one Live parameter. `[value, setValue]`, like useState -
@@ -106,9 +106,7 @@ export function useNativeVisibility<P extends Record<string, ParamSpec>>(
  * Only `hidden` is used, so this actually works where reflow could not, and no layer
  * is ever visible at the same time as another - so z-order never matters.
  */
-export function useNativePanel<P extends Record<string, ParamSpec>>(
-  surface: Surface<P>,
-): (mode: "web" | "native") => void {
+export function useNativePanel<P extends Record<string, ParamSpec>>(surface: Surface<P>): (mode: "web" | "native") => void {
   return useCallback(
     (mode: "web" | "native") => {
       const native = surface.layout?.native;
@@ -123,6 +121,25 @@ export function useNativePanel<P extends Record<string, ParamSpec>>(
   );
 }
 
+/**
+ * A one-way binding to an observed Live property, declared with `defineWatch()`.
+ *
+ * Read-only, so it returns the value alone - no setter. The mirror of `useParam`:
+ * a parameter the app both reads and writes; a watch it only reads. Turning the
+ * tempo, changing the scale, selecting a track in Live moves this React state, and
+ * the wrapper attaches every observer from `bang()` - the one place LiveAPI is
+ * safe - so the trap of a dead loadbang observer is not one a device can fall into.
+ *
+ * The selector is DERIVED (`watch_<key>`), exactly as `useParam`'s is, so a key
+ * that is not declared is a build error at the call site, not a value that never
+ * arrives.
+ */
+export function useWatch<W extends Record<string, WatchSpec>, K extends Extract<keyof W, string>>(watch: Watch<W>, key: K): WatchValue<W[K]> {
+  const store = useMemo(() => watchStore(watch), [watch]);
+  const values = useSyncExternalStore(store.subscribe, store.get, store.get);
+  return values[key] as WatchValue<W[K]>;
+}
+
 /**
  * A two-way binding to a JSON state slot, persisted in the Live SET.
  *

package/src/store.ts

@@ -30,7 +30,7 @@
  * 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 StateSpec, type Surface } from "./index";
+import { defaults, type ParamSpec, type StateSpec, type Surface, type WatchSpec } 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;
@@ -155,8 +155,70 @@ export function paramStore<P extends Record<string, ParamSpec>>(surface: Surface
  * OUT: `get_state <id>`, `sync_state <id> <json>`   - one handler each, in the wrapper.
  * IN:  `state_<id> <json>`                          - one binding per slot, so the
  *      bridge can dispatch it without the app unpacking an id.
+ *
+ * ------------------------------------------------------------------------------
+ * EVERY VALUE TRAVELS INSIDE AN ENVELOPE, because a Max [dict] IS a key/value map
+ * and cannot hold anything else.
+ *
+ * The wrapper stores a slot by handing the JSON to `Dict.parse()`. A dict has KEYS;
+ * that is what a dict is. So an OBJECT round-tripped fine and nothing else did:
+ * `state<string>` sent `"c1 e1"` and `state<FxParam[]>` sent `["cutoff"]`, and
+ * `parse()` had nowhere to put either. The dict stayed empty, `stringify()` gave back
+ * `{}`, and the app read its own default forever.
+ *
+ * That one bug wore two disguises, and cost real debugging as both: a drum map (an
+ * object) persisted while the pattern text (a string) silently did not - which looks
+ * exactly like Live losing your work; and the fx device's `named` slot (an array) came
+ * back `{}` on every load, which was written off as the state-DEFAULT seeding gap. That
+ * gap is real, but it is not this: `named` had never persisted at all.
+ *
+ * So the wire format is `{"__value": <whatever>}`, always. The dict gets its key, and
+ * `state<T>` means what it says for every T.
  * ------------------------------------------------------------------ */
 
+/** The one key a [dict] carries, so that a scalar has somewhere to live. */
+const ENVELOPE = "__value";
+
+/**
+ * The envelope, as JSON, with every literal space escaped - so it crosses as ONE atom.
+ *
+ * [jweb] hands each argument to Max, and Max SPLITS A SYMBOL ON WHITESPACE. The
+ * wrapper has always papered over this by rejoining the pieces with a single space,
+ * which works for exactly as long as the payload never contains meaningful whitespace.
+ * `JSON.stringify` of an object is compact, so a drum map arrived in one piece and the
+ * seam held.
+ *
+ * A PATTERN IS NOTHING BUT WHITESPACE. `"c1  e1"` would come back `"c1 e1"` - the run
+ * of spaces rejoined as one, the user's text quietly reformatted - and a multi-line
+ * pattern (which is the whole point of the Studio window) is worse.
+ *
+ * ` ` is JSON's own escape for a space, so the payload contains no literal spaces
+ * at all: Max cannot split what is not there, the rejoin becomes a no-op, and the dict's
+ * JSON parser turns the escapes back into the spaces the user typed. Newlines and tabs
+ * need no help - `JSON.stringify` already escapes those as `\n` and `\t`.
+ */
+function stateToWire(value: unknown): string {
+  return JSON.stringify({ [ENVELOPE]: value }).replace(/ /g, "\\u0020");
+}
+
+/**
+ * Unwrap what came out of the dict.
+ *
+ * A missing envelope is not an error, and there are two innocent ways to get one: a
+ * slot Live has never saved (a fresh, empty `{}`), or a value written by a build from
+ * before the envelope - which could only ever have been an object, since nothing else
+ * could be stored. Both are answered without blanking the app, so opening an old set
+ * keeps its drum map.
+ */
+function unwrap(parsed: unknown, fallback: unknown): unknown {
+  if (parsed && typeof parsed === "object" && ENVELOPE in (parsed as Record<string, unknown>)) {
+    return (parsed as Record<string, unknown>)[ENVELOPE];
+  }
+  // An empty dict means "nothing saved yet" - the declared default is the honest answer.
+  if (parsed && typeof parsed === "object" && Object.keys(parsed as object).length === 0) return fallback;
+  return parsed ?? fallback;
+}
+
 export interface StateStore {
   get(): Values;
   subscribe(fn: () => void): () => void;
@@ -190,7 +252,10 @@ export function stateStore(surface: { state?: Record<string, StateSpec> }): Stat
   for (const id of ids) {
     bindInlet(`state_${id}`, (raw) => {
       try {
-        values = { ...values, [id]: JSON.parse(String(raw)) };
+        // The dict hands back `{"__value": ...}` - see the envelope note above. An
+        // empty dict and a pre-envelope value both resolve to something sane rather
+        // than to nothing.
+        values = { ...values, [id]: unwrap(JSON.parse(String(raw)), surface.state![id].default) };
         notify();
       } catch {
         // An empty dict stringifies to "{}" and parses fine; anything that does
@@ -212,10 +277,73 @@ export function stateStore(surface: { state?: Record<string, StateSpec> }): Stat
     write(id, value) {
       values = { ...values, [id]: value };
       notify();
-      outlet("sync_state", id, JSON.stringify(value));
+      // Enveloped, ALWAYS - a bare string or array has nowhere to live in a [dict] -
+      // and space-escaped, so Max cannot split the payload on the way.
+      outlet("sync_state", id, stateToWire(value));
     },
   };
 
   stateStores.set(surface, store);
   return store;
 }
+
+/* ------------------------------------------------------------------ *
+ * The watch store - the read-only Live values behind useWatch().
+ *
+ * A watch is the mirror image of a parameter: it flows Live -> UI only, so this
+ * store has a `get`/`subscribe` and NO `write`. Each declared watch binds
+ * `watch_<key>` exactly once - same one-binding-per-selector reason paramStore
+ * exists - and fans out to subscribers. The wrapper attaches the observer (from
+ * bang(), the only safe place) and resends the current value on ui_ready, so a
+ * page that loaded after the last change still gets it; the app just calls
+ * uiReady() as it already does for tempo.
+ * ------------------------------------------------------------------ */
+
+export interface WatchStore {
+  get(): Values;
+  subscribe(fn: () => void): () => void;
+}
+
+const watchStores = new WeakMap<object, WatchStore>();
+
+/**
+ * One store per watch declaration, created once and never torn down - the bridge's
+ * bindings are process-wide, so tearing one down would unbind a watch another
+ * component still reads.
+ */
+export function watchStore(watch: { watches?: Record<string, WatchSpec>; keys?: readonly string[] }): WatchStore {
+  const existing = watchStores.get(watch);
+  if (existing) return existing;
+
+  const keys = watch.keys ?? (watch.watches ? Object.keys(watch.watches) : []);
+
+  // What the app shows before Live has replied: the declared defaults.
+  let values: Values = {};
+  for (const key of keys) values[key] = watch.watches?.[key].default;
+
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+
+  for (const key of keys) {
+    // `watch_<key> <value...>` - out of the wrapper's observeProperty, forwarded on
+    // change and once on ui_ready. A scalar arrives as one atom; a property that
+    // yields several (a colour, a pair) arrives spread, so keep the list intact.
+    bindInlet(`watch_${key}`, (...args) => {
+      values = { ...values, [key]: args.length <= 1 ? args[0] : args };
+      notify();
+    });
+  }
+
+  const store: WatchStore = {
+    get: () => values,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+
+  watchStores.set(watch, store);
+  return store;
+}