@m4l-jweb/surface 1.2.0 → 1.3.0

package/package.json

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

package/src/index.ts

@@ -265,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",
@@ -567,6 +593,81 @@ export function defineWatch<const W extends Record<string, WatchSpec>>(def: Watc
   return { ...def, keys };
 }
 
+/* ------------------------------------------------------------------ *
+ * defineFiles - declare that a device touches DISK, once, as code.
+ *
+ * The third sibling of defineSurface and defineWatch, and the one reality asked
+ * for. Writing a file is not one feature, it is three that must travel together:
+ *
+ *   the `download` chain   it owns [maxurl], and phase three of saveToFile is a
+ *                          `file://` place through it - even for a device that
+ *                          downloads nothing and only writes bytes it already has;
+ *   the device folder      where the files went, which the page cannot know and
+ *                          the wrapper has to tell it (`device_folder`);
+ *   the selectors          `fetch_to_file`, the `save_*` exchange.
+ *
+ * Get the first one wrong and the failure is SILENT: the bytes are written
+ * correctly, the place request leaves on an aux outlet with nothing on the other
+ * end, no reply ever comes, and the promise never settles. The UI sits on
+ * "Rendering..." next to a scratch file that looks almost right. Nothing in the
+ * build or the tests could see it, because nothing knew the device meant to write.
+ *
+ * Now it does. A device that declares files gets [maxurl] whether or not its
+ * manifest remembered to ask, and gets told its own folder; a device that declares
+ * none gets neither.
+ *
+ * NO SUBFOLDER OPTION, deliberately. A save's destination must be a FLAT name in
+ * the device folder: Max's [js] File and maxurl (libcurl) resolve a subdirectory
+ * differently, so `sub/x.wav` writes the .part where File agrees and the place
+ * cannot reach it (see saveToFile in @m4l-jweb/wrapper). An option for a path that
+ * does not work is worse than no option.
+ * ------------------------------------------------------------------ */
+
+export interface FilesDef {
+  /**
+   * The page holds the bytes and writes them next to the .amxd - a rendered WAV,
+   * an export, a bounce. `saveToFile()` in @m4l-jweb/bridge.
+   */
+  saves?: boolean;
+  /**
+   * The page hands Max a URL and Max streams it to disk on its own thread, with
+   * nothing crossing the message bridge. `fetchToFile()` in @m4l-jweb/bridge.
+   */
+  fetches?: boolean;
+  /**
+   * Tell the page where its files land, at ui_ready (`device_folder <path>`).
+   * On by default: a file the user cannot find is a file that was not written, and
+   * the page has no other way to learn its own device's folder. Turn it off for a
+   * device whose files are its own business - a cache it fills and reads back.
+   */
+  tellPage?: boolean;
+}
+
+export interface Files extends FilesDef {
+  readonly saves: boolean;
+  readonly fetches: boolean;
+  readonly tellPage: boolean;
+}
+
+/**
+ * Declare what this device does with disk.
+ *
+ * Like defineSurface and defineWatch, the checks run HERE, at call time, and
+ * throw - the build imports this module to derive the chain and the banner, so a
+ * bad declaration fails `pnpm build` and CI.
+ */
+export function defineFiles(def: FilesDef): Files {
+  const saves = def.saves ?? false;
+  const fetches = def.fetches ?? false;
+  // A declaration that claims neither would still pull in [maxurl] and still tell
+  // the page a folder, for a device that touches no disk at all. That is not a
+  // harmless default, it is a device carrying a chain nobody can explain.
+  if (!saves && !fetches) {
+    throw new Error(`files: declare at least one of saves / fetches - a device that does neither should not declare files at all`);
+  }
+  return { saves, fetches, tellPage: def.tellPage ?? true };
+}
+
 /** 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

@@ -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.