@m4l-jweb/surface 0.6.0 → 0.7.0

package/package.json

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

package/src/index.ts

@@ -92,10 +92,32 @@ export interface MenuSpec<O extends string = string> {
   short: string;
 }
 
-export type ParamSpec = DialSpec | ToggleSpec | MenuSpec;
+/**
+ * A LABELLED toggle button - a `live.text` in toggle mode, which a bare
+ * `live.toggle` cannot be: it carries visible text. The on/off value is the same as
+ * a toggle; `label` is what the button reads. Handy as a native view switch (a
+ * "Back" button) where the plain orange square of a toggle says nothing.
+ */
+export interface ButtonSpec {
+  kind: "button";
+  default: boolean;
+  /** The text on the button. */
+  label: string;
+  short: string;
+}
+
+export type ParamSpec = DialSpec | ToggleSpec | MenuSpec | ButtonSpec;
 
 /** 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 type ParamValue<P extends ParamSpec> = P extends DialSpec
+  ? number
+  : P extends ToggleSpec
+    ? boolean
+    : P extends ButtonSpec
+      ? boolean
+      : P extends MenuSpec<infer O>
+        ? O
+        : never;
 
 /* ------------------------------------------------------------------ *
  * Windows and State
@@ -160,6 +182,11 @@ export const toggle = (spec: Omit<ToggleSpec, "kind">): ToggleSpec => ({
   kind: "toggle",
   ...spec,
 });
+/** A labelled toggle button (`live.text`). Same on/off value as a toggle, with visible text. */
+export const button = (spec: Omit<ButtonSpec, "kind">): ButtonSpec => ({
+  kind: "button",
+  ...spec,
+});
 /**
  * The options are spelled out rather than written as `Omit<MenuSpec<O>, "kind">`,
  * and that is not a style choice: TypeScript cannot infer `O` THROUGH an `Omit`,
@@ -184,6 +211,47 @@ export interface Bank<K extends string> {
   params: readonly K[];
 }
 
+/**
+ * Which parameters render as NATIVE `live.*` objects in the device view, and how
+ * they are laid out.
+ *
+ * The compiler ALREADY generates a `live.dial` / `live.toggle` / `live.menu` for
+ * every declared parameter; they are invisible today only because they carry no
+ * `presentation` attribute, and Live shows the presentation view. Naming a
+ * parameter here makes the SAME object visible - a presentation overlay on codegen
+ * that already exists, with no wiring change: it is the same parameter, the same
+ * fan-out graph, `useParam()` still reads it, now drawn by Max instead of React.
+ */
+export interface NativeLayout<K extends string = string> {
+  /**
+   * In display order: fills rows top-to-bottom, then overflows into the next
+   * column (column-major, so adding a parameter does not reshuffle the rest).
+   */
+  params: readonly K[];
+  /**
+   * Max rows per column. Default 3 - the device view is a fixed ~169 px tall and a
+   * `live.dial` needs a 56 px pitch, so only 3 fit vertically.
+   */
+  rows?: number;
+  /**
+   * LAYERED "two screens" instead of side-by-side. When true, `[jweb]` is built
+   * full-width and the dials OVERLAP its left, and the app flips between them with
+   * `useNativePanel` (hide one layer, show the other) - because runtime reposition
+   * of native objects does not work in a frozen M4L device, only hide/show does.
+   * When false (the default), the dials sit BESIDE a right-shifted `[jweb]`, both
+   * visible at once.
+   */
+  panel?: boolean;
+  /**
+   * A parameter that is the VIEW SWITCH, not a grid dial: pinned to the top-right
+   * (over the web UI's own switch button, so the control stays in one place across
+   * both views), kept out of the `params` grid, and shown in both modes. Meant for a
+   * toggle in a `panel` layout - the way back from the native panel, since the web
+   * UI is hidden there.
+   */
+  switch?: K;
+}
+
 /**
  * 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
@@ -199,6 +267,8 @@ export interface SurfaceDef<
   banks?: readonly Bank<Extract<keyof P, string>>[];
   windows?: W;
   state?: S;
+  /** Which parameters render as native Max objects in the device view. */
+  layout?: { native?: NativeLayout<Extract<keyof P, string>> };
 }
 
 export interface Surface<
@@ -265,9 +335,39 @@ export function defineSurface<
     }
   }
 
+  // A native layout may only name parameters that exist, and may not ask for more
+  // rows than the device view holds. Both throw here, at build time, for the same
+  // reason the bank checks do: a typo would otherwise generate a cord from a box
+  // that never gets a presentation rect, or overflow a 169 px view silently.
+  const native = def.layout?.native;
+  if (native) {
+    for (const id of native.params) {
+      if (!def.params[id]) throw new Error(`surface: layout.native names "${id}", which is not a declared parameter`);
+    }
+    const rows = native.rows ?? 3;
+    if (rows < 1 || rows > 3) throw new Error(`surface: layout.native.rows must be 1..3 - the device view is 169 px tall`);
+    if (native.switch !== undefined && !def.params[native.switch]) {
+      throw new Error(`surface: layout.native.switch names "${native.switch}", which is not a declared parameter`);
+    }
+  }
+
   return { ...def, ids };
 }
 
