@m4l-jweb/surface 1.1.0 → 1.2.1

package/package.json

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

package/src/index.ts

@@ -164,6 +164,30 @@ export interface WindowSpec {
    * primitive rather than changing the first.
    */
   audio?: boolean;
+  /**
+   * Output latency of the sounding window's `[jweb~]`, in milliseconds - the ring
+   * buffer between Chromium's audio thread and MSP. Max 9 documents 0 as the
+   * minimum (~23 ms at 44.1kHz, ~21 ms at 48kHz), warns that the minimum "may
+   * result in occasional drop-outs or distortion", and caps the maximum at three
+   * times the minimum. Unset leaves the object's own default.
+   *
+   * Only meaningful with `audio: true`; ignored otherwise.
+   */
+  latency?: number;
+  /**
+   * The `rendermode` attribute stamped on the window's jweb object:
+   * 0 = onscreen, 1 = offscreen. The Max reference notes offscreen "is slower".
+   * Default is 1, which is what every generated window has shipped with so far.
+   */
+  rendermode?: 0 | 1;
+  /**
+   * Report interval of the window's level tap (`[peakamp~ N]`), in milliseconds.
+   * Default 10, which is 100 float messages per second per channel into the
+   * wrapper's [js]. Raise it to trade meter smoothness for message traffic.
+   *
+   * Only meaningful with `audio: true`; ignored otherwise.
+   */
+  levelInterval?: number;
   /**
    * Window content from a PREBUILT static directory rather than a component of
    * ours - a whole site, built by something else (its own Astro/vite build), and
@@ -241,13 +265,39 @@ export const dial = (spec: Omit<DialSpec, "kind">): DialSpec => ({
  * currently IS (name, unit, range - see describeParam in @m4l-jweb/bridge), and
  * keeps the scaling straight.
  */
-export const knobPool = <N extends number>(count: N, prefix = "s"): Record<string, DialSpec> => {
+/** 0 .. N-1 as a union. The recursion is bounded by the count the caller wrote. */
+type UpTo<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : UpTo<N, [...Acc, Acc["length"]]>;
+
+/**
+ * The dials are numbered from 1, and TypeScript cannot add. A lookup tuple is the
+ * whole trick: index 0 holds 1, index 7 holds 8. It stops at 32, which is four Push
+ * banks - past that `knobPool` still WORKS, its keys just widen back to `string` and
+ * `useParam(surface, "s33")` stops being checked.
+ */
+type OneBased = [
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+  17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32,
+];
+
+/** `PoolIds<8>` is `"s1" | ... | "s8"`. */
+export type PoolIds<N extends number, P extends string = "s"> = `${P}${OneBased[UpTo<N>] & number}`;
+
+/**
+ * The KEYS are the point, not just the values. `params: { ...knobPool(8) }` has to
+ * leave `keyof P` carrying `s1`..`s8`, or the spread widens the surface to an index
+ * signature and every downstream `useParam(surface, "s3")` and `layout.native.params`
+ * entry stops type-checking against the declaration it came from.
+ */
+export const knobPool = <N extends number, P extends string = "s">(
+  count: N,
+  prefix: P = "s" as P,
+): Record<PoolIds<N, P>, DialSpec> => {
   const out: Record<string, DialSpec> = {};
   for (let i = 1; i <= count; i++) {
     // The short name is what Push prints when nothing has borrowed the slot yet.
     out[`${prefix}${i}`] = dial({ range: [0, 1], default: 0, short: `${prefix.toUpperCase()}${i}` });
   }
-  return out;
+  return out as Record<PoolIds<N, P>, DialSpec>;
 };
 export const toggle = (spec: Omit<ToggleSpec, "kind">): ToggleSpec => ({
   kind: "toggle",

package/src/react.tsx

@@ -212,6 +212,21 @@ export interface PooledControl extends BorrowedControl {
  *    minimum - the bug that got an earlier attempt at this reverted. The wrapper
  *    answers whether each range took, and this hook scales exactly once either way.
  *
+ * `widenRange` IS OFF BY DEFAULT, and that is a measured decision rather than
+ * caution. A dial whose range was widened at runtime stops following its automation
+ * lane and any Rack macro mapped to it: both keep driving the parameter in the
+ * BUILD-TIME domain the frozen device gave them, so the value lands at the bottom of
+ * the new range and the dial never moves, silently. Left alone, the dials stay 0..1,
+ * this hook does the scaling, and automation, macros and Push all keep working - at
+ * the cost of the dial's own readout showing 0.44 rather than 600 Hz. Turn it on
+ * only where that readout is worth more than the automation.
+ *
+ * `describe: false` borrows and scales as usual but says NOTHING to Live. A device
+ * with two pages - a device view and a window - has two React trees against one
+ * pool, and both calling this means the last render wins: the dial ends up named
+ * after whichever page rendered most recently, flickering between them. Exactly one
+ * page should describe. The other still gets its `PooledControl[]` to draw.
+ *
  * KNOWN LIMIT, measured in Live: the name reaches the DEVICE PANEL, not Live's
  * parameter registry or a Rack macro picker, which keep the pool's own `S1..S8`.
  * A frozen device cannot rename a parameter there. So render the name in your own
@@ -221,6 +236,7 @@ export function useControls<P extends Record<string, ParamSpec>>(
   surface: Surface<P>,
   controls: readonly BorrowedControl[],
   poolIds: readonly Extract<keyof P, string>[],
+  options: { widenRange?: boolean; describe?: boolean } = {},
 ): PooledControl[] {
   /* eslint-disable react-hooks/rules-of-hooks */
   // A pool is dials, so its values are numbers - but `P` is the whole surface and
@@ -229,6 +245,8 @@ export function useControls<P extends Record<string, ParamSpec>>(
   const params = poolIds.map((id) => useParam(surface, id)) as unknown as [number, (v: number) => void][];
   /* eslint-enable react-hooks/rules-of-hooks */
 
+  const { widenRange = false, describe = true } = options;
+
   /** Which dials Live actually widened. Until it says so, the dial is 0..1. */
   const [real, setReal] = useState<boolean[]>([]);
   useEffect(() => {
@@ -250,6 +268,7 @@ export function useControls<P extends Record<string, ParamSpec>>(
   // parameter attributes, and a device re-rendering is not news.
   const described = useRef<string[]>([]);
   useEffect(() => {
+    if (!describe) return;
     for (let i = 0; i < poolIds.length; i++) {
       const c = controls[i];
       const key = c ? `${c.name} ${c.min} ${c.max} ${c.unit ?? ""}` : "";
@@ -257,10 +276,10 @@ export function useControls<P extends Record<string, ParamSpec>>(
       described.current[i] = key;
       // A slot nobody is borrowing goes back to its declared identity, or it would
       // keep the name of a control that is no longer there.
-      if (c) describeParam(poolIds[i], { name: c.name, unit: c.unit, range: [c.min, c.max] });
-      else describeParam(poolIds[i], { name: String(poolIds[i]).toUpperCase(), range: [0, 1] });
+      if (c) describeParam(poolIds[i], { name: c.name, unit: c.unit, range: [c.min, c.max], widenRange });
+      else describeParam(poolIds[i], { name: String(poolIds[i]).toUpperCase(), range: [0, 1], widenRange });
     }
-  }, [controls, poolIds]);
+  }, [controls, poolIds, widenRange, describe]);
 
   // Seed a slot the first time a given control takes it, so an untouched dial reads
   // what the control says rather than 0.