@m4l-jweb/surface 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/surface",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -24,7 +24,7 @@
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@m4l-jweb/bridge": "0.5.0"
+    "@m4l-jweb/bridge": "0.6.0"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/index.ts

@@ -97,6 +97,61 @@ 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;
 
+/* ------------------------------------------------------------------ *
+ * Windows and State
+ * ------------------------------------------------------------------ */
+
+/**
+ * A floating window: a SECOND page, in a window of its own.
+ *
+ * The device view in Live is a fixed ~169 px tall and does not scroll, so a UI
+ * that needs room (a pattern editor, a waveform) has nowhere to grow inside it.
+ * A declared window compiles to a subpatcher holding its own [jweb], and
+ * `useWindow()` opens it.
+ *
+ * `entry` names the component to bundle, from the device's own folder -
+ * `entry: "Window"` is `src/app/<device>/Window.tsx`. It is a separate BUNDLE, so
+ * it shares no React state with the device view: two pages, two Chromium
+ * contexts, talking only through Max.
+ */
+export interface WindowSpec {
+  kind: "window";
+  title: string;
+  width: number;
+  height: number;
+  entry: string;
+}
+
+/**
+ * A slot of JSON that survives a save - persisted in the LIVE SET, per instance.
+ *
+ * Not a parameter: Live never looks inside it, it does not automate, and it is not
+ * on Push. That is exactly what makes it the right home for the things a parameter
+ * cannot hold - a pattern, a preset, a grid of steps.
+ */
+export interface StateSpec<T = unknown> {
+  kind: "state";
+  default: T;
+}
+
+/** The value type a state slot carries, so `useStateSync` is typed from the declaration. */
+export type StateValue<S extends StateSpec> = S extends StateSpec<infer T> ? T : never;
+
+export const window = (spec: Omit<WindowSpec, "kind">): WindowSpec => ({
+  kind: "window",
+  ...spec,
+});
+
+/**
+ * The default is the TYPE. `state({ default: { voices: 4 } })` makes the slot
+ * `{ voices: number }` everywhere - in `useStateSync`, and in the setter that
+ * writes it back - with no type argument to pass and no `as` to remember.
+ */
+export const state = <T>(spec: Omit<StateSpec<T>, "kind">): StateSpec<T> => ({
+  kind: "state",
+  ...spec,
+});
+
 export const dial = (spec: Omit<DialSpec, "kind">): DialSpec => ({
   kind: "dial",
   ...spec,
@@ -129,12 +184,28 @@ export interface Bank<K extends string> {
   params: readonly K[];
 }
 
-export interface SurfaceDef<P extends Record<string, ParamSpec>> {
+/**
+ * The declaration. `P`, `S` and `W` are inferred from what you write - they exist so
+ * that `useParam`, `useStateSync` and `useWindow` are typed against THIS surface: a
+ * parameter, slot or window that is not declared here is a build error at the call
+ * site, not a control that silently does nothing.
+ */
+export interface SurfaceDef<
+  P extends Record<string, ParamSpec>,
+  S extends Record<string, StateSpec> = Record<string, StateSpec>,
+  W extends Record<string, WindowSpec> = Record<string, WindowSpec>,
+> {
   params: P;
   banks?: readonly Bank<Extract<keyof P, string>>[];
+  windows?: W;
+  state?: S;
 }
 
-export interface Surface<P extends Record<string, ParamSpec> = Record<string, ParamSpec>> extends SurfaceDef<P> {
+export interface Surface<
+  P extends Record<string, ParamSpec> = Record<string, ParamSpec>,
+  S extends Record<string, StateSpec> = Record<string, StateSpec>,
+  W extends Record<string, WindowSpec> = Record<string, WindowSpec>,
+> extends SurfaceDef<P, S, W> {
   /** Declaration order. This is also the order Push falls back to without banks. */
   readonly ids: readonly Extract<keyof P, string>[];
 }
@@ -154,7 +225,11 @@ export const BANK_SIZE = 8;
  * 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> {
+export function defineSurface<
+  const P extends Record<string, ParamSpec>,
+  const S extends Record<string, StateSpec>,
+  const W extends Record<string, WindowSpec>,
+>(def: SurfaceDef<P, S, W>): Surface<P, S, W> {
   const ids = Object.keys(def.params) as Extract<keyof P, string>[];
 
   for (const id of ids) {

package/src/react.tsx

@@ -17,8 +17,9 @@
  * 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";
+import { outlet } from "@m4l-jweb/bridge";
+import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, WindowSpec } from "./index";
+import { paramStore, stateStore } from "./store";
 
 /**
  * A two-way binding to one Live parameter. `[value, setValue]`, like useState -
@@ -43,3 +44,44 @@ export function useSurface<P extends Record<string, ParamSpec>>(
   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];
 }
+
+/**
+ * Open and close a declared floating window.
+ *
+ * The selectors are DERIVED from the declaration, exactly as the patcher's
+ * `[route window_<id>_open ...]` is - so the window id is typed against the
+ * surface and a typo is a build error, not a button that does nothing.
+ */
+export function useWindow<
+  P extends Record<string, ParamSpec>,
+  S extends Record<string, StateSpec>,
+  W extends Record<string, WindowSpec>,
+  K extends Extract<keyof W, string>,
+>(_surface: Surface<P, S, W>, id: K): { open: () => void; close: () => void } {
+  return useMemo(
+    () => ({
+      open: () => outlet(`window_${id}_open`, 1),
+      close: () => outlet(`window_${id}_close`, 1),
+    }),
+    [id],
+  );
+}
+
+/**
+ * A two-way binding to a JSON state slot, persisted in the Live SET.
+ *
+ * `[value, setValue]`, like useState - except the value survives saving, closing
+ * and reopening the set, and each instance of the device keeps its own. The type
+ * comes from the declaration's `default`, so there is nothing to cast.
+ */
+export function useStateSync<
+  P extends Record<string, ParamSpec>,
+  S extends Record<string, StateSpec>,
+  W extends Record<string, WindowSpec>,
+  K extends Extract<keyof S, string>,
+>(surface: Surface<P, S, W>, id: K): [StateValue<S[K]>, (value: StateValue<S[K]>) => void] {
+  const store = useMemo(() => stateStore(surface), [surface]);
+  const values = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const set = useCallback((value: StateValue<S[K]>) => store.write(id, value), [store, id]);
+  return [values[id] as StateValue<S[K]>, 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 Surface } from "./index";
+import { defaults, type ParamSpec, type StateSpec, 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;
@@ -133,3 +133,89 @@ export function paramStore<P extends Record<string, ParamSpec>>(surface: Surface
   stores.set(surface, store);
   return store;
 }
+
+/* ------------------------------------------------------------------ *
+ * The state store - the JSON behind useStateSync(), persisted in the Live SET.
+ *
+ * A parameter is a Live parameter: a number, automatable, on Push. A state slot is
+ * none of those things - it is whatever JSON the app wants to survive a save (a
+ * pattern, a preset, a grid of steps), and Live never looks inside it.
+ *
+ * ------------------------------------------------------------------------------
+ * THE ID IS AN ARGUMENT, NOT PART OF THE SELECTOR - and getting that wrong is why
+ * nothing this store wrote was ever saved.
+ *
+ * It used to emit `sync_state_<id> <json>`. Max dispatches a message on its FIRST
+ * WORD, so `sync_state_config` went looking for a `function sync_state_config()`,
+ * found none, and fell into the wrapper's anything() - which exists precisely to
+ * swallow messages meant for somebody else, silently, by design. The read path
+ * (`get_state <id>`, reply `state_<id> <json>`) had it right, so state loaded and
+ * never saved: the failure mode that looks like Live losing your data.
+ *
+ * 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.
+ * ------------------------------------------------------------------ */
+
+export interface StateStore {
+  get(): Values;
+  subscribe(fn: () => void): () => void;
+  write(id: string, value: unknown): void;
+}
+
+const stateStores = new WeakMap<object, StateStore>();
+
+/**
+ * One store per surface, for the same reason paramStore is: one binding per selector.
+ *
+ * It asks for the SLOTS, not for a `Surface<P, S>` - a store that named the
+ * parameter types would make every caller prove theirs match, and it does not read
+ * a single parameter. The hook keeps the types; this keeps the state.
+ */
+export function stateStore(surface: { state?: Record<string, StateSpec> }): StateStore {
+  const existing = stateStores.get(surface);
+  if (existing) return existing;
+
+  const ids = surface.state ? Object.keys(surface.state) : [];
+
+  // What the app shows before Live has replied: the declared defaults.
+  let values: Values = {};
+  for (const id of ids) values[id] = surface.state![id].default;
+
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+
+  for (const id of ids) {
+    bindInlet(`state_${id}`, (raw) => {
+      try {
+        values = { ...values, [id]: JSON.parse(String(raw)) };
+        notify();
+      } catch {
+        // An empty dict stringifies to "{}" and parses fine; anything that does
+        // not parse is a slot we have no value for, and the default already in
+        // `values` is the honest answer. Keep it rather than blanking the app.
+      }
+    });
+    // The page loads asynchronously and long after the device did, so nothing was
+    // listening when Live restored the pattr. Ask for it.
+    outlet("get_state", id);
+  }
+
+  const store: StateStore = {
+    get: () => values,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    write(id, value) {
+      values = { ...values, [id]: value };
+      notify();
+      outlet("sync_state", id, JSON.stringify(value));
+    },
+  };
+
+  stateStores.set(surface, store);
+  return store;
+}