+/**
+ * Does this parameter render as a native Max object? App code uses it to stop
+ * drawing an HTML control the device view now owns. Cheap and honest: a parameter
+ * that is not in `layout.native` is still an HTML control, so `useParam()` stays
+ * the source of truth either way.
+ */
+export const isNative = (surface: Surface, id: string): boolean => !!surface.layout?.native?.params.includes(id as never);
+
+/**
+ * The scripting name the build gives `[jweb]` when a surface declares native
+ * layout, so the app can hide/show it at runtime (see `useNativePanel`).
+ */
+export const JWEB_VARNAME = "obj-jweb";
+
 /** 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]> };
@@ -277,7 +377,7 @@ export function defaults<P extends Record<string, ParamSpec>>(surface: Surface<P
 
 /** 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 === "toggle" || spec.kind === "button") return value ? "on" : "off";
   if (spec.kind === "menu") return String(value);
   if (spec.format) return spec.format(Number(value));
   const n = Number(value);

package/src/react.tsx

@@ -19,6 +19,7 @@
 import { useCallback, useMemo, useSyncExternalStore } from "react";
 import { outlet } from "@m4l-jweb/bridge";
 import type { ParamSpec, ParamValue, StateSpec, StateValue, Surface, WindowSpec } from "./index";
+import { JWEB_VARNAME } from "./index";
 import { paramStore, stateStore } from "./store";
 
 /**
@@ -67,6 +68,61 @@ export function useWindow<
   );
 }
 
+/**
+ * Show or hide a NATIVE dial in the device view at runtime.
+ *
+ * `layout.native` makes a parameter a native `live.*` object, but its presentation
+ * is STATIC - the dial is always visible. This is the runtime override: the app says
+ * which native params should be shown, and a `[thispatcher]` runs `script show`/
+ * `script hide` on the object by its scripting name (`param-<id>`, see
+ * `applyNativeControl` in @m4l-jweb/build). The parameter itself is untouched - a
+ * hidden dial still automates, MIDI-maps and reaches Push; only visibility changes.
+ *
+ * Returns a stable `(id, visible) => void`. Drive it from an effect that mirrors the
+ * app's own "which stages are active" state, e.g. `useEffect` over the shown set.
+ */
+export function useNativeVisibility<P extends Record<string, ParamSpec>>(
+  _surface: Surface<P>,
+): (id: Extract<keyof P, string>, visible: boolean) => void {
+  return useCallback((id: Extract<keyof P, string>, visible: boolean) => {
+    // The varname applySurface() gave the object is `param-<id>`. Keep this prefix
+    // in step with that codegen - it is the one string both sides must agree on.
+    outlet(visible ? "native_show" : "native_hide", `param-${id}`);
+  }, []);
+}
+
+/**
+ * Flip the device view between the WEB UI and a NATIVE control panel - the "two
+ * screens" model. Runtime reposition/resize of presentation objects does NOT work in
+ * a frozen M4L device (measured: `presentation_rect` writes are stored but never
+ * redrawn), but `hidden` DOES. So instead of reflowing dials, we layer them:
+ *
+ *   "web"    - show [jweb] (full width), hide every native dial and the switch. The
+ *              web UI paints its own switch button; the native one would only fight
+ *              it for the same top-right spot.
+ *   "native" - hide [jweb], show every native dial AND the switch - which is the way
+ *              back, since the web UI is hidden here.
+ *
+ * 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 {
+  return useCallback(
+    (mode: "web" | "native") => {
+      const native = surface.layout?.native;
+      if (!native) return;
+      const web = mode === "web";
+      const toggle = (varname: string) => outlet(web ? "native_hide" : "native_show", varname);
+      outlet(web ? "native_show" : "native_hide", JWEB_VARNAME);
+      for (const id of native.params as readonly string[]) toggle(`param-${id}`);
+      if (native.switch) toggle(`param-${native.switch}`);
+    },
+    [surface],
+  );
+}
+
 /**
  * A two-way binding to a JSON state slot, persisted in the Live SET.
  *

package/src/store.ts

@@ -40,7 +40,7 @@ const EPSILON = 1e-6;
 
 /** Max stores every parameter as a NUMBER. A menu is an index into its options; a toggle is 0/1. */
 export function toWire(spec: ParamSpec, value: unknown): number {
-  if (spec.kind === "toggle") return value ? 1 : 0;
+  if (spec.kind === "toggle" || spec.kind === "button") return value ? 1 : 0;
   if (spec.kind === "menu") {
     const i = spec.options.indexOf(String(value));
     return i < 0 ? 0 : i;
@@ -50,7 +50,7 @@ export function toWire(spec: ParamSpec, value: unknown): number {
 
 /** ...and back. An out-of-range menu index falls back to the default rather than `undefined`. */
 export function fromWire(spec: ParamSpec, wire: number): unknown {
-  if (spec.kind === "toggle") return wire >= 0.5;
+  if (spec.kind === "toggle" || spec.kind === "button") return wire >= 0.5;
   if (spec.kind === "menu") return spec.options[Math.round(wire)] ?? spec.default;
   return wire;
 }